convertor/docs/configuration/environment-variables.md

環境變數設定

本文件列出 ConvertX-CN 所有可用的環境變數。

---

快速參考

優先級	變數	說明	預設值
必填	JWT_SECRET	登入驗證金鑰	隨機（每次重啟變）
建議	TZ	時區	UTC
建議	HTTP_ALLOWED	允許 HTTP	false
可選	TRUST_PROXY	信任反向代理	false

---

必填設定

JWT_SECRET

用於簽署登入驗證的密鑰。強烈建議設定。

項目	值
預設值	每次重啟隨機產生
建議值	至少 32 字元的隨機字串

不設定的話，每次容器重啟後所有使用者都需要重新登入。

產生方式：

# Linux / macOS
openssl rand -hex 32

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

---

網路與安全

HTTP_ALLOWED

允許非 HTTPS 連線。

項目	值
預設值	false

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

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

TRUST_PROXY

信任反向代理的 headers。

項目	值
預設值	false

情境	設定值
直接存取容器	false
透過 Nginx / Traefik / Caddy	true
透過 Cloudflare Tunnel	true

ACCOUNT_REGISTRATION

是否允許註冊新帳號。

項目	值
預設值	true

建議建立管理員帳號後改為 false。

ALLOW_UNAUTHENTICATED

是否允許未登入使用轉換功能。

項目	值
預設值	false

⚠️ 設為 true 有安全風險：任何人都可使用伺服器資源

---

一般設定

TZ

時區設定，影響日期顯示。

項目	值
預設值	UTC

常用值：

地區	值
台灣	Asia/Taipei
中國	Asia/Shanghai
香港	Asia/Hong_Kong
日本	Asia/Tokyo

AUTO_DELETE_EVERY_N_HOURS

自動刪除超過 N 小時的檔案。

項目	值
預設值	24
停用	0

---

介面設定

WEBROOT

子路徑部署前綴。

項目	值
預設值	空

若透過 https://example.com/convertx/ 存取：

- WEBROOT=/convertx

HIDE_HISTORY

隱藏歷史紀錄頁面。

項目	值
預設值	false

LANGUAGE

介面語言。

項目	值
預設值	auto

設為特定語言代碼（如 zh-TW）可強制使用該語言。

---

轉換設定

MAX_CONVERT_PROCESS

最大同時轉換數。

項目	值
預設值	0（無限制）

限制同時進行的轉換任務數量，避免伺服器過載。

FFMPEG_ARGS

FFmpeg 輸入參數，用於硬體加速。

# NVIDIA GPU
- FFMPEG_ARGS=-hwaccel cuda

# Intel QSV
- FFMPEG_ARGS=-hwaccel qsv

# AMD VAAPI
- FFMPEG_ARGS=-hwaccel vaapi

FFMPEG_OUTPUT_ARGS

FFmpeg 輸出參數。

# 使用 NVIDIA 編碼器
- FFMPEG_OUTPUT_ARGS=-c:v h264_nvenc -preset fast

---

PDFMathTranslate 設定

PDFMATHTRANSLATE_SERVICE

翻譯服務提供商。

項目	值
預設值	google

可選值：google, deepl, openai 等

PDFMATHTRANSLATE_MODELS_PATH

模型路徑。

項目	值
預設值	/models/pdfmathtranslate

---

情境範例

開發環境

environment:
  - TZ=Asia/Taipei
  - HTTP_ALLOWED=true
  - ACCOUNT_REGISTRATION=true

生產環境

environment:
  - JWT_SECRET=your-very-long-and-random-secret-key-change-me
  - TZ=Asia/Taipei
  - HTTP_ALLOWED=false
  - TRUST_PROXY=true
  - ACCOUNT_REGISTRATION=false
  - AUTO_DELETE_EVERY_N_HOURS=24

公開服務（允許匿名）

environment:
  - ALLOW_UNAUTHENTICATED=true
  - HIDE_HISTORY=true
  - AUTO_DELETE_EVERY_N_HOURS=1
  - MAX_CONVERT_PROCESS=2

硬體加速

environment:
  - JWT_SECRET=your-secret-key
  - FFMPEG_ARGS=-hwaccel cuda
  - FFMPEG_OUTPUT_ARGS=-c:v h264_nvenc -preset fast

---

相關文件

• 安全性設定
• Docker 部署
• 反向代理設定