新增錯誤排查與支援文件，提供常見問題解決方案；新增開發與貢獻指南，說明專案結構與開發流程；新增授權說明文件，詳述AGPL-3.0授權條款及第三方元件使用情況。

2026-01-25 16:09:58 +08:00 · 2026-01-25 16:09:58 +08:00 · caecb2e001
commit caecb2e001
parent 11d751250b
13 changed files with 3269 additions and 369 deletions
--- a/docs/03-環境變數與設定.md
+++ b/docs/03-環境變數與設定.md
@ -0,0 +1,444 @@
+# 環境變數與設定
+
+本文件詳細說明 ConvertX-CN 所有可用的環境變數與配置選項。
+
+---
+
+## 目錄
+
+- [必填設定](#必填設定)
+- [網路與安全](#網路與安全)
+- [一般設定](#一般設定)
+- [轉換設定](#轉換設定)
+- [PDF 翻譯設定](#pdf-翻譯設定)
+- [推薦配置範例](#推薦配置範例)
+- [安全性建議](#安全性建議)
+
+---
+
+## 快速參考表
+
+### 🔒 安全性設定
+
+| 變數 | 必要性 | 說明 | 預設值 | 範例 |
+|------|--------|------|--------|------|
+| `JWT_SECRET` | **必須** | Token 驗證密鑰 | 隨機（每次重啟變） | `Xk9mPqL2vN7wR4tY6uI8...` |
+| `HTTP_ALLOWED` | 否 | 是否允許 HTTP 連線 | `false` | `true` / `false` |
+| `TRUST_PROXY` | 否 | 是否信任反向代理 | `false` | `true` / `false` |
+| `ACCOUNT_REGISTRATION` | 否 | 是否允許註冊新帳號 | `true` | `true` / `false` |
+| `ALLOW_UNAUTHENTICATED` | 否 | 是否允許匿名使用 | `false` | `true` / `false` |
+
+### 🌐 一般設定
+
+| 變數 | 必要性 | 說明 | 預設值 | 範例 |
+|------|--------|------|--------|------|
+| `TZ` | 否 | 系統時區 | `UTC` | `Asia/Taipei` |
+| `LANGUAGE` | 否 | 介面語言 | `auto` | `zh-TW` |
+| `WEBROOT` | 否 | 子路徑前綴 | 空 | `/convertx` |
+| `HIDE_HISTORY` | 否 | 隱藏轉換歷史 | `false` | `true` / `false` |
+
+### ⚙️ 轉換設定
+
+| 變數 | 必要性 | 說明 | 預設值 | 範例 |
+|------|--------|------|--------|------|
+| `AUTO_DELETE_EVERY_N_HOURS` | 否 | 自動刪除間隔（小時） | `24` | `12` |
+| `MAX_CONVERT_PROCESS` | 否 | 最大同時轉換數 | `0`（無限制） | `4` |
+| `FFMPEG_ARGS` | 否 | FFmpeg 輸入參數 | 空 | `-hwaccel cuda` |
+| `FFMPEG_OUTPUT_ARGS` | 否 | FFmpeg 輸出參數 | 空 | `-c:v h264_nvenc` |
+
+### 📄 PDF 翻譯設定
+
+| 變數 | 必要性 | 說明 | 預設值 | 範例 |
+|------|--------|------|--------|------|
+| `PDFMATHTRANSLATE_SERVICE` | 否 | 翻譯服務 | `google` | `deepl` |
+| `PDFMATHTRANSLATE_MODELS_PATH` | 否 | 模型路徑 | `/models` | `/app/models` |
+
+---
+
+## 必填設定
+
+### JWT_SECRET
+
+用於簽署登入驗證的密鑰，**強烈建議在正式環境中設定**。
+
+| 項目 | 說明 |
+|------|------|
+| **類型** | 字串 |
+| **預設值** | 每次重啟隨機產生 |
+| **建議值** | 至少 32 字元的隨機字串 |
+| **必要性** | ⭐ 強烈建議 |
+
+**問題**：若不設定，每次容器重啟後所有使用者都需要重新登入。
+
+**產生方式**：
+
+```bash
+# Linux / macOS
+openssl rand -hex 32
+
+# Windows PowerShell
+-join ((1..32) | ForEach-Object { '{0:x2}' -f (Get-Random -Max 256) })
+
+# 線上工具
+# 使用任何密碼產生器產生 32 字元以上的隨機字串
+```
+
+**使用範例**：
+
+```yaml
+environment:
+  - JWT_SECRET=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6
+```
+
+---
+
+## 網路與安全
+
+### HTTP_ALLOWED
+
+控制是否允許非 HTTPS 連線。
+
+| 項目 | 說明 |
+|------|------|
+| **類型** | 布林值 |
+| **預設值** | `false` |
+| **可選值** | `true` / `false` |
+
+**使用情境**：
+
+| 情境 | 建議設定 |
+|------|---------|
+| 本地測試 (localhost) | `true` |
+| 已設定 HTTPS | `false` |
+| 無 HTTPS 但需遠端存取 | `true` |
+
+> ⚠️ **注意**：設為 `false` 但用 HTTP 存取會導致「登入後又被導回登入頁」
+
+```yaml
+environment:
+  - HTTP_ALLOWED=true  # 本地開發時使用
+```
+
+### TRUST_PROXY
+
+控制是否信任反向代理的 X-Forwarded-* headers。
+
+| 項目 | 說明 |
+|------|------|
+| **類型** | 布林值 |
+| **預設值** | `false` |
+| **可選值** | `true` / `false` |
+
+**使用情境**：
+
+| 情境 | 建議設定 |
+|------|---------|
+| 直接存取容器 | `false` |
+| 透過 Nginx / Traefik / Caddy | `true` |
+
+```yaml
+environment:
+  - TRUST_PROXY=true  # 使用反向代理時
+```
+
+### ACCOUNT_REGISTRATION
+
+控制是否允許新使用者註冊。
+
+| 項目 | 說明 |
+|------|------|
+| **類型** | 布林值 |
+| **預設值** | `true` |
+| **可選值** | `true` / `false` |
+
+```yaml
+environment:
+  - ACCOUNT_REGISTRATION=false  # 關閉公開註冊
+```
+
+### ALLOW_UNAUTHENTICATED
+
+控制是否允許未登入的匿名使用者使用轉換功能。
+
+| 項目 | 說明 |
+|------|------|
+| **類型** | 布林值 |
+| **預設值** | `false` |
+| **可選值** | `true` / `false` |
+
+```yaml
+environment:
+  - ALLOW_UNAUTHENTICATED=true  # 允許匿名使用
+```
+
+---
+
+## 一般設定
+
+### TZ
+
+設定系統時區，影響日誌時間顯示與自動清理排程。
+
+| 項目 | 說明 |
+|------|------|
+| **類型** | 時區字串 |
+| **預設值** | `UTC` |
+| **可選值** | [時區列表](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) |
+
+**常用時區**：
+
+| 地區 | 時區值 |
+|------|--------|
+| 台灣 | `Asia/Taipei` |
+| 香港 | `Asia/Hong_Kong` |
+| 中國大陸 | `Asia/Shanghai` |
+| 日本 | `Asia/Tokyo` |
+| 美國東部 | `America/New_York` |
+
+```yaml
+environment:
+  - TZ=Asia/Taipei
+```
+
+### LANGUAGE
+
+設定介面預設語言。
+
+| 項目 | 說明 |
+|------|------|
+| **類型** | 語言代碼 |
+| **預設值** | `auto`（自動偵測） |
+| **可選值** | `zh-TW`, `zh-CN`, `en`, `ja` 等 65 種 |
+
+```yaml
+environment:
+  - LANGUAGE=zh-TW
+```
+
+### WEBROOT
+
+設定子路徑前綴，用於反向代理配置。
+
+| 項目 | 說明 |
+|------|------|
+| **類型** | 路徑字串 |
+| **預設值** | 空（根路徑） |
+
+```yaml
+environment:
+  - WEBROOT=/convertx  # 訪問路徑變為 http://example.com/convertx
+```
+
+### HIDE_HISTORY
+
+控制是否隱藏轉換歷史紀錄。
+
+| 項目 | 說明 |
+|------|------|
+| **類型** | 布林值 |
+| **預設值** | `false` |
+
+```yaml
+environment:
+  - HIDE_HISTORY=true  # 隱藏歷史紀錄
+```
+
+---
+
+## 轉換設定
+
+### AUTO_DELETE_EVERY_N_HOURS
+
+設定自動刪除轉換檔案的間隔時間（小時）。
+
+| 項目 | 說明 |
+|------|------|
+| **類型** | 數字 |
+| **預設值** | `24` |
+| **建議範圍** | `1` - `168` |
+
+```yaml
+environment:
+  - AUTO_DELETE_EVERY_N_HOURS=12  # 每 12 小時清理一次
+```
+
+### MAX_CONVERT_PROCESS
+
+設定最大同時轉換任務數量。
+
+| 項目 | 說明 |
+|------|------|
+| **類型** | 數字 |
+| **預設值** | `0`（無限制） |
+| **建議值** | CPU 核心數 |
+
+```yaml
+environment:
+  - MAX_CONVERT_PROCESS=4  # 最多同時 4 個轉換任務
+```
+
+### FFMPEG_ARGS 與 FFMPEG_OUTPUT_ARGS
+
+設定 FFmpeg 的全域參數。
+
+| 變數 | 說明 |
+|------|------|
+| `FFMPEG_ARGS` | 輸入參數（套用於輸入檔案） |
+| `FFMPEG_OUTPUT_ARGS` | 輸出參數（套用於輸出檔案） |
+
+**GPU 加速範例**：
+
+```yaml
+environment:
+  # NVIDIA GPU 加速
+  - FFMPEG_ARGS=-hwaccel cuda
+  - FFMPEG_OUTPUT_ARGS=-c:v h264_nvenc
+```
+
+---
+
+## PDF 翻譯設定
+
+### PDFMATHTRANSLATE_SERVICE
+
+設定 PDF 翻譯使用的服務。
+
+| 項目 | 說明 |
+|------|------|
+| **類型** | 字串 |
+| **預設值** | `google` |
+| **可選值** | `google`, `deepl`, `azure` 等 |
+
+```yaml
+environment:
+  - PDFMATHTRANSLATE_SERVICE=google
+```
+
+### PDFMATHTRANSLATE_MODELS_PATH
+
+設定 PDF 翻譯模型的存放路徑。
+
+| 項目 | 說明 |
+|------|------|
+| **類型** | 路徑字串 |
+| **預設值** | `/models` |
+
+```yaml
+environment:
+  - PDFMATHTRANSLATE_MODELS_PATH=/app/models
+```
+
+---
+
+## 推薦配置範例
+
+### 本地開發環境
+
+```yaml
+services:
+  convertx:
+    image: convertx/convertx-cn:latest
+    ports:
+      - "3000:3000"
+    volumes:
+      - ./data:/app/data
+    environment:
+      - TZ=Asia/Taipei
+      - JWT_SECRET=dev-secret-key-for-local-testing
+      - HTTP_ALLOWED=true
+      - ACCOUNT_REGISTRATION=true
+```
+
+### 正式生產環境
+
+```yaml
+services:
+  convertx:
+    image: convertx/convertx-cn:latest
+    ports:
+      - "3000:3000"
+    volumes:
+      - ./data:/app/data
+    environment:
+      - TZ=Asia/Taipei
+      - JWT_SECRET=${JWT_SECRET}          # 使用環境變數或 secrets
+      - HTTP_ALLOWED=false
+      - TRUST_PROXY=true                   # 如果使用反向代理
+      - ACCOUNT_REGISTRATION=false         # 關閉公開註冊
+      - AUTO_DELETE_EVERY_N_HOURS=12
+      - MAX_CONVERT_PROCESS=4
+    deploy:
+      resources:
+        limits:
+          cpus: '4'
+          memory: 8G
+```
+
+### 公開服務（允許匿名）
+
+```yaml
+services:
+  convertx:
+    image: convertx/convertx-cn:latest
+    ports:
+      - "3000:3000"
+    volumes:
+      - ./data:/app/data
+    environment:
+      - TZ=Asia/Taipei
+      - JWT_SECRET=${JWT_SECRET}
+      - TRUST_PROXY=true
+      - ALLOW_UNAUTHENTICATED=true
+      - ACCOUNT_REGISTRATION=false
+      - AUTO_DELETE_EVERY_N_HOURS=1        # 頻繁清理
+      - MAX_CONVERT_PROCESS=2              # 限制資源使用
+```
+
+---
+
+## 安全性建議
+
+### ✅ 必做事項
+
+1. **設定固定的 JWT_SECRET**
+   - 至少 32 字元
+   - 使用隨機產生的字串
+   - 不要使用範例中的值
+
+2. **正式環境關閉 HTTP**
+   ```yaml
+   - HTTP_ALLOWED=false
+   ```
+
+3. **使用反向代理處理 HTTPS**
+   ```yaml
+   - TRUST_PROXY=true
+   ```
+
+4. **限制註冊功能**
+   ```yaml
+   - ACCOUNT_REGISTRATION=false
+   ```
+
+### ⚠️ 注意事項
+
+1. **不要在公開網路暴露管理介面**
+2. **定期更新 Docker 映像檔**
+3. **定期備份 data 目錄**
+4. **監控磁碟空間使用**
+
+### 🔐 進階安全設定
+
+```yaml
+environment:
+  - JWT_SECRET=${JWT_SECRET}
+  - HTTP_ALLOWED=false
+  - TRUST_PROXY=true
+  - ACCOUNT_REGISTRATION=false
+  - ALLOW_UNAUTHENTICATED=false
+  - AUTO_DELETE_EVERY_N_HOURS=6
+```
+
+---
+
+[⬆️ 回到頂部](#環境變數與設定) | [📚 回到目錄](00-專案總覽.md)