da856d89ff
- Create README.md for internationalization (i18n) documentation - Add English translation for main README and quick start guide - Add Japanese translation for main README - Add Simplified Chinese translation for main README - Introduce sample Docker Compose configurations for various deployment scenarios - Implement CI/CD documentation for testing and deployment workflows - Establish end-to-end testing guidelines and strategies - Create test strategy documentation outlining unit, integration, and E2E tests
2.5 KiB
2.5 KiB
API 總覽
ConvertX-CN 提供選用的 API Server，支援 REST 和 GraphQL 兩種 API 介面。
功能特色
- 🔐 JWT 認證：安全的 API 存取控制
- 🌐 REST + GraphQL：雙協議支援
- 🔍 智慧建議：轉換失敗時推薦替代引擎
- 🛠️ 20+ 轉換引擎：與 Web UI 共用完整轉換器
快速啟用
API Server 是選用功能，不影響 Web UI 使用。
啟用方式
docker compose --profile api up -d
服務端口
| 服務 | 端口 | 說明 |
|---|---|---|
| Web UI | 3000 | 網頁介面 |
| API Server | 3001 | REST & GraphQL |
API 端點
REST API
- Base URL:
http://localhost:3001/api/v1 - Content-Type:
application/json或multipart/form-data
GraphQL API
- Endpoint:
http://localhost:3001/graphql - Playground:
http://localhost:3001/graphql（開發模式）
認證
所有 API 請求（除健康檢查外）都需要 JWT Bearer Token：
Authorization: Bearer <your-jwt-token>
Token 結構
{
"sub": "user-id",
"exp": 1234567890,
"iat": 1234567890,
"email": "user@example.com",
"roles": ["user"]
}
API Server 只負責驗證 JWT，不負責產生 JWT。Token 應由獨立的認證服務產生。
環境變數
| 變數 | 說明 | 預設值 |
|---|---|---|
API_HOST |
監聽地址 | 0.0.0.0 |
API_PORT |
監聽埠 | 3001 |
JWT_SECRET |
JWT 驗證密鑰 | （需自行設定） |
UPLOAD_DIR |
上傳目錄 | ./data/uploads |
OUTPUT_DIR |
輸出目錄 | ./data/output |
MAX_FILE_SIZE |
最大檔案大小 | 104857600 |
快速範例
健康檢查
curl http://localhost:3001/health
回應：
{
"status": "healthy",
"version": "0.1.0",
"timestamp": "2026-01-23T10:30:00Z"
}
列出引擎
curl -H "Authorization: Bearer <token>" \
http://localhost:3001/api/v1/engines
轉換檔案
curl -X POST \
-H "Authorization: Bearer <token>" \
-F "file=@document.docx" \
-F "engine=libreoffice" \
-F "output_format=pdf" \
http://localhost:3001/api/v1/convert