Your Name 27ffdee6f4 fix: Docker image size and add download retry mechanism

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

2026-01-24 21:31:11 +08:00

6.7 KiB

Raw Blame History

Docker 部署指南

本文件說明如何使用 Docker 部署 ConvertX-CN。

💡 Lite 版：如果您只需要基本轉檔功能，可以使用 Lite 版，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 版部署指南

擴充版（Extended）- 自行建構

Dockerfile： Dockerfile.full

Image 大小：>10 GB

使用 Dockerfile.full 自行建構，適合需要：

✅ 65 種 OCR 語言（完整 Tesseract 語言包）
✅ 完整 TexLive（所有排版套件）
✅ 額外字型套件

docker build -f Dockerfile.full -t convertx-cn-extended .

⚠️ 注意：Image 大小可能超過 10GB，Build 時間約 30-60 分鐘

Docker Run

基本啟動

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`	時區設定

進階選項

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：

mkdir -p ~/convertx-cn/data

Windows PowerShell：

mkdir C:\convertx-cn\data

備份與還原

備份：

tar -czvf convertx-backup-$(date +%Y%m%d).tar.gz ./data

還原：

tar -xzvf convertx-backup-20260120.tar.gz

硬體加速

NVIDIA GPU (CUDA/NVENC)

安裝 NVIDIA Container Toolkit
Docker Compose 配置：

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)

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

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

資源限制

記憶體限制

services:
  convertx:
    deploy:
      resources:
        limits:
          memory: 4G
        reservations:
          memory: 2G

CPU 限制

services:
  convertx:
    deploy:
      resources:
        limits:
          cpus: "2"

版本更新

1. 拉取最新版本：

docker pull convertx/convertx-cn:latest

2. 停止並移除舊容器：

docker stop convertx-cn
docker rm convertx-cn

3. 重新啟動（使用相同的參數）：

docker run -d --name convertx-cn ...

或使用 Docker Compose：

docker compose pull
docker compose up -d

疑難排解

查看日誌

docker logs convertx-cn

持續追蹤日誌：

docker logs -f convertx-cn

進入容器

docker exec -it convertx-cn /bin/bash

常見問題

問題	解決方法
啟動失敗	檢查日誌 `docker logs`
Port 被占用	改用其他 port `-p 8080:3000`
權限錯誤	`chmod -R 777 ./data`
記憶體不足	增加記憶體限制或減少同時轉換數

6.7 KiB Raw Blame History Unescape Escape