feat: v0.1.9 - 全頁拖曳上傳 + i18n 修正 + 文件更新
✨ Features: - 全頁拖曳上傳：檔案可拖曳到頁面任何位置上傳 - 原本的上傳框視覺效果保持不變 🌍 i18n: - 刪除任務的 confirm/alert 訊息改用 i18n - 隨語言切換即時更新顯示內容 📚 Documentation: - README 新增「如何更新 ConvertX-CN 版本」章節 - 新增 deployment.md（Reverse Proxy、HTTPS） - 新增 Docker Compose 範例分層 - 更新 environment-variables.md
This commit is contained in:
Your Name
parent
a0eccf0437
commit
a45a049fe2
14 changed files with 1475 additions and 167 deletions
58
CHANGELOG.md
58
CHANGELOG.md
|
|
@ -1,5 +1,63 @@
|
||||||
# Changelog
|
# 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)
|
## [0.1.8](https://github.com/pi-docket/ConvertX-CN/releases/tag/v0.1.8) (2026-01-20)
|
||||||
|
|
||||||
### 🐛 Bug Fixes
|
### 🐛 Bug Fixes
|
||||||
|
|
|
||||||
|
|
@ -1,6 +1,6 @@
|
||||||
# ==============================================================================
|
# ==============================================================================
|
||||||
# ConvertX-CN 官方 Docker Image
|
# ConvertX-CN 官方 Docker Image
|
||||||
# 版本：v0.1.8
|
# 版本：v0.1.9
|
||||||
# ==============================================================================
|
# ==============================================================================
|
||||||
#
|
#
|
||||||
# 📦 Image 說明：
|
# 📦 Image 說明：
|
||||||
|
|
|
||||||
349
README.md
349
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
|
```bash
|
||||||
# 1. 建立資料夾
|
# 建立專案資料夾（可自訂位置）
|
||||||
|
mkdir -p ~/convertx-cn
|
||||||
|
cd ~/convertx-cn
|
||||||
|
|
||||||
|
# 建立 data 資料夾
|
||||||
mkdir -p data
|
mkdir -p data
|
||||||
|
|
||||||
# 2. 啟動容器
|
# 確認資料夾已建立
|
||||||
docker run -d \
|
ls -la
|
||||||
--name convertx-cn \
|
# 應該看到 data 資料夾
|
||||||
-p 3000:3000 \
|
|
||||||
-v ./data:/app/data \
|
|
||||||
-e TZ=Asia/Taipei \
|
|
||||||
convertx/convertx-cn:latest
|
|
||||||
```
|
```
|
||||||
|
|
||||||
開啟瀏覽器訪問 `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"`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## <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
|
```yaml
|
||||||
services:
|
services:
|
||||||
convertx:
|
convertx:
|
||||||
image: convertx/convertx-cn:latest
|
image: convertx/convertx-cn:v0.1.9 # 改成指定版本
|
||||||
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
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
然後執行：
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
docker compose down
|
||||||
|
docker compose pull
|
||||||
docker compose up -d
|
docker compose up -d
|
||||||
```
|
```
|
||||||
|
|
||||||
📖 完整部署指南請見 → [docs/getting-started.md](docs/getting-started.md)
|
### 驗證更新成功
|
||||||
|
|
||||||
|
開啟瀏覽器訪問 `http://localhost:3000`，頁面底部會顯示版本號。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## <20>🔧 進階設定
|
||||||
|
|
||||||
|
更多進階設定請參考：[docs/environment-variables.md](docs/environment-variables.md)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -83,13 +311,12 @@ docker compose up -d
|
||||||
|
|
||||||
ConvertX-CN 支援 **65 種語言**，包括：
|
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 |
|
| **歐洲** | English, Deutsch, Français, Español, Italiano 等 |
|
||||||
| **中東/南亞** | العربية, עברית, فارسی, Türkçe, हिन्दी, বাংলা, தமிழ், తెలుగు, मराठी, ગુજરાતી, ಕನ್ನಡ, മലയാളം, नेपाली, සිංහල |
|
| **中東/南亞** | العربية, עברית, हिन्दी, தமிழ் 等 |
|
||||||
| **東南亞** | ไทย, Tiếng Việt, Bahasa Indonesia, Bahasa Melayu, Filipino, မြန်မာ, ខ្មែរ, ລາວ |
|
| **東南亞** | ไทย, Tiếng Việt, Bahasa Indonesia 等 |
|
||||||
| **非洲** | Afrikaans, Kiswahili, አማርኛ, isiZulu |
|
|
||||||
|
|
||||||
語言會根據瀏覽器設定自動偵測，也可透過右上角選單手動切換。
|
語言會根據瀏覽器設定自動偵測，也可透過右上角選單手動切換。
|
||||||
|
|
||||||
|
|
@ -97,42 +324,42 @@ ConvertX-CN 支援 **65 種語言**，包括：
|
||||||
|
|
||||||
## 📦 內建轉換器
|
## 📦 內建轉換器
|
||||||
|
|
||||||
| 轉換器 | 用途 | 輸入格式 | 輸出格式 |
|
| 轉換器 | 用途 | 支援格式數 |
|
||||||
| -------------- | ------- | -------- | -------- |
|
| ----------- | ------ | ---------- |
|
||||||
| FFmpeg | 影音 | ~472 | ~199 |
|
| FFmpeg | 影音 | 400+ |
|
||||||
| ImageMagick | 圖片 | 245 | 183 |
|
| ImageMagick | 圖片 | 200+ |
|
||||||
| GraphicsMagick | 圖片 | 167 | 130 |
|
| LibreOffice | 文件 | 60+ |
|
||||||
| LibreOffice | 文件 | 41 | 22 |
|
| Pandoc | 文件 | 100+ |
|
||||||
| Pandoc | 文件 | 43 | 65 |
|
| Calibre | 電子書 | 40+ |
|
||||||
| Calibre | 電子書 | 26 | 19 |
|
| Inkscape | 向量圖 | 20+ |
|
||||||
| Inkscape | 向量圖 | 7 | 17 |
|
|
||||||
| Assimp | 3D 模型 | 77 | 23 |
|
|
||||||
|
|
||||||
完整列表 → [docs/converters.md](docs/converters.md)
|
完整列表 → [docs/converters.md](docs/converters.md)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 📖 文件導覽
|
## 🐳 Docker Image 資訊
|
||||||
|
|
||||||
| 文件 | 說明 |
|
|
||||||
| -------------------------------------------- | ---------------------- |
|
|
||||||
| [🚀 快速開始](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
|
|
||||||
|
|
||||||
| Tag | 說明 |
|
| Tag | 說明 |
|
||||||
| ----------------------------- | ---------- |
|
| ----------------------------- | ---------- |
|
||||||
| `convertx/convertx-cn:latest` | 最新穩定版 |
|
| `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
|
```bash
|
||||||
# 安裝依賴
|
# 安裝依賴
|
||||||
|
|
@ -163,10 +390,6 @@ bun run build
|
||||||
|
|
||||||
本專案基於 [C4illin/ConvertX](https://github.com/C4illin/ConvertX) 開發。
|
本專案基於 [C4illin/ConvertX](https://github.com/C4illin/ConvertX) 開發。
|
||||||
|
|
||||||
<a href="https://github.com/C4illin/ConvertX/graphs/contributors">
|
|
||||||
<img src="https://contrib.rocks/image?repo=C4illin/ConvertX" alt="Contributors" />
|
|
||||||
</a>
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 📜 License
|
## 📜 License
|
||||||
|
|
|
||||||
200
compose.yaml
200
compose.yaml
|
|
@ -1,50 +1,194 @@
|
||||||
# ==============================================================================
|
# ==============================================================================
|
||||||
# ConvertX-CN 部署範例（docker-compose.yml / compose.yaml）
|
# ConvertX-CN Docker Compose 教學版範例
|
||||||
|
#
|
||||||
|
# 📚 這份範例的設計理念：
|
||||||
|
# - 刻意保留完整註解，讓第一次用 Docker 的人也能成功部署
|
||||||
|
# - 每個設定都有說明其用途與風險
|
||||||
|
# - 如果你是 Docker 老手，可以自行精簡
|
||||||
#
|
#
|
||||||
# 🎉 這是完整版 image，已內建所有轉換依賴：
|
# 🎉 這是完整版 image，已內建所有轉換依賴：
|
||||||
# - LibreOffice (headless)
|
# - LibreOffice (headless) - 文件轉換
|
||||||
# - TexLive（CJK + 阿拉伯/希伯來語）
|
# - TexLive Full - LaTeX 完整版（含 CJK、阿拉伯、希伯來語支援）
|
||||||
# - Tesseract OCR + 中日韓英德法語言包
|
# - Tesseract OCR + 中日韓英德法語言包
|
||||||
# - CJK 字型（Noto CJK、標楷體）
|
# - CJK 字型（Noto CJK、標楷體、微軟核心字型）
|
||||||
# - Pandoc、FFmpeg、ImageMagick、OpenCV 等所有轉換器
|
# - Pandoc、FFmpeg、ImageMagick、Calibre 等所有轉換器
|
||||||
#
|
#
|
||||||
# ✅ 使用者不需要自己寫 Dockerfile
|
# ✅ 使用者不需要自己寫 Dockerfile
|
||||||
# ✅ 直接 docker compose up -d 即可使用
|
# ✅ 直接 docker compose up -d 即可使用
|
||||||
#
|
#
|
||||||
# ⚠️ 遠端部署注意事項：
|
# ⚠️ 部署前必做：
|
||||||
# 若透過 Nginx/Traefik 等 reverse proxy 存取，請設定：
|
# 1. 先建立 data 資料夾（見 README.md 步驟 2）
|
||||||
# - HTTP_ALLOWED=true（若 proxy 處理 HTTPS）
|
# 2. 修改 JWT_SECRET 為你自己的隨機字串
|
||||||
# - 或 TRUST_PROXY=true（讓應用正確判斷 HTTPS）
|
|
||||||
# ==============================================================================
|
# ==============================================================================
|
||||||
|
|
||||||
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
|
||||||
|
|
||||||
|
# 重啟策略：
|
||||||
|
# - unless-stopped：除非手動停止，否則自動重啟（推薦）
|
||||||
|
# - always：永遠自動重啟
|
||||||
|
# - no：不自動重啟
|
||||||
restart: unless-stopped
|
restart: unless-stopped
|
||||||
|
|
||||||
|
# =========================================================================
|
||||||
|
# 連接埠設定
|
||||||
|
# =========================================================================
|
||||||
|
# 格式：「主機埠號:容器埠號」
|
||||||
|
#
|
||||||
|
# 範例：
|
||||||
|
# - "3000:3000" → http://localhost:3000
|
||||||
|
# - "8080:3000" → http://localhost:8080
|
||||||
|
# - "80:3000" → http://localhost（需要 root 權限）
|
||||||
|
#
|
||||||
|
# 💡 若 3000 埠被佔用，改第一個數字即可
|
||||||
ports:
|
ports:
|
||||||
- "3000:3000"
|
- "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:
|
volumes:
|
||||||
- ./data:/app/data
|
- ./data:/app/data
|
||||||
|
|
||||||
|
# =========================================================================
|
||||||
|
# 環境變數設定
|
||||||
|
# =========================================================================
|
||||||
environment:
|
environment:
|
||||||
# === 帳號設定 ===
|
# -----------------------------------------------------------------------
|
||||||
- ACCOUNT_REGISTRATION=false # 是否允許註冊新帳號（首次帳號不受此限制）
|
# 時區設定
|
||||||
- JWT_SECRET=請更換為一個長且隨機的字串 # 若不設定則使用 randomUUID()
|
# -----------------------------------------------------------------------
|
||||||
|
# 影響檔案時間戳記與日期顯示格式
|
||||||
# === 安全設定 ===
|
# 常用值：Asia/Taipei, Asia/Shanghai, America/New_York, Europe/London
|
||||||
- HTTP_ALLOWED=false # 是否允許非 HTTPS 連線（僅本地測試時設為 true）
|
|
||||||
- TRUST_PROXY=false # 透過 reverse proxy 時設為 true（正確判斷 HTTPS）
|
|
||||||
- ALLOW_UNAUTHENTICATED=false # 是否允許未登入使用（僅本地測試時設為 true）
|
|
||||||
|
|
||||||
# === 檔案管理 ===
|
|
||||||
- AUTO_DELETE_EVERY_N_HOURS=24 # 自動刪除超過 N 小時的檔案（0 = 停用）
|
|
||||||
|
|
||||||
# === 時區設定 ===
|
|
||||||
- TZ=Asia/Taipei
|
- TZ=Asia/Taipei
|
||||||
|
|
||||||
# === 可選設定 ===
|
# -----------------------------------------------------------------------
|
||||||
# - WEBROOT=/convertx # 子路徑部署（例如 example.com/convertx/）
|
# JWT 密鑰（🔐 強烈建議設定）
|
||||||
# - HIDE_HISTORY=true # 隱藏歷史紀錄頁面
|
# -----------------------------------------------------------------------
|
||||||
# - LANGUAGE=zh-TW # 日期格式語言
|
# 用於使用者登入驗證的加密金鑰
|
||||||
# - FFMPEG_ARGS=-hwaccel vaapi # FFmpeg 硬體加速參數
|
#
|
||||||
# - MAX_CONVERT_PROCESS=4 # 最大同時轉換數（0 = 無限制）
|
# ⚠️ 若不設定會怎樣？
|
||||||
|
# 系統會使用 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
|
||||||
|
|
|
||||||
382
docs/deployment.md
Normal file
382
docs/deployment.md
Normal file
|
|
@ -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)
|
||||||
68
docs/docker-compose/README.md
Normal file
68
docs/docker-compose/README.md
Normal file
|
|
@ -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)
|
||||||
24
docs/docker-compose/compose.minimal.yml
Normal file
24
docs/docker-compose/compose.minimal.yml
Normal file
|
|
@ -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
|
||||||
87
docs/docker-compose/compose.production.yml
Normal file
87
docs/docker-compose/compose.production.yml
Normal file
|
|
@ -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"
|
||||||
|
#
|
||||||
|
# ==============================================================================
|
||||||
131
docs/docker-compose/compose.reference.yml
Normal file
131
docs/docker-compose/compose.reference.yml
Normal file
|
|
@ -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
|
||||||
|
# ==============================================================================
|
||||||
|
|
@ -11,7 +11,7 @@ ConvertX-CN 提供兩種 Docker Image 選項：
|
||||||
| Tag | 說明 |
|
| Tag | 說明 |
|
||||||
| ----------------------------- | ---------- |
|
| ----------------------------- | ---------- |
|
||||||
| `convertx/convertx-cn:latest` | 最新穩定版 |
|
| `convertx/convertx-cn:latest` | 最新穩定版 |
|
||||||
| `convertx/convertx-cn:v0.1.6` | 指定版本號 |
|
| `convertx/convertx-cn:v0.1.9` | 指定版本號 |
|
||||||
|
|
||||||
**內建功能：**
|
**內建功能：**
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,123 +1,249 @@
|
||||||
# 環境變數設定
|
# 環境變數設定
|
||||||
|
|
||||||
所有環境變數皆為選填，建議至少設定 `JWT_SECRET`。
|
本文件列出 ConvertX-CN 所有可用的環境變數設定。
|
||||||
|
|
||||||
|
## 快速參考
|
||||||
|
|
||||||
|
| 重要程度 | 變數 | 說明 |
|
||||||
|
| -------- | -------------- | ---------------- |
|
||||||
|
| 🔴 必填 | `JWT_SECRET` | 生產環境必須設定 |
|
||||||
|
| 🟡 建議 | `TZ` | 時區設定 |
|
||||||
|
| 🟡 建議 | `HTTP_ALLOWED` | 是否允許 HTTP |
|
||||||
|
| 🟢 可選 | 其他 | 依需求設定 |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 安全性設定
|
## 🔴 必填設定（生產環境）
|
||||||
|
|
||||||
| 變數名稱 | 預設值 | 說明 |
|
### JWT_SECRET
|
||||||
| ----------------------- | -------------- | ----------------------------------------------- |
|
|
||||||
| `JWT_SECRET` | `randomUUID()` | 用於簽署 JWT 的密鑰字串。**生產環境請務必設定** |
|
|
||||||
| `ACCOUNT_REGISTRATION` | `true` | 是否允許註冊新帳號（預設開放） |
|
|
||||||
| `HTTP_ALLOWED` | `false` | 是否允許 HTTP 連線（僅本地使用建議開啟） |
|
|
||||||
| `ALLOW_UNAUTHENTICATED` | `false` | 是否允許未登入使用 |
|
|
||||||
|
|
||||||
### 安全建議
|
| 項目 | 說明 |
|
||||||
|
| ------ | ---------------------------------- |
|
||||||
|
| 預設值 | `randomUUID()`（每次重啟都會改變） |
|
||||||
|
| 用途 | 用於簽署 JWT 的密鑰字串 |
|
||||||
|
|
||||||
|
**⚠️ 重要**：若不設定，每次容器重啟後所有使用者都需要重新登入。
|
||||||
|
|
||||||
|
**產生方式**：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Linux / macOS
|
||||||
|
openssl rand -hex 32
|
||||||
|
|
||||||
|
# 輸出範例
|
||||||
|
# a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6
|
||||||
|
```
|
||||||
|
|
||||||
|
**設定方式**：
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
# 生產環境（關閉註冊）
|
|
||||||
environment:
|
environment:
|
||||||
- JWT_SECRET=a-very-long-random-string-at-least-32-characters
|
- JWT_SECRET=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6
|
||||||
- ACCOUNT_REGISTRATION=false
|
|
||||||
- HTTP_ALLOWED=false
|
|
||||||
- ALLOW_UNAUTHENTICATED=false
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 檔案管理
|
## 🟡 建議設定
|
||||||
|
|
||||||
| 變數名稱 | 預設值 | 說明 |
|
### TZ（時區）
|
||||||
| --------------------------- | ------ | ------------------------------------- |
|
|
||||||
| `AUTO_DELETE_EVERY_N_HOURS` | `24` | 自動刪除超過 N 小時的檔案（0 = 停用） |
|
|
||||||
|
|
||||||
### 範例
|
| 項目 | 說明 |
|
||||||
|
| ------ | ------------------------------ |
|
||||||
|
| 預設值 | `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
|
```yaml
|
||||||
# 每 48 小時清理一次
|
# 每 48 小時清理一次
|
||||||
- AUTO_DELETE_EVERY_N_HOURS=48
|
- AUTO_DELETE_EVERY_N_HOURS=48
|
||||||
|
|
||||||
# 停用自動清理
|
# 停用自動清理（不建議，會佔滿磁碟）
|
||||||
- AUTO_DELETE_EVERY_N_HOURS=0
|
- AUTO_DELETE_EVERY_N_HOURS=0
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 轉換設定
|
## 🎨 介面設定
|
||||||
|
|
||||||
| 變數名稱 | 預設值 | 說明 |
|
### WEBROOT
|
||||||
| --------------------- | ------ | ---------------------------------------- |
|
|
||||||
| `MAX_CONVERT_PROCESS` | `0` | 最大同時轉換數（0 = 無限制） |
|
|
||||||
| `FFMPEG_ARGS` | - | FFmpeg 輸入參數，例如 `-hwaccel vaapi` |
|
|
||||||
| `FFMPEG_OUTPUT_ARGS` | - | FFmpeg 輸出參數，例如 `-preset veryfast` |
|
|
||||||
|
|
||||||
### 硬體加速範例
|
| 項目 | 說明 |
|
||||||
|
| ------ | ---------------------------- |
|
||||||
|
| 預設值 | (空) |
|
||||||
|
| 用途 | 子路徑部署，例如 `/convertx` |
|
||||||
|
|
||||||
```yaml
|
若透過子路徑存取（如 `https://example.com/convertx/`）：
|
||||||
# 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`）：
|
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
- WEBROOT=/convertx
|
- WEBROOT=/convertx
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### HIDE_HISTORY
|
||||||
|
|
||||||
|
| 項目 | 說明 |
|
||||||
|
| ------ | ---------------- |
|
||||||
|
| 預設值 | `false` |
|
||||||
|
| 用途 | 隱藏歷史紀錄頁面 |
|
||||||
|
|
||||||
|
### LANGUAGE
|
||||||
|
|
||||||
|
| 項目 | 說明 |
|
||||||
|
| ------ | --------------------------- |
|
||||||
|
| 預設值 | `en` |
|
||||||
|
| 用途 | 日期格式語言（BCP 47 格式） |
|
||||||
|
|
||||||
|
影響介面上的日期顯示格式（如 2026/01/20 vs 01/20/2026）。
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 本地化設定
|
## ⚙️ 轉換設定
|
||||||
|
|
||||||
| 變數名稱 | 預設值 | 說明 |
|
### MAX_CONVERT_PROCESS
|
||||||
| ---------- | ------ | --------------------------- |
|
|
||||||
| `LANGUAGE` | `en` | 日期格式語言（BCP 47 格式） |
|
|
||||||
| `TZ` | `UTC` | 時區設定 |
|
|
||||||
|
|
||||||
### 常用時區
|
| 項目 | 說明 |
|
||||||
|
| ------ | ---------------------------- |
|
||||||
|
| 預設值 | `0` |
|
||||||
|
| 用途 | 最大同時轉換數（0 = 無限制） |
|
||||||
|
|
||||||
|
限制同時進行的轉換任務數量，避免伺服器過載。
|
||||||
|
|
||||||
|
### FFMPEG_ARGS
|
||||||
|
|
||||||
|
| 項目 | 說明 |
|
||||||
|
| ------ | ------------------------------- |
|
||||||
|
| 預設值 | (空) |
|
||||||
|
| 用途 | FFmpeg 輸入參數，用於硬體加速等 |
|
||||||
|
|
||||||
|
**硬體加速範例**：
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
# 台灣
|
# NVIDIA GPU
|
||||||
- TZ=Asia/Taipei
|
- FFMPEG_ARGS=-hwaccel cuda
|
||||||
|
|
||||||
# 中國
|
# Intel QSV
|
||||||
- TZ=Asia/Shanghai
|
- FFMPEG_ARGS=-hwaccel qsv
|
||||||
|
|
||||||
# 日本
|
# AMD VAAPI
|
||||||
- TZ=Asia/Tokyo
|
- FFMPEG_ARGS=-hwaccel vaapi
|
||||||
|
```
|
||||||
|
|
||||||
# 美國東部
|
### FFMPEG_OUTPUT_ARGS
|
||||||
- TZ=America/New_York
|
|
||||||
|
| 項目 | 說明 |
|
||||||
|
| ------ | --------------- |
|
||||||
|
| 預設值 | (空) |
|
||||||
|
| 用途 | FFmpeg 輸出參數 |
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
# 使用較快的編碼預設
|
||||||
|
- FFMPEG_OUTPUT_ARGS=-preset veryfast
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 進階設定
|
## 🔧 進階設定
|
||||||
|
|
||||||
| 變數名稱 | 預設值 | 說明 |
|
### UNAUTHENTICATED_USER_SHARING
|
||||||
| ------------------------------ | ------- | ---------------------------- |
|
|
||||||
| `UNAUTHENTICATED_USER_SHARING` | `false` | 未登入使用者是否共享檔案空間 |
|
| 項目 | 說明 |
|
||||||
|
| ------ | ---------------------------- |
|
||||||
|
| 預設值 | `false` |
|
||||||
|
| 用途 | 未登入使用者是否共享檔案空間 |
|
||||||
|
|
||||||
|
設為 `true` 時，所有匿名使用者會看到相同的檔案。
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 完整範例
|
## 情境範例
|
||||||
|
|
||||||
### 開發環境
|
### 開發環境
|
||||||
|
|
||||||
|
|
@ -135,6 +261,7 @@ environment:
|
||||||
- JWT_SECRET=your-very-long-and-random-secret-key-change-me
|
- JWT_SECRET=your-very-long-and-random-secret-key-change-me
|
||||||
- ACCOUNT_REGISTRATION=false
|
- ACCOUNT_REGISTRATION=false
|
||||||
- HTTP_ALLOWED=false
|
- HTTP_ALLOWED=false
|
||||||
|
- TRUST_PROXY=true
|
||||||
- TZ=Asia/Taipei
|
- TZ=Asia/Taipei
|
||||||
- AUTO_DELETE_EVERY_N_HOURS=24
|
- AUTO_DELETE_EVERY_N_HOURS=24
|
||||||
```
|
```
|
||||||
|
|
@ -148,6 +275,14 @@ environment:
|
||||||
- AUTO_DELETE_EVERY_N_HOURS=1
|
- AUTO_DELETE_EVERY_N_HOURS=1
|
||||||
```
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 相關文件
|
||||||
|
|
||||||
|
- [進階部署指南](deployment.md)
|
||||||
|
- [Docker Compose 範例](docker-compose/)
|
||||||
|
- [常見問題](faq.md)
|
||||||
|
|
||||||
### 帶硬體加速
|
### 帶硬體加速
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
|
|
|
||||||
|
|
@ -1,6 +1,6 @@
|
||||||
{
|
{
|
||||||
"name": "convertx-frontend",
|
"name": "convertx-frontend",
|
||||||
"version": "0.1.8",
|
"version": "0.1.9",
|
||||||
"scripts": {
|
"scripts": {
|
||||||
"dev": "bun run --watch src/index.tsx",
|
"dev": "bun run --watch src/index.tsx",
|
||||||
"hot": "bun run --hot src/index.tsx",
|
"hot": "bun run --hot src/index.tsx",
|
||||||
|
|
|
||||||
|
|
@ -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
|
// Extracted handleFile function for reusability in drag-and-drop and file input
|
||||||
function handleFile(file) {
|
function handleFile(file) {
|
||||||
const fileList = document.querySelector("#file-list");
|
const fileList = document.querySelector("#file-list");
|
||||||
|
|
|
||||||
|
|
@ -311,7 +311,8 @@ export const history = new Elysia()
|
||||||
|
|
||||||
if (jobIds.length === 0) return;
|
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;
|
if (!confirmed) return;
|
||||||
|
|
||||||
try {
|
try {
|
||||||
|
|
@ -330,14 +331,18 @@ export const history = new Elysia()
|
||||||
const result = await response.json();
|
const result = await response.json();
|
||||||
|
|
||||||
if (result.success || result.deleted > 0) {
|
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();
|
window.location.reload();
|
||||||
} else {
|
} else {
|
||||||
alert('Failed to delete jobs. Please try again.');
|
alert(window.t('history', 'deleteError'));
|
||||||
}
|
}
|
||||||
} catch (error) {
|
} catch (error) {
|
||||||
console.error('Error deleting jobs:', error);
|
console.error('Error deleting jobs:', error);
|
||||||
alert('An error occurred while deleting jobs. Please try again.');
|
alert(window.t('history', 'deleteError'));
|
||||||
}
|
}
|
||||||
});
|
});
|
||||||
});
|
});
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue