convertx/convertx-cn

!https://github.com/pi-docket/ConvertX-CN/raw/main/images/logo.png

ConvertX-CN

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

!Docker Image Size (Latest Lite)>)

---

為什麼選擇 ConvertX-CN？

---

📚 文件目錄

完整文件請參閱 https://github.com/pi-docket/ConvertX-CN/blob/main/docs/00-%E5%B0%88%E6%A1%88%E7%B8%BD%E8%A6%BD.md

---

🚀 快速開始

步驟 1：建立 .env 檔案

⚠️ 必須先設定 JWT_SECRET，這是系統運作的必要條件

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

# 產生 .env 檔案
cat > .env << 'EOF'
# JWT 密鑰（必須設定！建議 32+ 字元）
JWT_SECRET=你的隨機密鑰請更換成自己的字串

# 時區
TZ=Asia/Taipei

# ========== 進階設定（選填）==========

# MinerU 處理模式：pipeline（預設）或 vlm
# MINERU_MODE=pipeline

# BabelDOC 翻譯引擎：local（預設）、openai、deepseek、custom
# BABELDOC_ENGINE=local

# API Keys（如需使用 OpenAI/DeepSeek 翻譯）
# OPENAI_API_KEY=sk-...
# DEEPSEEK_API_KEY=sk-...
EOF

# 產生安全的 JWT_SECRET（擇一執行）
# Linux/macOS:
# sed -i "s/你的隨機密鑰請更換成自己的字串/$(openssl rand -base64 32)/" .env
# Windows PowerShell:
# (Get-Content .env) -replace '你的隨機密鑰請更換成自己的字串', [Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Maximum 256 })) | Set-Content .env

步驟 2：Docker Compose（推薦）

bash
# 建立資料目錄
mkdir -p data

# 建立 docker-compose.yml
cat > docker-compose.yml << 'EOF'
services:
  convertx:
    image: convertx/convertx-cn:latest
    container_name: convertx-cn
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - ./data:/app/data
    env_file:
      - .env
EOF

# 啟動服務
docker compose up -d

開啟瀏覽器：http://localhost:3000

或使用 Docker Run

bash
docker run -d \
  --name convertx-cn \
  --restart unless-stopped \
  -p 3000:3000 \
  -v ./data:/app/data \
  --env-file .env \
  convertx/convertx-cn:latest

📖 詳細說明請參閱 https://github.com/pi-docket/ConvertX-CN/blob/main/docs/%E5%BF%AB%E9%80%9F%E5%85%A5%E9%96%80/%E5%BF%AB%E9%80%9F%E9%96%8B%E5%A7%8B.md

---

🔗 線上示範

![Live Demo]([***]

🔗 [*]

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

---

⚡ 常見問題速查

更多問題 → https://github.com/pi-docket/ConvertX-CN/blob/main/docs/%E5%BF%AB%E9%80%9F%E5%85%A5%E9%96%80/%E5%B8%B8%E8%A6%8B%E5%95%8F%E9%A1%8C.md

---

🐳 Docker vs Host 環境

為什麼推薦使用 Docker？

Host 環境常見問題

如果在 Host 環境（非 Docker）執行時看到以下錯誤：

llama-server: error while loading shared libraries: libmtmd.so.0
cannot open shared object file: No such file or directory

這是因為：

• llama-server 是 llama.cpp 編譯產生的執行檔
• libmtmd.so 是多模態支援的動態連結庫，需要與 llama-server 一起編譯
• Host 環境通常沒有這些預編譯的動態庫

解決方案（擇一）：

1. 使用 Docker（推薦）

   bash
   docker pull convertx/convertx-cn:latest
   

2. 從源碼編譯 llama.cpp

   bash
   git clone https://github.com/ggml-org/llama.cpp
   cd llama.cpp
   cmake -B build -DLLAMA_SERVER=ON
   cmake --build build
   # 複製執行檔和動態庫
   sudo cp build/bin/llama-server /usr/local/bin/
   sudo cp build/lib/*.so* /usr/local/lib/
   sudo ldconfig
   

3. 使用 pipeline 模式（不需要 llama-server）

   bash
   MINERU_BACKEND=pipeline
   

ℹ️ 系統會自動偵測 llama-server 的可用性，若無法啟動會自動回退到 pipeline 模式

---

📦 支援格式

完整列表 → https://github.com/pi-docket/ConvertX-CN/blob/main/docs/%E5%8A%9F%E8%83%BD%E8%AA%AA%E6%98%8E/%E8%BD%89%E6%8F%9B%E5%99%A8.md

---

🖼️ 預覽

!https://github.com/pi-docket/ConvertX-CN/raw/main/images/preview.png

---

🔄 更新

bash
docker compose down
docker compose pull
docker compose up -d

---

🎯 版本選擇：Lite / 一般版 / Full

ConvertX-CN 提供三個版本，滿足不同需求：

版本標籤

Lite 版快速啟動

bash
# 1. 建立 .env
mkdir -p ~/convertx-lite && cd ~/convertx-lite
cat > .env << 'EOF'
JWT_SECRET=你的隨機密鑰請更換成自己的字串
TZ=Asia/Taipei
ALLOW_UNAUTHENTICATED=true
EOF

# 2. 建立資料目錄並啟動
mkdir -p data
docker run -d \
  --name convertx-cn-lite \
  -p 3000:3000 \
  -v ./data:/app/data \
  --env-file .env \
  convertx/convertx-cn:latest-lite

📖 詳細說明請參閱 https://github.com/pi-docket/ConvertX-CN/blob/main/docs/02-%E9%83%A8%E7%BD%B2%E6%8C%87%E5%8D%97.md

---

🙏 致謝

本專案基於 https://github.com/C4illin/ConvertX 開發，感謝原作者的貢獻。