convertor/README.md

ConvertX-CN

開箱即用的全功能檔案轉換服務 | Self-hosted File Converter - Full Edition

---

✨ 什麼是 ConvertX-CN？

ConvertX-CN 是基於 C4illin/ConvertX 的完整版 Fork，專為中文使用者優化，並預載所有轉換依賴。

🎉 一鍵部署，無需額外配置
使用者 不需要自己寫 Dockerfile，直接 docker run 或 docker compose up 即可使用。

主要特色

特色	說明
🌍 65+ 語言支援	繁體中文、簡體中文、英文、日文、韓文等 65 種語言
📦 完整內建	LibreOffice、FFmpeg、Pandoc、Calibre 等 20+ 轉換器
🎨 CJK 字型	Noto CJK、微軟核心字型、標楷體等中日韓字型
🔤 OCR 支援	Tesseract + 多語言語言包
⚡ LaTeX 完整版	TexLive Full，支援所有 LaTeX 需求
🐳 開箱即用	一個 Docker 命令即可啟動

---

📚 關於本文件

📖 本 README 定位為「新手教學入口」

我們的 docker-compose.yml 範例刻意保留完整註解，而非極簡化：

• ✅ 讓第一次用 Docker 的人也能成功部署
• ✅ 透過註解說明每個設定的意義與風險
• ✅ 避免新手踩雷（登入失敗、資料遺失等）

如果你是 Docker 老手，可直接使用 精簡版範例。

---

🚀 新手完整部署教學（一步一步）

⚠️ 請務必按順序執行，不要跳過任何步驟！

步驟 1：安裝 Docker

如果尚未安裝 Docker，請先安裝：

• Windows / macOS: 下載 Docker Desktop
• Linux: 執行 curl -fsSL https://get.docker.com | sh

步驟 2：建立 data 資料夾（⚠️ 非常重要）

🚨 這一步絕對不能跳過！

data 資料夾是用來存放：

• 📁 上傳的檔案
• 📁 轉換後的結果
• 📁 使用者資料與設定

如果不先建立這個資料夾，Docker 可能會建立「匿名 volume」，導致：

• ❌ 容器刪除後資料全部消失
• ❌ 無法在主機上找到轉換結果
• ❌ 難以備份與遷移

請根據你的作業系統執行對應指令：

Linux / macOS

# 建立專案資料夾（可自訂位置）
mkdir -p ~/convertx-cn
cd ~/convertx-cn

# 建立 data 資料夾
mkdir -p data

# 確認資料夾已建立
ls -la
# 應該看到 data 資料夾

Windows（PowerShell）

# 建立專案資料夾（可自訂位置）
mkdir C:\convertx-cn
cd C:\convertx-cn

# 建立 data 資料夾
mkdir data

# 確認資料夾已建立
dir
# 應該看到 data 資料夾

Windows（CMD）

:: 建立專案資料夾（可自訂位置）
mkdir C:\convertx-cn
cd C:\convertx-cn

:: 建立 data 資料夾
mkdir data

:: 確認資料夾已建立
dir
:: 應該看到 data 資料夾

步驟 3：建立 docker-compose.yml

在剛才建立的資料夾中，建立 docker-compose.yml 檔案：

# ==============================================================================
# ConvertX-CN 新手教學版 docker-compose.yml
#
# 📚 這份範例刻意保留完整註解，讓第一次用 Docker 的人也能成功部署
# ==============================================================================

services:
  convertx:
    # ===== 映像檔設定 =====
    # convertx-cn 是完整版，已內建所有轉換工具（約 4-6 GB）
    image: convertx/convertx-cn:latest
    container_name: convertx-cn
    restart: unless-stopped

    # ===== 連接埠設定 =====
    # 格式：「主機埠號:容器埠號」
    # 若 3000 埠已被佔用，可改為 3001:3000、8080:3000 等
    ports:
      - "3000:3000"

    # ===== 資料儲存（⚠️ 非常重要）=====
    # ./data 是你主機上的實體資料夾
    # /app/data 是容器內的路徑
    #
    # 🚨 注意事項：
    #    1. 請務必先建立 data 資料夾（見上方步驟 2）
    #    2. 這裡存放：上傳檔案、轉換結果、使用者資料
    #    3. 若改用 Docker volume（如 convertx_data:/app/data），
    #       資料會存在 Docker 內部，較難直接存取
    volumes:
      - ./data:/app/data

    # ===== 環境變數設定 =====
    environment:
      # --- 時區設定 ---
      # 影響檔案時間戳記與日期顯示
      - TZ=Asia/Taipei

      # --- JWT 密鑰（🔐 建議設定）---
      # 用於使用者登入驗證的加密金鑰
      # ⚠️ 若不設定：每次重啟容器後所有人都會被登出
      # ⚠️ 正式使用請改成你自己的隨機字串！
      - JWT_SECRET=請改成你自己的長隨機字串-至少32個字元

      # --- 帳號註冊 ---
      # true  = 允許任何人註冊新帳號
      # false = 關閉註冊（建議正式使用時設為 false）
      # 💡 首次建立的帳號不受此限制
      - ACCOUNT_REGISTRATION=true

      # --- HTTP 存取設定 ---
      # true  = 允許非 HTTPS 連線（⚠️ 不安全，僅本地測試用）
      # false = 必須 HTTPS（Cookie 才會正常運作）
      #
      # 🏠 本地測試（localhost）：設為 true
      # 🌐 遠端部署（有 HTTPS）：設為 false
      - HTTP_ALLOWED=true

      # --- Reverse Proxy 設定 ---
      # 若你透過 Nginx / Traefik / Cloudflare 等存取，設為 true
      # 讓應用正確判斷連線是否為 HTTPS
      - TRUST_PROXY=false

      # --- 未登入存取 ---
      # true  = 允許未登入使用轉換功能（⚠️ 公開服務才開）
      # false = 必須登入才能使用
      - ALLOW_UNAUTHENTICATED=false

      # --- 自動清理 ---
      # 自動刪除超過 N 小時的轉換檔案（0 = 不自動刪除）
      - AUTO_DELETE_EVERY_N_HOURS=24

步驟 4：啟動服務

# 啟動（首次會下載映像檔，約 4-6 GB，請耐心等待）
docker compose up -d

# 查看執行狀態
docker compose ps

# 查看 log（確認沒有錯誤）
docker compose logs -f
# 按 Ctrl+C 可退出 log 查看

步驟 5：開啟瀏覽器使用

1. 開啟瀏覽器，訪問 http://localhost:3000
2. 點擊 Register 註冊第一個帳號
3. 登入後即可開始轉換檔案！

✅ 首次註冊的帳號會自動成為管理員

---

⚠️ 新手常見問題與解決方案

問題 1：登入後又被導回登入頁

原因：Cookie 無法正確設定（常見於遠端部署）

解決方案：

• 若使用 HTTP（無 HTTPS）：設定 HTTP_ALLOWED=true
• 若透過 Reverse Proxy：設定 TRUST_PROXY=true

問題 2：重啟容器後資料消失

原因：沒有正確掛載 volume

解決方案：

1. 確認已建立 data 資料夾
2. 確認 docker-compose.yml 中有 ./data:/app/data
3. 不要使用 docker run 時忘記加 -v ./data:/app/data

問題 3：重啟後所有人被登出

原因：沒有設定 JWT_SECRET

解決方案：設定固定的 JWT_SECRET 環境變數

問題 4：3000 埠被佔用

解決方案：改用其他埠號，如 "8080:3000"

---

<EFBFBD> 如何更新 ConvertX-CN 版本

當有新版本發布時，請依照以下步驟更新。

使用 Docker Compose 更新（推薦）

# 1. 進入你的 ConvertX-CN 專案資料夾
cd ~/convertx-cn  # 或你當初建立的位置

# 2. 停止目前執行中的服務
docker compose down

# 3. 拉取最新的映像檔
docker compose pull

# 4. 重新啟動服務
docker compose up -d

# 5. 確認版本（查看 log）
docker compose logs | head -20

更新到指定版本

如果你想更新到特定版本（例如 v0.1.9），請修改 docker-compose.yml：

services:
  convertx:
    image: convertx/convertx-cn:v0.1.9 # 改成指定版本

然後執行：

docker compose down
docker compose pull
docker compose up -d

驗證更新成功

開啟瀏覽器訪問 http://localhost:3000，頁面底部會顯示版本號。

---

<EFBFBD>🔧 進階設定

更多進階設定請參考：docs/environment-variables.md

---

🌍 語言支援

ConvertX-CN 支援 65 種語言，包括：

區域	語言
東亞	繁體中文（預設）、简体中文、日本語、한국어
歐洲	English, Deutsch, Français, Español, Italiano 等
中東/南亞	العربية, עברית, हिन्दी, தமிழ் 等
東南亞	ไทย, Tiếng Việt, Bahasa Indonesia 等

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

---

📦 內建轉換器

轉換器	用途	支援格式數
FFmpeg	影音	400+
ImageMagick	圖片	200+
LibreOffice	文件	60+
Pandoc	文件	100+
Calibre	電子書	40+
Inkscape	向量圖	20+

完整列表 → docs/converters.md

---

🐳 Docker Image 資訊

Tag	說明
convertx/convertx-cn:latest	最新穩定版
convertx/convertx-cn:v0.1.9	指定版本

⚠️ 首次下載說明
由於內建完整依賴（LibreOffice、TexLive 等），映像檔約 4-6 GB。
首次 docker pull 需要較長時間，請耐心等待。

---

📖 更多文件

文件	說明
⚙️ 環境變數	所有環境變數完整說明
🚀 進階部署	Reverse Proxy、HTTPS、生產
🐳 Docker 進階	自訂 Build、Image 說明
📦 轉換器列表	支援的格式完整列表
❓ 常見問題	更多疑難排解
📁 Docker Compose 範例	各種情境的範例檔案

---

📸 預覽

---

🛠️ 開發者資訊

# 安裝依賴
bun install

# 開發模式
bun run dev

# 建構
bun run build

歡迎 Pull Request！請使用 Conventional Commits 格式。

---

🙏 致謝

本專案基於 C4illin/ConvertX 開發。

---

📜 License

MIT License

---

Powered by ConvertX-CN
https://github.com/pi-docket/ConvertX-CN