394dcbec1a
- Updated tables for service ports, environment variables, HTTP status codes, and error codes to enhance readability. - Streamlined JavaScript examples for file conversion and added comments for better understanding. - Enhanced troubleshooting section with clearer formatting and additional explanations. - Improved licensing section with detailed requirements and third-party component licenses. - Organized the document structure for better navigation and accessibility.
446 lines
11 KiB
Markdown
446 lines
11 KiB
Markdown
# 環境變數與設定
|
||
|
||
本文件詳細說明 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)
|