feat: v0.1.9 - Setup 頁面 i18n + 語言選擇器 UI 修復 + 文件重構
✨ Features: - 全頁拖曳上傳：檔案可拖曳到頁面任何位置 - Setup 頁面新增語言選擇器 🐛 Bug Fixes: - 語言 icon 尺寸修復（h-5→h-6） - Dropdown 背景完全不透明 - 新增 scrollbar 樣式 🌍 i18n: - 所有 confirm/alert 訊息國際化 - Setup 頁面 i18n 完整化 📚 Documentation: - README 精簡為開箱即用版本 - 新增 docs/deployment/, docs/config/, docs/versions/
This commit is contained in:
Your Name
parent
a45a049fe2
commit
d563682753
14 changed files with 1305 additions and 594 deletions
62
CHANGELOG.md
62
CHANGELOG.md
|
|
@ -5,56 +5,42 @@
|
||||||
### ✨ Features
|
### ✨ Features
|
||||||
|
|
||||||
- **全頁拖曳上傳**：檔案可拖曳到頁面任何位置上傳
|
- **全頁拖曳上傳**：檔案可拖曳到頁面任何位置上傳
|
||||||
- 不再需要精準拖到上傳框內
|
- **Setup 頁面語言切換**：首次設定頁面新增語言選擇器
|
||||||
- 原本的上傳框視覺效果保持不變
|
|
||||||
- 點擊上傳功能不受影響
|
### 🐛 Bug Fixes
|
||||||
|
|
||||||
|
- **語言選擇器 UI 修復**：
|
||||||
|
- 語言 icon 尺寸從 h-5 w-5 增大至 h-6 w-6，與文字視覺高度一致
|
||||||
|
- Dropdown 背景改為完全不透明，提升可讀性
|
||||||
|
- 新增 scrollbar 樣式，改善滾動體驗
|
||||||
|
- 邊框顏色加深，增強視覺對比
|
||||||
|
|
||||||
### 🌍 i18n
|
### 🌍 i18n
|
||||||
|
|
||||||
- **提示訊息國際化**：所有 confirm / alert 訊息改用 i18n
|
- **提示訊息國際化**：所有 confirm / alert 訊息改用 i18n
|
||||||
- 刪除任務前的確認提示
|
- **Setup 頁面 i18n 完整化**：首次設定頁面所有文字皆使用 i18n key
|
||||||
- 刪除成功 / 失敗提示
|
|
||||||
- 錯誤訊息
|
|
||||||
- 隨語言切換即時更新顯示內容
|
|
||||||
|
|
||||||
### 📚 Documentation
|
### 📚 Documentation
|
||||||
|
|
||||||
- **新增版本更新教學**：README 新增「如何更新 ConvertX-CN 版本」章節
|
**README 重新定位為「開箱即用」**：
|
||||||
- 完整的 Docker Compose 更新步驟
|
|
||||||
- 更新到指定版本的方法
|
|
||||||
- 驗證更新成功的方式
|
|
||||||
|
|
||||||
- **README 重新定位**：從參考手冊改為「新手教學入口」
|
- 精簡至 100 行內，5 分鐘完成部署
|
||||||
- 完整 5 步驟部署教學（從安裝 Docker 到成功使用）
|
- 只保留必要參數說明
|
||||||
- 跨平台 data 資料夾建立指令（Linux / macOS / Windows）
|
- 進階內容移至 docs 子目錄
|
||||||
- 常見問題 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 設定
|
| `docs/deployment/` | quickstart, docker-compose, update |
|
||||||
- 安全性建議與防火牆設定
|
| `docs/config/` | environment, security |
|
||||||
- 備份與還原指南
|
| `docs/versions/` | latest, pinned-version |
|
||||||
|
|
||||||
- **更新 environment-variables.md**：
|
**文件拆分原則**：
|
||||||
- 依重要程度分類（必填 / 建議 / 可選）
|
|
||||||
- 每個變數都有詳細設定指南
|
|
||||||
- 常見情境範例
|
|
||||||
|
|
||||||
### 🎯 Design Philosophy
|
- README = 新手入口（一分鐘看懂怎麼部署）
|
||||||
|
- docs/ = 進階參考（完整設定、情境範例）
|
||||||
本專案的 README 與 docker-compose.yml 定位為「教學版」：
|
- 每個文件都有清楚的連結導航
|
||||||
|
|
||||||
- README 是新手的第一個成功體驗
|
|
||||||
- docker-compose.yml 寧願註解多，也不要極簡
|
|
||||||
- 強調「為什麼要這樣設」與「不這樣設會怎樣」
|
|
||||||
|
|
||||||
如需精簡版配置，請使用 `docs/docker-compose/compose.minimal.yml`。
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
|
||||||
377
README.md
377
README.md
|
|
@ -2,403 +2,110 @@
|
||||||
|
|
||||||
# ConvertX-CN
|
# ConvertX-CN
|
||||||
|
|
||||||
**開箱即用的全功能檔案轉換服務** | **Self-hosted File Converter - Full Edition**
|
**開箱即用的全功能檔案轉換服務** — 5 分鐘完成部署
|
||||||
|
|
||||||
[](https://github.com/pi-docket/ConvertX-CN/actions/workflows/release.yml)
|
[](https://hub.docker.com/r/convertx/convertx-cn)
|
||||||
[](https://hub.docker.com/r/convertx/convertx-cn)
|
|
||||||
[](https://github.com/pi-docket/ConvertX-CN/releases)
|
[](https://github.com/pi-docket/ConvertX-CN/releases)
|
||||||
[](LICENSE)
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## ✨ 什麼是 ConvertX-CN？
|
## 這是什麼？
|
||||||
|
|
||||||
ConvertX-CN 是基於 [C4illin/ConvertX](https://github.com/C4illin/ConvertX) 的**完整版 Fork**，專為中文使用者優化，並預載所有轉換依賴。
|
自架的檔案轉換服務，支援 **1000+ 格式**，包含影音、圖片、文件、電子書等。
|
||||||
|
已內建 LibreOffice、FFmpeg、Pandoc 等 20+ 轉換器與中日韓字型，**一個 Docker 命令就能跑**。
|
||||||
> 🎉 **一鍵部署，無需額外配置**
|
|
||||||
> 使用者 **不需要自己寫 Dockerfile**，直接 `docker run` 或 `docker compose up` 即可使用。
|
|
||||||
|
|
||||||
### 主要特色
|
|
||||||
|
|
||||||
| 特色 | 說明 |
|
|
||||||
| ------------------- | -------------------------------------------------- |
|
|
||||||
| 🌍 **65+ 語言支援** | 繁體中文、簡體中文、英文、日文、韓文等 65 種語言 |
|
|
||||||
| 📦 **完整內建** | LibreOffice、FFmpeg、Pandoc、Calibre 等 20+ 轉換器 |
|
|
||||||
| 🎨 **CJK 字型** | Noto CJK、微軟核心字型、標楷體等中日韓字型 |
|
|
||||||
| 🔤 **OCR 支援** | Tesseract + 多語言語言包 |
|
|
||||||
| ⚡ **LaTeX 完整版** | TexLive Full，支援所有 LaTeX 需求 |
|
|
||||||
| 🐳 **開箱即用** | 一個 Docker 命令即可啟動 |
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 📚 關於本文件
|
## 快速部署
|
||||||
|
|
||||||
> **📖 本 README 定位為「新手教學入口」**
|
### 1. 建立資料夾
|
||||||
>
|
|
||||||
> 我們的 `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
|
```bash
|
||||||
# 建立專案資料夾（可自訂位置）
|
mkdir -p ~/convertx-cn/data && cd ~/convertx-cn
|
||||||
mkdir -p ~/convertx-cn
|
|
||||||
cd ~/convertx-cn
|
|
||||||
|
|
||||||
# 建立 data 資料夾
|
|
||||||
mkdir -p data
|
|
||||||
|
|
||||||
# 確認資料夾已建立
|
|
||||||
ls -la
|
|
||||||
# 應該看到 data 資料夾
|
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Windows（PowerShell）
|
> Windows 請用 `mkdir C:\convertx-cn\data` 並 `cd C:\convertx-cn`
|
||||||
|
|
||||||
```powershell
|
### 2. 建立 docker-compose.yml
|
||||||
# 建立專案資料夾（可自訂位置）
|
|
||||||
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` 檔案：
|
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
# ==============================================================================
|
|
||||||
# ConvertX-CN 新手教學版 docker-compose.yml
|
|
||||||
#
|
|
||||||
# 📚 這份範例刻意保留完整註解，讓第一次用 Docker 的人也能成功部署
|
|
||||||
# ==============================================================================
|
|
||||||
|
|
||||||
services:
|
services:
|
||||||
convertx:
|
convertx:
|
||||||
# ===== 映像檔設定 =====
|
|
||||||
# convertx-cn 是完整版，已內建所有轉換工具（約 4-6 GB）
|
|
||||||
image: convertx/convertx-cn:latest
|
image: convertx/convertx-cn:latest
|
||||||
container_name: convertx-cn
|
container_name: convertx-cn
|
||||||
restart: unless-stopped
|
restart: unless-stopped
|
||||||
|
|
||||||
# ===== 連接埠設定 =====
|
|
||||||
# 格式：「主機埠號:容器埠號」
|
|
||||||
# 若 3000 埠已被佔用，可改為 3001:3000、8080:3000 等
|
|
||||||
ports:
|
ports:
|
||||||
- "3000:3000"
|
- "3000:3000"
|
||||||
|
|
||||||
# ===== 資料儲存（⚠️ 非常重要）=====
|
|
||||||
# ./data 是你主機上的實體資料夾
|
|
||||||
# /app/data 是容器內的路徑
|
|
||||||
#
|
|
||||||
# 🚨 注意事項：
|
|
||||||
# 1. 請務必先建立 data 資料夾（見上方步驟 2）
|
|
||||||
# 2. 這裡存放：上傳檔案、轉換結果、使用者資料
|
|
||||||
# 3. 若改用 Docker volume（如 convertx_data:/app/data），
|
|
||||||
# 資料會存在 Docker 內部，較難直接存取
|
|
||||||
volumes:
|
volumes:
|
||||||
- ./data:/app/data
|
- ./data:/app/data
|
||||||
|
|
||||||
# ===== 環境變數設定 =====
|
|
||||||
environment:
|
environment:
|
||||||
# --- 時區設定 ---
|
|
||||||
# 影響檔案時間戳記與日期顯示
|
|
||||||
- TZ=Asia/Taipei
|
- TZ=Asia/Taipei
|
||||||
|
- JWT_SECRET=請改成你自己的隨機字串至少32字元
|
||||||
# --- 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：啟動服務
|
| 參數 | 說明 | 必要 |
|
||||||
|
| ------------ | ---------------------------------- | ---- |
|
||||||
|
| `./data` | 存放檔案的資料夾，必須先建立 | ✅ |
|
||||||
|
| `JWT_SECRET` | 登入驗證金鑰，不設會每次重啟被登出 | ✅ |
|
||||||
|
| `TZ` | 時區（預設 UTC） | — |
|
||||||
|
|
||||||
|
### 3. 啟動
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 啟動（首次會下載映像檔，約 4-6 GB，請耐心等待）
|
|
||||||
docker compose up -d
|
docker compose up -d
|
||||||
|
|
||||||
# 查看執行狀態
|
|
||||||
docker compose ps
|
|
||||||
|
|
||||||
# 查看 log（確認沒有錯誤）
|
|
||||||
docker compose logs -f
|
|
||||||
# 按 Ctrl+C 可退出 log 查看
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### 步驟 5：開啟瀏覽器使用
|
首次下載約 4-6 GB，需等待幾分鐘。
|
||||||
|
|
||||||
1. 開啟瀏覽器，訪問 `http://localhost:3000`
|
### 4. 使用
|
||||||
2. 點擊 **Register** 註冊第一個帳號
|
|
||||||
3. 登入後即可開始轉換檔案！
|
|
||||||
|
|
||||||
> ✅ **首次註冊的帳號會自動成為管理員**
|
開啟 `http://localhost:3000`，註冊帳號即可使用。
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## ⚠️ 新手常見問題與解決方案
|
## 常見問題
|
||||||
|
|
||||||
### 問題 1：登入後又被導回登入頁
|
| 問題 | 解法 |
|
||||||
|
| -------------------- | --------------------------------------------------------------------- |
|
||||||
|
| 登入後又被踢回登入頁 | 設定 `HTTP_ALLOWED=true`（本地測試）或 `TRUST_PROXY=true`（反向代理） |
|
||||||
|
| 重啟後資料消失 | 確認 `./data:/app/data` 且資料夾存在 |
|
||||||
|
| 重啟後被登出 | 設定固定的 `JWT_SECRET` |
|
||||||
|
|
||||||
**原因**：Cookie 無法正確設定（常見於遠端部署）
|
更多問題 → [docs/faq.md](docs/faq.md)
|
||||||
|
|
||||||
**解決方案**：
|
|
||||||
|
|
||||||
- 若使用 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"`
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## <20> 如何更新 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
|
```bash
|
||||||
|
cd ~/convertx-cn
|
||||||
docker compose down
|
docker compose down
|
||||||
docker compose pull
|
docker compose pull
|
||||||
docker compose up -d
|
docker compose up -d
|
||||||
```
|
```
|
||||||
|
|
||||||
### 驗證更新成功
|
詳細說明 → [docs/deployment/update.md](docs/deployment/update.md)
|
||||||
|
|
||||||
開啟瀏覽器訪問 `http://localhost:3000`，頁面底部會顯示版本號。
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## <20>🔧 進階設定
|
## 進階設定
|
||||||
|
|
||||||
更多進階設定請參考：[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/) | 各種情境的範例檔案 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📸 預覽
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🛠️ 開發者資訊
|
## License
|
||||||
|
|
||||||
```bash
|
[MIT](LICENSE) | 基於 [C4illin/ConvertX](https://github.com/C4illin/ConvertX)
|
||||||
# 安裝依賴
|
|
||||||
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)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
<p align="center">
|
|
||||||
<b>Powered by ConvertX-CN</b><br>
|
|
||||||
<a href="https://github.com/pi-docket/ConvertX-CN">https://github.com/pi-docket/ConvertX-CN</a>
|
|
||||||
</p>
|
|
||||||
|
|
|
||||||
237
docs/config/environment.md
Normal file
237
docs/config/environment.md
Normal file
|
|
@ -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)
|
||||||
208
docs/config/security.md
Normal file
208
docs/config/security.md
Normal file
|
|
@ -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)
|
||||||
163
docs/deployment/docker-compose.md
Normal file
163
docs/deployment/docker-compose.md
Normal file
|
|
@ -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` - 完整參考
|
||||||
130
docs/deployment/quickstart.md
Normal file
130
docs/deployment/quickstart.md
Normal file
|
|
@ -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)
|
||||||
144
docs/deployment/update.md
Normal file
144
docs/deployment/update.md
Normal file
|
|
@ -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)
|
||||||
|
|
@ -5,49 +5,44 @@
|
||||||
## 範例檔案
|
## 範例檔案
|
||||||
|
|
||||||
| 檔案 | 適用情境 | 說明 |
|
| 檔案 | 適用情境 | 說明 |
|
||||||
| ------------------------------------------------ | ----------- | ------------------------- |
|
| ------------------------------------------------ | ----------- | --------------------- |
|
||||||
| [compose.minimal.yml](compose.minimal.yml) | Docker 老手 | 最精簡的可用配置 |
|
| [compose.minimal.yml](compose.minimal.yml) | Docker 老手 | 最精簡的可用配置 |
|
||||||
| [compose.production.yml](compose.production.yml) | 生產環境 | 含 Reverse Proxy 設定說明 |
|
| [compose.production.yml](compose.production.yml) | 生產環境 | 含 Reverse Proxy 設定 |
|
||||||
| [compose.reference.yml](compose.reference.yml) | 參考文件 | 所有可用設定的完整參考 |
|
| [compose.reference.yml](compose.reference.yml) | 參考文件 | 所有設定的完整參考 |
|
||||||
|
|
||||||
|
## 快速選擇
|
||||||
|
|
||||||
|
| 你是... | 使用 |
|
||||||
|
| ------------ | ------------------------------ |
|
||||||
|
| 新手 | [README 主頁](../../README.md) |
|
||||||
|
| Docker 熟手 | compose.minimal.yml |
|
||||||
|
| 生產環境 | compose.production.yml |
|
||||||
|
| 查詢所有選項 | compose.reference.yml |
|
||||||
|
|
||||||
## 如何使用
|
## 如何使用
|
||||||
|
|
||||||
### 方式 1：直接使用範例檔案
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 下載範例
|
# 下載範例
|
||||||
curl -O https://raw.githubusercontent.com/pi-docket/ConvertX-CN/main/docs/docker-compose/compose.minimal.yml
|
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
|
mv compose.minimal.yml docker-compose.yml
|
||||||
|
|
||||||
# 建立 data 資料夾
|
# 建立 data 資料夾
|
||||||
mkdir -p data
|
mkdir -p data
|
||||||
|
|
||||||
# 修改設定（至少要改 JWT_SECRET）
|
# 修改 JWT_SECRET
|
||||||
nano docker-compose.yml
|
nano docker-compose.yml
|
||||||
|
|
||||||
# 啟動
|
# 啟動
|
||||||
docker compose up -d
|
docker compose up -d
|
||||||
```
|
```
|
||||||
|
|
||||||
### 方式 2：複製內容
|
## 相關文件
|
||||||
|
|
||||||
1. 點擊上方檔案連結
|
- [Docker Compose 詳解](../deployment/docker-compose.md)
|
||||||
2. 複製內容
|
- [環境變數說明](../config/environment.md)
|
||||||
3. 貼到你的 `docker-compose.yml`
|
- [版本選擇指南](../versions/)
|
||||||
4. 修改必要設定
|
|
||||||
5. 執行 `docker compose up -d`
|
|
||||||
|
|
||||||
## 選擇指南
|
|
||||||
|
|
||||||
### 我是新手
|
|
||||||
|
|
||||||
請直接使用 [README 主頁](../../README.md) 的教學版範例。
|
|
||||||
|
|
||||||
### 我熟悉 Docker
|
|
||||||
|
|
||||||
使用 [compose.minimal.yml](compose.minimal.yml)，只需修改 `JWT_SECRET`。
|
|
||||||
|
|
||||||
### 我要部署到正式環境
|
### 我要部署到正式環境
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,154 +1,27 @@
|
||||||
# 環境變數設定
|
# 環境變數設定
|
||||||
|
|
||||||
本文件列出 ConvertX-CN 所有可用的環境變數設定。
|
> 📦 本文件已遷移至新位置，請參閱：[docs/config/environment.md](config/environment.md)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## 快速參考
|
## 快速參考
|
||||||
|
|
||||||
| 重要程度 | 變數 | 說明 |
|
完整說明請參考 [環境變數完整說明](config/environment.md)。
|
||||||
| -------- | -------------- | ---------------- |
|
|
||||||
| 🔴 必填 | `JWT_SECRET` | 生產環境必須設定 |
|
| 優先級 | 變數 | 說明 |
|
||||||
| 🟡 建議 | `TZ` | 時區設定 |
|
| ------ | -------------- | ------------- |
|
||||||
| 🟡 建議 | `HTTP_ALLOWED` | 是否允許 HTTP |
|
| 必填 | `JWT_SECRET` | 登入驗證金鑰 |
|
||||||
| 🟢 可選 | 其他 | 依需求設定 |
|
| 建議 | `TZ` | 時區設定 |
|
||||||
|
| 建議 | `HTTP_ALLOWED` | 是否允許 HTTP |
|
||||||
|
| 可選 | `TRUST_PROXY` | 信任反向代理 |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🔴 必填設定（生產環境）
|
## 相關文件
|
||||||
|
|
||||||
### JWT_SECRET
|
- [環境變數完整說明](config/environment.md)
|
||||||
|
- [安全性設定](config/security.md)
|
||||||
| 項目 | 說明 |
|
- [進階部署指南](deployment.md)
|
||||||
| ------ | ---------------------------------- |
|
|
||||||
| 預設值 | `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
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
|
||||||
29
docs/versions/README.md
Normal file
29
docs/versions/README.md
Normal file
|
|
@ -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)
|
||||||
105
docs/versions/latest.md
Normal file
105
docs/versions/latest.md
Normal file
|
|
@ -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)
|
||||||
120
docs/versions/pinned-version.md
Normal file
120
docs/versions/pinned-version.md
Normal file
|
|
@ -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)
|
||||||
|
|
@ -28,7 +28,7 @@ export const LanguageSelector = ({
|
||||||
viewBox="0 0 24 24"
|
viewBox="0 0 24 24"
|
||||||
stroke-width="1.5"
|
stroke-width="1.5"
|
||||||
stroke="currentColor"
|
stroke="currentColor"
|
||||||
class="h-5 w-5"
|
class="h-6 w-6"
|
||||||
>
|
>
|
||||||
<path
|
<path
|
||||||
stroke-linecap="round"
|
stroke-linecap="round"
|
||||||
|
|
@ -58,8 +58,9 @@ export const LanguageSelector = ({
|
||||||
<ul
|
<ul
|
||||||
id="language-dropdown"
|
id="language-dropdown"
|
||||||
class={`
|
class={`
|
||||||
absolute top-full right-0 z-50 mt-2 hidden max-h-[320px] min-w-[160px] flex-col
|
absolute top-full right-0 z-50 mt-2 scrollbar hidden max-h-[320px] min-w-[180px] flex-col
|
||||||
overflow-y-auto rounded border border-neutral-700 bg-neutral-800 shadow-lg
|
overflow-y-auto rounded border border-neutral-600 bg-neutral-800 shadow-xl
|
||||||
|
scrollbar-thumb-neutral-600 scrollbar-track-neutral-800
|
||||||
`}
|
`}
|
||||||
role="menu"
|
role="menu"
|
||||||
>
|
>
|
||||||
|
|
|
||||||
|
|
@ -3,6 +3,7 @@ import { jwt } from "@elysiajs/jwt";
|
||||||
import { Elysia, t } from "elysia";
|
import { Elysia, t } from "elysia";
|
||||||
import { BaseHtml } from "../components/base";
|
import { BaseHtml } from "../components/base";
|
||||||
import { Header } from "../components/header";
|
import { Header } from "../components/header";
|
||||||
|
import { LanguageSelector } from "../components/languageSelector";
|
||||||
import db from "../db/db";
|
import db from "../db/db";
|
||||||
import { User } from "../db/types";
|
import { User } from "../db/types";
|
||||||
import {
|
import {
|
||||||
|
|
@ -93,6 +94,17 @@ export const user = new Elysia()
|
||||||
|
|
||||||
return (
|
return (
|
||||||
<BaseHtml title="ConvertX-CN | Setup" webroot={WEBROOT} locale={locale}>
|
<BaseHtml title="ConvertX-CN | Setup" webroot={WEBROOT} locale={locale}>
|
||||||
|
<>
|
||||||
|
<header class="w-full p-4">
|
||||||
|
<nav
|
||||||
|
class={`
|
||||||
|
mx-auto flex max-w-4xl items-center justify-between rounded-sm bg-neutral-900 p-4
|
||||||
|
`}
|
||||||
|
>
|
||||||
|
<strong>ConvertX-CN</strong>
|
||||||
|
<LanguageSelector currentLocale={locale} webroot={WEBROOT} t={t} />
|
||||||
|
</nav>
|
||||||
|
</header>
|
||||||
<main
|
<main
|
||||||
class={`
|
class={`
|
||||||
mx-auto w-full max-w-4xl flex-1 px-2
|
mx-auto w-full max-w-4xl flex-1 px-2
|
||||||
|
|
@ -144,6 +156,7 @@ export const user = new Elysia()
|
||||||
</footer>
|
</footer>
|
||||||
</article>
|
</article>
|
||||||
</main>
|
</main>
|
||||||
|
</>
|
||||||
</BaseHtml>
|
</BaseHtml>
|
||||||
);
|
);
|
||||||
})
|
})
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue