From a45a049fe20531776733081c2b5398852077ee01 Mon Sep 17 00:00:00 2001 From: Your Name Date: Tue, 20 Jan 2026 15:09:30 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20v0.1.9=20-=20=E5=85=A8=E9=A0=81?= =?UTF-8?q?=E6=8B=96=E6=9B=B3=E4=B8=8A=E5=82=B3=20+=20i18n=20=E4=BF=AE?= =?UTF-8?q?=E6=AD=A3=20+=20=E6=96=87=E4=BB=B6=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ✨ Features: - 全頁拖曳上傳：檔案可拖曳到頁面任何位置上傳 - 原本的上傳框視覺效果保持不變 🌍 i18n: - 刪除任務的 confirm/alert 訊息改用 i18n - 隨語言切換即時更新顯示內容 📚 Documentation: - README 新增「如何更新 ConvertX-CN 版本」章節 - 新增 deployment.md（Reverse Proxy、HTTPS） - 新增 Docker Compose 範例分層 - 更新 environment-variables.md --- CHANGELOG.md | 58 ++++ Dockerfile | 2 +- README.md | 349 +++++++++++++++---- compose.yaml | 200 +++++++++-- docs/deployment.md | 382 +++++++++++++++++++++ docs/docker-compose/README.md | 68 ++++ docs/docker-compose/compose.minimal.yml | 24 ++ docs/docker-compose/compose.production.yml | 87 +++++ docs/docker-compose/compose.reference.yml | 131 +++++++ docs/docker.md | 2 +- docs/environment-variables.md | 273 +++++++++++---- package.json | 2 +- public/script.js | 51 +++ src/pages/history.tsx | 13 +- 14 files changed, 1475 insertions(+), 167 deletions(-) create mode 100644 docs/deployment.md create mode 100644 docs/docker-compose/README.md create mode 100644 docs/docker-compose/compose.minimal.yml create mode 100644 docs/docker-compose/compose.production.yml create mode 100644 docs/docker-compose/compose.reference.yml diff --git a/CHANGELOG.md b/CHANGELOG.md index 3cad6e2..a387912 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,63 @@ # Changelog +## [0.1.9](https://github.com/pi-docket/ConvertX-CN/releases/tag/v0.1.9) (2026-01-20) + +### ✨ Features + +- **全頁拖曳上傳**：檔案可拖曳到頁面任何位置上傳 + - 不再需要精準拖到上傳框內 + - 原本的上傳框視覺效果保持不變 + - 點擊上傳功能不受影響 + +### 🌍 i18n + +- **提示訊息國際化**：所有 confirm / alert 訊息改用 i18n + - 刪除任務前的確認提示 + - 刪除成功 / 失敗提示 + - 錯誤訊息 + - 隨語言切換即時更新顯示內容 + +### 📚 Documentation + +- **新增版本更新教學**：README 新增「如何更新 ConvertX-CN 版本」章節 + - 完整的 Docker Compose 更新步驟 + - 更新到指定版本的方法 + - 驗證更新成功的方式 + +- **README 重新定位**：從參考手冊改為「新手教學入口」 + - 完整 5 步驟部署教學（從安裝 Docker 到成功使用） + - 跨平台 data 資料夾建立指令（Linux / macOS / Windows） + - 常見問題 FAQ（登入失敗、資料遺失、被登出） + - 明確說明為何範例保留完整註解（教學導向） + +- **Docker Compose 範例分層**： + - `compose.minimal.yml` - 精簡版（Docker 老手） + - `compose.production.yml` - 生產環境（含 Reverse Proxy 說明） + - `compose.reference.yml` - 完整參考（所有環境變數） + +- **新增 deployment.md**： + - Reverse Proxy 設定（Nginx / Traefik / Caddy） + - HTTPS / Let's Encrypt 設定 + - 安全性建議與防火牆設定 + - 備份與還原指南 + +- **更新 environment-variables.md**： + - 依重要程度分類（必填 / 建議 / 可選） + - 每個變數都有詳細設定指南 + - 常見情境範例 + +### 🎯 Design Philosophy + +本專案的 README 與 docker-compose.yml 定位為「教學版」： + +- README 是新手的第一個成功體驗 +- docker-compose.yml 寧願註解多，也不要極簡 +- 強調「為什麼要這樣設」與「不這樣設會怎樣」 + +如需精簡版配置，請使用 `docs/docker-compose/compose.minimal.yml`。 + +--- + ## [0.1.8](https://github.com/pi-docket/ConvertX-CN/releases/tag/v0.1.8) (2026-01-20) ### 🐛 Bug Fixes diff --git a/Dockerfile b/Dockerfile index 961251b..1113226 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,6 +1,6 @@ # ============================================================================== # ConvertX-CN 官方 Docker Image -# 版本：v0.1.8 +# 版本：v0.1.9 # ============================================================================== # # 📦 Image 說明： diff --git a/README.md b/README.md index a90839f..daa7fd7 100644 --- a/README.md +++ b/README.md @@ -31,51 +31,279 @@ ConvertX-CN 是基於 [C4illin/ConvertX](https://github.com/C4illin/ConvertX) --- -## 🚀 快速開始 +## 📚 關於本文件 -### 最快方式：Docker Run +> **📖 本 README 定位為「新手教學入口」** +> +> 我們的 `docker-compose.yml` 範例**刻意保留完整註解**，而非極簡化： +> +> - ✅ 讓第一次用 Docker 的人也能成功部署 +> - ✅ 透過註解說明每個設定的意義與風險 +> - ✅ 避免新手踩雷（登入失敗、資料遺失等） +> +> 如果你是 Docker 老手，可直接使用 [精簡版範例](docs/docker-compose/compose.minimal.yml)。 + +--- + +## 🚀 新手完整部署教學（一步一步） + +> ⚠️ **請務必按順序執行，不要跳過任何步驟！** + +### 步驟 1：安裝 Docker + +如果尚未安裝 Docker，請先安裝： + +- **Windows / macOS**: 下載 [Docker Desktop](https://www.docker.com/products/docker-desktop/) +- **Linux**: 執行 `curl -fsSL https://get.docker.com | sh` + +### 步驟 2：建立 data 資料夾（⚠️ 非常重要） + +> 🚨 **這一步絕對不能跳過！** +> +> `data` 資料夾是用來存放： +> +> - 📁 上傳的檔案 +> - 📁 轉換後的結果 +> - 📁 使用者資料與設定 +> +> **如果不先建立這個資料夾**，Docker 可能會建立「匿名 volume」，導致： +> +> - ❌ 容器刪除後資料全部消失 +> - ❌ 無法在主機上找到轉換結果 +> - ❌ 難以備份與遷移 + +**請根據你的作業系統執行對應指令：** + +#### Linux / macOS ```bash -# 1. 建立資料夾 +# 建立專案資料夾（可自訂位置） +mkdir -p ~/convertx-cn +cd ~/convertx-cn + +# 建立 data 資料夾 mkdir -p data -# 2. 啟動容器 -docker run -d \ - --name convertx-cn \ - -p 3000:3000 \ - -v ./data:/app/data \ - -e TZ=Asia/Taipei \ - convertx/convertx-cn:latest +# 確認資料夾已建立 +ls -la +# 應該看到 data 資料夾 ``` -開啟瀏覽器訪問 `http://localhost:3000`，**直接註冊帳號**即可使用！ +#### Windows（PowerShell） -> ✅ **預設開放註冊**：無需設定環境變數，首次使用直接點擊 Register 註冊 +```powershell +# 建立專案資料夾（可自訂位置） +mkdir C:\convertx-cn +cd C:\convertx-cn -### 推薦方式：Docker Compose +# 建立 data 資料夾 +mkdir data -建立 `docker-compose.yml`： +# 確認資料夾已建立 +dir +# 應該看到 data 資料夾 +``` + +#### Windows（CMD） + +```cmd +:: 建立專案資料夾（可自訂位置） +mkdir C:\convertx-cn +cd C:\convertx-cn + +:: 建立 data 資料夾 +mkdir data + +:: 確認資料夾已建立 +dir +:: 應該看到 data 資料夾 +``` + +### 步驟 3：建立 docker-compose.yml + +在剛才建立的資料夾中，建立 `docker-compose.yml` 檔案： + +```yaml +# ============================================================================== +# ConvertX-CN 新手教學版 docker-compose.yml +# +# 📚 這份範例刻意保留完整註解，讓第一次用 Docker 的人也能成功部署 +# ============================================================================== + +services: + convertx: + # ===== 映像檔設定 ===== + # convertx-cn 是完整版，已內建所有轉換工具（約 4-6 GB） + image: convertx/convertx-cn:latest + container_name: convertx-cn + restart: unless-stopped + + # ===== 連接埠設定 ===== + # 格式：「主機埠號:容器埠號」 + # 若 3000 埠已被佔用，可改為 3001:3000、8080:3000 等 + ports: + - "3000:3000" + + # ===== 資料儲存（⚠️ 非常重要）===== + # ./data 是你主機上的實體資料夾 + # /app/data 是容器內的路徑 + # + # 🚨 注意事項： + # 1. 請務必先建立 data 資料夾（見上方步驟 2） + # 2. 這裡存放：上傳檔案、轉換結果、使用者資料 + # 3. 若改用 Docker volume（如 convertx_data:/app/data）， + # 資料會存在 Docker 內部，較難直接存取 + volumes: + - ./data:/app/data + + # ===== 環境變數設定 ===== + environment: + # --- 時區設定 --- + # 影響檔案時間戳記與日期顯示 + - TZ=Asia/Taipei + + # --- JWT 密鑰（🔐 建議設定）--- + # 用於使用者登入驗證的加密金鑰 + # ⚠️ 若不設定：每次重啟容器後所有人都會被登出 + # ⚠️ 正式使用請改成你自己的隨機字串！ + - JWT_SECRET=請改成你自己的長隨機字串-至少32個字元 + + # --- 帳號註冊 --- + # true = 允許任何人註冊新帳號 + # false = 關閉註冊（建議正式使用時設為 false） + # 💡 首次建立的帳號不受此限制 + - ACCOUNT_REGISTRATION=true + + # --- HTTP 存取設定 --- + # true = 允許非 HTTPS 連線（⚠️ 不安全，僅本地測試用） + # false = 必須 HTTPS（Cookie 才會正常運作） + # + # 🏠 本地測試（localhost）：設為 true + # 🌐 遠端部署（有 HTTPS）：設為 false + - HTTP_ALLOWED=true + + # --- Reverse Proxy 設定 --- + # 若你透過 Nginx / Traefik / Cloudflare 等存取，設為 true + # 讓應用正確判斷連線是否為 HTTPS + - TRUST_PROXY=false + + # --- 未登入存取 --- + # true = 允許未登入使用轉換功能（⚠️ 公開服務才開） + # false = 必須登入才能使用 + - ALLOW_UNAUTHENTICATED=false + + # --- 自動清理 --- + # 自動刪除超過 N 小時的轉換檔案（0 = 不自動刪除） + - AUTO_DELETE_EVERY_N_HOURS=24 +``` + +### 步驟 4：啟動服務 + +```bash +# 啟動（首次會下載映像檔，約 4-6 GB，請耐心等待） +docker compose up -d + +# 查看執行狀態 +docker compose ps + +# 查看 log（確認沒有錯誤） +docker compose logs -f +# 按 Ctrl+C 可退出 log 查看 +``` + +### 步驟 5：開啟瀏覽器使用 + +1. 開啟瀏覽器，訪問 `http://localhost:3000` +2. 點擊 **Register** 註冊第一個帳號 +3. 登入後即可開始轉換檔案！ + +> ✅ **首次註冊的帳號會自動成為管理員** + +--- + +## ⚠️ 新手常見問題與解決方案 + +### 問題 1：登入後又被導回登入頁 + +**原因**：Cookie 無法正確設定（常見於遠端部署） + +**解決方案**： + +- 若使用 HTTP（無 HTTPS）：設定 `HTTP_ALLOWED=true` +- 若透過 Reverse Proxy：設定 `TRUST_PROXY=true` + +### 問題 2：重啟容器後資料消失 + +**原因**：沒有正確掛載 volume + +**解決方案**： + +1. 確認已建立 `data` 資料夾 +2. 確認 docker-compose.yml 中有 `./data:/app/data` +3. 不要使用 `docker run` 時忘記加 `-v ./data:/app/data` + +### 問題 3：重啟後所有人被登出 + +**原因**：沒有設定 `JWT_SECRET` + +**解決方案**：設定固定的 `JWT_SECRET` 環境變數 + +### 問題 4：3000 埠被佔用 + +**解決方案**：改用其他埠號，如 `"8080:3000"` + +--- + +## � 如何更新 ConvertX-CN 版本 + +> 當有新版本發布時，請依照以下步驟更新。 + +### 使用 Docker Compose 更新（推薦） + +```bash +# 1. 進入你的 ConvertX-CN 專案資料夾 +cd ~/convertx-cn # 或你當初建立的位置 + +# 2. 停止目前執行中的服務 +docker compose down + +# 3. 拉取最新的映像檔 +docker compose pull + +# 4. 重新啟動服務 +docker compose up -d + +# 5. 確認版本（查看 log） +docker compose logs | head -20 +``` + +### 更新到指定版本 + +如果你想更新到特定版本（例如 v0.1.9），請修改 `docker-compose.yml`： ```yaml 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=your-secret-key-change-me + image: convertx/convertx-cn:v0.1.9 # 改成指定版本 ``` +然後執行： + ```bash +docker compose down +docker compose pull docker compose up -d ``` -📖 完整部署指南請見 → [docs/getting-started.md](docs/getting-started.md) +### 驗證更新成功 + +開啟瀏覽器訪問 `http://localhost:3000`，頁面底部會顯示版本號。 + +--- + +## �🔧 進階設定 + +更多進階設定請參考：[docs/environment-variables.md](docs/environment-variables.md) --- @@ -83,13 +311,12 @@ docker compose up -d ConvertX-CN 支援 **65 種語言**，包括： -| 區域 | 語言 | -| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **東亞** | 繁體中文（預設）、简体中文、日本語、한국어 | -| **歐洲** | English, Deutsch, Français, Español, Italiano, Português, Русский, Polski, Nederlands, Українська, Čeština, Svenska, Dansk, Suomi, Norsk, Ελληνικά, Magyar, Română, Български, Hrvatski, Slovenčina, Slovenščina, Lietuvių, Latviešu, Eesti, Српски, Català, Euskara, Galego, Íslenska, Gaeilge, Cymraeg, Malti, Македонски, Shqip | -| **中東/南亞** | العربية, עברית, فارسی, Türkçe, हिन्दी, বাংলা, தமிழ், తెలుగు, मराठी, ગુજરાતી, ಕನ್ನಡ, മലയാളം, नेपाली, සිංහල | -| **東南亞** | ไทย, Tiếng Việt, Bahasa Indonesia, Bahasa Melayu, Filipino, မြန်မာ, ខ្មែរ, ລາວ | -| **非洲** | Afrikaans, Kiswahili, አማርኛ, isiZulu | +| 區域 | 語言 | +| ------------- | ------------------------------------------------ | +| **東亞** | 繁體中文（預設）、简体中文、日本語、한국어 | +| **歐洲** | English, Deutsch, Français, Español, Italiano 等 | +| **中東/南亞** | العربية, עברית, हिन्दी, தமிழ் 等 | +| **東南亞** | ไทย, Tiếng Việt, Bahasa Indonesia 等 | 語言會根據瀏覽器設定自動偵測，也可透過右上角選單手動切換。 @@ -97,42 +324,42 @@ ConvertX-CN 支援 **65 種語言**，包括： ## 📦 內建轉換器 -| 轉換器 | 用途 | 輸入格式 | 輸出格式 | -| -------------- | ------- | -------- | -------- | -| FFmpeg | 影音 | ~472 | ~199 | -| ImageMagick | 圖片 | 245 | 183 | -| GraphicsMagick | 圖片 | 167 | 130 | -| LibreOffice | 文件 | 41 | 22 | -| Pandoc | 文件 | 43 | 65 | -| Calibre | 電子書 | 26 | 19 | -| Inkscape | 向量圖 | 7 | 17 | -| Assimp | 3D 模型 | 77 | 23 | +| 轉換器 | 用途 | 支援格式數 | +| ----------- | ------ | ---------- | +| FFmpeg | 影音 | 400+ | +| ImageMagick | 圖片 | 200+ | +| LibreOffice | 文件 | 60+ | +| Pandoc | 文件 | 100+ | +| Calibre | 電子書 | 40+ | +| Inkscape | 向量圖 | 20+ | 完整列表 → [docs/converters.md](docs/converters.md) --- -## 📖 文件導覽 - -| 文件 | 說明 | -| -------------------------------------------- | ---------------------- | -| [🚀 快速開始](docs/getting-started.md) | Docker 部署教學 | -| [🐳 Docker 配置](docs/docker.md) | 完整 Docker 設定指南 | -| [⚙️ 環境變數](docs/environment-variables.md) | 所有環境變數說明 | -| [❓ 常見問題](docs/faq.md) | FAQ 疑難排解 | -| [🌍 多語言](docs/i18n.md) | i18n 語言設定與新增 | -| [📦 轉換器列表](docs/converters.md) | 支援的轉換格式完整列表 | - ---- - -## 🐳 Docker Image +## 🐳 Docker Image 資訊 | Tag | 說明 | | ----------------------------- | ---------- | | `convertx/convertx-cn:latest` | 最新穩定版 | -| `convertx/convertx-cn:v0.1.5` | 指定版本 | +| `convertx/convertx-cn:v0.1.9` | 指定版本 | -> ⚠️ 由於內建完整依賴，Image 約 4-6 GB，首次下載需較長時間。 +> ⚠️ **首次下載說明** +> 由於內建完整依賴（LibreOffice、TexLive 等），映像檔約 **4-6 GB**。 +> 首次 `docker pull` 需要較長時間，請耐心等待。 + +--- + +## 📖 更多文件 + +| 文件 | 說明 | +| ---------------------------------------------- | -------------------------- | +| [⚙️ 環境變數](docs/environment-variables.md) | 所有環境變數完整說明 | +| [🚀 進階部署](docs/deployment.md) | Reverse Proxy、HTTPS、生產 | +| [🐳 Docker 進階](docs/docker.md) | 自訂 Build、Image 說明 | +| [📦 轉換器列表](docs/converters.md) | 支援的格式完整列表 | +| [❓ 常見問題](docs/faq.md) | 更多疑難排解 | +| [📁 Docker Compose 範例](docs/docker-compose/) | 各種情境的範例檔案 | --- @@ -142,7 +369,7 @@ ConvertX-CN 支援 **65 種語言**，包括： --- -## 🛠️ 開發 +## 🛠️ 開發者資訊 ```bash # 安裝依賴 @@ -163,10 +390,6 @@ bun run build 本專案基於 [C4illin/ConvertX](https://github.com/C4illin/ConvertX) 開發。 - - Contributors - - --- ## 📜 License diff --git a/compose.yaml b/compose.yaml index a3c36c9..d7995e8 100644 --- a/compose.yaml +++ b/compose.yaml @@ -1,50 +1,194 @@ # ============================================================================== -# ConvertX-CN 部署範例（docker-compose.yml / compose.yaml） +# ConvertX-CN Docker Compose 教學版範例 +# +# 📚 這份範例的設計理念： +# - 刻意保留完整註解，讓第一次用 Docker 的人也能成功部署 +# - 每個設定都有說明其用途與風險 +# - 如果你是 Docker 老手，可以自行精簡 # # 🎉 這是完整版 image，已內建所有轉換依賴： -# - LibreOffice (headless) -# - TexLive（CJK + 阿拉伯/希伯來語） +# - LibreOffice (headless) - 文件轉換 +# - TexLive Full - LaTeX 完整版（含 CJK、阿拉伯、希伯來語支援） # - Tesseract OCR + 中日韓英德法語言包 -# - CJK 字型（Noto CJK、標楷體） -# - Pandoc、FFmpeg、ImageMagick、OpenCV 等所有轉換器 +# - CJK 字型（Noto CJK、標楷體、微軟核心字型） +# - Pandoc、FFmpeg、ImageMagick、Calibre 等所有轉換器 # # ✅ 使用者不需要自己寫 Dockerfile # ✅ 直接 docker compose up -d 即可使用 # -# ⚠️ 遠端部署注意事項： -# 若透過 Nginx/Traefik 等 reverse proxy 存取，請設定： -# - HTTP_ALLOWED=true（若 proxy 處理 HTTPS） -# - 或 TRUST_PROXY=true（讓應用正確判斷 HTTPS） +# ⚠️ 部署前必做： +# 1. 先建立 data 資料夾（見 README.md 步驟 2） +# 2. 修改 JWT_SECRET 為你自己的隨機字串 # ============================================================================== services: convertx: + # ========================================================================= + # 映像檔設定 + # ========================================================================= + # convertx-cn 是完整版，已內建所有轉換工具 + # ⚠️ 首次下載約 4-6 GB，請耐心等待 image: convertx/convertx-cn:latest + + # 容器名稱，方便識別與管理 container_name: convertx-cn + + # 重啟策略： + # - unless-stopped：除非手動停止，否則自動重啟（推薦） + # - always：永遠自動重啟 + # - no：不自動重啟 restart: unless-stopped + + # ========================================================================= + # 連接埠設定 + # ========================================================================= + # 格式：「主機埠號:容器埠號」 + # + # 範例： + # - "3000:3000" → http://localhost:3000 + # - "8080:3000" → http://localhost:8080 + # - "80:3000" → http://localhost（需要 root 權限） + # + # 💡 若 3000 埠被佔用，改第一個數字即可 ports: - "3000:3000" + + # ========================================================================= + # 資料儲存設定（⚠️ 非常重要） + # ========================================================================= + # 格式：「主機路徑:容器路徑」 + # + # ./data 是你主機上的實體資料夾（相對於 docker-compose.yml 的位置） + # /app/data 是容器內的路徑 + # + # 這裡存放： + # 📁 上傳的檔案 + # 📁 轉換後的結果 + # 📁 使用者帳號資料（SQLite 資料庫） + # + # 🚨 重要提醒： + # 1. 請務必先建立 data 資料夾再啟動容器！ + # 若資料夾不存在，Docker 可能會建立「匿名 volume」， + # 這會導致容器刪除後資料全部遺失，且難以找回。 + # + # 2. 如果你想用 Docker named volume 取代本地資料夾： + # - convertx_data:/app/data + # 但資料會存在 Docker 內部，較難直接存取與備份。 + # + # 3. 建議定期備份 data 資料夾！ volumes: - ./data:/app/data + + # ========================================================================= + # 環境變數設定 + # ========================================================================= environment: - # === 帳號設定 === - - ACCOUNT_REGISTRATION=false # 是否允許註冊新帳號（首次帳號不受此限制） - - JWT_SECRET=請更換為一個長且隨機的字串 # 若不設定則使用 randomUUID() - - # === 安全設定 === - - HTTP_ALLOWED=false # 是否允許非 HTTPS 連線（僅本地測試時設為 true） - - TRUST_PROXY=false # 透過 reverse proxy 時設為 true（正確判斷 HTTPS） - - ALLOW_UNAUTHENTICATED=false # 是否允許未登入使用（僅本地測試時設為 true） - - # === 檔案管理 === - - AUTO_DELETE_EVERY_N_HOURS=24 # 自動刪除超過 N 小時的檔案（0 = 停用） - - # === 時區設定 === + # ----------------------------------------------------------------------- + # 時區設定 + # ----------------------------------------------------------------------- + # 影響檔案時間戳記與日期顯示格式 + # 常用值：Asia/Taipei, Asia/Shanghai, America/New_York, Europe/London - TZ=Asia/Taipei - # === 可選設定 === - # - WEBROOT=/convertx # 子路徑部署（例如 example.com/convertx/） - # - HIDE_HISTORY=true # 隱藏歷史紀錄頁面 - # - LANGUAGE=zh-TW # 日期格式語言 - # - FFMPEG_ARGS=-hwaccel vaapi # FFmpeg 硬體加速參數 - # - MAX_CONVERT_PROCESS=4 # 最大同時轉換數（0 = 無限制） + # ----------------------------------------------------------------------- + # JWT 密鑰（🔐 強烈建議設定） + # ----------------------------------------------------------------------- + # 用於使用者登入驗證的加密金鑰 + # + # ⚠️ 若不設定會怎樣？ + # 系統會使用 randomUUID() 產生臨時金鑰， + # 但每次容器重啟後金鑰會改變，導致： + # → 所有使用者的登入狀態失效 + # → 所有人都需要重新登入 + # + # ✅ 正確做法： + # 設定一個長且隨機的字串（建議 32 字元以上） + # 可以用 openssl rand -hex 32 產生 + # + # 🚨 請務必將下面的值改成你自己的！ + - JWT_SECRET=請改成你自己的長隨機字串-至少32個字元-不要用這個預設值 + + # ----------------------------------------------------------------------- + # 帳號註冊設定 + # ----------------------------------------------------------------------- + # true = 允許任何人註冊新帳號 + # false = 關閉註冊功能 + # + # 💡 注意：首次註冊的帳號不受此限制 + # 即使設為 false，仍可註冊第一個帳號（管理員） + # + # 📌 建議： + # - 首次部署時設為 true，註冊好帳號後改為 false + # - 或者直接設為 false，只用第一個註冊的帳號 + - ACCOUNT_REGISTRATION=true + + # ----------------------------------------------------------------------- + # HTTP 存取設定（🔒 安全性相關） + # ----------------------------------------------------------------------- + # true = 允許非 HTTPS 連線 + # false = 必須 HTTPS 連線（Cookie 設定 Secure 屬性） + # + # ⚠️ 這個設定影響登入功能是否正常運作！ + # + # 📌 設定指南： + # 🏠 本地測試（http://localhost） → true + # 🌐 遠端部署且有 HTTPS → false + # 🌐 遠端部署但沒有 HTTPS（不建議） → true（但不安全） + # + # 🚨 常見問題： + # 若設為 false 但實際用 HTTP 存取， + # 會導致「登入後又被導回登入頁」的問題 + - HTTP_ALLOWED=true + + # ----------------------------------------------------------------------- + # Reverse Proxy 信任設定 + # ----------------------------------------------------------------------- + # 若你透過 Nginx / Traefik / Cloudflare / Caddy 等存取，設為 true + # + # 作用：讓應用程式信任 X-Forwarded-Proto 等 header， + # 正確判斷連線是否為 HTTPS + # + # 📌 設定指南： + # 直接存取容器（無 proxy） → false + # 透過 reverse proxy 存取 → true + - TRUST_PROXY=false + + # ----------------------------------------------------------------------- + # 未登入存取設定 + # ----------------------------------------------------------------------- + # true = 允許未登入的訪客使用轉換功能 + # false = 必須登入才能使用 + # + # ⚠️ 設為 true 的風險： + # - 任何人都可以使用你的服務器資源 + # - 可能被濫用（大量轉換、儲存空間耗盡） + # + # 📌 建議：除非你明確要提供公開服務，否則設為 false + - ALLOW_UNAUTHENTICATED=false + + # ----------------------------------------------------------------------- + # 自動清理設定 + # ----------------------------------------------------------------------- + # 自動刪除超過 N 小時的轉換檔案 + # 設為 0 = 停用自動刪除 + # + # 💡 建議設定適當的值，避免磁碟空間被轉換檔案塞滿 + - AUTO_DELETE_EVERY_N_HOURS=24 + + # ----------------------------------------------------------------------- + # 進階設定（可選，需要時取消註解） + # ----------------------------------------------------------------------- + # 子路徑部署（例如 https://example.com/convertx/） + # - WEBROOT=/convertx + + # 隱藏歷史紀錄頁面 + # - HIDE_HISTORY=true + + # 日期格式語言（影響時間顯示格式） + # - LANGUAGE=zh-TW + + # FFmpeg 硬體加速參數 + # - FFMPEG_ARGS=-hwaccel vaapi + + # 最大同時轉換數（0 = 無限制） + # - MAX_CONVERT_PROCESS=4 diff --git a/docs/deployment.md b/docs/deployment.md new file mode 100644 index 0000000..1e063a3 --- /dev/null +++ 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) diff --git a/docs/docker-compose/README.md b/docs/docker-compose/README.md new file mode 100644 index 0000000..a53a516 --- /dev/null +++ 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) diff --git a/docs/docker-compose/compose.minimal.yml b/docs/docker-compose/compose.minimal.yml new file mode 100644 index 0000000..0ffa684 --- /dev/null +++ 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 diff --git a/docs/docker-compose/compose.production.yml b/docs/docker-compose/compose.production.yml new file mode 100644 index 0000000..a96e64e --- /dev/null +++ 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" +# +# ============================================================================== diff --git a/docs/docker-compose/compose.reference.yml b/docs/docker-compose/compose.reference.yml new file mode 100644 index 0000000..c3caae7 --- /dev/null +++ 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 +# ============================================================================== diff --git a/docs/docker.md b/docs/docker.md index 66f406b..7448e9c 100644 --- 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` | 指定版本號 | **內建功能：** diff --git a/docs/environment-variables.md b/docs/environment-variables.md index 9541075..44e52f0 100644 --- 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 diff --git a/package.json b/package.json index e78705f..0c39ff0 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "convertx-frontend", - "version": "0.1.8", + "version": "0.1.9", "scripts": { "dev": "bun run --watch src/index.tsx", "hot": "bun run --hot src/index.tsx", diff --git a/public/script.js b/public/script.js index 7ac410b..ec2931c 100644 --- a/public/script.js +++ b/public/script.js @@ -55,6 +55,57 @@ dropZone.addEventListener("drop", (e) => { } }); +// ===== 全頁拖曳上傳支援 ===== +// 允許使用者將檔案拖曳到頁面任何位置即可上傳 +// UI 完全不變，只是擴大拖曳的偵測範圍 + +let dragCounter = 0; + +document.addEventListener("dragenter", (e) => { + e.preventDefault(); + dragCounter++; + // 當檔案進入頁面時，顯示 dropzone 的 dragover 效果 + if (e.dataTransfer.types.includes("Files")) { + dropZone.classList.add("dragover"); + } +}); + +document.addEventListener("dragleave", (e) => { + e.preventDefault(); + dragCounter--; + // 只有當完全離開頁面時才移除效果 + if (dragCounter === 0) { + dropZone.classList.remove("dragover"); + } +}); + +document.addEventListener("dragover", (e) => { + e.preventDefault(); + // 保持 dragover 效果 + if (e.dataTransfer.types.includes("Files")) { + dropZone.classList.add("dragover"); + } +}); + +document.addEventListener("drop", (e) => { + e.preventDefault(); + dragCounter = 0; + dropZone.classList.remove("dragover"); + + const files = e.dataTransfer.files; + + if (files.length === 0) { + console.warn("No files dropped — likely a URL or unsupported source."); + return; + } + + for (const file of files) { + console.log("Handling dropped file (page-level):", file.name); + handleFile(file); + } +}); +// ===== 全頁拖曳上傳支援結束 ===== + // Extracted handleFile function for reusability in drag-and-drop and file input function handleFile(file) { const fileList = document.querySelector("#file-list"); diff --git a/src/pages/history.tsx b/src/pages/history.tsx index 35faa59..c7161b7 100644 --- a/src/pages/history.tsx +++ b/src/pages/history.tsx @@ -311,7 +311,8 @@ export const history = new Elysia() if (jobIds.length === 0) return; - const confirmed = confirm(\`Are you sure you want to delete \${jobIds.length} job(s)? This action cannot be undone.\`); + const confirmMessage = window.t('history', 'confirmDelete', { count: jobIds.length }); + const confirmed = confirm(confirmMessage); if (!confirmed) return; try { @@ -330,14 +331,18 @@ export const history = new Elysia() const result = await response.json(); if (result.success || result.deleted > 0) { - alert(\`Successfully deleted \${result.deleted} job(s).\${result.failed > 0 ? \` Failed to delete \${result.failed} job(s).\` : ''}\`); + let successMessage = window.t('history', 'deleteSuccess', { deleted: result.deleted }); + if (result.failed > 0) { + successMessage += ' ' + window.t('history', 'deleteFailed', { failed: result.failed }); + } + alert(successMessage); window.location.reload(); } else { - alert('Failed to delete jobs. Please try again.'); + alert(window.t('history', 'deleteError')); } } catch (error) { console.error('Error deleting jobs:', error); - alert('An error occurred while deleting jobs. Please try again.'); + alert(window.t('history', 'deleteError')); } }); });