# 環境變數設定

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

---

## 📋 快速參考表

### 🔒 安全性設定

| 變數                    | 說明         | 預設值             | 必填 |
| ----------------------- | ------------ | ------------------ | ---- |
| `JWT_SECRET`            | 登入驗證金鑰 | 隨機（每次重啟變） | ⭐   |
| `HTTP_ALLOWED`          | 允許 HTTP    | `false`            |      |
| `TRUST_PROXY`           | 信任反向代理 | `false`            |      |
| `ACCOUNT_REGISTRATION`  | 允許註冊     | `true`             |      |
| `ALLOW_UNAUTHENTICATED` | 允許匿名     | `false`            |      |

### 🌐 一般設定

| 變數                        | 說明             | 預設值  |
| --------------------------- | ---------------- | ------- |
| `TZ`                        | 時區             | `UTC`   |
| `AUTO_DELETE_EVERY_N_HOURS` | 自動刪除（小時） | `24`    |
| `WEBROOT`                   | 子路徑前綴       | 空      |
| `HIDE_HISTORY`              | 隱藏歷史紀錄     | `false` |
| `LANGUAGE`                  | 介面語言         | `auto`  |

### ⚙️ 轉換設定

| 變數                  | 說明            | 預設值        |
| --------------------- | --------------- | ------------- |
| `MAX_CONVERT_PROCESS` | 最大同時轉換數  | `0`（無限制） |
| `FFMPEG_ARGS`         | FFmpeg 輸入參數 | 空            |
| `FFMPEG_OUTPUT_ARGS`  | FFmpeg 輸出參數 | 空            |

### 📄 PDF 翻譯設定

| 變數                           | 說明     | 預設值    |
| ------------------------------ | -------- | --------- |
| `PDFMATHTRANSLATE_SERVICE`     | 翻譯服務 | `google`  |
| `PDFMATHTRANSLATE_MODELS_PATH` | 模型路徑 | `/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) })
```

---

## 網路與安全

### 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/` 存取：

```yaml
- WEBROOT=/convertx
```

### HIDE_HISTORY

隱藏歷史紀錄頁面。

| 項目   | 值      |
| ------ | ------- |
| 預設值 | `false` |

### LANGUAGE

介面語言。

| 項目   | 值     |
| ------ | ------ |
| 預設值 | `auto` |

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

---

## 轉換設定

### MAX_CONVERT_PROCESS

最大同時轉換數。

| 項目   | 值            |
| ------ | ------------- |
| 預設值 | `0`（無限制） |

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

### FFMPEG_ARGS

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

```yaml
# NVIDIA GPU
- FFMPEG_ARGS=-hwaccel cuda

# Intel QSV
- FFMPEG_ARGS=-hwaccel qsv

# AMD VAAPI
- FFMPEG_ARGS=-hwaccel vaapi
```

### FFMPEG_OUTPUT_ARGS

FFmpeg 輸出參數。

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

---

## PDFMathTranslate 設定

### PDFMATHTRANSLATE_SERVICE

翻譯服務提供商。

| 項目   | 值       |
| ------ | -------- |
| 預設值 | `google` |

可選值：`google`, `deepl`, `openai` 等

### PDFMATHTRANSLATE_MODELS_PATH

模型路徑。

| 項目   | 值                         |
| ------ | -------------------------- |
| 預設值 | `/models/pdfmathtranslate` |

---

## 情境範例

### 開發環境

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

### 生產環境

```yaml
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
```

### 公開服務（允許匿名）

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

### 硬體加速

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

---

## 相關文件

- [安全性設定](安全性.md)
- [Docker 部署](../部署指南/Docker部署.md)
- [反向代理設定](../部署指南/反向代理.md)