feat: v0.1.9 - 全頁拖曳上傳 + i18n 修正 + 文件更新

✨ Features: - 全頁拖曳上傳：檔案可拖曳到頁面任何位置上傳 - 原本的上傳框視覺效果保持不變 🌍 i18n: - 刪除任務的 confirm/alert 訊息改用 i18n - 隨語言切換即時更新顯示內容 📚 Documentation: - README 新增「如何更新 ConvertX-CN 版本」章節 - 新增 deployment.md（Reverse Proxy、HTTPS） - 新增 Docker Compose 範例分層 - 更新 environment-variables.md
2026-01-20 15:09:30 +08:00 · 2026-01-20 15:09:30 +08:00 · a45a049fe2
commit a45a049fe2
parent a0eccf0437
14 changed files with 1475 additions and 167 deletions
--- a/docs/deployment.md
+++ b/docs/deployment.md
@ -0,0 +1,382 @@
+# 進階部署指南
+
+本文件說明如何在生產環境中部署 ConvertX-CN，包括 Reverse Proxy、HTTPS、安全性設定等。
+
+---
+
+## 目錄
+
+- [部署前檢查清單](#部署前檢查清單)
+- [Reverse Proxy 設定](#reverse-proxy-設定)
+  - [Nginx](#nginx)
+  - [Traefik](#traefik)
+  - [Caddy](#caddy)
+- [HTTPS 設定](#https-設定)
+- [安全性建議](#安全性建議)
+- [子路徑部署](#子路徑部署)
+- [效能調整](#效能調整)
+- [備份與還原](#備份與還原)
+
+---
+
+## 部署前檢查清單
+
+在部署到生產環境前，請確認以下項目：
+
+- [ ] 已建立 `data` 資料夾（實體資料夾，非匿名 volume）
+- [ ] 已設定固定的 `JWT_SECRET`（至少 32 字元）
+- [ ] 已關閉 `ACCOUNT_REGISTRATION`（或確認要開放註冊）
+- [ ] 已設定 `TRUST_PROXY=true`（若使用 Reverse Proxy）
+- [ ] 已設定 `HTTP_ALLOWED=false`（若有 HTTPS）
+- [ ] 已設定防火牆規則
+- [ ] 已設定定期備份
+
+---
+
+## Reverse Proxy 設定
+
+### 重要環境變數
+
+透過 Reverse Proxy 存取時，請設定：
+
+```yaml
+environment:
+  - TRUST_PROXY=true # 信任 X-Forwarded-* headers
+  - HTTP_ALLOWED=false # Proxy 已處理 HTTPS
+```
+
+### Nginx
+
+```nginx
+# /etc/nginx/sites-available/convertx
+server {
+    listen 80;
+    server_name convertx.example.com;
+
+    # 強制跳轉 HTTPS
+    return 301 https://$server_name$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name convertx.example.com;
+
+    # SSL 憑證（使用 Let's Encrypt）
+    ssl_certificate /etc/letsencrypt/live/convertx.example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/convertx.example.com/privkey.pem;
+
+    # SSL 安全設定
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_prefer_server_ciphers on;
+    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
+
+    # 檔案上傳大小限制（根據需求調整）
+    client_max_body_size 500M;
+
+    # 上傳超時設定
+    proxy_read_timeout 300s;
+    proxy_send_timeout 300s;
+
+    location / {
+        proxy_pass http://127.0.0.1:3000;
+        proxy_http_version 1.1;
+
+        # 必要的 headers
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        # WebSocket 支援（若需要）
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+    }
+}
+```
+
+### Traefik
+
+#### 使用 Docker Labels
+
+```yaml
+# docker-compose.yml
+services:
+  convertx:
+    image: convertx/convertx-cn:latest
+    container_name: convertx-cn
+    restart: unless-stopped
+    volumes:
+      - ./data:/app/data
+    environment:
+      - JWT_SECRET=your-secret-key
+      - TRUST_PROXY=true
+      - HTTP_ALLOWED=false
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.convertx.rule=Host(`convertx.example.com`)"
+      - "traefik.http.routers.convertx.entrypoints=websecure"
+      - "traefik.http.routers.convertx.tls=true"
+      - "traefik.http.routers.convertx.tls.certresolver=letsencrypt"
+      - "traefik.http.services.convertx.loadbalancer.server.port=3000"
+    networks:
+      - traefik-network
+
+networks:
+  traefik-network:
+    external: true
+```
+
+#### 使用動態配置檔
+
+```yaml
+# traefik/dynamic/convertx.yml
+http:
+  routers:
+    convertx:
+      rule: "Host(`convertx.example.com`)"
+      service: convertx
+      entryPoints:
+        - websecure
+      tls:
+        certResolver: letsencrypt
+
+  services:
+    convertx:
+      loadBalancer:
+        servers:
+          - url: "http://127.0.0.1:3000"
+```
+
+### Caddy
+
+```
+# Caddyfile
+convertx.example.com {
+    reverse_proxy 127.0.0.1:3000
+
+    # 檔案上傳大小限制
+    request_body {
+        max_size 500MB
+    }
+}
+```
+
+Caddy 會自動處理 HTTPS 憑證。
+
+---
+
+## HTTPS 設定
+
+### Let's Encrypt（推薦）
+
+使用 Certbot 取得免費憑證：
+
+```bash
+# 安裝 Certbot
+sudo apt install certbot python3-certbot-nginx
+
+# 取得憑證（Nginx）
+sudo certbot --nginx -d convertx.example.com
+
+# 自動續約測試
+sudo certbot renew --dry-run
+```
+
+### 自簽憑證（測試用）
+
+```bash
+# 產生自簽憑證
+openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
+  -keyout /etc/ssl/private/convertx.key \
+  -out /etc/ssl/certs/convertx.crt \
+  -subj "/CN=convertx.example.com"
+```
+
+---
+
+## 安全性建議
+
+### 1. 環境變數設定
+
+```yaml
+environment:
+  # 必須設定固定值
+  - JWT_SECRET=使用 openssl rand -hex 32 產生
+
+  # 關閉不需要的功能
+  - ACCOUNT_REGISTRATION=false
+  - ALLOW_UNAUTHENTICATED=false
+  - HTTP_ALLOWED=false
+
+  # 定期清理檔案
+  - AUTO_DELETE_EVERY_N_HOURS=24
+```
+
+### 2. 防火牆設定
+
+```bash
+# 只開放 80 和 443
+sudo ufw allow 80/tcp
+sudo ufw allow 443/tcp
+sudo ufw enable
+
+# 不要直接開放 3000 埠
+```
+
+### 3. Docker 網路隔離
+
+```yaml
+services:
+  convertx:
+    # 只監聽 localhost
+    ports:
+      - "127.0.0.1:3000:3000"
+```
+
+### 4. 資源限制
+
+```yaml
+services:
+  convertx:
+    deploy:
+      resources:
+        limits:
+          cpus: "4"
+          memory: 8G
+        reservations:
+          cpus: "1"
+          memory: 2G
+```
+
+---
+
+## 子路徑部署
+
+若需要在子路徑部署（如 `https://example.com/convertx/`）：
+
+### 環境變數
+
+```yaml
+environment:
+  - WEBROOT=/convertx
+```
+
+### Nginx 設定
+
+```nginx
+location /convertx/ {
+    proxy_pass http://127.0.0.1:3000/;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+}
+```
+
+---
+
+## 效能調整
+
+### 1. 限制同時轉換數
+
+```yaml
+environment:
+  - MAX_CONVERT_PROCESS=4
+```
+
+### 2. FFmpeg 硬體加速
+
+```yaml
+environment:
+  # NVIDIA GPU
+  - FFMPEG_ARGS=-hwaccel cuda
+
+  # Intel QSV
+  - FFMPEG_ARGS=-hwaccel qsv
+
+  # AMD VAAPI
+  - FFMPEG_ARGS=-hwaccel vaapi
+```
+
+### 3. 容器資源限制
+
+見上方「資源限制」區塊。
+
+---
+
+## 備份與還原
+
+### 備份
+
+```bash
+# 停止容器
+docker compose stop
+
+# 備份 data 資料夾
+tar -czvf convertx-backup-$(date +%Y%m%d).tar.gz data/
+
+# 重新啟動
+docker compose start
+```
+
+### 自動備份腳本
+
+```bash
+#!/bin/bash
+# /opt/scripts/backup-convertx.sh
+
+BACKUP_DIR="/opt/backups/convertx"
+DATA_DIR="/opt/convertx/data"
+KEEP_DAYS=7
+
+# 建立備份
+mkdir -p $BACKUP_DIR
+tar -czvf "$BACKUP_DIR/convertx-$(date +%Y%m%d).tar.gz" -C $(dirname $DATA_DIR) $(basename $DATA_DIR)
+
+# 清理舊備份
+find $BACKUP_DIR -name "convertx-*.tar.gz" -mtime +$KEEP_DAYS -delete
+```
+
+加入 crontab：
+
+```bash
+# 每天凌晨 3 點備份
+0 3 * * * /opt/scripts/backup-convertx.sh
+```
+
+### 還原
+
+```bash
+# 停止容器
+docker compose stop
+
+# 還原 data 資料夾
+tar -xzvf convertx-backup-20260120.tar.gz
+
+# 重新啟動
+docker compose start
+```
+
+---
+
+## 常見問題
+
+### 問題：Reverse Proxy 後登入失敗
+
+**解決方案**：設定 `TRUST_PROXY=true`
+
+### 問題：上傳大檔案失敗
+
+**解決方案**：調整 Nginx 的 `client_max_body_size`
+
+### 問題：轉換超時
+
+**解決方案**：調整 Nginx 的 `proxy_read_timeout`
+
+---
+
+## 相關文件
+
+- [環境變數完整說明](environment-variables.md)
+- [Docker Compose 範例](docker-compose/)
+- [常見問題](faq.md)
--- a/docs/docker-compose/README.md
+++ b/docs/docker-compose/README.md
@ -0,0 +1,68 @@
+# Docker Compose 範例檔案
+
+本資料夾提供不同情境的 Docker Compose 範例。
+
+## 範例檔案
+
+| 檔案                                             | 適用情境    | 說明                      |
+| ------------------------------------------------ | ----------- | ------------------------- |
+| [compose.minimal.yml](compose.minimal.yml)       | Docker 老手 | 最精簡的可用配置          |
+| [compose.production.yml](compose.production.yml) | 生產環境    | 含 Reverse Proxy 設定說明 |
+| [compose.reference.yml](compose.reference.yml)   | 參考文件    | 所有可用設定的完整參考    |
+
+## 如何使用
+
+### 方式 1：直接使用範例檔案
+
+```bash
+# 下載範例
+curl -O https://raw.githubusercontent.com/pi-docket/ConvertX-CN/main/docs/docker-compose/compose.minimal.yml
+
+# 重命名為 docker-compose.yml
+mv compose.minimal.yml docker-compose.yml
+
+# 建立 data 資料夾
+mkdir -p data
+
+# 修改設定（至少要改 JWT_SECRET）
+nano docker-compose.yml
+
+# 啟動
+docker compose up -d
+```
+
+### 方式 2：複製內容
+
+1. 點擊上方檔案連結
+2. 複製內容
+3. 貼到你的 `docker-compose.yml`
+4. 修改必要設定
+5. 執行 `docker compose up -d`
+
+## 選擇指南
+
+### 我是新手
+
+請直接使用 [README 主頁](../../README.md) 的教學版範例。
+
+### 我熟悉 Docker
+
+使用 [compose.minimal.yml](compose.minimal.yml)，只需修改 `JWT_SECRET`。
+
+### 我要部署到正式環境
+
+使用 [compose.production.yml](compose.production.yml)，包含：
+
+- Reverse Proxy 設定說明
+- 安全性設定建議
+- HTTPS 配置範例
+
+### 我想了解所有設定
+
+參考 [compose.reference.yml](compose.reference.yml)，包含所有環境變數的說明。
+
+## 相關文件
+
+- [環境變數完整說明](../environment-variables.md)
+- [進階部署指南](../deployment.md)
+- [Docker 進階配置](../docker.md)
--- a/docs/docker-compose/compose.minimal.yml
+++ b/docs/docker-compose/compose.minimal.yml
@ -0,0 +1,24 @@
+# ==============================================================================
+# ConvertX-CN 精簡版 Docker Compose（適合 Docker 老手）
+#
+# ⚠️ 使用前請確認：
+#    1. 已建立 data 資料夾
+#    2. 已將 JWT_SECRET 改成你自己的值
+#
+# 📚 完整設定說明請見：docs/environment-variables.md
+# ==============================================================================
+
+services:
+  convertx:
+    image: convertx/convertx-cn:latest
+    container_name: convertx-cn
+    restart: unless-stopped
+    ports:
+      - "3000:3000"
+    volumes:
+      - ./data:/app/data
+    environment:
+      - TZ=Asia/Taipei
+      - JWT_SECRET=change-me-to-a-random-string-at-least-32-chars
+      - ACCOUNT_REGISTRATION=false
+      - HTTP_ALLOWED=false
--- a/docs/docker-compose/compose.production.yml
+++ b/docs/docker-compose/compose.production.yml
@ -0,0 +1,87 @@
+# ==============================================================================
+# ConvertX-CN 生產環境 Docker Compose
+#
+# 適用情境：
+#   - 透過 Reverse Proxy（Nginx / Traefik / Caddy）存取
+#   - 已設定 HTTPS
+#   - 需要限制註冊與存取
+#
+# ⚠️ 使用前請確認：
+#    1. 已建立 data 資料夾
+#    2. 已將 JWT_SECRET 改成你自己的值
+#    3. 已設定好 Reverse Proxy
+# ==============================================================================
+
+services:
+  convertx:
+    image: convertx/convertx-cn:latest
+    container_name: convertx-cn
+    restart: unless-stopped
+
+    # 生產環境通常只監聽 localhost，由 Reverse Proxy 轉發
+    # 若需要直接對外，改為 "3000:3000"
+    ports:
+      - "127.0.0.1:3000:3000"
+
+    volumes:
+      - ./data:/app/data
+
+    environment:
+      # === 必填設定 ===
+      # 🔐 JWT 密鑰：請務必改成你自己的隨機字串（至少 32 字元）
+      # 可用 openssl rand -hex 32 產生
+      - JWT_SECRET=change-me-to-a-very-long-random-string-at-least-32-characters
+
+      # === 安全設定 ===
+      # 關閉註冊（首次帳號仍可建立）
+      - ACCOUNT_REGISTRATION=false
+
+      # 不允許 HTTP（要求 HTTPS）
+      - HTTP_ALLOWED=false
+
+      # 信任 Reverse Proxy 的 X-Forwarded-* headers
+      - TRUST_PROXY=true
+
+      # 必須登入才能使用
+      - ALLOW_UNAUTHENTICATED=false
+
+      # === 時區與清理 ===
+      - TZ=Asia/Taipei
+      - AUTO_DELETE_EVERY_N_HOURS=24
+
+      # === 可選：子路徑部署 ===
+      # 若透過 https://example.com/convertx/ 存取，取消下行註解
+      # - WEBROOT=/convertx
+
+# ==============================================================================
+# Reverse Proxy 設定範例
+# ==============================================================================
+#
+# Nginx 範例：
+# -------------
+# server {
+#     listen 443 ssl http2;
+#     server_name example.com;
+#
+#     location / {
+#         proxy_pass http://127.0.0.1:3000;
+#         proxy_set_header Host $host;
+#         proxy_set_header X-Real-IP $remote_addr;
+#         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+#         proxy_set_header X-Forwarded-Proto $scheme;
+#
+#         # 檔案上傳大小限制
+#         client_max_body_size 500M;
+#     }
+# }
+#
+# Traefik 範例（labels）：
+# ------------------------
+# labels:
+#   - "traefik.enable=true"
+#   - "traefik.http.routers.convertx.rule=Host(`convertx.example.com`)"
+#   - "traefik.http.routers.convertx.tls=true"
+#   - "traefik.http.routers.convertx.tls.certresolver=letsencrypt"
+#   - "traefik.http.services.convertx.loadbalancer.server.port=3000"
+#
+# ==============================================================================
--- a/docs/docker-compose/compose.reference.yml
+++ b/docs/docker-compose/compose.reference.yml
@ -0,0 +1,131 @@
+# ==============================================================================
+# ConvertX-CN 完整參考 Docker Compose
+#
+# 📚 這是所有可用設定的完整參考
+#    大部分設定都有預設值，不需要全部設定
+#    請根據需求取消註解並修改
+#
+# 🎯 設定分類：
+#    [必填] - 生產環境必須設定
+#    [建議] - 建議設定以獲得最佳體驗
+#    [可選] - 依需求設定
+#    [進階] - 特殊情境才需要
+# ==============================================================================
+
+services:
+  convertx:
+    image: convertx/convertx-cn:latest
+    container_name: convertx-cn
+    restart: unless-stopped
+    ports:
+      - "3000:3000"
+    volumes:
+      - ./data:/app/data
+
+    environment:
+      # =========================================================================
+      # [必填] 安全性設定
+      # =========================================================================
+
+      # JWT 密鑰：用於使用者登入驗證的加密金鑰
+      # ⚠️ 生產環境必須設定固定值，否則每次重啟所有人都會被登出
+      # 產生方式：openssl rand -hex 32
+      - JWT_SECRET=your-very-long-random-secret-key-at-least-32-characters
+
+      # =========================================================================
+      # [建議] 基本設定
+      # =========================================================================
+
+      # 時區設定：影響檔案時間戳記與日期顯示
+      - TZ=Asia/Taipei
+
+      # 帳號註冊：是否允許新使用者註冊
+      # true  = 開放註冊
+      # false = 關閉註冊（首次帳號不受限制）
+      - ACCOUNT_REGISTRATION=false
+
+      # 自動清理：自動刪除超過 N 小時的轉換檔案
+      # 0 = 停用自動清理
+      - AUTO_DELETE_EVERY_N_HOURS=24
+
+      # =========================================================================
+      # [可選] HTTP / HTTPS 設定
+      # =========================================================================
+
+      # HTTP 存取：是否允許非 HTTPS 連線
+      # true  = 允許 HTTP（本地測試用）
+      # false = 必須 HTTPS（生產環境建議）
+      - HTTP_ALLOWED=false
+
+      # 信任 Proxy：透過 Reverse Proxy 存取時設為 true
+      # 讓應用正確判斷 X-Forwarded-Proto 等 headers
+      - TRUST_PROXY=false
+
+      # =========================================================================
+      # [可選] 存取控制
+      # =========================================================================
+
+      # 未登入存取：是否允許未登入使用者使用轉換功能
+      # true  = 允許匿名使用（公開服務）
+      # false = 必須登入
+      - ALLOW_UNAUTHENTICATED=false
+
+      # 未登入使用者共享空間：匿名使用者是否共享同一個檔案空間
+      # true  = 共享（所有匿名使用者看到相同檔案）
+      # false = 獨立（以 session 區分）
+      # - UNAUTHENTICATED_USER_SHARING=false
+
+      # =========================================================================
+      # [可選] 介面設定
+      # =========================================================================
+
+      # 子路徑部署：若透過子路徑存取（如 /convertx），設定此值
+      # 範例：https://example.com/convertx/ → WEBROOT=/convertx
+      # - WEBROOT=/convertx
+
+      # 隱藏歷史：是否隱藏轉換歷史頁面
+      # - HIDE_HISTORY=true
+
+      # 日期格式語言：影響介面上的日期顯示格式
+      # 使用 BCP 47 語言標籤
+      # - LANGUAGE=zh-TW
+
+      # =========================================================================
+      # [進階] 轉換設定
+      # =========================================================================
+
+      # 最大同時轉換數：限制同時進行的轉換任務數量
+      # 0 = 無限制
+      # - MAX_CONVERT_PROCESS=4
+
+      # FFmpeg 輸入參數：用於硬體加速等
+      # - FFMPEG_ARGS=-hwaccel cuda
+      # - FFMPEG_ARGS=-hwaccel qsv
+      # - FFMPEG_ARGS=-hwaccel vaapi
+
+      # FFmpeg 輸出參數：用於編碼設定等
+      # - FFMPEG_OUTPUT_ARGS=-preset veryfast
+
+# ==============================================================================
+# 環境變數快速參考
+# ==============================================================================
+#
+# | 變數名稱                      | 預設值     | 說明                      |
+# |-------------------------------|------------|---------------------------|
+# | JWT_SECRET                    | random     | JWT 簽署密鑰              |
+# | TZ                            | UTC        | 時區                      |
+# | ACCOUNT_REGISTRATION          | true       | 是否開放註冊              |
+# | HTTP_ALLOWED                  | false      | 是否允許 HTTP             |
+# | TRUST_PROXY                   | false      | 是否信任 Reverse Proxy    |
+# | ALLOW_UNAUTHENTICATED         | false      | 是否允許未登入使用        |
+# | AUTO_DELETE_EVERY_N_HOURS     | 24         | 自動清理時間（小時）      |
+# | WEBROOT                       | (空)       | 子路徑部署                |
+# | HIDE_HISTORY                  | false      | 隱藏歷史頁面              |
+# | LANGUAGE                      | en         | 日期格式語言              |
+# | MAX_CONVERT_PROCESS           | 0          | 最大同時轉換數            |
+# | FFMPEG_ARGS                   | (空)       | FFmpeg 輸入參數           |
+# | FFMPEG_OUTPUT_ARGS            | (空)       | FFmpeg 輸出參數           |
+# | UNAUTHENTICATED_USER_SHARING  | false      | 匿名使用者共享空間        |
+#
+# 完整說明請見：docs/environment-variables.md
+# ==============================================================================
--- a/docs/docker.md
+++ b/docs/docker.md
@ -11,7 +11,7 @@ ConvertX-CN 提供兩種 Docker Image 選項：
 | Tag                           | 說明       |
 | ----------------------------- | ---------- |
 | `convertx/convertx-cn:latest` | 最新穩定版 |
-| `convertx/convertx-cn:v0.1.6` | 指定版本號 |
+| `convertx/convertx-cn:v0.1.9` | 指定版本號 |

 **內建功能：**

--- a/docs/environment-variables.md
+++ b/docs/environment-variables.md
@ -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