Elijah/convertor
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

fix: Docker image size and add download retry mechanism

Browse source 
## Bug Fixes
- Fix standard image size issue (was ~1.5GB, should be 8-12GB)
- Add strict model validation during build
- Add retry mechanism (--retry 3 --retry-delay 5) to all curl downloads

## Documentation
- Clarify version terminology: Standard (一般版), Extended (擴充版), Lite (Lite版)
- Remove duplicate docs/環境變數總覽.md
- Improve environment variable documentation structure
- Add quick reference tables for environment variables

## Build
- Explicitly specify 'file: Dockerfile' in release.yml
- Use 'buildcache-full' cache key to prevent cross-pollution
This commit is contained in:
Your Name 2026-01-24 21:31:11 +08:00
parent ee7c1da01f
commit 27ffdee6f4
8 changed files with 284 additions and 280 deletions
Download patch file Download diff file Expand all files Collapse all files

197
docs/環境變數總覽.md
View file

@ -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
```

120
docs/部署指南/Docker-Lite.md
View file

@ -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)](<https://img.shields.io/docker/image-size/convertx/convertx-cn/latest-lite?label=image%20size%20(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)](<https://img.shields.io/docker/image-size/convertx/convertx-cn/latest-lite?label=image%20size%20(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)

52
docs/部署指南/Docker.md
View file

@ -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 分鐘**

44
docs/配置設定/環境變數.md
View file

@ -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