feat(i18n): add multilingual support with translations for English, Japanese, and Simplified Chinese
- Create README.md for internationalization (i18n) documentation - Add English translation for main README and quick start guide - Add Japanese translation for main README - Add Simplified Chinese translation for main README - Introduce sample Docker Compose configurations for various deployment scenarios - Implement CI/CD documentation for testing and deployment workflows - Establish end-to-end testing guidelines and strategies - Create test strategy documentation outlining unit, integration, and E2E tests
This commit is contained in:
Your Name
parent
b3b382d1e0
commit
da856d89ff
42 changed files with 4901 additions and 263 deletions
255
docs/deployment/docker.md
Normal file
255
docs/deployment/docker.md
Normal file
|
|
@ -0,0 +1,255 @@
|
|||
# Docker 部署指南
|
||||
|
||||
本文件說明如何使用 Docker 部署 ConvertX-CN。
|
||||
|
||||
---
|
||||
|
||||
## Docker Image 版本
|
||||
|
||||
### 官方預建版（推薦）
|
||||
|
||||
| Tag | 說明 |
|
||||
| ----------------------------- | ---------- |
|
||||
| `convertx/convertx-cn:latest` | 最新穩定版 |
|
||||
| `convertx/convertx-cn:v0.1.x` | 指定版本號 |
|
||||
|
||||
**內建功能：**
|
||||
|
||||
- ✅ 核心轉換工具（FFmpeg、LibreOffice、ImageMagick 等）
|
||||
- ✅ OCR 支援：英文、繁/簡中文、日文、韓文、德文、法文
|
||||
- ✅ 字型：Noto CJK、Liberation、自訂中文字型
|
||||
- ✅ TexLive（支援 CJK/德/法）
|
||||
|
||||
**Image 大小：約 4-6 GB**
|
||||
|
||||
### 完整版（自行 Build）
|
||||
|
||||
使用 `Dockerfile.full` 自行建構，適合需要：
|
||||
|
||||
- 65 種 OCR 語言
|
||||
- 完整 TexLive
|
||||
- 額外字型套件
|
||||
|
||||
```bash
|
||||
docker build -f Dockerfile.full -t convertx-cn-full .
|
||||
```
|
||||
|
||||
> ⚠️ 注意：Image 大小可能超過 **10GB**，Build 時間約 **30-60 分鐘**
|
||||
|
||||
---
|
||||
|
||||
## Docker Run
|
||||
|
||||
### 基本啟動
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name convertx-cn \
|
||||
--restart unless-stopped \
|
||||
-p 3000:3000 \
|
||||
-v ./data:/app/data \
|
||||
-e TZ=Asia/Taipei \
|
||||
-e JWT_SECRET=你的隨機字串至少32字元 \
|
||||
convertx/convertx-cn:latest
|
||||
```
|
||||
|
||||
### 參數說明
|
||||
|
||||
| 參數 | 說明 |
|
||||
| -------------------------- | ---------- |
|
||||
| `-d` | 背景執行 |
|
||||
| `--name convertx-cn` | 容器名稱 |
|
||||
| `--restart unless-stopped` | 自動重啟 |
|
||||
| `-p 3000:3000` | 連接埠映射 |
|
||||
| `-v ./data:/app/data` | 資料持久化 |
|
||||
| `-e TZ=Asia/Taipei` | 時區設定 |
|
||||
|
||||
### 進階選項
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name convertx-cn \
|
||||
--restart unless-stopped \
|
||||
-p 3000:3000 \
|
||||
-v ./data:/app/data \
|
||||
-e TZ=Asia/Taipei \
|
||||
-e JWT_SECRET=你的隨機字串 \
|
||||
-e ACCOUNT_REGISTRATION=false \
|
||||
-e HTTP_ALLOWED=true \
|
||||
-e AUTO_DELETE_EVERY_N_HOURS=24 \
|
||||
convertx/convertx-cn:latest
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 資料持久化
|
||||
|
||||
### Volume 結構
|
||||
|
||||
```
|
||||
./data/
|
||||
├── convertx.db # SQLite 資料庫
|
||||
├── uploads/ # 上傳的原始檔案
|
||||
└── output/ # 轉換後的檔案
|
||||
```
|
||||
|
||||
### 建立資料夾
|
||||
|
||||
**重要**：請務必先建立資料夾，否則 Docker 會建立匿名 volume。
|
||||
|
||||
```bash
|
||||
# Linux / macOS
|
||||
mkdir -p ~/convertx-cn/data
|
||||
|
||||
# Windows PowerShell
|
||||
mkdir C:\convertx-cn\data
|
||||
```
|
||||
|
||||
### 備份與還原
|
||||
|
||||
```bash
|
||||
# 備份
|
||||
tar -czvf convertx-backup-$(date +%Y%m%d).tar.gz ./data
|
||||
|
||||
# 還原
|
||||
tar -xzvf convertx-backup-20260120.tar.gz
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 硬體加速
|
||||
|
||||
### NVIDIA GPU (CUDA/NVENC)
|
||||
|
||||
1. 安裝 [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html)
|
||||
|
||||
2. Docker Compose 配置：
|
||||
|
||||
```yaml
|
||||
services:
|
||||
convertx:
|
||||
image: convertx/convertx-cn:latest
|
||||
deploy:
|
||||
resources:
|
||||
reservations:
|
||||
devices:
|
||||
- driver: nvidia
|
||||
count: all
|
||||
capabilities: [gpu]
|
||||
environment:
|
||||
- FFMPEG_ARGS=-hwaccel cuda -hwaccel_output_format cuda
|
||||
- FFMPEG_OUTPUT_ARGS=-c:v h264_nvenc -preset fast
|
||||
```
|
||||
|
||||
### Intel Quick Sync Video (QSV)
|
||||
|
||||
```yaml
|
||||
services:
|
||||
convertx:
|
||||
image: convertx/convertx-cn:latest
|
||||
devices:
|
||||
- /dev/dri:/dev/dri
|
||||
environment:
|
||||
- FFMPEG_ARGS=-hwaccel qsv
|
||||
- FFMPEG_OUTPUT_ARGS=-c:v h264_qsv -preset faster
|
||||
```
|
||||
|
||||
### AMD VAAPI
|
||||
|
||||
```yaml
|
||||
services:
|
||||
convertx:
|
||||
image: convertx/convertx-cn:latest
|
||||
devices:
|
||||
- /dev/dri:/dev/dri
|
||||
environment:
|
||||
- FFMPEG_ARGS=-hwaccel vaapi -hwaccel_device /dev/dri/renderD128
|
||||
- FFMPEG_OUTPUT_ARGS=-c:v h264_vaapi
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 資源限制
|
||||
|
||||
### 記憶體限制
|
||||
|
||||
```yaml
|
||||
services:
|
||||
convertx:
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
memory: 4G
|
||||
reservations:
|
||||
memory: 2G
|
||||
```
|
||||
|
||||
### CPU 限制
|
||||
|
||||
```yaml
|
||||
services:
|
||||
convertx:
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: "2"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 版本更新
|
||||
|
||||
```bash
|
||||
# 拉取最新版本
|
||||
docker pull convertx/convertx-cn:latest
|
||||
|
||||
# 停止並移除舊容器
|
||||
docker stop convertx-cn
|
||||
docker rm convertx-cn
|
||||
|
||||
# 重新啟動（使用相同的參數）
|
||||
docker run -d \
|
||||
--name convertx-cn \
|
||||
# ... 其他參數
|
||||
```
|
||||
|
||||
或使用 Docker Compose：
|
||||
|
||||
```bash
|
||||
docker compose pull
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 疑難排解
|
||||
|
||||
### 查看日誌
|
||||
|
||||
```bash
|
||||
docker logs convertx-cn
|
||||
docker logs -f convertx-cn # 持續追蹤
|
||||
```
|
||||
|
||||
### 進入容器
|
||||
|
||||
```bash
|
||||
docker exec -it convertx-cn /bin/bash
|
||||
```
|
||||
|
||||
### 常見問題
|
||||
|
||||
| 問題 | 解決方法 |
|
||||
| ----------- | ------------------------------ |
|
||||
| 啟動失敗 | 檢查日誌 `docker logs` |
|
||||
| Port 被占用 | 改用其他 port `-p 8080:3000` |
|
||||
| 權限錯誤 | `chmod -R 777 ./data` |
|
||||
| 記憶體不足 | 增加記憶體限制或減少同時轉換數 |
|
||||
|
||||
---
|
||||
|
||||
## 相關文件
|
||||
|
||||
- [Docker Compose 詳解](docker-compose.md)
|
||||
- [反向代理設定](reverse-proxy.md)
|
||||
- [環境變數設定](../configuration/environment-variables.md)
|
||||
287
docs/deployment/reverse-proxy.md
Normal file
287
docs/deployment/reverse-proxy.md
Normal file
|
|
@ -0,0 +1,287 @@
|
|||
# 反向代理設定
|
||||
|
||||
本文件說明如何在 Nginx、Traefik、Caddy 等反向代理後部署 ConvertX-CN。
|
||||
|
||||
---
|
||||
|
||||
## 必要環境變數
|
||||
|
||||
透過反向代理存取時，請設定：
|
||||
|
||||
```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;
|
||||
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 3600s;
|
||||
proxy_send_timeout 3600s;
|
||||
|
||||
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";
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 啟用設定
|
||||
|
||||
```bash
|
||||
sudo ln -s /etc/nginx/sites-available/convertx /etc/nginx/sites-enabled/
|
||||
sudo nginx -t
|
||||
sudo systemctl reload nginx
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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=${JWT_SECRET}
|
||||
- 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
|
||||
|
||||
### 基本配置
|
||||
|
||||
```
|
||||
convertx.example.com {
|
||||
reverse_proxy localhost:3000 {
|
||||
header_up X-Real-IP {remote_host}
|
||||
header_up X-Forwarded-Proto {scheme}
|
||||
}
|
||||
|
||||
request_body {
|
||||
max_size 500MB
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 子路徑部署
|
||||
|
||||
```
|
||||
example.com {
|
||||
handle_path /convertx/* {
|
||||
reverse_proxy localhost:3000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
記得設定環境變數：
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- WEBROOT=/convertx
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Cloudflare Tunnel
|
||||
|
||||
### 1. 建立 Tunnel
|
||||
|
||||
```bash
|
||||
cloudflared tunnel create convertx
|
||||
```
|
||||
|
||||
### 2. 配置
|
||||
|
||||
```yaml
|
||||
# ~/.cloudflared/config.yml
|
||||
tunnel: <tunnel-id>
|
||||
credentials-file: ~/.cloudflared/<tunnel-id>.json
|
||||
|
||||
ingress:
|
||||
- hostname: convertx.example.com
|
||||
service: http://localhost:3000
|
||||
- service: http_status:404
|
||||
```
|
||||
|
||||
### 3. 啟動
|
||||
|
||||
```bash
|
||||
cloudflared tunnel run convertx
|
||||
```
|
||||
|
||||
### 4. 環境變數
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- TRUST_PROXY=true
|
||||
- HTTP_ALLOWED=false
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 子路徑部署
|
||||
|
||||
如需在子路徑部署（如 `https://example.com/convertx`）：
|
||||
|
||||
### 1. 設定環境變數
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- WEBROOT=/convertx
|
||||
```
|
||||
|
||||
### 2. Nginx 配置
|
||||
|
||||
```nginx
|
||||
location /convertx/ {
|
||||
proxy_pass http://localhost:3000/;
|
||||
# ... 其他 proxy 設定
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Caddy 配置
|
||||
|
||||
```
|
||||
example.com {
|
||||
handle_path /convertx/* {
|
||||
reverse_proxy localhost:3000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## HTTPS 憑證
|
||||
|
||||
### Let's Encrypt（推薦）
|
||||
|
||||
使用 Certbot 自動取得憑證：
|
||||
|
||||
```bash
|
||||
sudo apt install certbot python3-certbot-nginx
|
||||
sudo certbot --nginx -d convertx.example.com
|
||||
```
|
||||
|
||||
### 自簽憑證（測試用）
|
||||
|
||||
```bash
|
||||
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
|
||||
-keyout /etc/nginx/ssl/convertx.key \
|
||||
-out /etc/nginx/ssl/convertx.crt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 疑難排解
|
||||
|
||||
### 登入後被踢回登入頁
|
||||
|
||||
1. 確認 `TRUST_PROXY=true`
|
||||
2. 確認反向代理正確傳送 `X-Forwarded-Proto` header
|
||||
|
||||
### 上傳檔案失敗
|
||||
|
||||
1. 調高 `client_max_body_size`（Nginx）
|
||||
2. 調高 `request_body max_size`（Caddy）
|
||||
3. 調高超時設定
|
||||
|
||||
### WebSocket 連線失敗
|
||||
|
||||
確認反向代理正確處理 WebSocket：
|
||||
|
||||
```nginx
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 相關文件
|
||||
|
||||
- [Docker 部署](docker.md)
|
||||
- [安全性設定](../configuration/security.md)
|
||||
- [環境變數](../configuration/environment-variables.md)
|
||||
Loading…
Add table
Add a link
Reference in a new issue