27ffdee6f4
## Bug Fixes - Fix standard image size issue (was ~1.5GB, should be 8-12GB) - Add strict model validation during build - Add retry mechanism (--retry 3 --retry-delay 5) to all curl downloads ## Documentation - Clarify version terminology: Standard (一般版), Extended (擴充版), Lite (Lite版) - Remove duplicate docs/環境變數總覽.md - Improve environment variable documentation structure - Add quick reference tables for environment variables ## Build - Explicitly specify 'file: Dockerfile' in release.yml - Use 'buildcache-full' cache key to prevent cross-pollution
299 lines
6.1 KiB
Markdown
299 lines
6.1 KiB
Markdown
# 環境變數設定
|
|
|
|
本文件列出 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)
|