27ffdee6f4
## 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
321 lines
6.7 KiB
Markdown
321 lines
6.7 KiB
Markdown
# Docker 部署指南
|
||
|
||
本文件說明如何使用 Docker 部署 ConvertX-CN。
|
||
|
||
> 💡 **Lite 版**：如果您只需要基本轉檔功能，可以使用 [Lite 版](Docker-Lite.md)，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` | 一般版最新穩定版 |
|
||
| `convertx/convertx-cn:latest-lite` | Lite 版最新穩定版 |
|
||
| `convertx/convertx-cn:v0.1.x` | 一般版指定版本號 |
|
||
| `convertx/convertx-cn:v0.1.x-lite` | Lite 版指定版本號 |
|
||
|
||
---
|
||
|
||
### 一般版（Standard） ⭐ 推薦
|
||
|
||
**Image Tag：** `convertx/convertx-cn:latest`
|
||
|
||
**Image 大小：約 8-12 GB**
|
||
|
||
> 💡 **開箱即用**：所有 AI 模型在 Build 階段已預下載，Runtime 不需要網路即可使用所有功能。
|
||
|
||
**內建功能：**
|
||
|
||
- ✅ 核心轉換工具（FFmpeg、LibreOffice、ImageMagick 等）
|
||
- ✅ OCR 支援：英文、繁/簡中文、日文、韓文、德文、法文（7 種語言）
|
||
- ✅ PDF 翻譯：PDFMathTranslate、BabelDOC
|
||
- ✅ PDF 轉 Markdown：MinerU
|
||
- ✅ 字型：Noto CJK、Liberation、Source Han Serif
|
||
- ✅ TexLive（支援 CJK/德/法）
|
||
- ✅ 電子書轉換（Calibre）
|
||
- ✅ CAD/3D 支援（assimp）
|
||
|
||
---
|
||
|
||
### Lite 版（Lightweight）
|
||
|
||
**Image Tag：** `convertx/convertx-cn:latest-lite`
|
||
|
||
**Image 大小：約 1.2-1.5 GB**
|
||
|
||
**內建功能：**
|
||
|
||
- ✅ 核心轉換工具（FFmpeg、LibreOffice、GraphicsMagick）
|
||
- ✅ 文件轉換（Pandoc）
|
||
- ✅ PDF/A 轉換、PDF 防修改、PDF 數位簽章
|
||
- ✅ 基本 CJK 字型
|
||
- ❌ 不含 OCR、AI 翻譯、MinerU、Calibre
|
||
|
||
> 📖 Lite 版詳細說明請參閱 [Lite 版部署指南](Docker-Lite.md)
|
||
|
||
---
|
||
|
||
### 擴充版（Extended）- 自行建構
|
||
|
||
**Dockerfile：** `Dockerfile.full`
|
||
|
||
**Image 大小：>10 GB**
|
||
|
||
使用 `Dockerfile.full` 自行建構，適合需要：
|
||
|
||
- ✅ 65 種 OCR 語言（完整 Tesseract 語言包）
|
||
- ✅ 完整 TexLive（所有排版套件）
|
||
- ✅ 額外字型套件
|
||
|
||
```bash
|
||
docker build -f Dockerfile.full -t convertx-cn-extended .
|
||
```
|
||
|
||
> ⚠️ 注意：Image 大小可能超過 **10GB**，Build 時間約 **30-60 分鐘**
|
||
|
||
---
|
||
|
||
## Docker Run
|
||
|
||
### 基本啟動
|
||
|
||
```bash
|
||
docker run -d \
|
||
--name convertx-cn \
|
||
--restart unless-stopped \
|
||
-p 3000:3000 \
|
||
-v ./data:/app/data \
|
||
-e TZ=Asia/Taipei \
|
||
-e JWT_SECRET=你的隨機字串至少32字元 \
|
||
convertx/convertx-cn:latest
|
||
```
|
||
|
||
### 參數說明
|
||
|
||
| 參數 | 說明 |
|
||
| -------------------------- | ---------- |
|
||
| `-d` | 背景執行 |
|
||
| `--name convertx-cn` | 容器名稱 |
|
||
| `--restart unless-stopped` | 自動重啟 |
|
||
| `-p 3000:3000` | 連接埠映射 |
|
||
| `-v ./data:/app/data` | 資料持久化 |
|
||
| `-e TZ=Asia/Taipei` | 時區設定 |
|
||
|
||
### 進階選項
|
||
|
||
```bash
|
||
docker run -d \
|
||
--name convertx-cn \
|
||
--restart unless-stopped \
|
||
-p 3000:3000 \
|
||
-v ./data:/app/data \
|
||
-e TZ=Asia/Taipei \
|
||
-e JWT_SECRET=你的隨機字串 \
|
||
-e ACCOUNT_REGISTRATION=false \
|
||
-e HTTP_ALLOWED=true \
|
||
-e AUTO_DELETE_EVERY_N_HOURS=24 \
|
||
convertx/convertx-cn:latest
|
||
```
|
||
|
||
---
|
||
|
||
## 資料持久化
|
||
|
||
### Volume 結構
|
||
|
||
```
|
||
./data/
|
||
├── convertx.db # SQLite 資料庫
|
||
├── uploads/ # 上傳的原始檔案
|
||
└── output/ # 轉換後的檔案
|
||
```
|
||
|
||
### 建立資料夾
|
||
|
||
**重要**：請務必先建立資料夾，否則 Docker 會建立匿名 volume。
|
||
|
||
**Linux / macOS：**
|
||
|
||
```bash
|
||
mkdir -p ~/convertx-cn/data
|
||
```
|
||
|
||
**Windows PowerShell：**
|
||
|
||
```powershell
|
||
mkdir C:\convertx-cn\data
|
||
```
|
||
|
||
### 備份與還原
|
||
|
||
**備份：**
|
||
|
||
```bash
|
||
tar -czvf convertx-backup-$(date +%Y%m%d).tar.gz ./data
|
||
```
|
||
|
||
**還原：**
|
||
|
||
```bash
|
||
tar -xzvf convertx-backup-20260120.tar.gz
|
||
```
|
||
|
||
---
|
||
|
||
## 硬體加速
|
||
|
||
### NVIDIA GPU (CUDA/NVENC)
|
||
|
||
1. 安裝 [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html)
|
||
|
||
2. Docker Compose 配置：
|
||
|
||
```yaml
|
||
services:
|
||
convertx:
|
||
image: convertx/convertx-cn:latest
|
||
deploy:
|
||
resources:
|
||
reservations:
|
||
devices:
|
||
- driver: nvidia
|
||
count: all
|
||
capabilities: [gpu]
|
||
environment:
|
||
- FFMPEG_ARGS=-hwaccel cuda -hwaccel_output_format cuda
|
||
- FFMPEG_OUTPUT_ARGS=-c:v h264_nvenc -preset fast
|
||
```
|
||
|
||
### Intel Quick Sync Video (QSV)
|
||
|
||
```yaml
|
||
services:
|
||
convertx:
|
||
image: convertx/convertx-cn:latest
|
||
devices:
|
||
- /dev/dri:/dev/dri
|
||
environment:
|
||
- FFMPEG_ARGS=-hwaccel qsv
|
||
- FFMPEG_OUTPUT_ARGS=-c:v h264_qsv -preset faster
|
||
```
|
||
|
||
### AMD VAAPI
|
||
|
||
```yaml
|
||
services:
|
||
convertx:
|
||
image: convertx/convertx-cn:latest
|
||
devices:
|
||
- /dev/dri:/dev/dri
|
||
environment:
|
||
- FFMPEG_ARGS=-hwaccel vaapi -hwaccel_device /dev/dri/renderD128
|
||
- FFMPEG_OUTPUT_ARGS=-c:v h264_vaapi
|
||
```
|
||
|
||
---
|
||
|
||
## 資源限制
|
||
|
||
### 記憶體限制
|
||
|
||
```yaml
|
||
services:
|
||
convertx:
|
||
deploy:
|
||
resources:
|
||
limits:
|
||
memory: 4G
|
||
reservations:
|
||
memory: 2G
|
||
```
|
||
|
||
### CPU 限制
|
||
|
||
```yaml
|
||
services:
|
||
convertx:
|
||
deploy:
|
||
resources:
|
||
limits:
|
||
cpus: "2"
|
||
```
|
||
|
||
---
|
||
|
||
## 版本更新
|
||
|
||
**1. 拉取最新版本：**
|
||
|
||
```bash
|
||
docker pull convertx/convertx-cn:latest
|
||
```
|
||
|
||
**2. 停止並移除舊容器：**
|
||
|
||
```bash
|
||
docker stop convertx-cn
|
||
docker rm convertx-cn
|
||
```
|
||
|
||
**3. 重新啟動（使用相同的參數）：**
|
||
|
||
```bash
|
||
docker run -d --name convertx-cn ...
|
||
```
|
||
|
||
或使用 Docker Compose：
|
||
|
||
```bash
|
||
docker compose pull
|
||
docker compose up -d
|
||
```
|
||
|
||
---
|
||
|
||
## 疑難排解
|
||
|
||
### 查看日誌
|
||
|
||
```bash
|
||
docker logs convertx-cn
|
||
```
|
||
|
||
持續追蹤日誌：
|
||
|
||
```bash
|
||
docker logs -f convertx-cn
|
||
```
|
||
|
||
### 進入容器
|
||
|
||
```bash
|
||
docker exec -it convertx-cn /bin/bash
|
||
```
|
||
|
||
### 常見問題
|
||
|
||
| 問題 | 解決方法 |
|
||
| ----------- | ------------------------------ |
|
||
| 啟動失敗 | 檢查日誌 `docker logs` |
|
||
| Port 被占用 | 改用其他 port `-p 8080:3000` |
|
||
| 權限錯誤 | `chmod -R 777 ./data` |
|
||
| 記憶體不足 | 增加記憶體限制或減少同時轉換數 |
|
||
|
||
---
|
||
|
||
## 相關文件
|
||
|
||
- [Docker Compose 詳解](Docker組合.md)
|
||
- [反向代理設定](反向代理.md)
|
||
- [環境變數設定](../配置設定/環境變數.md)
|