convertor/docs/03-環境變數與設定.md

環境變數與設定

本文件詳細說明 ConvertX-CN 所有可用的環境變數與配置選項。

---

目錄

• 必填設定
• 網路與安全
• 一般設定
• 轉換設定
• 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 字元的隨機字串
必要性	⭐ 強烈建議

問題：若不設定，每次容器重啟後所有使用者都需要重新登入。

產生方式：

# Linux / macOS
openssl rand -hex 32

# Windows PowerShell
-join ((1..32) | ForEach-Object { '{0:x2}' -f (Get-Random -Max 256) })

# 線上工具
# 使用任何密碼產生器產生 32 字元以上的隨機字串

使用範例：

environment:
  - JWT_SECRET=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6

---

網路與安全

HTTP_ALLOWED

控制是否允許非 HTTPS 連線。

項目	說明
類型	布林值
預設值	false
可選值	true / false

使用情境：

情境	建議設定
本地測試 (localhost)	true
已設定 HTTPS	false
無 HTTPS 但需遠端存取	true

⚠️ 注意：設為 false 但用 HTTP 存取會導致「登入後又被導回登入頁」

environment:
  - HTTP_ALLOWED=true # 本地開發時使用

TRUST_PROXY

控制是否信任反向代理的 X-Forwarded-* headers。

項目	說明
類型	布林值
預設值	false
可選值	true / false

使用情境：

情境	建議設定
直接存取容器	false
透過 Nginx / Traefik / Caddy	true

environment:
  - TRUST_PROXY=true # 使用反向代理時

ACCOUNT_REGISTRATION

控制是否允許新使用者註冊。

項目	說明
類型	布林值
預設值	true
可選值	true / false

environment:
  - ACCOUNT_REGISTRATION=false # 關閉公開註冊

ALLOW_UNAUTHENTICATED

控制是否允許未登入的匿名使用者使用轉換功能。

項目	說明
類型	布林值
預設值	false
可選值	true / false

environment:
  - ALLOW_UNAUTHENTICATED=true # 允許匿名使用

---

一般設定

TZ

設定系統時區，影響日誌時間顯示與自動清理排程。

項目	說明
類型	時區字串
預設值	UTC
可選值	時區列表

常用時區：

地區	時區值
台灣	Asia/Taipei
香港	Asia/Hong_Kong
中國大陸	Asia/Shanghai
日本	Asia/Tokyo
美國東部	America/New_York

environment:
  - TZ=Asia/Taipei

LANGUAGE

設定介面預設語言。

項目	說明
類型	語言代碼
預設值	auto（自動偵測）
可選值	zh-TW, zh-CN, en, ja 等 65 種

environment:
  - LANGUAGE=zh-TW

WEBROOT

設定子路徑前綴，用於反向代理配置。

項目	說明
類型	路徑字串
預設值	空（根路徑）

environment:
  - WEBROOT=/convertx # 訪問路徑變為 http://example.com/convertx

HIDE_HISTORY

控制是否隱藏轉換歷史紀錄。

項目	說明
類型	布林值
預設值	false

environment:
  - HIDE_HISTORY=true # 隱藏歷史紀錄

---

轉換設定

AUTO_DELETE_EVERY_N_HOURS

設定自動刪除轉換檔案的間隔時間（小時）。

項目	說明
類型	數字
預設值	24
建議範圍	1 - 168

environment:
  - AUTO_DELETE_EVERY_N_HOURS=12 # 每 12 小時清理一次

MAX_CONVERT_PROCESS

設定最大同時轉換任務數量。

項目	說明
類型	數字
預設值	0（無限制）
建議值	CPU 核心數

environment:
  - MAX_CONVERT_PROCESS=4 # 最多同時 4 個轉換任務

FFMPEG_ARGS 與 FFMPEG_OUTPUT_ARGS

設定 FFmpeg 的全域參數。

變數	說明
FFMPEG_ARGS	輸入參數（套用於輸入檔案）
FFMPEG_OUTPUT_ARGS	輸出參數（套用於輸出檔案）

GPU 加速範例：

environment:
  # NVIDIA GPU 加速
  - FFMPEG_ARGS=-hwaccel cuda
  - FFMPEG_OUTPUT_ARGS=-c:v h264_nvenc

---

PDF 翻譯設定

PDFMATHTRANSLATE_SERVICE

設定 PDF 翻譯使用的服務。

項目	說明
類型	字串
預設值	google
可選值	google, deepl, azure 等

environment:
  - PDFMATHTRANSLATE_SERVICE=google

PDFMATHTRANSLATE_MODELS_PATH

設定 PDF 翻譯模型的存放路徑。

項目	說明
類型	路徑字串
預設值	/models

environment:
  - PDFMATHTRANSLATE_MODELS_PATH=/app/models

---

推薦配置範例

本地開發環境

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

正式生產環境

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

公開服務（允許匿名）

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

   - HTTP_ALLOWED=false
   

3. 使用反向代理處理 HTTPS

   - TRUST_PROXY=true
   

4. 限制註冊功能

   - ACCOUNT_REGISTRATION=false
   

⚠️ 注意事項

1. 不要在公開網路暴露管理介面
2. 定期更新 Docker 映像檔
3. 定期備份 data 目錄
4. 監控磁碟空間使用

🔐 進階安全設定

environment:
  - JWT_SECRET=${JWT_SECRET}
  - HTTP_ALLOWED=false
  - TRUST_PROXY=true
  - ACCOUNT_REGISTRATION=false
  - ALLOW_UNAUTHENTICATED=false
  - AUTO_DELETE_EVERY_N_HOURS=6

---

⬆️ 回到頂部 | 📚 回到目錄