Elijah/convertor
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
convertor/docs/03-環境變數與設定.md

9.3 KiB
Raw Blame History

環境變數與設定

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

目錄

快速參考表

🔒 安全性設定

變數 必要性 說明 預設值 範例
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

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