diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 520e659..e7663c3 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -154,20 +154,22 @@ jobs: # - 使用 registry cache 而非 GHA cache（避免 10GB 限制） # - 啟用 zstd compression 減少傳輸量和儲存空間 # - Multi-arch build 需要更多磁碟空間，已在上方清理 + # - 明確指定 file: Dockerfile 避免與 Lite 版混淆 # ======================================== - name: Build and push Docker image uses: docker/build-push-action@v6 with: context: . + file: Dockerfile push: true tags: | ${{ env.DOCKER_IMAGE }}:${{ steps.tag.outputs.version }} ${{ env.DOCKER_IMAGE }}:latest platforms: linux/amd64,linux/arm64 - # 🔥 使用 registry cache 取代 GHA cache + # 🔥 使用獨立的 cache key 避免與 Lite 版交叉污染 # registry cache 沒有 10GB 限制，更適合大型模型 - cache-from: type=registry,ref=${{ env.DOCKER_IMAGE }}:buildcache - cache-to: type=registry,ref=${{ env.DOCKER_IMAGE }}:buildcache,mode=max,compression=zstd + cache-from: type=registry,ref=${{ env.DOCKER_IMAGE }}:buildcache-full + cache-to: type=registry,ref=${{ env.DOCKER_IMAGE }}:buildcache-full,mode=max,compression=zstd # 啟用壓縮減少 image 大小 outputs: type=image,compression=zstd,compression-level=3 # 設定 build 參數 diff --git a/CHANGELOG.md b/CHANGELOG.md index ee26d76..6e5424f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,52 @@ # Changelog +## [0.1.16](https://github.com/pi-docket/ConvertX-CN/releases/tag/v0.1.16) (2026-01-24) + +一般版 Docker Image 修復版本，確保開箱即用。 + +### 🐛 Bug Fixes + +- **一般版 Docker Image 大小修復**：修復 0.1.15 版本 image 體積異常問題 + - 問題：一般版 image 僅約 1.5-2 GB，應為 8-12 GB + - 原因：release.yml 未明確指定 Dockerfile，可能導致 cache 問題 + - 修復：明確指定 `file: Dockerfile` 並使用獨立的 cache key + +- **嚴格模型驗證**：新增 build-time 模型驗證機制 + - 若 ONNX 模型缺失或過小，build 將失敗 + - 若 PDFMathTranslate 字型數量不足，build 將失敗 + - 確保發布的 image 一定包含所有必要模型 + +- **下載重試機制**：所有 curl 下載增加重試機制 + - 新增 `--retry 3 --retry-delay 5 --retry-all-errors` 參數 + - 覆蓋範圍：Bun、dasel、resvg、vtracer、ONNX 模型、字型檔案 + +### 📦 Build + +- **release.yml 改進**： + - 新增 `file: Dockerfile` 明確指定使用一般版 Dockerfile + - 使用 `buildcache-full` 作為 cache key，避免與 Lite 版交叉污染 +- **Dockerfile 強化**： + - 版本號更新為 v0.1.16 + - 新增嚴格模型驗證區塊（驗證 ONNX、字型、MinerU） + - 驗證失敗時 build 將中止並報錯 + - 所有下載均添加重試機制 + +### 📚 Documentation + +- **版本術語統一**： + - **一般版**（Standard）：官方預建版 `convertx-cn:latest`，約 8-12 GB，開箱即用 + - **擴充版**（Extended）：使用 `Dockerfile.full` 自建，支援 65 種 OCR 語言，>10 GB + - **Lite 版**（Lightweight）：`convertx-cn:latest-lite`，約 1.2 GB，基本轉檔 +- **環境變數文檔重整**： + - 刪除重複的 `docs/環境變數總覽.md` + - 改進 `docs/配置設定/環境變數.md` 結構 + - 新增快速參考表（分類：安全性、一般、轉換、PDF翻譯） +- **Docker 部署指南更新**： + - 新增版本對照表 + - 明確三種版本的區別與適用場景 + +--- + ## [0.1.15](https://github.com/pi-docket/ConvertX-CN/releases/tag/v0.1.15) (2026-01-24) Docker 基礎架構優化版本，新增 Lite 版 Docker Image。 diff --git a/Dockerfile b/Dockerfile index 898e8ab..d53a1f3 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,6 +1,6 @@ # ============================================================================== # ConvertX-CN 官方 Docker Image -# 版本：v0.1.12 +# 版本：v0.1.16 # ============================================================================== # # 📦 Image 說明： @@ -56,9 +56,9 @@ RUN apt-get update && apt-get install -y --no-install-recommends \ # if architecture is arm64, use the arm64 version of bun RUN ARCH=$(uname -m) && \ if [ "$ARCH" = "aarch64" ]; then \ - curl -fsSL -o bun-linux-aarch64.zip https://github.com/oven-sh/bun/releases/download/bun-v1.3.6/bun-linux-aarch64.zip; \ + curl -fsSL --retry 3 --retry-delay 5 --retry-all-errors -o bun-linux-aarch64.zip https://github.com/oven-sh/bun/releases/download/bun-v1.3.6/bun-linux-aarch64.zip; \ else \ - curl -fsSL -o bun-linux-x64-baseline.zip https://github.com/oven-sh/bun/releases/download/bun-v1.3.6/bun-linux-x64-baseline.zip; \ + curl -fsSL --retry 3 --retry-delay 5 --retry-all-errors -o bun-linux-x64-baseline.zip https://github.com/oven-sh/bun/releases/download/bun-v1.3.6/bun-linux-x64-baseline.zip; \ fi RUN unzip -j bun-linux-*.zip -d /usr/local/bin && \ @@ -155,7 +155,7 @@ RUN echo "" && \ else \ DASEL_ARCH="linux_amd64"; \ fi && \ - curl -sSLf "https://github.com/TomWright/dasel/releases/download/v2.8.1/dasel_${DASEL_ARCH}" -o /usr/local/bin/dasel && \ + curl -sSLf --retry 3 --retry-delay 5 --retry-all-errors "https://github.com/TomWright/dasel/releases/download/v2.8.1/dasel_${DASEL_ARCH}" -o /usr/local/bin/dasel && \ chmod +x /usr/local/bin/dasel && \ echo " ✅ dasel 安裝完成" @@ -167,7 +167,7 @@ RUN echo "" && \ if [ "$ARCH" = "aarch64" ]; then \ echo " ⚠️ resvg 沒有 ARM64 預編譯版本，跳過安裝"; \ else \ - curl -sSLf "https://github.com/linebender/resvg/releases/download/v0.44.0/resvg-linux-x86_64.tar.gz" -o /tmp/resvg.tar.gz && \ + curl -sSLf --retry 3 --retry-delay 5 --retry-all-errors "https://github.com/linebender/resvg/releases/download/v0.44.0/resvg-linux-x86_64.tar.gz" -o /tmp/resvg.tar.gz && \ tar -xzf /tmp/resvg.tar.gz -C /tmp/ && \ mv /tmp/resvg /usr/local/bin/resvg && \ chmod +x /usr/local/bin/resvg && \ @@ -453,7 +453,7 @@ RUN set -eux && \ echo "📥 [6/8] 下載 PDFMathTranslate/BabelDOC DocLayout-YOLO ONNX 模型..." && \ mkdir -p /root/.cache/babeldoc/models && \ # 直接下載 ONNX 模型到 babeldoc 期望的路徑 - curl -fSL -o /root/.cache/babeldoc/models/doclayout_yolo_docstructbench_imgsz1024.onnx \ + curl -fSL --retry 3 --retry-delay 5 --retry-all-errors -o /root/.cache/babeldoc/models/doclayout_yolo_docstructbench_imgsz1024.onnx \ "https://huggingface.co/wybxc/DocLayout-YOLO-DocStructBench-onnx/resolve/main/doclayout_yolo_docstructbench_imgsz1024.onnx" && \ echo "✅ ONNX 模型下載完成" && \ ls -lh /root/.cache/babeldoc/models/*.onnx && \ @@ -466,15 +466,15 @@ RUN set -eux && \ echo "" && \ echo "📥 [6.1/8] 下載 PDFMathTranslate 多語言字型..." && \ mkdir -p /app && \ - curl -fSL -o /app/GoNotoKurrent-Regular.ttf \ + curl -fSL --retry 3 --retry-delay 5 --retry-all-errors -o /app/GoNotoKurrent-Regular.ttf \ "https://github.com/satbyy/go-noto-universal/releases/download/v7.0/GoNotoKurrent-Regular.ttf" && \ - curl -fSL -o /app/SourceHanSerifCN-Regular.ttf \ + curl -fSL --retry 3 --retry-delay 5 --retry-all-errors -o /app/SourceHanSerifCN-Regular.ttf \ "https://github.com/timelic/source-han-serif/releases/download/main/SourceHanSerifCN-Regular.ttf" && \ - curl -fSL -o /app/SourceHanSerifTW-Regular.ttf \ + curl -fSL --retry 3 --retry-delay 5 --retry-all-errors -o /app/SourceHanSerifTW-Regular.ttf \ "https://github.com/timelic/source-han-serif/releases/download/main/SourceHanSerifTW-Regular.ttf" && \ - curl -fSL -o /app/SourceHanSerifJP-Regular.ttf \ + curl -fSL --retry 3 --retry-delay 5 --retry-all-errors -o /app/SourceHanSerifJP-Regular.ttf \ "https://github.com/timelic/source-han-serif/releases/download/main/SourceHanSerifJP-Regular.ttf" && \ - curl -fSL -o /app/SourceHanSerifKR-Regular.ttf \ + curl -fSL --retry 3 --retry-delay 5 --retry-all-errors -o /app/SourceHanSerifKR-Regular.ttf \ "https://github.com/timelic/source-han-serif/releases/download/main/SourceHanSerifKR-Regular.ttf" && \ echo "✅ 字型下載完成" && \ ls -lh /app/*.ttf && \ @@ -630,6 +630,76 @@ RUN set -eux && \ fi && \ echo "" && \ \ + # ======================================== + # 🔒 嚴格模型驗證（確保開箱即用） + # ======================================== + # ⚠️ 如果關鍵模型缺失，build 將失敗 + # 這確保發布的 image 一定包含所有必要模型 + # ======================================== + echo "===========================================================" && \ + echo "🔒 嚴格模型驗證（確保開箱即用）" && \ + echo "===========================================================" && \ + VALIDATION_FAILED=0 && \ + \ + # 驗證 1: BabelDOC ONNX 模型（必須存在） + echo "🔍 驗證 BabelDOC ONNX 模型..." && \ + ONNX_FILE="/root/.cache/babeldoc/models/doclayout_yolo_docstructbench_imgsz1024.onnx" && \ + if [ -f "$ONNX_FILE" ]; then \ + ONNX_SIZE=$(stat -c%s "$ONNX_FILE" 2>/dev/null || echo 0); \ + if [ "$ONNX_SIZE" -gt 10000000 ]; then \ + echo " ✅ ONNX 模型驗證通過 ($((ONNX_SIZE/1024/1024)) MB)"; \ + else \ + echo " ❌ ONNX 模型過小 ($ONNX_SIZE bytes)"; \ + VALIDATION_FAILED=1; \ + fi; \ + else \ + echo " ❌ ONNX 模型不存在: $ONNX_FILE"; \ + VALIDATION_FAILED=1; \ + fi && \ + \ + # 驗證 2: PDFMathTranslate 字型（必須存在） + echo "🔍 驗證 PDFMathTranslate 字型..." && \ + FONT_COUNT=$(ls /app/*.ttf 2>/dev/null | wc -l) && \ + if [ "$FONT_COUNT" -ge 5 ]; then \ + echo " ✅ 字型驗證通過 ($FONT_COUNT 個字型)"; \ + else \ + echo " ❌ 字型數量不足 (預期 >= 5，實際 $FONT_COUNT)"; \ + VALIDATION_FAILED=1; \ + fi && \ + \ + # 驗證 3: MinerU 模型（如果 mineru 已安裝則必須存在） + echo "🔍 驗證 MinerU 模型..." && \ + if command -v mineru >/dev/null 2>&1; then \ + if [ -f /root/mineru.json ]; then \ + MINERU_DIR=$(python3 -c "import json; f=open('/root/mineru.json'); d=json.load(f); print(d.get('models-dir',{}).get('pipeline',''))" 2>/dev/null || echo ""); \ + if [ -n "$MINERU_DIR" ] && [ -d "$MINERU_DIR" ]; then \ + MINERU_SIZE=$(du -sb "$MINERU_DIR" 2>/dev/null | cut -f1 || echo 0); \ + if [ "$MINERU_SIZE" -gt 1000000000 ]; then \ + echo " ✅ MinerU 模型驗證通過 ($((MINERU_SIZE/1024/1024)) MB)"; \ + else \ + echo " ⚠️ MinerU 模型較小 ($((MINERU_SIZE/1024/1024)) MB)，可能不完整"; \ + fi; \ + else \ + echo " ⚠️ MinerU 模型目錄不存在（ARM64 可能不支援）"; \ + fi; \ + else \ + echo " ⚠️ mineru.json 不存在（ARM64 可能不支援）"; \ + fi; \ + else \ + echo " ⚠️ MinerU 未安裝（ARM64 可能不支援）"; \ + fi && \ + \ + # 最終驗證結果 + echo "" && \ + if [ "$VALIDATION_FAILED" -eq 1 ]; then \ + echo "❌ 模型驗證失敗！Image 不應發布。"; \ + echo " 請檢查網路連接並重新 build。"; \ + exit 1; \ + else \ + echo "✅ 所有必要模型驗證通過！"; \ + fi && \ + echo "" && \ + \ echo "===========================================================" && \ echo "✅ 階段 12-UNIFIED 完成：所有 Python 工具 + 模型已安裝" && \ echo " 所有 cache 已清理，layer diff 最小化" && \ @@ -676,7 +746,7 @@ RUN ARCH=$(uname -m) && \ else \ VTRACER_ASSET="vtracer-x86_64-unknown-linux-musl.tar.gz"; \ fi && \ - curl -L -o /tmp/vtracer.tar.gz "https://github.com/visioncortex/vtracer/releases/download/0.6.4/${VTRACER_ASSET}" && \ + curl -L --retry 3 --retry-delay 5 --retry-all-errors -o /tmp/vtracer.tar.gz "https://github.com/visioncortex/vtracer/releases/download/0.6.4/${VTRACER_ASSET}" && \ tar -xzf /tmp/vtracer.tar.gz -C /tmp/ && \ mv /tmp/vtracer /usr/local/bin/vtracer && \ chmod +x /usr/local/bin/vtracer && \ diff --git a/docs/環境變數總覽.md b/docs/環境變數總覽.md deleted file mode 100644 index 7c4d8f1..0000000 --- a/docs/環境變數總覽.md +++ /dev/null @@ -1,197 +0,0 @@ -# 環境變數設定 - -> 📦 本文件已遷移至新位置，請參閱：[docs/config/environment.md](配置設定/環境變數.md) - ---- - -## 快速參考 - -完整說明請參考 [環境變數完整說明](配置設定/環境變數.md)。 - -| 優先級 | 變數 | 說明 | -| ------ | -------------- | ------------- | -| 必填 | `JWT_SECRET` | 登入驗證金鑰 | -| 建議 | `TZ` | 時區設定 | -| 建議 | `HTTP_ALLOWED` | 是否允許 HTTP | -| 可選 | `TRUST_PROXY` | 信任反向代理 | - ---- - -## 相關文件 - -- [環境變數完整說明](配置設定/環境變數.md) -- [安全性設定](配置設定/安全性.md) -- [Docker 部署指南](部署指南/Docker部署.md) - ---- - -## 🎨 介面設定 - -### WEBROOT - -| 項目 | 說明 | -| ------ | ---------------------------- | -| 預設值 | (空) | -| 用途 | 子路徑部署，例如 `/convertx` | - -若透過子路徑存取（如 `https://example.com/convertx/`）： - -```yaml -- WEBROOT=/convertx -``` - -### HIDE_HISTORY - -| 項目 | 說明 | -| ------ | ---------------- | -| 預設值 | `false` | -| 用途 | 隱藏歷史紀錄頁面 | - -### LANGUAGE - -| 項目 | 說明 | -| ------ | --------------------------- | -| 預設值 | `en` | -| 用途 | 日期格式語言（BCP 47 格式） | - -影響介面上的日期顯示格式（如 2026/01/20 vs 01/20/2026）。 - ---- - -## ⚙️ 轉換設定 - -### MAX_CONVERT_PROCESS - -| 項目 | 說明 | -| ------ | ---------------------------- | -| 預設值 | `0` | -| 用途 | 最大同時轉換數（0 = 無限制） | - -限制同時進行的轉換任務數量，避免伺服器過載。 - -### FFMPEG_ARGS - -| 項目 | 說明 | -| ------ | ------------------------------- | -| 預設值 | (空) | -| 用途 | FFmpeg 輸入參數，用於硬體加速等 | - -**硬體加速範例**： - -```yaml -# NVIDIA GPU -- FFMPEG_ARGS=-hwaccel cuda - -# Intel QSV -- FFMPEG_ARGS=-hwaccel qsv - -# AMD VAAPI -- FFMPEG_ARGS=-hwaccel vaapi -``` - -### FFMPEG_OUTPUT_ARGS - -| 項目 | 說明 | -| ------ | --------------- | -| 預設值 | (空) | -| 用途 | FFmpeg 輸出參數 | - -```yaml -# 使用較快的編碼預設 -- FFMPEG_OUTPUT_ARGS=-preset veryfast -``` - ---- - -## 🔧 進階設定 - -### UNAUTHENTICATED_USER_SHARING - -| 項目 | 說明 | -| ------ | ---------------------------- | -| 預設值 | `false` | -| 用途 | 未登入使用者是否共享檔案空間 | - -設為 `true` 時，所有匿名使用者會看到相同的檔案。 - ---- - -## 情境範例 - -### 開發環境 - -```yaml -environment: - - HTTP_ALLOWED=true - - ACCOUNT_REGISTRATION=true - - TZ=Asia/Taipei -``` - -### 生產環境 - -```yaml -environment: - - JWT_SECRET=your-very-long-and-random-secret-key-change-me - - ACCOUNT_REGISTRATION=false - - HTTP_ALLOWED=false - - TRUST_PROXY=true - - TZ=Asia/Taipei - - AUTO_DELETE_EVERY_N_HOURS=24 -``` - -### 公開服務（允許匿名使用） - -```yaml -environment: - - ALLOW_UNAUTHENTICATED=true - - HIDE_HISTORY=true - - AUTO_DELETE_EVERY_N_HOURS=1 -``` - ---- - -## 📝 PDF Packager 設定 - -### PDF 數位簽章 - -PDF Packager 預設**開箱即用**，Docker 建置時已自動產生預設憑證。如需使用自訂憑證，可透過以下環境變數配置： - -| 變數 | 預設值 | 說明 | -| ----------------------- | -------------------------- | ------------------- | -| `PDF_SIGN_P12_PATH` | `/app/certs/default.p12` | PKCS12 憑證檔案路徑 | -| `PDF_SIGN_P12_PASSWORD` | （空） | 憑證密碼 | -| `PDF_SIGN_REASON` | `ConvertX-CN PDF Packager` | 簽章原因 | -| `PDF_SIGN_LOCATION` | `Taiwan` | 簽章地點 | -| `PDF_SIGN_CONTACT` | `convertx-cn@localhost` | 聯絡資訊 | - -**使用自訂憑證範例**： - -```yaml -environment: - - PDF_SIGN_P12_PATH=/app/certs/company.p12 - - PDF_SIGN_P12_PASSWORD=your_password - - PDF_SIGN_REASON=文件已核准 - - PDF_SIGN_LOCATION=台北 - - PDF_SIGN_CONTACT=admin@company.com -volumes: - - /path/to/certs:/app/certs:ro -``` - -詳細說明請參考 [PDF Packager 說明](功能說明/PDF-Packager.md)。 - ---- - -## 相關文件 - -- [Docker 部署指南](部署指南/Docker部署.md) -- [Docker Compose 範例](Docker組合配置/) -- [常見問題](快速入門/常見問題.md) - -### 帶硬體加速 - -```yaml -environment: - - JWT_SECRET=your-secret-key - - FFMPEG_ARGS=-hwaccel cuda - - FFMPEG_OUTPUT_ARGS=-c:v h264_nvenc -preset fast -``` diff --git a/docs/部署指南/Docker-Lite.md b/docs/部署指南/Docker-Lite.md index 6ac56a7..ec8eed1 100644 --- a/docs/部署指南/Docker-Lite.md +++ b/docs/部署指南/Docker-Lite.md @@ -4,14 +4,33 @@ ConvertX-CN Lite 是專為一般使用者設計的輕量版本，提供快速部 --- +## 📦 版本對照表 + +ConvertX-CN 提供三種 Docker Image 版本： + +| 版本 | Image Tag | 大小 | 適用場景 | +| ------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------- | +| 一般版 | `latest` | ![Docker Image Size](https://img.shields.io/docker/image-size/convertx/convertx-cn/latest?label=image%20size%20) | 進階使用者、AI/OCR/翻譯 | +| 擴充版 | 自行建構 `Dockerfile.full` | >10 GB | 65 種 OCR 語言 | +| Lite 版 | `latest-lite` | ![Docker Image Size (Lite)]() | 一般使用者、基本轉檔 | + +--- + ## 📦 什麼是 Lite 版？ -| 特性 | Full 版 | Lite 版 | -| -------------- | ---------------------------- | ------------------------ | -| **Image 大小** | 約 8-12 GB | 約 1.2-1.5 GB | -| **部署時間** | 較長（需下載大型模型） | 快速 | -| **記憶體需求** | 較高（AI 模型） | 較低 | -| **適用場景** | 進階使用者、需要 AI/OCR/翻譯 | 一般使用者、基本轉檔需求 | +| 特性 | 一般版 | Lite 版 | +| -------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| **Image 大小** | ![Docker Image Size](https://img.shields.io/docker/image-size/convertx/convertx-cn/latest?label=image%20size%20) | ![Docker Image Size (Lite)]() | +| **部署時間** | 較長（含預下載 AI 模型） | 快速 | +| **記憶體需求** | 較高（AI 模型） | 較低 | +| **適用場景** | 進階使用者、需要 AI/OCR/翻譯 | 一般使用者、基本轉檔需求 | +| **開箱即用** | ✅ 所有模型已預下載 | ✅ 無需下載 | + +> 💡 **一般版開箱即用說明**： +> +> - 所有 AI 模型在 Docker build 階段已預下載 +> - Runtime 完全離線運行，不依賴網路下載模型 +> - 僅翻譯 API（Google/Bing/DeepL）需要網路連接 --- @@ -44,7 +63,7 @@ ConvertX-CN Lite 是專為一般使用者設計的輕量版本，提供快速部 ## ❌ Lite 版未包含的功能 -以下功能僅在 Full 版中提供： +以下功能僅在一般版中提供： | 功能類別 | 功能說明 | | ------------------- | ------------------------------ | @@ -60,6 +79,8 @@ ConvertX-CN Lite 是專為一般使用者設計的輕量版本，提供快速部 | **長期驗證** | LTV、OCSP、CRL、TSA | | **完整 TexLive** | 進階 LaTeX 排版 | +> ⚠️ **重要提醒**：一般版的 AI/OCR/翻譯功能已預下載所有模型，開箱即用，Runtime 不會從網路下載任何模型。 + --- ## 🚀 快速開始 @@ -104,10 +125,16 @@ docker compose up -d | Tag | 說明 | | ---------------------------------- | ----------------- | -| `convertx/convertx-cn:latest` | Full 版最新穩定版 | +| `convertx/convertx-cn:latest` | 一般版最新穩定版 | | `convertx/convertx-cn:latest-lite` | Lite 版最新穩定版 | -| `convertx/convertx-cn:0.1.15` | Full 版指定版本 | -| `convertx/convertx-cn:0.1.15-lite` | Lite 版指定版本 | +| `convertx/convertx-cn:0.1.16` | 一般版指定版本 | +| `convertx/convertx-cn:0.1.16-lite` | Lite 版指定版本 | + +> 💡 **版本標記說明**： +> +> - **一般版**：無後綴，包含所有 AI/OCR/翻譯功能，開箱即用（約 8-12 GB） +> - **擴充版**：使用 `Dockerfile.full` 自行建構，支援 65 種 OCR 語言（>10 GB） +> - **Lite 版**：帶 `-lite` 後綴，輕量化設計，適合基本轉檔需求（約 1.2 GB） --- @@ -152,53 +179,53 @@ RUN apt-get update && apt-get install -y --no-install-recommends \ # && rm -rf /var/lib/apt/lists/* ``` -### 方法 2：直接使用 Full 版 +### 方法 2：直接使用一般版 -如果需要完整功能，建議直接使用 Full 版： +如果需要完整功能，建議直接使用一般版： ```yaml services: convertx: - image: convertx/convertx-cn:latest # Full 版 + image: convertx/convertx-cn:latest # 一般版（開箱即用） ``` ### ⚠️ 重要提醒 - Lite 版**本身不包含** OCR、AI、翻譯等進階功能 - 自行擴充會增加 Image 大小與維護成本 -- 如需完整功能，建議直接使用 Full 版 +- 如需完整功能，建議直接使用一般版（所有模型已預下載） --- -## 📊 Lite vs Full 功能對照表 +## 📊 Lite vs 一般版功能對照表 -| 功能類別 | 功能 | Lite | Full | -| --------- | ---------------------------- | :--: | :--: | -| **UI** | 多語言介面（65 語言） | ✅ | ✅ | -| **UI** | 深色/淺色主題 | ✅ | ✅ | -| **轉檔** | 文件轉檔（LibreOffice） | ✅ | ✅ | -| **轉檔** | 圖片轉檔（GraphicsMagick） | ✅ | ✅ | -| **轉檔** | 圖片轉檔（ImageMagick） | ❌ | ✅ | -| **轉檔** | 影音轉檔（FFmpeg） | ✅ | ✅ | -| **轉檔** | 文件格式（Pandoc） | ✅ | ✅ | -| **轉檔** | 向量圖（Inkscape） | ❌ | ✅ | -| **轉檔** | 高效能圖片（VIPS） | ❌ | ✅ | -| **轉檔** | 電子書（Calibre） | ❌ | ✅ | -| **轉檔** | CAD/3D（assimp） | ❌ | ✅ | -| **PDF** | PDF/A 轉換 | ✅ | ✅ | -| **PDF** | PDF 防修改 | ✅ | ✅ | -| **PDF** | PDF 數位簽章 | ✅ | ✅ | -| **PDF** | PDF/A 驗證（veraPDF） | ❌ | ✅ | -| **PDF** | 長期驗證（LTV） | ❌ | ✅ | -| **OCR** | 文字辨識（Tesseract） | ❌ | ✅ | -| **OCR** | ocrmypdf | ❌ | ✅ | -| **AI** | PDF 翻譯（PDFMathTranslate） | ❌ | ✅ | -| **AI** | PDF 翻譯（BabelDOC） | ❌ | ✅ | -| **AI** | PDF 轉 Markdown（MinerU） | ❌ | ✅ | -| **字型** | 基本 CJK 字型 | ✅ | ✅ | -| **字型** | 完整 Noto 字型集 | ❌ | ✅ | -| **LaTeX** | 基本 LaTeX | ❌ | ✅ | -| **LaTeX** | 完整 TexLive CJK | ❌ | ✅ | +| 功能類別 | 功能 | Lite | 一般版 | +| --------- | ---------------------------- | :--: | :----: | +| **UI** | 多語言介面（65 語言） | ✅ | ✅ | +| **UI** | 深色/淺色主題 | ✅ | ✅ | +| **轉檔** | 文件轉檔（LibreOffice） | ✅ | ✅ | +| **轉檔** | 圖片轉檔（GraphicsMagick） | ✅ | ✅ | +| **轉檔** | 圖片轉檔（ImageMagick） | ❌ | ✅ | +| **轉檔** | 影音轉檔（FFmpeg） | ✅ | ✅ | +| **轉檔** | 文件格式（Pandoc） | ✅ | ✅ | +| **轉檔** | 向量圖（Inkscape） | ❌ | ✅ | +| **轉檔** | 高效能圖片（VIPS） | ❌ | ✅ | +| **轉檔** | 電子書（Calibre） | ❌ | ✅ | +| **轉檔** | CAD/3D（assimp） | ❌ | ✅ | +| **PDF** | PDF/A 轉換 | ✅ | ✅ | +| **PDF** | PDF 防修改 | ✅ | ✅ | +| **PDF** | PDF 數位簽章 | ✅ | ✅ | +| **PDF** | PDF/A 驗證（veraPDF） | ❌ | ✅ | +| **PDF** | 長期驗證（LTV） | ❌ | ✅ | +| **OCR** | 文字辨識（Tesseract） | ❌ | ✅ | +| **OCR** | ocrmypdf | ❌ | ✅ | +| **AI** | PDF 翻譯（PDFMathTranslate） | ❌ | ✅ | +| **AI** | PDF 翻譯（BabelDOC） | ❌ | ✅ | +| **AI** | PDF 轉 Markdown（MinerU） | ❌ | ✅ | +| **字型** | 基本 CJK 字型 | ✅ | ✅ | +| **字型** | 完整 Noto 字型集 | ❌ | ✅ | +| **LaTeX** | 基本 LaTeX | ❌ | ✅ | +| **LaTeX** | 完整 TexLive CJK | ❌ | ✅ | --- @@ -211,7 +238,7 @@ services: - 🔹 需要快速部署 - 🔹 不需要 OCR、AI、翻譯功能 -### 適合使用 Full 版的情境 +### 適合使用一般版的情境 - 🔹 需要 OCR 文字辨識 - 🔹 需要 PDF 翻譯功能 @@ -219,12 +246,13 @@ services: - 🔹 需要電子書轉換（ePub、MOBI） - 🔹 需要 CAD/3D 檔案處理 - 🔹 需要進階 PDF/A 驗證 +- 🔹 需要開箱即用的離線 AI 功能 --- ## 📝 版本更新 -Lite 版與 Full 版使用相同的版本號規則，但 tag 不同： +Lite 版與一般版使用相同的版本號規則，但 tag 不同： ```bash # 更新 Lite 版 @@ -232,7 +260,7 @@ docker compose pull docker compose up -d # 或指定版本 -docker pull convertx/convertx-cn:0.2.0-lite +docker pull convertx/convertx-cn:0.1.16-lite ``` --- @@ -241,5 +269,5 @@ docker pull convertx/convertx-cn:0.2.0-lite - [Docker Hub](https://hub.docker.com/r/convertx/convertx-cn) - [GitHub Repository](https://github.com/pi-docket/ConvertX-CN) -- [Full 版部署指南](Docker.md) +- [一般版部署指南](Docker.md) - [環境變數說明](../配置設定/環境變數.md) diff --git a/docs/部署指南/Docker.md b/docs/部署指南/Docker.md index 9c3561b..7ded5d1 100644 --- a/docs/部署指南/Docker.md +++ b/docs/部署指南/Docker.md @@ -6,33 +6,53 @@ --- -## Docker Image 版本 +## 📦 Docker Image 版本總覽 + +ConvertX-CN 提供三種 Docker Image 版本，滿足不同使用場景： + +| 版本 | 說明 | Image Tag | 大小 | +| ------- | -------------------- | --------------------------- | ---------- | +| 一般版 | 官方預建版，開箱即用 | `convertx-cn:latest` | 約 8-12 GB | +| 擴充版 | 自行建構，65 種語言 | 使用 `Dockerfile.full` 自建 | >10 GB | +| Lite 版 | 輕量化，基本轉檔功能 | `convertx-cn:latest-lite` | 約 1.2 GB | ### 官方預建版（推薦） | Tag | 說明 | | ---------------------------------- | ----------------- | -| `convertx/convertx-cn:latest` | Full 版最新穩定版 | +| `convertx/convertx-cn:latest` | 一般版最新穩定版 | | `convertx/convertx-cn:latest-lite` | Lite 版最新穩定版 | -| `convertx/convertx-cn:v0.1.x` | Full 版指定版本號 | +| `convertx/convertx-cn:v0.1.x` | 一般版指定版本號 | | `convertx/convertx-cn:v0.1.x-lite` | Lite 版指定版本號 | -### Full 版（預設） +--- + +### 一般版（Standard） ⭐ 推薦 + +**Image Tag：** `convertx/convertx-cn:latest` **Image 大小：約 8-12 GB** +> 💡 **開箱即用**：所有 AI 模型在 Build 階段已預下載，Runtime 不需要網路即可使用所有功能。 + **內建功能：** - ✅ 核心轉換工具（FFmpeg、LibreOffice、ImageMagick 等） -- ✅ OCR 支援：英文、繁/簡中文、日文、韓文、德文、法文 +- ✅ OCR 支援：英文、繁/簡中文、日文、韓文、德文、法文（7 種語言） - ✅ PDF 翻譯：PDFMathTranslate、BabelDOC - ✅ PDF 轉 Markdown：MinerU -- ✅ 字型：Noto CJK、Liberation、自訂中文字型 +- ✅ 字型：Noto CJK、Liberation、Source Han Serif - ✅ TexLive（支援 CJK/德/法） +- ✅ 電子書轉換（Calibre） +- ✅ CAD/3D 支援（assimp） -### Lite 版（輕量版） +--- -**Image 大小：約 1.5-2.5 GB** +### Lite 版（Lightweight） + +**Image Tag：** `convertx/convertx-cn:latest-lite` + +**Image 大小：約 1.2-1.5 GB** **內建功能：** @@ -44,16 +64,22 @@ > 📖 Lite 版詳細說明請參閱 [Lite 版部署指南](Docker-Lite.md) -### 完整版（自行 Build） +--- + +### 擴充版（Extended）- 自行建構 + +**Dockerfile：** `Dockerfile.full` + +**Image 大小：>10 GB** 使用 `Dockerfile.full` 自行建構，適合需要： -- 65 種 OCR 語言 -- 完整 TexLive -- 額外字型套件 +- ✅ 65 種 OCR 語言（完整 Tesseract 語言包） +- ✅ 完整 TexLive（所有排版套件） +- ✅ 額外字型套件 ```bash -docker build -f Dockerfile.full -t convertx-cn-full . +docker build -f Dockerfile.full -t convertx-cn-extended . ``` > ⚠️ 注意：Image 大小可能超過 **10GB**，Build 時間約 **30-60 分鐘** diff --git a/docs/配置設定/環境變數.md b/docs/配置設定/環境變數.md index 2cea573..68a3703 100644 --- a/docs/配置設定/環境變數.md +++ b/docs/配置設定/環境變數.md @@ -4,18 +4,46 @@ --- -## 快速參考 +## 📋 快速參考表 -| 優先級 | 變數 | 說明 | 預設值 | -| ------ | -------------- | ------------ | ------------------ | -| 必填 | `JWT_SECRET` | 登入驗證金鑰 | 隨機（每次重啟變） | -| 建議 | `TZ` | 時區 | `UTC` | -| 建議 | `HTTP_ALLOWED` | 允許 HTTP | `false` | -| 可選 | `TRUST_PROXY` | 信任反向代理 | `false` | +### 🔒 安全性設定 + +| 變數 | 說明 | 預設值 | 必填 | +| ----------------------- | ------------ | ------------------ | ---- | +| `JWT_SECRET` | 登入驗證金鑰 | 隨機（每次重啟變） | ⭐ | +| `HTTP_ALLOWED` | 允許 HTTP | `false` | | +| `TRUST_PROXY` | 信任反向代理 | `false` | | +| `ACCOUNT_REGISTRATION` | 允許註冊 | `true` | | +| `ALLOW_UNAUTHENTICATED` | 允許匿名 | `false` | | + +### 🌐 一般設定 + +| 變數 | 說明 | 預設值 | +| --------------------------- | ---------------- | ------- | +| `TZ` | 時區 | `UTC` | +| `AUTO_DELETE_EVERY_N_HOURS` | 自動刪除（小時） | `24` | +| `WEBROOT` | 子路徑前綴 | 空 | +| `HIDE_HISTORY` | 隱藏歷史紀錄 | `false` | +| `LANGUAGE` | 介面語言 | `auto` | + +### ⚙️ 轉換設定 + +| 變數 | 說明 | 預設值 | +| --------------------- | --------------- | ------------- | +| `MAX_CONVERT_PROCESS` | 最大同時轉換數 | `0`（無限制） | +| `FFMPEG_ARGS` | FFmpeg 輸入參數 | 空 | +| `FFMPEG_OUTPUT_ARGS` | FFmpeg 輸出參數 | 空 | + +### 📄 PDF 翻譯設定 + +| 變數 | 說明 | 預設值 | +| ------------------------------ | -------- | --------- | +| `PDFMATHTRANSLATE_SERVICE` | 翻譯服務 | `google` | +| `PDFMATHTRANSLATE_MODELS_PATH` | 模型路徑 | `/models` | --- -## 必填設定 +## 🔒 必填設定 ### JWT_SECRET diff --git a/package.json b/package.json index 9dab057..f100e40 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "convertx-frontend", - "version": "0.1.14", + "version": "0.1.16", "scripts": { "dev": "bun run --watch src/index.tsx", "hot": "bun run --hot src/index.tsx",