# 環境變數與設定

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