新增錯誤排查與支援文件，提供常見問題解決方案；新增開發與貢獻指南，說明專案結構與開發流程；新增授權說明文件，詳述AGPL-3.0授權條款及第三方元件使用情況。
This commit is contained in:
Your Name
parent
11d751250b
commit
caecb2e001
13 changed files with 3269 additions and 369 deletions
380
docs/02-部署指南.md
Normal file
380
docs/02-部署指南.md
Normal file
|
|
@ -0,0 +1,380 @@
|
|||
# 部署指南
|
||||
|
||||
詳細說明 ConvertX-CN 的各種部署方式與進階配置。
|
||||
|
||||
---
|
||||
|
||||
## 目錄
|
||||
|
||||
- [本地部署步驟](#本地部署步驟)
|
||||
- [Docker 設定](#docker-設定)
|
||||
- [反向代理設定](#反向代理設定)
|
||||
- [HTTPS 設定](#https-設定)
|
||||
- [更新與維護](#更新與維護)
|
||||
|
||||
---
|
||||
|
||||
## 本地部署步驟
|
||||
|
||||
### 系統需求
|
||||
|
||||
| 項目 | 最低需求 | 建議配置 |
|
||||
|------|---------|---------|
|
||||
| CPU | 2 核心 | 4 核心以上 |
|
||||
| 記憶體 | 4 GB | 8 GB 以上 |
|
||||
| 磁碟空間 | 10 GB | 30 GB SSD |
|
||||
| 網路 | 10 Mbps | 100 Mbps |
|
||||
|
||||
### 準備工作
|
||||
|
||||
1. **安裝 Docker**
|
||||
|
||||
```bash
|
||||
# Ubuntu / Debian
|
||||
curl -fsSL https://get.docker.com | sh
|
||||
sudo usermod -aG docker $USER
|
||||
|
||||
# CentOS / RHEL
|
||||
sudo yum install -y docker
|
||||
sudo systemctl start docker
|
||||
sudo systemctl enable docker
|
||||
```
|
||||
|
||||
2. **建立專案目錄**
|
||||
|
||||
```bash
|
||||
mkdir -p ~/convertx-cn/data
|
||||
cd ~/convertx-cn
|
||||
```
|
||||
|
||||
3. **產生 JWT 密鑰**
|
||||
|
||||
```bash
|
||||
# Linux / macOS
|
||||
openssl rand -hex 32
|
||||
|
||||
# Windows PowerShell
|
||||
-join ((1..32) | ForEach-Object { '{0:x2}' -f (Get-Random -Max 256) })
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Docker 設定
|
||||
|
||||
### 基本部署
|
||||
|
||||
```yaml
|
||||
# docker-compose.yml
|
||||
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字元
|
||||
```
|
||||
|
||||
### 進階部署（含資源限制）
|
||||
|
||||
```yaml
|
||||
# docker-compose.yml
|
||||
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字元
|
||||
- MAX_CONVERT_PROCESS=4
|
||||
- AUTO_DELETE_EVERY_N_HOURS=12
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: '4'
|
||||
memory: 8G
|
||||
reservations:
|
||||
cpus: '2'
|
||||
memory: 4G
|
||||
healthcheck:
|
||||
test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
|
||||
interval: 30s
|
||||
timeout: 10s
|
||||
retries: 3
|
||||
```
|
||||
|
||||
### Lite 版部署
|
||||
|
||||
適用於資源有限或只需要基本轉換功能的環境：
|
||||
|
||||
```yaml
|
||||
# docker-compose.yml
|
||||
services:
|
||||
convertx:
|
||||
image: convertx/convertx-cn:latest-lite
|
||||
container_name: convertx-cn-lite
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "3000:3000"
|
||||
volumes:
|
||||
- ./data:/app/data
|
||||
environment:
|
||||
- TZ=Asia/Taipei
|
||||
- JWT_SECRET=您的隨機密鑰至少32字元
|
||||
```
|
||||
|
||||
### 環境變數說明
|
||||
|
||||
| 變數 | 說明 | 預設值 |
|
||||
|------|------|--------|
|
||||
| `JWT_SECRET` | 登入驗證金鑰（**必填**） | 隨機（每次重啟變） |
|
||||
| `TZ` | 時區 | `UTC` |
|
||||
| `HTTP_ALLOWED` | 允許 HTTP 連線 | `false` |
|
||||
| `TRUST_PROXY` | 信任反向代理 | `false` |
|
||||
|
||||
> 📖 完整變數列表請參閱 [03-環境變數與設定](03-環境變數與設定.md)
|
||||
|
||||
---
|
||||
|
||||
## 反向代理設定
|
||||
|
||||
### 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 設定
|
||||
|
||||
```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.certresolver=letsencrypt"
|
||||
- "traefik.http.services.convertx.loadbalancer.server.port=3000"
|
||||
```
|
||||
|
||||
### Caddy 設定
|
||||
|
||||
```
|
||||
# Caddyfile
|
||||
convertx.example.com {
|
||||
reverse_proxy localhost:3000
|
||||
}
|
||||
```
|
||||
|
||||
### 反向代理必要設定
|
||||
|
||||
使用反向代理時，請確保設定以下環境變數：
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- TRUST_PROXY=true # 信任反向代理的 headers
|
||||
- HTTP_ALLOWED=false # 反向代理已處理 HTTPS
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## HTTPS 設定
|
||||
|
||||
### 使用 Let's Encrypt
|
||||
|
||||
1. **安裝 Certbot**
|
||||
|
||||
```bash
|
||||
# Ubuntu / Debian
|
||||
sudo apt install certbot python3-certbot-nginx
|
||||
|
||||
# CentOS / RHEL
|
||||
sudo yum install certbot python3-certbot-nginx
|
||||
```
|
||||
|
||||
2. **取得憑證**
|
||||
|
||||
```bash
|
||||
sudo certbot --nginx -d convertx.example.com
|
||||
```
|
||||
|
||||
3. **自動續約**
|
||||
|
||||
```bash
|
||||
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.local"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 更新與維護
|
||||
|
||||
### 更新至最新版本
|
||||
|
||||
```bash
|
||||
# 進入專案目錄
|
||||
cd ~/convertx-cn
|
||||
|
||||
# 停止並更新
|
||||
docker compose down
|
||||
docker compose pull
|
||||
docker compose up -d
|
||||
|
||||
# 清理舊映像檔
|
||||
docker image prune -f
|
||||
```
|
||||
|
||||
### 備份資料
|
||||
|
||||
```bash
|
||||
# 備份資料目錄
|
||||
tar -czvf convertx-backup-$(date +%Y%m%d).tar.gz ./data
|
||||
|
||||
# 還原資料
|
||||
tar -xzvf convertx-backup-20260125.tar.gz
|
||||
```
|
||||
|
||||
### 查看日誌
|
||||
|
||||
```bash
|
||||
# 即時日誌
|
||||
docker logs -f convertx-cn
|
||||
|
||||
# 最近 100 行
|
||||
docker logs --tail 100 convertx-cn
|
||||
|
||||
# 指定時間範圍
|
||||
docker logs --since "2026-01-25T00:00:00" convertx-cn
|
||||
```
|
||||
|
||||
### 重新啟動
|
||||
|
||||
```bash
|
||||
# 重新啟動容器
|
||||
docker restart convertx-cn
|
||||
|
||||
# 完全重建
|
||||
docker compose down
|
||||
docker compose up -d --force-recreate
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 進階配置
|
||||
|
||||
### 使用外部資料庫
|
||||
|
||||
```yaml
|
||||
services:
|
||||
convertx:
|
||||
image: convertx/convertx-cn:latest
|
||||
environment:
|
||||
- DATABASE_URL=sqlite:///app/data/mydb.sqlite
|
||||
volumes:
|
||||
- ./data:/app/data
|
||||
```
|
||||
|
||||
### 設定 API Server
|
||||
|
||||
```yaml
|
||||
services:
|
||||
convertx:
|
||||
image: convertx/convertx-cn:latest
|
||||
ports:
|
||||
- "3000:3000"
|
||||
volumes:
|
||||
- ./data:/app/data
|
||||
environment:
|
||||
- JWT_SECRET=${JWT_SECRET}
|
||||
|
||||
api-server:
|
||||
image: convertx/convertx-cn-api:latest
|
||||
ports:
|
||||
- "3001:3001"
|
||||
environment:
|
||||
- JWT_SECRET=${JWT_SECRET}
|
||||
- API_PORT=3001
|
||||
depends_on:
|
||||
- convertx
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
[⬆️ 回到頂部](#部署指南) | [📚 回到目錄](00-專案總覽.md)
|
||||
Loading…
Add table
Add a link
Reference in a new issue