# 環境變數設定

> 📦 本文件已遷移至新位置，請參閱：[docs/config/environment.md](配置設定/環境變數.md)

---

## 快速參考

完整說明請參考 [環境變數完整說明](配置設定/環境變數.md)。

| 優先級 | 變數           | 說明          |
| ------ | -------------- | ------------- |
| 必填   | `JWT_SECRET`   | 登入驗證金鑰  |
| 建議   | `TZ`           | 時區設定      |
| 建議   | `HTTP_ALLOWED` | 是否允許 HTTP |
| 可選   | `TRUST_PROXY`  | 信任反向代理  |

---

## 相關文件

- [環境變數完整說明](配置設定/環境變數.md)
- [安全性設定](配置設定/安全性.md)
- [Docker 部署指南](部署指南/Docker部署.md)

---

## 🎨 介面設定

### WEBROOT

| 項目   | 說明                         |
| ------ | ---------------------------- |
| 預設值 | (空)                         |
| 用途   | 子路徑部署，例如 `/convertx` |

若透過子路徑存取（如 `https://example.com/convertx/`）：

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

### HIDE_HISTORY

| 項目   | 說明             |
| ------ | ---------------- |
| 預設值 | `false`          |
| 用途   | 隱藏歷史紀錄頁面 |

### LANGUAGE

| 項目   | 說明                        |
| ------ | --------------------------- |
| 預設值 | `en`                        |
| 用途   | 日期格式語言（BCP 47 格式） |

影響介面上的日期顯示格式（如 2026/01/20 vs 01/20/2026）。

---

## ⚙️ 轉換設定

### MAX_CONVERT_PROCESS

| 項目   | 說明                         |
| ------ | ---------------------------- |
| 預設值 | `0`                          |
| 用途   | 最大同時轉換數（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
# 使用較快的編碼預設
- FFMPEG_OUTPUT_ARGS=-preset veryfast
```

---

## 🔧 進階設定

### UNAUTHENTICATED_USER_SHARING

| 項目   | 說明                         |
| ------ | ---------------------------- |
| 預設值 | `false`                      |
| 用途   | 未登入使用者是否共享檔案空間 |

設為 `true` 時，所有匿名使用者會看到相同的檔案。

---

## 情境範例

### 開發環境

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

### 生產環境

```yaml
environment:
  - JWT_SECRET=your-very-long-and-random-secret-key-change-me
  - ACCOUNT_REGISTRATION=false
  - HTTP_ALLOWED=false
  - TRUST_PROXY=true
  - TZ=Asia/Taipei
  - AUTO_DELETE_EVERY_N_HOURS=24
```

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

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

---

## 📝 PDF Packager 設定

### PDF 數位簽章

PDF Packager 預設**開箱即用**，Docker 建置時已自動產生預設憑證。如需使用自訂憑證，可透過以下環境變數配置：

| 變數                    | 預設值                     | 說明                |
| ----------------------- | -------------------------- | ------------------- |
| `PDF_SIGN_P12_PATH`     | `/app/certs/default.p12`   | PKCS12 憑證檔案路徑 |
| `PDF_SIGN_P12_PASSWORD` | （空）                     | 憑證密碼            |
| `PDF_SIGN_REASON`       | `ConvertX-CN PDF Packager` | 簽章原因            |
| `PDF_SIGN_LOCATION`     | `Taiwan`                   | 簽章地點            |
| `PDF_SIGN_CONTACT`      | `convertx-cn@localhost`    | 聯絡資訊            |

**使用自訂憑證範例**：

```yaml
environment:
  - PDF_SIGN_P12_PATH=/app/certs/company.p12
  - PDF_SIGN_P12_PASSWORD=your_password
  - PDF_SIGN_REASON=文件已核准
  - PDF_SIGN_LOCATION=台北
  - PDF_SIGN_CONTACT=admin@company.com
volumes:
  - /path/to/certs:/app/certs:ro
```

詳細說明請參考 [PDF Packager 說明](功能說明/PDF-Packager.md)。

---

## 相關文件

- [Docker 部署指南](部署指南/Docker部署.md)
- [Docker Compose 範例](Docker組合配置/)
- [常見問題](快速入門/常見問題.md)

### 帶硬體加速

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