Add comprehensive documentation for ConvertX-CN deployment and configuration

- Create 指定版本部署.md to explain fixed version deployment - Create 最新版.md detailing the use of the latest tag - Create 版本選擇指南.md to guide users on version selection - Add Nginx and Traefik configuration examples for reverse proxy - Introduce minimal and production configuration examples - Develop Docker deployment guide with detailed steps - Implement quick start guide for first-time Docker users - Include version update instructions and rollback procedures - Add troubleshooting section for common issues - Enhance overall documentation structure and links for better navigation
2026-01-23 22:05:09 +08:00 · 2026-01-23 22:05:09 +08:00 · 3f1a5e0fbf
commit 3f1a5e0fbf
parent c2d3d13c89
51 changed files with 544 additions and 579 deletions
--- a/docs/Docker組合配置/README.md
+++ b/docs/Docker組合配置/README.md
@ -0,0 +1,63 @@
+# 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)   | 參考文件    | 所有設定的完整參考    |
+
+## 快速選擇
+
+| 你是...      | 使用                          |
+| ------------ | ----------------------------- |
+| 新手         | [README 主頁](../說明文件.md) |
+| Docker 熟手  | compose.minimal.yml           |
+| 生產環境     | compose.production.yml        |
+| 查詢所有選項 | compose.reference.yml         |
+
+## 如何使用
+
+```bash
+# 下載範例
+curl -O https://raw.githubusercontent.com/pi-docket/ConvertX-CN/main/docs/docker-compose/compose.minimal.yml
+
+# 重命名
+mv compose.minimal.yml docker-compose.yml
+
+# 建立 data 資料夾
+mkdir -p data
+
+# 修改 JWT_SECRET
+nano docker-compose.yml
+
+# 啟動
+docker compose up -d
+```
+
+## 相關文件
+
+- [Docker Compose 詳解](../部署指南/Docker組合.md)
+- [環境變數說明](../配置設定/環境變數.md)
+- [版本選擇指南](../版本/)
+
+### 我要部署到正式環境
+
+使用 [compose.production.yml](compose.production.yml)，包含：
+
+- Reverse Proxy 設定說明
+- 安全性設定建議
+- HTTPS 配置範例
+
+### 我想了解所有設定
+
+參考 [compose.reference.yml](compose.reference.yml)，包含所有環境變數的說明。
+
+## 相關文件
+
+- [環境變數完整說明](../環境變數總覽.md)
+- [進階部署指南](../部署總覽.md)
+- [Docker 進階配置](../Docker說明.md)
--- a/docs/Docker組合配置/compose.minimal.yml
+++ b/docs/Docker組合配置/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.production.yml
+++ b/docs/Docker組合配置/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.reference.yml
+++ b/docs/Docker組合配置/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組合配置/生產環境配置.yml
+++ b/docs/Docker組合配置/生產環境配置.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組合配置/說明文件.md
+++ b/docs/Docker組合配置/說明文件.md
@ -0,0 +1,57 @@
+# 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)   | 參考文件    | 所有設定的完整參考    |
+
+## 快速選擇
+
+| 你是...      | 使用                          |
+| ------------ | ----------------------------- |
+| 新手         | [README 主頁](../說明文件.md) |
+| Docker 熟手  | compose.minimal.yml           |
+| 生產環境     | compose.production.yml        |
+| 查詢所有選項 | compose.reference.yml         |
+
+## 如何使用
+
+```bash
+# 下載範例
+curl -O https://raw.githubusercontent.com/pi-docket/ConvertX-CN/main/docs/Docker組合配置/compose.minimal.yml
+
+# 重命名
+mv compose.minimal.yml docker-compose.yml
+
+# 建立 data 資料夾
+mkdir -p data
+
+# 修改 JWT_SECRET
+nano docker-compose.yml
+
+# 啟動
+docker compose up -d
+```
+
+## 相關文件
+
+- [Docker Compose 詳解](../部署指南/Docker組合.md)
+- [環境變數說明](../配置設定/環境變數.md)
+- [版本選擇指南](../版本/)
+
+### 我要部署到正式環境
+
+使用 [compose.production.yml](compose.production.yml)，包含：
+
+- Reverse Proxy 設定說明
+- 安全性設定建議
+- HTTPS 配置範例
+
+### 我想了解所有設定
+
+參考 [compose.reference.yml](compose.reference.yml)，包含所有環境變數的說明。