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,290 @@
+# 反向代理設定
+
+本文件說明如何在 Nginx、Traefik、Caddy 等反向代理後部署 ConvertX-CN。
+
+---
+
+## 必要環境變數
+
+透過反向代理存取時，請設定：
+
+- `TRUST_PROXY=true` — 信任 X-Forwarded-\* headers
+- `HTTP_ALLOWED=false` — Proxy 已處理 HTTPS
+
+```yaml
+environment:
+  - TRUST_PROXY=true
+  - HTTP_ALLOWED=false
+```
+
+---
+
+## Nginx
+
+### 基本配置
+
+```nginx
+# /etc/nginx/sites-available/convertx
+server {
+    listen 80;
+    server_name convertx.example.com;
+    return 301 https://$server_name$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name convertx.example.com;
+
+    # SSL 憑證（Let's Encrypt）
+    ssl_certificate /etc/letsencrypt/live/convertx.example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/convertx.example.com/privkey.pem;
+
+    # SSL 安全設定
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_prefer_server_ciphers on;
+    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
+
+    # 檔案上傳大小限制
+    client_max_body_size 500M;
+
+    # 超時設定（大檔案轉換需要）
+    proxy_read_timeout 3600s;
+    proxy_send_timeout 3600s;
+
+    location / {
+        proxy_pass http://127.0.0.1:3000;
+        proxy_http_version 1.1;
+
+        # 必要的 headers
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        # WebSocket 支援
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+    }
+}
+```
+
+### 啟用設定
+
+```bash
+sudo ln -s /etc/nginx/sites-available/convertx /etc/nginx/sites-enabled/
+sudo nginx -t
+sudo systemctl reload nginx
+```
+
+---
+
+## Traefik
+
+### Docker Labels 方式
+
+```yaml
+# docker-compose.yml
+services:
+  convertx:
+    image: convertx/convertx-cn:latest
+    container_name: convertx-cn
+    restart: unless-stopped
+    volumes:
+      - ./data:/app/data
+    environment:
+      - JWT_SECRET=${JWT_SECRET}
+      - TRUST_PROXY=true
+      - HTTP_ALLOWED=false
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.convertx.rule=Host(`convertx.example.com`)"
+      - "traefik.http.routers.convertx.entrypoints=websecure"
+      - "traefik.http.routers.convertx.tls=true"
+      - "traefik.http.routers.convertx.tls.certresolver=letsencrypt"
+      - "traefik.http.services.convertx.loadbalancer.server.port=3000"
+    networks:
+      - traefik-network
+
+networks:
+  traefik-network:
+    external: true
+```
+
+### 動態配置檔
+
+```yaml
+# traefik/dynamic/convertx.yml
+http:
+  routers:
+    convertx:
+      rule: "Host(`convertx.example.com`)"
+      service: convertx
+      entryPoints:
+        - websecure
+      tls:
+        certResolver: letsencrypt
+
+  services:
+    convertx:
+      loadBalancer:
+        servers:
+          - url: "http://127.0.0.1:3000"
+```
+
+---
+
+## Caddy
+
+### 基本配置
+
+```
+convertx.example.com {
+    reverse_proxy localhost:3000 {
+        header_up X-Real-IP {remote_host}
+        header_up X-Forwarded-Proto {scheme}
+    }
+
+    request_body {
+        max_size 500MB
+    }
+}
+```
+
+### 子路徑部署
+
+```
+example.com {
+    handle_path /convertx/* {
+        reverse_proxy localhost:3000
+    }
+}
+```
+
+記得設定環境變數：
+
+```yaml
+environment:
+  - WEBROOT=/convertx
+```
+
+---
+
+## Cloudflare Tunnel
+
+### 1. 建立 Tunnel
+
+```bash
+cloudflared tunnel create convertx
+```
+
+### 2. 配置
+
+```yaml
+# ~/.cloudflared/config.yml
+tunnel: <tunnel-id>
+credentials-file: ~/.cloudflared/<tunnel-id>.json
+
+ingress:
+  - hostname: convertx.example.com
+    service: http://localhost:3000
+  - service: http_status:404
+```
+
+### 3. 啟動
+
+```bash
+cloudflared tunnel run convertx
+```
+
+### 4. 環境變數
+
+```yaml
+environment:
+  - TRUST_PROXY=true
+  - HTTP_ALLOWED=false
+```
+
+---
+
+## 子路徑部署
+
+如需在子路徑部署（如 `https://example.com/convertx`）：
+
+### 1. 設定環境變數
+
+```yaml
+environment:
+  - WEBROOT=/convertx
+```
+
+### 2. Nginx 配置
+
+```nginx
+location /convertx/ {
+    proxy_pass http://localhost:3000/;
+    # ... 其他 proxy 設定
+}
+```
+
+### 3. Caddy 配置
+
+```
+example.com {
+    handle_path /convertx/* {
+        reverse_proxy localhost:3000
+    }
+}
+```
+
+---
+
+## HTTPS 憑證
+
+### Let's Encrypt（推薦）
+
+使用 Certbot 自動取得憑證：
+
+```bash
+sudo apt install certbot python3-certbot-nginx
+sudo certbot --nginx -d convertx.example.com
+```
+
+### 自簽憑證（測試用）
+
+```bash
+openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
+  -keyout /etc/nginx/ssl/convertx.key \
+  -out /etc/nginx/ssl/convertx.crt
+```
+
+---
+
+## 疑難排解
+
+### 登入後被踢回登入頁
+
+1. 確認 `TRUST_PROXY=true`
+2. 確認反向代理正確傳送 `X-Forwarded-Proto` header
+
+### 上傳檔案失敗
+
+1. 調高 `client_max_body_size`（Nginx）
+2. 調高 `request_body max_size`（Caddy）
+3. 調高超時設定
+
+### WebSocket 連線失敗
+
+確認反向代理正確處理 WebSocket：
+
+```nginx
+proxy_set_header Upgrade $http_upgrade;
+proxy_set_header Connection "upgrade";
+```
+
+---
+
+## 相關文件
+
+- [Docker 部署](docker.md)
+- [安全性設定](../configuration/security.md)
+- [環境變數](../configuration/environment-variables.md)