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

# 環境變數與設定

本文件詳細說明 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)