feat: v0.1.9 - 全頁拖曳上傳 + i18n 修正 + 文件更新
✨ Features: - 全頁拖曳上傳：檔案可拖曳到頁面任何位置上傳 - 原本的上傳框視覺效果保持不變 🌍 i18n: - 刪除任務的 confirm/alert 訊息改用 i18n - 隨語言切換即時更新顯示內容 📚 Documentation: - README 新增「如何更新 ConvertX-CN 版本」章節 - 新增 deployment.md（Reverse Proxy、HTTPS） - 新增 Docker Compose 範例分層 - 更新 environment-variables.md
This commit is contained in:
Your Name
parent
a0eccf0437
commit
a45a049fe2
14 changed files with 1475 additions and 167 deletions
|
|
@ -1,123 +1,249 @@
|
|||
# 環境變數設定
|
||||
|
||||
所有環境變數皆為選填，建議至少設定 `JWT_SECRET`。
|
||||
本文件列出 ConvertX-CN 所有可用的環境變數設定。
|
||||
|
||||
## 快速參考
|
||||
|
||||
| 重要程度 | 變數 | 說明 |
|
||||
| -------- | -------------- | ---------------- |
|
||||
| 🔴 必填 | `JWT_SECRET` | 生產環境必須設定 |
|
||||
| 🟡 建議 | `TZ` | 時區設定 |
|
||||
| 🟡 建議 | `HTTP_ALLOWED` | 是否允許 HTTP |
|
||||
| 🟢 可選 | 其他 | 依需求設定 |
|
||||
|
||||
---
|
||||
|
||||
## 安全性設定
|
||||
## 🔴 必填設定（生產環境）
|
||||
|
||||
| 變數名稱 | 預設值 | 說明 |
|
||||
| ----------------------- | -------------- | ----------------------------------------------- |
|
||||
| `JWT_SECRET` | `randomUUID()` | 用於簽署 JWT 的密鑰字串。**生產環境請務必設定** |
|
||||
| `ACCOUNT_REGISTRATION` | `true` | 是否允許註冊新帳號（預設開放） |
|
||||
| `HTTP_ALLOWED` | `false` | 是否允許 HTTP 連線（僅本地使用建議開啟） |
|
||||
| `ALLOW_UNAUTHENTICATED` | `false` | 是否允許未登入使用 |
|
||||
### JWT_SECRET
|
||||
|
||||
### 安全建議
|
||||
| 項目 | 說明 |
|
||||
| ------ | ---------------------------------- |
|
||||
| 預設值 | `randomUUID()`（每次重啟都會改變） |
|
||||
| 用途 | 用於簽署 JWT 的密鑰字串 |
|
||||
|
||||
**⚠️ 重要**：若不設定，每次容器重啟後所有使用者都需要重新登入。
|
||||
|
||||
**產生方式**：
|
||||
|
||||
```bash
|
||||
# Linux / macOS
|
||||
openssl rand -hex 32
|
||||
|
||||
# 輸出範例
|
||||
# a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6
|
||||
```
|
||||
|
||||
**設定方式**：
|
||||
|
||||
```yaml
|
||||
# 生產環境（關閉註冊）
|
||||
environment:
|
||||
- JWT_SECRET=a-very-long-random-string-at-least-32-characters
|
||||
- ACCOUNT_REGISTRATION=false
|
||||
- HTTP_ALLOWED=false
|
||||
- ALLOW_UNAUTHENTICATED=false
|
||||
- JWT_SECRET=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 檔案管理
|
||||
## 🟡 建議設定
|
||||
|
||||
| 變數名稱 | 預設值 | 說明 |
|
||||
| --------------------------- | ------ | ------------------------------------- |
|
||||
| `AUTO_DELETE_EVERY_N_HOURS` | `24` | 自動刪除超過 N 小時的檔案（0 = 停用） |
|
||||
### TZ（時區）
|
||||
|
||||
### 範例
|
||||
| 項目 | 說明 |
|
||||
| ------ | ------------------------------ |
|
||||
| 預設值 | `UTC` |
|
||||
| 用途 | 影響檔案時間戳記與日期顯示格式 |
|
||||
|
||||
**常用值**：
|
||||
|
||||
| 地區 | 設定值 |
|
||||
| ---- | --------------------- |
|
||||
| 台灣 | `Asia/Taipei` |
|
||||
| 中國 | `Asia/Shanghai` |
|
||||
| 香港 | `Asia/Hong_Kong` |
|
||||
| 日本 | `Asia/Tokyo` |
|
||||
| 美東 | `America/New_York` |
|
||||
| 美西 | `America/Los_Angeles` |
|
||||
| 英國 | `Europe/London` |
|
||||
|
||||
### HTTP_ALLOWED
|
||||
|
||||
| 項目 | 說明 |
|
||||
| ------ | --------------------- |
|
||||
| 預設值 | `false` |
|
||||
| 用途 | 是否允許非 HTTPS 連線 |
|
||||
|
||||
**設定指南**：
|
||||
|
||||
| 情境 | 設定值 |
|
||||
| ------------------------------ | ------- |
|
||||
| 本地測試（http://localhost） | `true` |
|
||||
| 遠端部署且有 HTTPS | `false` |
|
||||
| 遠端部署但沒有 HTTPS（不建議） | `true` |
|
||||
|
||||
**⚠️ 常見問題**：若設為 `false` 但實際用 HTTP 存取，會導致「登入後又被導回登入頁」。
|
||||
|
||||
### TRUST_PROXY
|
||||
|
||||
| 項目 | 說明 |
|
||||
| ------ | ------------------------------------ |
|
||||
| 預設值 | `false` |
|
||||
| 用途 | 透過 Reverse Proxy 存取時設為 `true` |
|
||||
|
||||
讓應用程式信任 `X-Forwarded-Proto` 等 headers，正確判斷連線是否為 HTTPS。
|
||||
|
||||
**設定指南**：
|
||||
|
||||
| 情境 | 設定值 |
|
||||
| ---------------------------- | ------- |
|
||||
| 直接存取容器（無 Proxy） | `false` |
|
||||
| 透過 Nginx / Traefik / Caddy | `true` |
|
||||
|
||||
---
|
||||
|
||||
## 🔒 安全性設定
|
||||
|
||||
### ACCOUNT_REGISTRATION
|
||||
|
||||
| 項目 | 說明 |
|
||||
| ------ | ------------------ |
|
||||
| 預設值 | `true` |
|
||||
| 用途 | 是否允許註冊新帳號 |
|
||||
|
||||
**💡 注意**：首次註冊的帳號不受此限制，即使設為 `false` 仍可建立第一個帳號。
|
||||
|
||||
**建議**：
|
||||
|
||||
- 首次部署時設為 `true`
|
||||
- 註冊好管理員帳號後改為 `false`
|
||||
|
||||
### ALLOW_UNAUTHENTICATED
|
||||
|
||||
| 項目 | 說明 |
|
||||
| ------ | -------------------------- |
|
||||
| 預設值 | `false` |
|
||||
| 用途 | 是否允許未登入使用轉換功能 |
|
||||
|
||||
**⚠️ 風險**：設為 `true` 時：
|
||||
|
||||
- 任何人都可使用伺服器資源
|
||||
- 可能被濫用（大量轉換、儲存空間耗盡）
|
||||
|
||||
**建議**：除非明確要提供公開服務，否則保持 `false`。
|
||||
|
||||
---
|
||||
|
||||
## 📁 檔案管理
|
||||
|
||||
### AUTO_DELETE_EVERY_N_HOURS
|
||||
|
||||
| 項目 | 說明 |
|
||||
| ------ | ------------------------------------- |
|
||||
| 預設值 | `24` |
|
||||
| 用途 | 自動刪除超過 N 小時的檔案（0 = 停用） |
|
||||
|
||||
**範例**：
|
||||
|
||||
```yaml
|
||||
# 每 48 小時清理一次
|
||||
- AUTO_DELETE_EVERY_N_HOURS=48
|
||||
|
||||
# 停用自動清理
|
||||
# 停用自動清理（不建議，會佔滿磁碟）
|
||||
- AUTO_DELETE_EVERY_N_HOURS=0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 轉換設定
|
||||
## 🎨 介面設定
|
||||
|
||||
| 變數名稱 | 預設值 | 說明 |
|
||||
| --------------------- | ------ | ---------------------------------------- |
|
||||
| `MAX_CONVERT_PROCESS` | `0` | 最大同時轉換數（0 = 無限制） |
|
||||
| `FFMPEG_ARGS` | - | FFmpeg 輸入參數，例如 `-hwaccel vaapi` |
|
||||
| `FFMPEG_OUTPUT_ARGS` | - | FFmpeg 輸出參數，例如 `-preset veryfast` |
|
||||
### WEBROOT
|
||||
|
||||
### 硬體加速範例
|
||||
| 項目 | 說明 |
|
||||
| ------ | ---------------------------- |
|
||||
| 預設值 | (空) |
|
||||
| 用途 | 子路徑部署，例如 `/convertx` |
|
||||
|
||||
```yaml
|
||||
# NVIDIA GPU 加速
|
||||
- FFMPEG_ARGS=-hwaccel cuda
|
||||
|
||||
# Intel QSV 加速
|
||||
- FFMPEG_ARGS=-hwaccel qsv
|
||||
|
||||
# AMD VAAPI 加速
|
||||
- FFMPEG_ARGS=-hwaccel vaapi
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 介面設定
|
||||
|
||||
| 變數名稱 | 預設值 | 說明 |
|
||||
| -------------- | ------- | ---------------------------- |
|
||||
| `WEBROOT` | - | 子路徑部署，例如 `/convertx` |
|
||||
| `HIDE_HISTORY` | `false` | 隱藏歷史紀錄頁面 |
|
||||
|
||||
### 子路徑部署
|
||||
|
||||
如果需要在子路徑部署（如 `https://example.com/convertx`）：
|
||||
若透過子路徑存取（如 `https://example.com/convertx/`）：
|
||||
|
||||
```yaml
|
||||
- WEBROOT=/convertx
|
||||
```
|
||||
|
||||
### HIDE_HISTORY
|
||||
|
||||
| 項目 | 說明 |
|
||||
| ------ | ---------------- |
|
||||
| 預設值 | `false` |
|
||||
| 用途 | 隱藏歷史紀錄頁面 |
|
||||
|
||||
### LANGUAGE
|
||||
|
||||
| 項目 | 說明 |
|
||||
| ------ | --------------------------- |
|
||||
| 預設值 | `en` |
|
||||
| 用途 | 日期格式語言（BCP 47 格式） |
|
||||
|
||||
影響介面上的日期顯示格式（如 2026/01/20 vs 01/20/2026）。
|
||||
|
||||
---
|
||||
|
||||
## 本地化設定
|
||||
## ⚙️ 轉換設定
|
||||
|
||||
| 變數名稱 | 預設值 | 說明 |
|
||||
| ---------- | ------ | --------------------------- |
|
||||
| `LANGUAGE` | `en` | 日期格式語言（BCP 47 格式） |
|
||||
| `TZ` | `UTC` | 時區設定 |
|
||||
### MAX_CONVERT_PROCESS
|
||||
|
||||
### 常用時區
|
||||
| 項目 | 說明 |
|
||||
| ------ | ---------------------------- |
|
||||
| 預設值 | `0` |
|
||||
| 用途 | 最大同時轉換數（0 = 無限制） |
|
||||
|
||||
限制同時進行的轉換任務數量，避免伺服器過載。
|
||||
|
||||
### FFMPEG_ARGS
|
||||
|
||||
| 項目 | 說明 |
|
||||
| ------ | ------------------------------- |
|
||||
| 預設值 | (空) |
|
||||
| 用途 | FFmpeg 輸入參數，用於硬體加速等 |
|
||||
|
||||
**硬體加速範例**：
|
||||
|
||||
```yaml
|
||||
# 台灣
|
||||
- TZ=Asia/Taipei
|
||||
# NVIDIA GPU
|
||||
- FFMPEG_ARGS=-hwaccel cuda
|
||||
|
||||
# 中國
|
||||
- TZ=Asia/Shanghai
|
||||
# Intel QSV
|
||||
- FFMPEG_ARGS=-hwaccel qsv
|
||||
|
||||
# 日本
|
||||
- TZ=Asia/Tokyo
|
||||
# AMD VAAPI
|
||||
- FFMPEG_ARGS=-hwaccel vaapi
|
||||
```
|
||||
|
||||
# 美國東部
|
||||
- TZ=America/New_York
|
||||
### FFMPEG_OUTPUT_ARGS
|
||||
|
||||
| 項目 | 說明 |
|
||||
| ------ | --------------- |
|
||||
| 預設值 | (空) |
|
||||
| 用途 | FFmpeg 輸出參數 |
|
||||
|
||||
```yaml
|
||||
# 使用較快的編碼預設
|
||||
- FFMPEG_OUTPUT_ARGS=-preset veryfast
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 進階設定
|
||||
## 🔧 進階設定
|
||||
|
||||
| 變數名稱 | 預設值 | 說明 |
|
||||
| ------------------------------ | ------- | ---------------------------- |
|
||||
| `UNAUTHENTICATED_USER_SHARING` | `false` | 未登入使用者是否共享檔案空間 |
|
||||
### UNAUTHENTICATED_USER_SHARING
|
||||
|
||||
| 項目 | 說明 |
|
||||
| ------ | ---------------------------- |
|
||||
| 預設值 | `false` |
|
||||
| 用途 | 未登入使用者是否共享檔案空間 |
|
||||
|
||||
設為 `true` 時，所有匿名使用者會看到相同的檔案。
|
||||
|
||||
---
|
||||
|
||||
## 完整範例
|
||||
## 情境範例
|
||||
|
||||
### 開發環境
|
||||
|
||||
|
|
@ -135,6 +261,7 @@ 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
|
||||
```
|
||||
|
|
@ -148,6 +275,14 @@ environment:
|
|||
- AUTO_DELETE_EVERY_N_HOURS=1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 相關文件
|
||||
|
||||
- [進階部署指南](deployment.md)
|
||||
- [Docker Compose 範例](docker-compose/)
|
||||
- [常見問題](faq.md)
|
||||
|
||||
### 帶硬體加速
|
||||
|
||||
```yaml
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue