feat: 新增 OCRmyPDF 轉換引擎 (v0.1.14)

## 新功能 - OCRmyPDF 轉換引擎：將掃描版 PDF 轉換為可搜尋 PDF - 支援 7 種語言：en, zh-TW, zh, ja, ko, de, fr - 與 PDFMathTranslate 風格一致的 UI 格式 (pdf-<lang>) - 自動偵測頁面方向並旋轉 - 自動校正傾斜 - 跳過已有文字層的頁面 - 詳細的 5 階段處理進度輸出 ## 建置 - Dockerfile：安裝 ocrmypdf 與 Tesseract OCR 語言包 ## 文件 - 更新 OCR 功能文件 - 文件目錄結構改為中文名稱 ## 測試 - 修復 BabelDOC 和 PDFMathTranslate 測試的 OCR mock - 所有 345 個測試通過
2026-01-23 16:28:33 +08:00 · 2026-01-23 16:28:33 +08:00 · a06df23b1d
commit a06df23b1d
parent f24eec070c
53 changed files with 1427 additions and 675 deletions
--- a/docs/快速入門/常見問題.md
+++ b/docs/快速入門/常見問題.md
@ -0,0 +1,192 @@
+# 常見問題 FAQ
+
+---
+
+## 🔐 登入與帳號
+
+### Q: 如何註冊帳號？
+
+首次訪問 ConvertX-CN 時：
+
+1. 開啟 `http://localhost:3000`
+2. 點擊右上角 **Register**
+3. 輸入 Email 和密碼
+4. 完成！系統會自動登入
+
+> ✅ **預設開放註冊**，無需設定任何環境變數
+
+### Q: 可以關閉公開註冊嗎？
+
+可以。如果您想限制只有現有用戶可使用：
+
+```yaml
+environment:
+  - ACCOUNT_REGISTRATION=false
+```
+
+> ⚠️ 請確保您已經有至少一個帳號，否則將無法登入
+
+### Q: 忘記密碼怎麼辦？
+
+目前版本尚未提供密碼重設功能。您可以：
+
+1. 刪除 `data/convertx.db`
+2. 重新啟動容器
+3. 重新註冊
+
+> ⚠️ 這會刪除所有用戶資料和轉換歷史
+
+### Q: 登入後又被踢回登入頁？
+
+這通常是 Cookie 設定問題。請檢查：
+
+1. **沒有 HTTPS 但 HTTP_ALLOWED=false**
+
+   ```yaml
+   - HTTP_ALLOWED=true # 允許 HTTP 連線
+   ```
+
+2. **使用反向代理但沒設定 TRUST_PROXY**
+
+   ```yaml
+   - TRUST_PROXY=true # 信任反向代理
+   ```
+
+3. **沒有設定 JWT_SECRET**
+   ```yaml
+   - JWT_SECRET=固定的隨機字串
+   ```
+
+---
+
+## 🐳 Docker 相關
+
+### Q: 為什麼 Image 這麼大（4-6 GB）？
+
+ConvertX-CN 是「完整版」，內建：
+
+- LibreOffice（文件轉換）
+- TexLive（LaTeX 支援）
+- FFmpeg（影音轉換）
+- Tesseract + 多語言 OCR
+- CJK 字型
+
+如果您只需要基本功能，可使用原作者的輕量版：`ghcr.io/c4illin/convertx:latest`
+
+### Q: Docker 啟動失敗？
+
+常見原因：
+
+1. **Port 被占用**：改用其他 port，如 `-p 3001:3000`
+2. **磁碟空間不足**：Image 需約 6GB
+3. **權限問題**：確保 `./data` 資料夾有寫入權限
+
+```bash
+chmod -R 777 ./data
+```
+
+### Q: 資料存在哪裡？
+
+所有資料存放在掛載的 `/app/data` 目錄：
+
+```
+./data/
+├── convertx.db  # SQLite 資料庫
+├── uploads/     # 上傳的原始檔案
+└── output/      # 轉換後的檔案
+```
+
+### Q: 如何備份資料？
+
+直接備份 `./data` 資料夾：
+
+```bash
+tar -czvf convertx-backup.tar.gz ./data
+```
+
+### Q: 如何更新版本？
+
+```bash
+docker compose pull
+docker compose up -d
+```
+
+---
+
+## 🌍 語言相關
+
+### Q: 如何切換介面語言？
+
+1. 點擊右上角語言圖示 🌐
+2. 從下拉選單選擇語言
+3. 頁面自動更新
+
+語言偏好會儲存在 Cookie 中。
+
+### Q: 支援哪些語言？
+
+目前支援 65 種語言，包含：
+
+- 繁體中文、簡體中文
+- 日文、韓文
+- 英文、德文、法文
+- 更多詳見 [多語言支援](../功能說明/多語言.md)
+
+---
+
+## 📄 轉換相關
+
+### Q: 支援哪些格式？
+
+1000+ 種格式，詳見 [支援的轉換器](../功能說明/轉換器.md)
+
+### Q: 轉換失敗怎麼辦？
+
+1. 檢查檔案是否損壞
+2. 檢查容器日誌：`docker logs convertx-cn`
+3. 嘗試不同的轉換引擎
+
+### Q: 檔案大小有限制嗎？
+
+預設無限制，但可透過反向代理設定限制：
+
+```nginx
+client_max_body_size 500M;
+```
+
+### Q: 轉換很慢怎麼辦？
+
+1. 增加容器記憶體限制
+2. 考慮使用硬體加速（GPU）
+3. 限制同時轉換數量：
+   ```yaml
+   - MAX_CONVERT_PROCESS=2
+   ```
+
+---
+
+## 🔧 進階問題
+
+### Q: 如何使用反向代理？
+
+詳見 [反向代理設定](../部署指南/反向代理.md)
+
+### Q: 如何啟用硬體加速？
+
+詳見 [進階配置 - 硬體加速](../部署指南/Docker.md#硬體加速)
+
+### Q: 如何啟用 API Server？
+
+```bash
+docker compose --profile api up -d
+```
+
+詳見 [API 文件](../API/總覽.md)
+
+---
+
+## 還有問題？
+
+- 📖 查看 [完整文件](../README.md)
+- 🐛 回報問題：[GitHub Issues](https://github.com/pi-docket/ConvertX-CN/issues)
+- 💬 討論區：[GitHub Discussions](https://github.com/pi-docket/ConvertX-CN/discussions)
--- a/docs/快速入門/快速開始.md
+++ b/docs/快速入門/快速開始.md
@ -0,0 +1,144 @@
+# 快速開始
+
+5 分鐘內完成 ConvertX-CN 部署。
+
+---
+
+## 前置需求
+
+- Docker 20.10+（[安裝指南](https://docs.docker.com/get-docker/)）
+- 4GB+ 記憶體
+- 10GB+ 磁碟空間
+
+---
+
+## 方法一：Docker Run（最快）
+
+### 1. 建立資料夾
+
+```bash
+# Linux / macOS
+mkdir -p ~/convertx-cn/data && cd ~/convertx-cn
+
+# Windows PowerShell
+mkdir C:\convertx-cn\data; cd C:\convertx-cn
+
+# Windows CMD
+mkdir C:\convertx-cn\data
+cd C:\convertx-cn
+```
+
+### 2. 啟動容器
+
+```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
+```
+
+### 3. 開始使用
+
+開啟瀏覽器訪問：`http://localhost:3000`
+
+1. 點擊右上角 **Register** 註冊帳號
+2. 輸入 Email 和密碼
+3. 完成！開始轉換檔案
+
+---
+
+## 方法二：Docker Compose（推薦）
+
+### 1. 建立專案資料夾
+
+```bash
+mkdir -p ~/convertx-cn && cd ~/convertx-cn
+```
+
+### 2. 建立配置檔
+
+建立 `docker-compose.yml`：
+
+```yaml
+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=請更換為一個長且隨機的字串
+```
+
+### 3. 啟動服務
+
+```bash
+docker compose up -d
+```
+
+---
+
+## 驗證安裝
+
+### 檢查容器狀態
+
+```bash
+docker ps
+# 應該看到 convertx-cn 容器正在運行
+
+docker logs convertx-cn
+# 應該看到 "🦊 Elysia is running at http://localhost:3000"
+```
+
+### 健康檢查
+
+```bash
+curl http://localhost:3000/healthcheck
+# 應該返回 "OK"
+```
+
+---
+
+## 首次設定
+
+### 建立帳號
+
+首次訪問時，系統會顯示註冊頁面。第一個註冊的帳號即為管理員。
+
+### 關閉公開註冊
+
+如果只有您使用，建議關閉公開註冊：
+
+```yaml
+environment:
+  - ACCOUNT_REGISTRATION=false
+```
+
+---
+
+## 常見啟動問題
+
+| 問題               | 解決方法                                       |
+| ------------------ | ---------------------------------------------- |
+| Port 被占用        | 改用其他 port，如 `-p 8080:3000`               |
+| 登入後被踢回登入頁 | 加上 `HTTP_ALLOWED=true` 或 `TRUST_PROXY=true` |
+| 重啟後被登出       | 設定固定的 `JWT_SECRET`                        |
+| 重啟後資料消失     | 確認 `./data:/app/data` 且資料夾存在           |
+| 權限錯誤           | 執行 `chmod -R 777 ./data`                     |
+
+---
+
+## 下一步
+
+- 📖 [Docker 詳細配置](../部署指南/Docker.md)
+- ⚙️ [環境變數設定](../配置設定/環境變數.md)
+- 🔒 [安全性設定](../配置設定/安全性.md)
+- 🔧 [反向代理設定](../部署指南/反向代理.md)
--- a/docs/快速入門/概覽.md
+++ b/docs/快速入門/概覽.md
@ -0,0 +1,83 @@
+# ConvertX-CN 概覽
+
+ConvertX-CN 是一個功能完整的自託管檔案轉換平台，支援 1000+ 種格式轉換。
+
+---
+
+## 什麼是 ConvertX-CN？
+
+ConvertX-CN 是 fork 自 [C4illin/ConvertX](https://github.com/C4illin/ConvertX) 的增強版本，針對中文使用者與亞洲地區需求進行優化：
+
+- **完整的轉換能力**：整合 20+ 種轉換引擎
+- **中文優化**：內建 CJK 字型、OCR 語言包
+- **一鍵部署**：Docker 容器化，無需安裝依賴
+- **多語言介面**：支援 65 種語言
+
+---
+
+## 核心功能
+
+### 📄 文件轉換
+
+| 引擎        | 用途         | 格式數 |
+| ----------- | ------------ | ------ |
+| LibreOffice | 辦公文件     | 60+    |
+| Pandoc      | 標記語言文件 | 100+   |
+| Calibre     | 電子書       | 40+    |
+| XeLaTeX     | LaTeX 文件   | 1      |
+
+### 🖼️ 圖片處理
+
+| 引擎        | 用途         | 格式數 |
+| ----------- | ------------ | ------ |
+| ImageMagick | 圖片轉換     | 200+   |
+| Vips        | 高效圖片處理 | 45+    |
+| Inkscape    | 向量圖形     | 20+    |
+| Potrace     | 點陣轉向量   | 11     |
+
+### 🎬 影音轉換
+
+| 引擎   | 用途     | 格式數 |
+| ------ | -------- | ------ |
+| FFmpeg | 影音轉換 | 400+   |
+
+### 🔬 進階功能
+
+| 引擎             | 用途             |
+| ---------------- | ---------------- |
+| MinerU           | PDF → Markdown   |
+| PDFMathTranslate | PDF 公式翻譯保留 |
+| Tesseract OCR    | 光學字元辨識     |
+
+---
+
+## 系統需求
+
+| 需求     | 最低   | 建議   |
+| -------- | ------ | ------ |
+| Docker   | 20.10+ | 24.0+  |
+| RAM      | 4 GB   | 8 GB   |
+| 磁碟空間 | 10 GB  | 20 GB  |
+| CPU      | 2 核心 | 4 核心 |
+
+---
+
+## 與原版差異
+
+| 功能     | ConvertX | ConvertX-CN          |
+| -------- | -------- | -------------------- |
+| 鏡像大小 | ~2 GB    | ~4-6 GB              |
+| OCR 語言 | 英文     | 中日韓英德法         |
+| CJK 字型 | ❌       | ✅ Noto CJK + 標楷體 |
+| TexLive  | 基本     | 完整                 |
+| 繁中介面 | ❌       | ✅ 預設              |
+| MinerU   | ❌       | ✅                   |
+| PDF 翻譯 | ❌       | ✅ PDFMathTranslate  |
+
+---
+
+## 下一步
+
+- 🚀 [快速開始](快速開始.md) — 5 分鐘內完成部署
+- ❓ [常見問題](常見問題.md) — 解決常見問題
+- 📦 [Docker 部署](../部署指南/Docker.md) — 詳細部署指南