394dcbec1a
- Updated tables for service ports, environment variables, HTTP status codes, and error codes to enhance readability. - Streamlined JavaScript examples for file conversion and added comments for better understanding. - Enhanced troubleshooting section with clearer formatting and additional explanations. - Improved licensing section with detailed requirements and third-party component licenses. - Organized the document structure for better navigation and accessibility.
380 lines
7.5 KiB
Markdown
380 lines
7.5 KiB
Markdown
# 部署指南
|
||
|
||
詳細說明 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)
|