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

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)