diff --git a/CHANGELOG.md b/CHANGELOG.md index a387912..79fbf2d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,56 +5,42 @@ ### ✨ Features - **全頁拖曳上傳**：檔案可拖曳到頁面任何位置上傳 - - 不再需要精準拖到上傳框內 - - 原本的上傳框視覺效果保持不變 - - 點擊上傳功能不受影響 +- **Setup 頁面語言切換**：首次設定頁面新增語言選擇器 + +### 🐛 Bug Fixes + +- **語言選擇器 UI 修復**： + - 語言 icon 尺寸從 h-5 w-5 增大至 h-6 w-6，與文字視覺高度一致 + - Dropdown 背景改為完全不透明，提升可讀性 + - 新增 scrollbar 樣式，改善滾動體驗 + - 邊框顏色加深，增強視覺對比 ### 🌍 i18n - **提示訊息國際化**：所有 confirm / alert 訊息改用 i18n - - 刪除任務前的確認提示 - - 刪除成功 / 失敗提示 - - 錯誤訊息 - - 隨語言切換即時更新顯示內容 +- **Setup 頁面 i18n 完整化**：首次設定頁面所有文字皆使用 i18n key ### 📚 Documentation -- **新增版本更新教學**：README 新增「如何更新 ConvertX-CN 版本」章節 - - 完整的 Docker Compose 更新步驟 - - 更新到指定版本的方法 - - 驗證更新成功的方式 +**README 重新定位為「開箱即用」**： -- **README 重新定位**：從參考手冊改為「新手教學入口」 - - 完整 5 步驟部署教學（從安裝 Docker 到成功使用） - - 跨平台 data 資料夾建立指令（Linux / macOS / Windows） - - 常見問題 FAQ（登入失敗、資料遺失、被登出） - - 明確說明為何範例保留完整註解（教學導向） +- 精簡至 100 行內，5 分鐘完成部署 +- 只保留必要參數說明 +- 進階內容移至 docs 子目錄 -- **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 設定 - - 安全性建議與防火牆設定 - - 備份與還原指南 +| 目錄 | 內容 | +| ------------------ | ---------------------------------- | +| `docs/deployment/` | quickstart, docker-compose, update | +| `docs/config/` | environment, security | +| `docs/versions/` | latest, pinned-version | -- **更新 environment-variables.md**： - - 依重要程度分類（必填 / 建議 / 可選） - - 每個變數都有詳細設定指南 - - 常見情境範例 +**文件拆分原則**： -### 🎯 Design Philosophy - -本專案的 README 與 docker-compose.yml 定位為「教學版」： - -- README 是新手的第一個成功體驗 -- docker-compose.yml 寧願註解多，也不要極簡 -- 強調「為什麼要這樣設」與「不這樣設會怎樣」 - -如需精簡版配置，請使用 `docs/docker-compose/compose.minimal.yml`。 +- README = 新手入口（一分鐘看懂怎麼部署） +- docs/ = 進階參考（完整設定、情境範例） +- 每個文件都有清楚的連結導航 --- diff --git a/README.md b/README.md index daa7fd7..33d462d 100644 --- a/README.md +++ b/README.md @@ -2,403 +2,110 @@ # ConvertX-CN -**開箱即用的全功能檔案轉換服務** | **Self-hosted File Converter - Full Edition** +**開箱即用的全功能檔案轉換服務** — 5 分鐘完成部署 -[![Docker](https://github.com/pi-docket/ConvertX-CN/actions/workflows/release.yml/badge.svg)](https://github.com/pi-docket/ConvertX-CN/actions/workflows/release.yml) -[![Docker Pulls](https://img.shields.io/docker/pulls/convertx/convertx-cn?style=flat&logo=docker&label=Docker%20Hub)](https://hub.docker.com/r/convertx/convertx-cn) +[![Docker Pulls](https://img.shields.io/docker/pulls/convertx/convertx-cn?style=flat&logo=docker)](https://hub.docker.com/r/convertx/convertx-cn) [![GitHub Release](https://img.shields.io/github/v/release/pi-docket/ConvertX-CN)](https://github.com/pi-docket/ConvertX-CN/releases) -[![License](https://img.shields.io/github/license/pi-docket/ConvertX-CN)](LICENSE) --- -## ✨ 什麼是 ConvertX-CN？ +## 這是什麼？ -ConvertX-CN 是基於 [C4illin/ConvertX](https://github.com/C4illin/ConvertX) 的**完整版 Fork**，專為中文使用者優化，並預載所有轉換依賴。 - -> 🎉 **一鍵部署，無需額外配置** -> 使用者 **不需要自己寫 Dockerfile**，直接 `docker run` 或 `docker compose up` 即可使用。 - -### 主要特色 - -| 特色 | 說明 | -| ------------------- | -------------------------------------------------- | -| 🌍 **65+ 語言支援** | 繁體中文、簡體中文、英文、日文、韓文等 65 種語言 | -| 📦 **完整內建** | LibreOffice、FFmpeg、Pandoc、Calibre 等 20+ 轉換器 | -| 🎨 **CJK 字型** | Noto CJK、微軟核心字型、標楷體等中日韓字型 | -| 🔤 **OCR 支援** | Tesseract + 多語言語言包 | -| ⚡ **LaTeX 完整版** | TexLive Full，支援所有 LaTeX 需求 | -| 🐳 **開箱即用** | 一個 Docker 命令即可啟動 | +自架的檔案轉換服務，支援 **1000+ 格式**，包含影音、圖片、文件、電子書等。 +已內建 LibreOffice、FFmpeg、Pandoc 等 20+ 轉換器與中日韓字型，**一個 Docker 命令就能跑**。 --- -## 📚 關於本文件 +## 快速部署 -> **📖 本 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 +### 1. 建立資料夾 ```bash -# 建立專案資料夾（可自訂位置） -mkdir -p ~/convertx-cn -cd ~/convertx-cn - -# 建立 data 資料夾 -mkdir -p data - -# 確認資料夾已建立 -ls -la -# 應該看到 data 資料夾 +mkdir -p ~/convertx-cn/data && cd ~/convertx-cn ``` -#### Windows（PowerShell） +> Windows 請用 `mkdir C:\convertx-cn\data` 並 `cd C:\convertx-cn` -```powershell -# 建立專案資料夾（可自訂位置） -mkdir C:\convertx-cn -cd C:\convertx-cn - -# 建立 data 資料夾 -mkdir data - -# 確認資料夾已建立 -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` 檔案： +### 2. 建立 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 + - JWT_SECRET=請改成你自己的隨機字串至少32字元 ``` -### 步驟 4：啟動服務 +| 參數 | 說明 | 必要 | +| ------------ | ---------------------------------- | ---- | +| `./data` | 存放檔案的資料夾，必須先建立 | ✅ | +| `JWT_SECRET` | 登入驗證金鑰，不設會每次重啟被登出 | ✅ | +| `TZ` | 時區（預設 UTC） | — | + +### 3. 啟動 ```bash -# 啟動（首次會下載映像檔，約 4-6 GB，請耐心等待） docker compose up -d - -# 查看執行狀態 -docker compose ps - -# 查看 log（確認沒有錯誤） -docker compose logs -f -# 按 Ctrl+C 可退出 log 查看 ``` -### 步驟 5：開啟瀏覽器使用 +首次下載約 4-6 GB，需等待幾分鐘。 -1. 開啟瀏覽器，訪問 `http://localhost:3000` -2. 點擊 **Register** 註冊第一個帳號 -3. 登入後即可開始轉換檔案！ +### 4. 使用 -> ✅ **首次註冊的帳號會自動成為管理員** +開啟 `http://localhost:3000`，註冊帳號即可使用。 --- -## ⚠️ 新手常見問題與解決方案 +## 常見問題 -### 問題 1：登入後又被導回登入頁 +| 問題 | 解法 | +| -------------------- | --------------------------------------------------------------------- | +| 登入後又被踢回登入頁 | 設定 `HTTP_ALLOWED=true`（本地測試）或 `TRUST_PROXY=true`（反向代理） | +| 重啟後資料消失 | 確認 `./data:/app/data` 且資料夾存在 | +| 重啟後被登出 | 設定固定的 `JWT_SECRET` | -**原因**：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"` +更多問題 → [docs/faq.md](docs/faq.md) --- -## � 如何更新 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:v0.1.9 # 改成指定版本 -``` - -然後執行： +## 更新版本 ```bash +cd ~/convertx-cn docker compose down docker compose pull docker compose up -d ``` -### 驗證更新成功 - -開啟瀏覽器訪問 `http://localhost:3000`，頁面底部會顯示版本號。 +詳細說明 → [docs/deployment/update.md](docs/deployment/update.md) --- -## �🔧 進階設定 +## 進階設定 -更多進階設定請參考：[docs/environment-variables.md](docs/environment-variables.md) +| 需求 | 文件 | +| ------------------- | -------------------------------------------------------- | +| 完整環境變數 | [docs/config/environment.md](docs/config/environment.md) | +| 反向代理 / HTTPS | [docs/deployment.md](docs/deployment.md) | +| 安全性設定 | [docs/config/security.md](docs/config/security.md) | +| Docker Compose 範例 | [docs/docker-compose/](docs/docker-compose/) | +| 版本選擇指南 | [docs/versions/](docs/versions/) | --- -## 🌍 語言支援 - -ConvertX-CN 支援 **65 種語言**，包括： - -| 區域 | 語言 | -| ------------- | ------------------------------------------------ | -| **東亞** | 繁體中文（預設）、简体中文、日本語、한국어 | -| **歐洲** | English, Deutsch, Français, Español, Italiano 等 | -| **中東/南亞** | العربية, עברית, हिन्दी, தமிழ் 等 | -| **東南亞** | ไทย, Tiếng Việt, Bahasa Indonesia 等 | - -語言會根據瀏覽器設定自動偵測，也可透過右上角選單手動切換。 - ---- - -## 📦 內建轉換器 - -| 轉換器 | 用途 | 支援格式數 | -| ----------- | ------ | ---------- | -| FFmpeg | 影音 | 400+ | -| ImageMagick | 圖片 | 200+ | -| LibreOffice | 文件 | 60+ | -| Pandoc | 文件 | 100+ | -| Calibre | 電子書 | 40+ | -| Inkscape | 向量圖 | 20+ | - -完整列表 → [docs/converters.md](docs/converters.md) - ---- - -## 🐳 Docker Image 資訊 - -| Tag | 說明 | -| ----------------------------- | ---------- | -| `convertx/convertx-cn:latest` | 最新穩定版 | -| `convertx/convertx-cn:v0.1.9` | 指定版本 | - -> ⚠️ **首次下載說明** -> 由於內建完整依賴（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/) | 各種情境的範例檔案 | - ---- - -## 📸 預覽 +## 預覽 ![ConvertX-CN Preview](images/preview.png) --- -## 🛠️ 開發者資訊 +## License -```bash -# 安裝依賴 -bun install - -# 開發模式 -bun run dev - -# 建構 -bun run build -``` - -歡迎 Pull Request！請使用 [Conventional Commits](https://www.conventionalcommits.org/) 格式。 - ---- - -## 🙏 致謝 - -本專案基於 [C4illin/ConvertX](https://github.com/C4illin/ConvertX) 開發。 - ---- - -## 📜 License - -[MIT License](LICENSE) - ---- - -

- Powered by ConvertX-CN
- https://github.com/pi-docket/ConvertX-CN -

+[MIT](LICENSE) | 基於 [C4illin/ConvertX](https://github.com/C4illin/ConvertX) diff --git a/docs/config/environment.md b/docs/config/environment.md new file mode 100644 index 0000000..b1afe4d --- /dev/null +++ b/docs/config/environment.md @@ -0,0 +1,237 @@ +# 環境變數完整說明 + +本文件列出 ConvertX-CN 所有可用的環境變數設定。 + +--- + +## 快速參考 + +| 優先級 | 變數 | 說明 | 預設值 | +| ------ | -------------- | ------------ | ------------------ | +| 必填 | `JWT_SECRET` | 登入驗證金鑰 | 隨機（每次重啟變） | +| 建議 | `TZ` | 時區 | `UTC` | +| 建議 | `HTTP_ALLOWED` | 允許 HTTP | `false` | +| 可選 | `TRUST_PROXY` | 信任反向代理 | `false` | +| 可選 | 其他 | 依需求設定 | - | + +--- + +## 必填設定 + +### JWT_SECRET + +用於簽署登入驗證的密鑰。 + +| 項目 | 值 | +| ------ | ---------------------- | +| 預設值 | 每次重啟隨機產生 | +| 建議值 | 至少 32 字元的隨機字串 | + +不設定的話，每次容器重啟後所有使用者都需要重新登入。 + +產生方式： + +```bash +openssl rand -hex 32 +``` + +--- + +## 網路與安全 + +### HTTP_ALLOWED + +允許非 HTTPS 連線。 + +| 項目 | 值 | +| ------ | ------- | +| 預設值 | `false` | + +| 情境 | 設定值 | +| --------------------- | ------- | +| 本地測試 (localhost) | `true` | +| 有 HTTPS | `false` | +| 無 HTTPS 但需遠端存取 | `true` | + +設為 `false` 但用 HTTP 存取會導致「登入後又被導回登入頁」。 + +### TRUST_PROXY + +信任反向代理的 headers（`X-Forwarded-Proto` 等）。 + +| 項目 | 值 | +| ------ | ------- | +| 預設值 | `false` | + +| 情境 | 設定值 | +| ---------------------------- | ------- | +| 直接存取容器 | `false` | +| 透過 Nginx / Traefik / Caddy | `true` | + +詳見 [安全性設定](security.md)。 + +### 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 + +日期格式語言（BCP 47 格式）。 + +| 項目 | 值 | +| ------ | ---- | +| 預設值 | `en` | + +--- + +## 轉換設定 + +### MAX_CONVERT_PROCESS + +最大同時轉換任務數。 + +| 項目 | 值 | +| ------ | ------------- | +| 預設值 | `0`（無限制） | + +### FFMPEG_ARGS + +FFmpeg 輸入參數（硬體加速等）。 + +| 項目 | 值 | +| ------ | --- | +| 預設值 | 空 | + +```yaml +# NVIDIA GPU +- FFMPEG_ARGS=-hwaccel cuda + +# Intel QSV +- FFMPEG_ARGS=-hwaccel qsv +``` + +### FFMPEG_OUTPUT_ARGS + +FFmpeg 輸出參數。 + +| 項目 | 值 | +| ------ | --- | +| 預設值 | 空 | + +```yaml +- FFMPEG_OUTPUT_ARGS=-preset veryfast +``` + +--- + +## 情境範例 + +### 開發環境 + +```yaml +environment: + - TZ=Asia/Taipei + - HTTP_ALLOWED=true + - ACCOUNT_REGISTRATION=true +``` + +### 生產環境 + +```yaml +environment: + - TZ=Asia/Taipei + - JWT_SECRET=your-production-secret-at-least-32-chars + - 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 +``` + +--- + +## 相關文件 + +- [安全性設定](security.md) +- [進階部署](../deployment.md) +- [Docker Compose 詳解](../deployment/docker-compose.md) diff --git a/docs/config/security.md b/docs/config/security.md new file mode 100644 index 0000000..e2bea6e --- /dev/null +++ b/docs/config/security.md @@ -0,0 +1,208 @@ +# 安全性設定 + +本文件說明 ConvertX-CN 的安全性相關設定與最佳實踐。 + +--- + +## Cookie 與登入安全 + +### HTTP_ALLOWED + +控制是否允許非 HTTPS 連線。 + +```yaml +- HTTP_ALLOWED=true # 允許 HTTP（不安全，僅測試用） +- HTTP_ALLOWED=false # 僅允許 HTTPS（預設） +``` + +#### 運作原理 + +當 `HTTP_ALLOWED=false` 時，Cookie 會設定 `Secure` 屬性，只在 HTTPS 連線下傳送。 + +若實際用 HTTP 存取： + +- 瀏覽器不會傳送 Cookie +- 每次請求都像未登入 +- 造成「登入後又被踢回登入頁」 + +#### 設定建議 + +| 情境 | 設定值 | +| ------------------ | ------- | +| `localhost` 測試 | `true` | +| 區網 IP 測試 | `true` | +| 有 HTTPS 憑證 | `false` | +| 透過反向代理 HTTPS | `false` | + +--- + +### TRUST_PROXY + +是否信任反向代理傳來的 headers。 + +```yaml +- TRUST_PROXY=true # 信任 X-Forwarded-* headers +- TRUST_PROXY=false # 不信任（預設） +``` + +#### 運作原理 + +當請求經過反向代理時： + +- 原始連線：使用者 → Nginx (HTTPS) → ConvertX (HTTP) +- 沒有 TRUST_PROXY：ConvertX 看到的是 HTTP 連線 +- 有 TRUST_PROXY：ConvertX 讀取 `X-Forwarded-Proto: https`，知道原始是 HTTPS + +#### 設定建議 + +| 情境 | 設定值 | +| ---------------------------- | ------- | +| 直接存取容器（無 Proxy） | `false` | +| 透過 Nginx / Traefik / Caddy | `true` | +| 透過 Cloudflare Tunnel | `true` | + +#### 安全注意 + +只在確實有反向代理時才設為 `true`。若直接暴露容器且設為 `true`，攻擊者可偽造 headers。 + +--- + +## 帳號安全 + +### ACCOUNT_REGISTRATION + +```yaml +- ACCOUNT_REGISTRATION=true # 開放註冊 +- ACCOUNT_REGISTRATION=false # 關閉註冊 +``` + +#### 建議流程 + +1. 首次部署設為 `true` +2. 註冊管理員帳號 +3. 改為 `false` +4. 重啟容器 + +首次註冊的帳號不受此限制。 + +### JWT_SECRET + +```yaml +- JWT_SECRET=your-secret-key-at-least-32-chars +``` + +#### 重要性 + +- 用於簽署登入 Token +- 不設定：每次重啟產生新密鑰，所有人被登出 +- 設定固定值：登入狀態跨重啟保留 + +#### 產生方式 + +```bash +# Linux / macOS +openssl rand -hex 32 + +# 輸出範例 +# a1b2c3d4e5f6789...（64 字元） +``` + +--- + +## 公開服務安全 + +### ALLOW_UNAUTHENTICATED + +```yaml +- ALLOW_UNAUTHENTICATED=true # 允許未登入使用 +- ALLOW_UNAUTHENTICATED=false # 必須登入（預設） +``` + +#### 風險 + +設為 `true` 時： + +- 任何人可使用轉換功能 +- 消耗伺服器 CPU / 記憶體 / 磁碟 +- 可能被惡意利用 + +#### 緩解措施 + +若需要公開服務，建議： + +```yaml +environment: + - ALLOW_UNAUTHENTICATED=true + - AUTO_DELETE_EVERY_N_HOURS=1 # 頻繁清理 + - HIDE_HISTORY=true # 隱藏歷史 + - MAX_CONVERT_PROCESS=2 # 限制同時轉換數 +``` + +--- + +## 網路安全 + +### 防火牆 + +只開放必要的埠： + +```bash +# 僅允許特定 IP 存取 +ufw allow from 192.168.1.0/24 to any port 3000 +``` + +### 只允許本地存取 + +若透過反向代理，可限制容器只監聽 localhost： + +```yaml +ports: + - "127.0.0.1:3000:3000" +``` + +這樣只有本機的反向代理可以存取，外部無法直接連線。 + +--- + +## 設定範例 + +### 最小安全配置（本地測試） + +```yaml +environment: + - HTTP_ALLOWED=true +``` + +### 標準安全配置（生產環境） + +```yaml +environment: + - JWT_SECRET=your-production-secret + - HTTP_ALLOWED=false + - TRUST_PROXY=true + - ACCOUNT_REGISTRATION=false +``` + +### 高安全配置（敏感環境） + +```yaml +services: + convertx: + ports: + - "127.0.0.1:3000:3000" # 只允許本地 + environment: + - JWT_SECRET=your-very-long-random-secret + - HTTP_ALLOWED=false + - TRUST_PROXY=true + - ACCOUNT_REGISTRATION=false + - ALLOW_UNAUTHENTICATED=false + - AUTO_DELETE_EVERY_N_HOURS=1 +``` + +--- + +## 相關文件 + +- [環境變數完整說明](environment.md) +- [反向代理設定](../deployment.md) +- [Docker Compose 詳解](../deployment/docker-compose.md) diff --git a/docs/deployment/docker-compose.md b/docs/deployment/docker-compose.md new file mode 100644 index 0000000..ec01663 --- /dev/null +++ b/docs/deployment/docker-compose.md @@ -0,0 +1,163 @@ +# Docker Compose 詳解 + +本文件說明 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 +``` + +--- + +## 映像檔選擇 + +```yaml +image: convertx/convertx-cn:latest # 最新穩定版 +image: convertx/convertx-cn:v0.1.9 # 指定版本 +``` + +- `latest`：自動獲取最新版本，適合測試環境 +- 指定版本：適合生產環境，避免意外升級 + +詳見 [版本選擇指南](../versions/)。 + +--- + +## 連接埠設定 + +```yaml +ports: + - "3000:3000" # 主機埠:容器埠 + - "8080:3000" # 使用 8080 埠 + - "127.0.0.1:3000:3000" # 僅本地存取 +``` + +| 設定 | 說明 | +| ----------------------- | -------------------- | +| `"3000:3000"` | 所有網路介面可存取 | +| `"127.0.0.1:3000:3000"` | 僅本機可存取 | +| `"8080:3000"` | 使用 8080 埠對外開放 | + +--- + +## 資料儲存 + +### 使用資料夾掛載（推薦） + +```yaml +volumes: + - ./data:/app/data +``` + +- 資料存在主機上的 `./data` 資料夾 +- 方便備份、遷移、直接存取 + +### 使用 Docker Volume + +```yaml +volumes: + - convertx_data:/app/data + +volumes: + convertx_data: +``` + +- 資料由 Docker 管理 +- 備份需透過 Docker 指令 + +--- + +## 環境變數 + +### 必要設定 + +```yaml +environment: + - JWT_SECRET=your-secret-key-at-least-32-chars +``` + +### 建議設定 + +```yaml +environment: + - TZ=Asia/Taipei + - HTTP_ALLOWED=true # 本地測試 + - ACCOUNT_REGISTRATION=true +``` + +### 生產環境設定 + +```yaml +environment: + - TZ=Asia/Taipei + - JWT_SECRET=your-production-secret + - HTTP_ALLOWED=false + - TRUST_PROXY=true + - ACCOUNT_REGISTRATION=false + - AUTO_DELETE_EVERY_N_HOURS=24 +``` + +完整環境變數說明請參考 [環境變數文件](../config/environment.md)。 + +--- + +## 重啟策略 + +```yaml +restart: unless-stopped # 推薦 +restart: always # 總是重啟 +restart: on-failure # 僅失敗時重啟 +restart: "no" # 不自動重啟 +``` + +--- + +## 資源限制 + +```yaml +deploy: + resources: + limits: + memory: 4G + cpus: "2" + reservations: + memory: 1G + cpus: "0.5" +``` + +--- + +## 健康檢查 + +```yaml +healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:3000/healthcheck"] + interval: 30s + timeout: 10s + retries: 3 + start_period: 60s +``` + +--- + +## 完整範例 + +請參考 [Docker Compose 範例資料夾](../docker-compose/)： + +- `compose.minimal.yml` - 最精簡設定 +- `compose.production.yml` - 生產環境 +- `compose.reference.yml` - 完整參考 diff --git a/docs/deployment/quickstart.md b/docs/deployment/quickstart.md new file mode 100644 index 0000000..c26d173 --- /dev/null +++ b/docs/deployment/quickstart.md @@ -0,0 +1,130 @@ +# 快速部署指南 + +本文件提供 ConvertX-CN 的完整部署步驟，適合第一次使用 Docker 的使用者。 + +--- + +## 前置需求 + +- [Docker](https://www.docker.com/products/docker-desktop/) 或 [Docker Engine](https://docs.docker.com/engine/install/) +- 約 6 GB 硬碟空間 +- 網路連線（首次下載映像檔） + +--- + +## 步驟 1：安裝 Docker + +### Windows / macOS + +下載並安裝 [Docker Desktop](https://www.docker.com/products/docker-desktop/)。 + +### Linux + +```bash +curl -fsSL https://get.docker.com | sh +sudo usermod -aG docker $USER +# 登出再登入，讓群組生效 +``` + +驗證安裝： + +```bash +docker --version +docker compose version +``` + +--- + +## 步驟 2：建立專案資料夾 + +### Linux / macOS + +```bash +mkdir -p ~/convertx-cn/data +cd ~/convertx-cn +``` + +### Windows (PowerShell) + +```powershell +mkdir C:\convertx-cn\data +cd C:\convertx-cn +``` + +> ⚠️ `data` 資料夾必須先建立，否則 Docker 會建立匿名 volume，導致資料難以存取。 + +--- + +## 步驟 3：建立 docker-compose.yml + +在專案資料夾建立 `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=請改成你自己的隨機字串至少32字元 +``` + +### 必要參數說明 + +| 參數 | 說明 | +| ------------ | ---------------------------------- | +| `./data` | 存放上傳檔案與轉換結果，必須先建立 | +| `JWT_SECRET` | 登入驗證金鑰，不設會每次重啟被登出 | + +--- + +## 步驟 4：啟動服務 + +```bash +docker compose up -d +``` + +首次執行會下載映像檔（約 4-6 GB），需等待幾分鐘。 + +查看狀態： + +```bash +docker compose ps +docker compose logs -f # Ctrl+C 退出 +``` + +--- + +## 步驟 5：使用 + +1. 開啟瀏覽器，訪問 `http://localhost:3000` +2. 點擊 **Register** 註冊帳號 +3. 開始轉換檔案 + +首次註冊的帳號會自動成為管理員。 + +--- + +## 常見問題 + +| 問題 | 解法 | +| -------------------- | ------------------------------------ | +| 登入後又被踢回登入頁 | 加上 `HTTP_ALLOWED=true` | +| 重啟後資料消失 | 確認 `./data:/app/data` 且資料夾存在 | +| 重啟後被登出 | 設定固定的 `JWT_SECRET` | +| 3000 埠被佔用 | 改用 `"8080:3000"` | + +更多問題請參考 [FAQ](../faq.md)。 + +--- + +## 下一步 + +- [環境變數完整說明](../config/environment.md) +- [反向代理與 HTTPS](../deployment.md) +- [版本更新方法](update.md) diff --git a/docs/deployment/update.md b/docs/deployment/update.md new file mode 100644 index 0000000..743312f --- /dev/null +++ b/docs/deployment/update.md @@ -0,0 +1,144 @@ +# 版本更新指南 + +本文件說明如何更新 ConvertX-CN 到新版本。 + +--- + +## 使用 Docker Compose 更新 + +### 更新到最新版 + +```bash +# 1. 進入專案資料夾 +cd ~/convertx-cn + +# 2. 停止服務 +docker compose down + +# 3. 拉取最新映像檔 +docker compose pull + +# 4. 重新啟動 +docker compose up -d +``` + +### 更新到指定版本 + +修改 `docker-compose.yml`： + +```yaml +services: + convertx: + image: convertx/convertx-cn:v0.1.9 # 指定版本 +``` + +然後執行： + +```bash +docker compose down +docker compose pull +docker compose up -d +``` + +--- + +## 驗證更新 + +### 查看 Log + +```bash +docker compose logs | head -20 +``` + +### 檢查網頁版本 + +開啟 `http://localhost:3000`，頁面底部會顯示版本號。 + +### 檢查映像檔版本 + +```bash +docker images convertx/convertx-cn +``` + +--- + +## 備份建議 + +更新前建議備份 `data` 資料夾： + +```bash +# Linux / macOS +cp -r ./data ./data.backup.$(date +%Y%m%d) + +# Windows PowerShell +Copy-Item -Recurse .\data .\data.backup.$(Get-Date -Format "yyyyMMdd") +``` + +--- + +## 回滾版本 + +如果新版本有問題，可以回滾到舊版本： + +```yaml +services: + convertx: + image: convertx/convertx-cn:v0.1.8 # 舊版本 +``` + +```bash +docker compose down +docker compose pull +docker compose up -d +``` + +--- + +## 清理舊映像檔 + +更新後可清理不再使用的舊映像檔，釋放磁碟空間： + +```bash +docker image prune -a +``` + +> ⚠️ 此指令會刪除所有未使用的映像檔，不只是 ConvertX-CN。 + +只刪除 ConvertX-CN 舊版本： + +```bash +# 列出所有版本 +docker images convertx/convertx-cn + +# 刪除特定版本 +docker rmi convertx/convertx-cn:v0.1.7 +``` + +--- + +## 自動更新（進階） + +可使用 [Watchtower](https://containrrr.dev/watchtower/) 自動更新容器： + +```yaml +services: + convertx: + image: convertx/convertx-cn:latest + # ... 其他設定 + + watchtower: + image: containrrr/watchtower + volumes: + - /var/run/docker.sock:/var/run/docker.sock + command: --interval 86400 # 每 24 小時檢查一次 +``` + +> ⚠️ 自動更新適合測試環境。生產環境建議手動更新，確認新版本穩定後再升級。 + +--- + +## 相關文件 + +- [版本選擇指南](../versions/) +- [GitHub Releases](https://github.com/pi-docket/ConvertX-CN/releases) +- [Changelog](../../CHANGELOG.md) diff --git a/docs/docker-compose/README.md b/docs/docker-compose/README.md index a53a516..602445e 100644 --- a/docs/docker-compose/README.md +++ b/docs/docker-compose/README.md @@ -4,50 +4,45 @@ ## 範例檔案 -| 檔案 | 適用情境 | 說明 | -| ------------------------------------------------ | ----------- | ------------------------- | -| [compose.minimal.yml](compose.minimal.yml) | Docker 老手 | 最精簡的可用配置 | -| [compose.production.yml](compose.production.yml) | 生產環境 | 含 Reverse Proxy 設定說明 | -| [compose.reference.yml](compose.reference.yml) | 參考文件 | 所有可用設定的完整參考 | +| 檔案 | 適用情境 | 說明 | +| ------------------------------------------------ | ----------- | --------------------- | +| [compose.minimal.yml](compose.minimal.yml) | Docker 老手 | 最精簡的可用配置 | +| [compose.production.yml](compose.production.yml) | 生產環境 | 含 Reverse Proxy 設定 | +| [compose.reference.yml](compose.reference.yml) | 參考文件 | 所有設定的完整參考 | + +## 快速選擇 + +| 你是... | 使用 | +| ------------ | ------------------------------ | +| 新手 | [README 主頁](../../README.md) | +| Docker 熟手 | compose.minimal.yml | +| 生產環境 | compose.production.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） +# 修改 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`。 +- [Docker Compose 詳解](../deployment/docker-compose.md) +- [環境變數說明](../config/environment.md) +- [版本選擇指南](../versions/) ### 我要部署到正式環境 diff --git a/docs/environment-variables.md b/docs/environment-variables.md index 44e52f0..43f02b0 100644 --- a/docs/environment-variables.md +++ b/docs/environment-variables.md @@ -1,154 +1,27 @@ # 環境變數設定 -本文件列出 ConvertX-CN 所有可用的環境變數設定。 +> 📦 本文件已遷移至新位置，請參閱：[docs/config/environment.md](config/environment.md) + +--- ## 快速參考 -| 重要程度 | 變數 | 說明 | -| -------- | -------------- | ---------------- | -| 🔴 必填 | `JWT_SECRET` | 生產環境必須設定 | -| 🟡 建議 | `TZ` | 時區設定 | -| 🟡 建議 | `HTTP_ALLOWED` | 是否允許 HTTP | -| 🟢 可選 | 其他 | 依需求設定 | +完整說明請參考 [環境變數完整說明](config/environment.md)。 + +| 優先級 | 變數 | 說明 | +| ------ | -------------- | ------------- | +| 必填 | `JWT_SECRET` | 登入驗證金鑰 | +| 建議 | `TZ` | 時區設定 | +| 建議 | `HTTP_ALLOWED` | 是否允許 HTTP | +| 可選 | `TRUST_PROXY` | 信任反向代理 | --- -## 🔴 必填設定（生產環境） +## 相關文件 -### JWT_SECRET - -| 項目 | 說明 | -| ------ | ---------------------------------- | -| 預設值 | `randomUUID()`（每次重啟都會改變） | -| 用途 | 用於簽署 JWT 的密鑰字串 | - -**⚠️ 重要**：若不設定，每次容器重啟後所有使用者都需要重新登入。 - -**產生方式**： - -```bash -# Linux / macOS -openssl rand -hex 32 - -# 輸出範例 -# a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6 -``` - -**設定方式**： - -```yaml -environment: - - JWT_SECRET=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6 -``` - ---- - -## 🟡 建議設定 - -### 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 -``` +- [環境變數完整說明](config/environment.md) +- [安全性設定](config/security.md) +- [進階部署指南](deployment.md) --- diff --git a/docs/versions/README.md b/docs/versions/README.md new file mode 100644 index 0000000..6fd6c37 --- /dev/null +++ b/docs/versions/README.md @@ -0,0 +1,29 @@ +# 版本選擇指南 + +本目錄說明如何選擇適合的版本標籤。 + +--- + +## 快速建議 + +| 情境 | 建議版本 | +| -------- | ----------------------- | +| 個人測試 | `latest` | +| 家庭使用 | `latest` | +| 團隊環境 | 指定版本（如 `v0.1.9`） | +| 生產環境 | 指定版本（如 `v0.1.9`） | + +--- + +## 文件列表 + +- [使用 latest 標籤](latest.md) - 自動更新的優缺點 +- [指定版本部署](pinned-version.md) - 生產環境推薦做法 + +--- + +## 相關連結 + +- [GitHub Releases](https://github.com/pi-docket/ConvertX-CN/releases) +- [Changelog](../../CHANGELOG.md) +- [版本更新指南](../deployment/update.md) diff --git a/docs/versions/latest.md b/docs/versions/latest.md new file mode 100644 index 0000000..0582771 --- /dev/null +++ b/docs/versions/latest.md @@ -0,0 +1,105 @@ +# 使用 latest 標籤 + +本文件說明使用 `latest` 標籤的注意事項。 + +--- + +## 什麼是 latest？ + +```yaml +image: convertx/convertx-cn:latest +``` + +`latest` 是指向最新穩定版本的標籤。每次發布新版本時，`latest` 會自動更新。 + +--- + +## 優點 + +- 自動獲取新功能與修復 +- 不需要手動修改 docker-compose.yml +- 適合快速測試 + +--- + +## 風險 + +### 意外更新 + +當執行 `docker compose pull` 時，會自動下載最新版本： + +```bash +docker compose pull # 可能拉到新版本 +docker compose up -d # 使用新版本啟動 +``` + +如果新版本有重大變更，可能影響正常使用。 + +### 無法回滾 + +如果沒有記錄使用的版本，出問題時難以回滾。 + +### 不一致 + +多台伺服器在不同時間部署，可能跑不同版本。 + +--- + +## 適用情境 + +| 情境 | 是否適合 latest | +| -------- | --------------- | +| 個人測試 | ✅ | +| 家庭使用 | ✅ | +| 團隊協作 | ⚠️ 視情況 | +| 生產環境 | ❌ | + +--- + +## 使用建議 + +### 測試環境 + +```yaml +image: convertx/convertx-cn:latest +``` + +可以使用 `latest`，享受自動更新的便利。 + +### 生產環境 + +建議使用固定版本： + +```yaml +image: convertx/convertx-cn:v0.1.9 +``` + +詳見 [指定版本部署](pinned-version.md)。 + +--- + +## 如何知道 latest 是哪個版本？ + +### 方法 1：查看 log + +```bash +docker compose logs | head -10 +``` + +### 方法 2：檢查映像檔 + +```bash +docker inspect convertx/convertx-cn:latest | grep -i version +``` + +### 方法 3：查看網頁 + +開啟 `http://localhost:3000`，頁面底部會顯示版本號。 + +--- + +## 相關文件 + +- [指定版本部署](pinned-version.md) +- [版本更新指南](../deployment/update.md) +- [GitHub Releases](https://github.com/pi-docket/ConvertX-CN/releases) diff --git a/docs/versions/pinned-version.md b/docs/versions/pinned-version.md new file mode 100644 index 0000000..cf60512 --- /dev/null +++ b/docs/versions/pinned-version.md @@ -0,0 +1,120 @@ +# 指定版本部署 + +本文件說明如何使用固定版本標籤部署 ConvertX-CN。 + +--- + +## 為什麼要指定版本？ + +使用固定版本可以： + +- 確保每次部署結果一致 +- 避免意外升級造成問題 +- 方便在多台伺服器部署相同版本 +- 出問題時容易回滾 + +--- + +## 如何指定版本 + +修改 `docker-compose.yml`： + +```yaml +services: + convertx: + image: convertx/convertx-cn:v0.1.9 # 指定版本 +``` + +--- + +## 查看可用版本 + +### GitHub Releases + +[https://github.com/pi-docket/ConvertX-CN/releases](https://github.com/pi-docket/ConvertX-CN/releases) + +### Docker Hub + +```bash +# 列出所有標籤 +docker search convertx/convertx-cn --limit 100 + +# 或查看 Docker Hub 網頁 +# https://hub.docker.com/r/convertx/convertx-cn/tags +``` + +--- + +## 版本命名規則 + +| 格式 | 說明 | 範例 | +| -------- | -------------------- | -------- | +| `vX.Y.Z` | 正式版本 | `v0.1.9` | +| `latest` | 最新穩定版 | - | +| `main` | 最新開發版（不穩定） | - | + +--- + +## 升級到新版本 + +1. 查看 [Changelog](../../CHANGELOG.md) 確認變更 +2. 修改 docker-compose.yml 的版本號 +3. 執行更新 + +```bash +docker compose down +docker compose pull +docker compose up -d +``` + +詳見 [版本更新指南](../deployment/update.md)。 + +--- + +## 回滾到舊版本 + +如果新版本有問題： + +1. 修改版本號為舊版本 + +```yaml +image: convertx/convertx-cn:v0.1.8 +``` + +2. 重新部署 + +```bash +docker compose down +docker compose pull +docker compose up -d +``` + +--- + +## 生產環境建議 + +### 部署流程 + +1. 在測試環境使用 `latest` 或新版本 +2. 確認功能正常 +3. 記錄版本號 +4. 生產環境使用該固定版本 + +### 版本記錄 + +建議在 docker-compose.yml 加上註解： + +```yaml +services: + convertx: + # 2026-01-20 升級：修復 PDF 轉換問題 + image: convertx/convertx-cn:v0.1.9 +``` + +--- + +## 相關文件 + +- [使用 latest 標籤](latest.md) +- [版本更新指南](../deployment/update.md) +- [Changelog](../../CHANGELOG.md) diff --git a/src/components/languageSelector.tsx b/src/components/languageSelector.tsx index e88ffdd..13c7ae2 100644 --- a/src/components/languageSelector.tsx +++ b/src/components/languageSelector.tsx @@ -28,7 +28,7 @@ export const LanguageSelector = ({ viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" - class="h-5 w-5" + class="h-6 w-6" >