feat(api): Docker Compose 整合與補充文件 - Docker Compose profiles 支援選用 API Server - API Server Dockerfile (多階段建置) - .env.api.example 環境變數範本 - integration_tests.rs 完整整合測試 - health_check.sh 健康檢查腳本 - 主專案 README 新增 API Server 說明區塊

compose.yaml

@@ -19,6 +19,27 @@
 # ⚠️ 部署前必做：
 #    1. 先建立 data 資料夾（見 README.md 步驟 2）
 #    2. 修改 JWT_SECRET 為你自己的隨機字串
+#
+# ==============================================================================
+# 🆕 API Server（選用功能）
+# ==============================================================================
+#
+# ConvertX 現在提供獨立的 REST / GraphQL API Server！
+#
+# ⚠️ 預設不啟動 API Server
+#    一般使用者只需要 Web UI，不需要啟動 API
+#
+# 🚀 如何啟用 API Server？
+#    使用 profile 功能：
+#
+#    # 只啟動 Web UI（預設行為）
+#    docker compose up -d
+#
+#    # 同時啟動 Web UI + API Server
+#    docker compose --profile api up -d
+#
+# 📖 API 文件請參考：api-server/README.md
+#
 # ==============================================================================
 
 services:
@@ -192,3 +213,120 @@ services:
 
       # 最大同時轉換數（0 = 無限制）
       # - MAX_CONVERT_PROCESS=4
+
+  # ===========================================================================
+  # ConvertX API Server（選用服務）
+  # ===========================================================================
+  #
+  # 🆕 REST + GraphQL API 伺服器
+  #
+  # ⚠️ 這是選用服務，預設不啟動！
+  #    使用 --profile api 才會啟動
+  #
+  # 🚀 啟動方式：
+  #    docker compose --profile api up -d
+  #
+  # 📖 API 端點：
+  #    - REST API:  http://localhost:3001/api/v1/
+  #    - GraphQL:   http://localhost:3001/graphql
+  #    - 健康檢查: http://localhost:3001/health
+  #
+  # 🔐 認證方式：
+  #    所有 API（除健康檢查）都需要 JWT Bearer Token
+  #    Token 需由外部認證服務產生
+  #
+  # ===========================================================================
+  convertx-api:
+    # 使用 profile 使其成為選用服務
+    profiles:
+      - api
+
+    # 使用本地 Dockerfile 建置
+    build:
+      context: ./api-server
+      dockerfile: Dockerfile
+
+    # 或使用預建的 image（取消下面的註解）
+    # image: convertx/convertx-api:latest
+
+    container_name: convertx-api
+
+    restart: unless-stopped
+
+    # =========================================================================
+    # 連接埠設定
+    # =========================================================================
+    # API Server 預設使用 3001 埠，避免與 Web UI (3000) 衝突
+    ports:
+      - "3001:3001"
+
+    # =========================================================================
+    # 資料儲存設定
+    # =========================================================================
+    # 與 Web UI 共用相同的 data 目錄
+    # API Server 會在 data/uploads 和 data/output 下建立子目錄
+    volumes:
+      - ./data:/app/data
+
+    # =========================================================================
+    # 環境變數設定
+    # =========================================================================
+    # 可使用 env_file 載入 .env.api 檔案
+    env_file:
+      - path: .env.api
+        required: false
+
+    environment:
+      # 時區設定
+      - TZ=Asia/Taipei
+
+      # -----------------------------------------------------------------------
+      # API Server 專用設定
+      # -----------------------------------------------------------------------
+      # API 監聽地址與埠
+      - API_HOST=0.0.0.0
+      - API_PORT=3001
+
+      # -----------------------------------------------------------------------
+      # JWT 密鑰（🔐 必須設定）
+      # -----------------------------------------------------------------------
+      # ⚠️ 這是 API Server 驗證 Token 用的密鑰
+      #    必須與產生 Token 的認證服務使用相同的密鑰
+      #
+      # 🚨 請務必修改為你自己的密鑰！
+      - JWT_SECRET=${API_JWT_SECRET:-請設定你的API專用JWT密鑰}
+
+      # -----------------------------------------------------------------------
+      # 檔案儲存路徑
+      # -----------------------------------------------------------------------
+      - UPLOAD_DIR=/app/data/api-uploads
+      - OUTPUT_DIR=/app/data/api-output
+
+      # -----------------------------------------------------------------------
+      # 其他設定
+      # -----------------------------------------------------------------------
+      # 最大檔案大小（預設 100MB）
+      - MAX_FILE_SIZE=104857600
+
+      # 日誌級別
+      - RUST_LOG=convertx_api=info,tower_http=info
+
+    # =========================================================================
+    # 健康檢查
+    # =========================================================================
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:3001/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 10s
+
+    # =========================================================================
+    # 資源限制（可選）
+    # =========================================================================
+    # deploy:
+    #   resources:
+    #     limits:
+    #       memory: 2G
+    #     reservations:
+    #       memory: 512M