convertor/README.md

ConvertX-CN

開箱即用的全功能檔案轉換服務 — 一個 Docker 命令，5 分鐘部署完成

---

為什麼選擇 ConvertX-CN？

• 支援 1000+ 格式（影音、圖片、文件、電子書）
• 已內建 LibreOffice、FFmpeg、Pandoc 等 20+ 轉換器
• 預載中日韓字型與 OCR 語言包
• 支援 65 種介面語言

---

線上示範

想先試用再部署？歡迎使用我們的示範站：

🔗 https://convertx-cn.bioailab.qzz.io

項目	內容
範例帳號	admin@example.com
範例密碼	admin

⚠️ 示範站僅供測試，請勿上傳敏感檔案。資料可能定期清除。

---

快速啟動（Docker Run）

1. 建立資料夾

mkdir -p ~/convertx-cn/data && cd ~/convertx-cn

2. 啟動容器

JWT_SECRET=請改成你自己的隨機字串至少32字元

docker run -d \
  --name convertx-cn \
  --restart unless-stopped \
  -p 3000:3000 \
  -v ./data:/app/data \
  -e TZ=Asia/Taipei \
  -e JWT_SECRET=e78a2da4-135f-06a8-fa46-17ef7990f5d1 \
  convertx/convertx-cn:latest

3. 開啟瀏覽器

  http://localhost:3000

首次下載約 4-6 GB，請耐心等待。

---

Docker Compose（推薦）

1. 建立專案資料夾

Linux / macOS

mkdir -p ~/convertx-cn && cd ~/convertx-cn

Windows PowerShell

mkdir C:\convertx-cn; cd C:\convertx-cn

Windows CMD

mkdir C:\convertx-cn
cd C:\convertx-cn

2. 建立 docker-compose.yml（在專案資料夾下）

• 範例內容（請修改 JWT_SECRET=請改成你自己的隨機字串至少32字元）：

services:
  convertx:
    image: convertx/convertx-cn:latest
    container_name: convertx-cn
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - ./data:/app/data
    environment:
      - TZ=Asia/Taipei
      - JWT_SECRET=e78a2da4-135f-06a8-fa46-17ef7990f5d1

3. 啟動：

docker compose up -d

更多範例 → docs/docker-compose/

---

重要：資料夾說明

./data 是你主機上的實體資料夾，用於存放上傳檔案、轉換結果與使用者資料。

作業系統	建立指令
Linux / macOS	mkdir -p ~/convertx-cn/data
Windows (PS)	mkdir C:\convertx-cn\data
Windows (CMD)	mkdir C:\convertx-cn\data

若不先建立，Docker 會建立匿名 volume，導致資料難以存取或備份。

---

必要參數

參數	說明
./data	主機資料夾，必須先建立
JWT_SECRET	登入驗證金鑰，不設會每次重啟被登出

其他環境變數 → docs/config/environment.md

---

常見問題

問題	解法
登入後又被踢回登入頁	加上 HTTP_ALLOWED=true 或 TRUST_PROXY=true
重啟後資料消失	確認 ./data:/app/data 且資料夾存在
重啟後被登出	設定固定的 JWT_SECRET

更多問題 → docs/faq.md

---

支援格式

轉換器	用途	格式數
FFmpeg	影音	400+
ImageMagick	圖片	200+
LibreOffice	文件	60+
Pandoc	文件	100+
Calibre	電子書	40+
Inkscape	向量圖	20+
MinerU	文件→MD	2
PDFMathTranslate	PDF 翻譯	15+

完整列表 → docs/converters.md

---

Dark Mode

ConvertX-CN 支援亮色與暗色主題。

• 可手動切換主題（點擊導覽列的太陽/月亮圖示）
• 偏好設定自動儲存於瀏覽器
• 預設跟隨系統色彩偏好

---

MinerU

ConvertX 內建文件轉換引擎。

• md-t（表格以 Markdown 呈現）
• md-i（表格以圖片呈現）

輸出格式：.tar（不壓縮封裝）

---

PDFMathTranslate 引擎

PDFMathTranslate 是一個內容轉換引擎，用於翻譯 PDF 文件同時保留數學公式與排版。

功能特點

• 📊 保留數學公式、圖表、目錄與註解
• 🌐 支援多種目標語言（中文、英文、日文、韓文等）
• 🤖 支援多種翻譯服務（Google、DeepL、OpenAI 等）

輸出格式

所有輸出一律打包為 .tar 檔案，包含：

• original.pdf — 原始 PDF 文件
• translated-<lang>.pdf — 翻譯後的 PDF 文件

可用的目標格式

PDFMathTranslate
├─ pdf-en    （翻譯為英文）
├─ pdf-zh    （翻譯為簡體中文）
├─ pdf-zh-TW （翻譯為繁體中文）
├─ pdf-ja    （翻譯為日文）
├─ pdf-ko    （翻譯為韓文）
├─ pdf-de    （翻譯為德文）
├─ pdf-fr    （翻譯為法文）
└─ ...

環境變數

變數	說明	預設值
PDFMATHTRANSLATE_SERVICE	翻譯服務提供商	google
PDFMATHTRANSLATE_MODELS_PATH	模型路徑	/models/pdfmathtranslate

注意事項

• 所需模型已在 Docker build 階段預先下載
• 不會在 runtime 隱式下載任何模型
• 使用 Google 翻譯為預設服務（免費），可透過環境變數切換

---

檔案傳輸機制

Contents.CN 使用統一的檔案傳輸策略：

檔案大小	傳輸方式	說明
≤ 10MB	直接傳輸	單一請求完成上傳/下載
> 10MB	分段傳輸	使用 5MB chunks 分段傳輸

多檔輸出封裝

• ✅ 唯一允許格式：.tar
• ❌ 禁止使用：.tar.gz、.tgz、.zip

設計原則

• 分段傳輸僅存在於傳輸層
• 轉換引擎只接收完整檔案
• 前後端使用共用傳輸模組

---

語言支援

支援 65 種語言，包含繁體中文、簡體中文、英文、日文、韓文等。

語言會根據瀏覽器設定自動偵測，也可透過右上角選單手動切換。

詳細說明 → docs/i18n.md

---

版本與更新

docker compose down
docker compose pull
docker compose up -d

• 版本說明 → docs/versions/
• 更新指南 → docs/deployment/update.md
• Changelog → CHANGELOG.md

---

API Server（選用）

如需以程式整合方式使用 ConvertX 的轉檔功能，可啟用 API Server。

⚠️ API Server 為選用功能，不影響現有 Web UI 的使用。若只使用網頁介面，無需任何額外設定。

功能特點

• 🔐 JWT 認證 — 安全的 API 存取控制
• 🌐 REST + GraphQL — 雙協議支援，滿足不同整合需求
• 🔍 智慧建議 — 轉換失敗時自動推薦替代引擎
• 🛠️ 20+ 轉換引擎 — 與 Web UI 共用完整轉換器套件

快速啟用

# 同時啟動 Web UI 與 API Server
docker compose --profile api up -d

服務	端口	說明
Web UI	3000	網頁介面
API Server	3001	REST & GraphQL

API 文件

詳細的 API 規格與使用說明：

• 📘 API Server README
• 📗 API 規格文件
• 📙 架構說明

---

進階文件

文件	說明
環境變數	所有可用參數
安全性設定	HTTP_ALLOWED、TRUST_PROXY
反向代理	Nginx / Traefik / Caddy
Docker 進階	自訂 Build
FAQ	疑難排解

---

預覽

---

License

MIT | 基於 C4illin/ConvertX