Elijah/convertor
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat: v0.1.9 - Setup 頁面 i18n + 語言選擇器 UI 修復 + 文件重構

Browse source 
✨ 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 2026-01-20 15:55:49 +08:00
parent a45a049fe2
commit d563682753
14 changed files with 1305 additions and 594 deletions
Download patch file Download diff file Expand all files Collapse all files

237
docs/config/environment.md Normal file
View 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
View 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
View 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
View 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
View 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)

45
docs/docker-compose/README.md
View file

@ -4,50 +4,45 @@
## 範例檔案
| 檔案 | 適用情境 | 說明 |
| ------------------------------------------------ | ----------- | ------------------------- |
| [compose.minimal.yml](compose.minimal.yml) | Docker 老手 | 最精簡的可用配置 |
| [compose.production.yml](compose.production.yml) | 生產環境 | 含 Reverse Proxy 設定說明 |
| [compose.reference.yml](compose.reference.yml) | 參考文件 | 所有可用設定的完整參考 |
| 檔案 | 適用情境 | 說明 |
| ------------------------------------------------ | ----------- | --------------------- |
| [compose.minimal.yml](compose.minimal.yml) | Docker 老手 | 最精簡的可用配置 |
| [compose.production.yml](compose.production.yml) | 生產環境 | 含 Reverse Proxy 設定 |
| [compose.reference.yml](compose.reference.yml) | 參考文件 | 所有設定的完整參考 |
## 快速選擇
| 你是... | 使用 |
| ------------ | ------------------------------ |
| 新手 | [README 主頁](../../README.md) |
| Docker 熟手 | compose.minimal.yml |
| 生產環境 | compose.production.yml |
| 查詢所有選項 | compose.reference.yml |
## 如何使用
### 方式 1：直接使用範例檔案
```bash
# 下載範例
curl -O https://raw.githubusercontent.com/pi-docket/ConvertX-CN/main/docs/docker-compose/compose.minimal.yml
# 重命名為 docker-compose.yml
# 重命名
mv compose.minimal.yml docker-compose.yml
# 建立 data 資料夾
mkdir -p data
# 修改設定（至少要改 JWT_SECRET）
# 修改 JWT_SECRET
nano docker-compose.yml
# 啟動
docker compose up -d
```
### 方式 2：複製內容
## 相關文件
1. 點擊上方檔案連結
2. 複製內容
3. 貼到你的 `docker-compose.yml`
4. 修改必要設定
5. 執行 `docker compose up -d`
## 選擇指南
### 我是新手
請直接使用 [README 主頁](../../README.md) 的教學版範例。
### 我熟悉 Docker
使用 [compose.minimal.yml](compose.minimal.yml)，只需修改 `JWT_SECRET`。
- [Docker Compose 詳解](../deployment/docker-compose.md)
- [環境變數說明](../config/environment.md)
- [版本選擇指南](../versions/)
### 我要部署到正式環境

157
docs/environment-variables.md
View file

@ -1,154 +1,27 @@
# 環境變數設定
本文件列出 ConvertX-CN 所有可用的環境變數設定。
> 📦 本文件已遷移至新位置，請參閱：[docs/config/environment.md](config/environment.md)
---
## 快速參考
| 重要程度 | 變數 | 說明 |
| -------- | -------------- | ---------------- |
| 🔴 必填 | `JWT_SECRET` | 生產環境必須設定 |
| 🟡 建議 | `TZ` | 時區設定 |
| 🟡 建議 | `HTTP_ALLOWED` | 是否允許 HTTP |
| 🟢 可選 | 其他 | 依需求設定 |
完整說明請參考 [環境變數完整說明](config/environment.md)。
| 優先級 | 變數 | 說明 |
| ------ | -------------- | ------------- |
| 必填 | `JWT_SECRET` | 登入驗證金鑰 |
| 建議 | `TZ` | 時區設定 |
| 建議 | `HTTP_ALLOWED` | 是否允許 HTTP |
| 可選 | `TRUST_PROXY` | 信任反向代理 |
---
## 🔴 必填設定（生產環境）
## 相關文件
### JWT_SECRET
| 項目 | 說明 |
| ------ | ---------------------------------- |
| 預設值 | `randomUUID()`（每次重啟都會改變） |
| 用途 | 用於簽署 JWT 的密鑰字串 |
**⚠️ 重要**：若不設定，每次容器重啟後所有使用者都需要重新登入。
**產生方式**：
```bash
# Linux / macOS
openssl rand -hex 32
# 輸出範例
# a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6
```
**設定方式**：
```yaml
environment:
- JWT_SECRET=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6
```
---
## 🟡 建議設定
### TZ（時區）
| 項目 | 說明 |
| ------ | ------------------------------ |
| 預設值 | `UTC` |
| 用途 | 影響檔案時間戳記與日期顯示格式 |
**常用值**：
| 地區 | 設定值 |
| ---- | --------------------- |
| 台灣 | `Asia/Taipei` |
| 中國 | `Asia/Shanghai` |
| 香港 | `Asia/Hong_Kong` |
| 日本 | `Asia/Tokyo` |
| 美東 | `America/New_York` |
| 美西 | `America/Los_Angeles` |
| 英國 | `Europe/London` |
### HTTP_ALLOWED
| 項目 | 說明 |
| ------ | --------------------- |
| 預設值 | `false` |
| 用途 | 是否允許非 HTTPS 連線 |
**設定指南**：
| 情境 | 設定值 |
| ------------------------------ | ------- |
| 本地測試（http://localhost） | `true` |
| 遠端部署且有 HTTPS | `false` |
| 遠端部署但沒有 HTTPS（不建議） | `true` |
**⚠️ 常見問題**：若設為 `false` 但實際用 HTTP 存取，會導致「登入後又被導回登入頁」。
### TRUST_PROXY
| 項目 | 說明 |
| ------ | ------------------------------------ |
| 預設值 | `false` |
| 用途 | 透過 Reverse Proxy 存取時設為 `true` |
讓應用程式信任 `X-Forwarded-Proto` 等 headers，正確判斷連線是否為 HTTPS。
**設定指南**：
| 情境 | 設定值 |
| ---------------------------- | ------- |
| 直接存取容器（無 Proxy） | `false` |
| 透過 Nginx / Traefik / Caddy | `true` |
---
## 🔒 安全性設定
### ACCOUNT_REGISTRATION
| 項目 | 說明 |
| ------ | ------------------ |
| 預設值 | `true` |
| 用途 | 是否允許註冊新帳號 |
**💡 注意**：首次註冊的帳號不受此限制，即使設為 `false` 仍可建立第一個帳號。
**建議**：
- 首次部署時設為 `true`
- 註冊好管理員帳號後改為 `false`
### ALLOW_UNAUTHENTICATED
| 項目 | 說明 |
| ------ | -------------------------- |
| 預設值 | `false` |
| 用途 | 是否允許未登入使用轉換功能 |
**⚠️ 風險**：設為 `true` 時：
- 任何人都可使用伺服器資源
- 可能被濫用（大量轉換、儲存空間耗盡）
**建議**：除非明確要提供公開服務，否則保持 `false`。
---
## 📁 檔案管理
### AUTO_DELETE_EVERY_N_HOURS
| 項目 | 說明 |
| ------ | ------------------------------------- |
| 預設值 | `24` |
| 用途 | 自動刪除超過 N 小時的檔案（0 = 停用） |
**範例**：
```yaml
# 每 48 小時清理一次
- AUTO_DELETE_EVERY_N_HOURS=48
# 停用自動清理（不建議，會佔滿磁碟）
- AUTO_DELETE_EVERY_N_HOURS=0
```
- [環境變數完整說明](config/environment.md)
- [安全性設定](config/security.md)
- [進階部署指南](deployment.md)
---

29
docs/versions/README.md Normal file
View 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
View 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
View 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)