convertor/docs/02-部署指南.md

部署指南

詳細說明 ConvertX-CN 的各種部署方式與進階配置。

---

目錄

• 本地部署步驟
• Docker 設定
• 反向代理設定
• HTTPS 設定
• 更新與維護

---

本地部署步驟

系統需求

項目	最低需求	建議配置
CPU	2 核心	4 核心以上
記憶體	4 GB	8 GB 以上
磁碟空間	10 GB	30 GB SSD
網路	10 Mbps	100 Mbps

準備工作

1. 安裝 Docker

   # 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. 建立專案目錄

   mkdir -p ~/convertx-cn/data
   cd ~/convertx-cn
   

3. 產生 JWT 密鑰

   # Linux / macOS
   openssl rand -hex 32
   
   # Windows PowerShell
   -join ((1..32) | ForEach-Object { '{0:x2}' -f (Get-Random -Max 256) })
   

---

Docker 設定

基本部署

# 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字元

進階部署（含資源限制）

# 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 版部署

適用於資源有限或只需要基本轉換功能的環境：

# 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-環境變數與設定

---

反向代理設定

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";
    }
}

啟用設定：

sudo ln -s /etc/nginx/sites-available/convertx /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Traefik 設定

# 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
}

反向代理必要設定

使用反向代理時，請確保設定以下環境變數：

environment:
  - TRUST_PROXY=true      # 信任反向代理的 headers
  - HTTP_ALLOWED=false    # 反向代理已處理 HTTPS

---

HTTPS 設定

使用 Let's Encrypt

1. 安裝 Certbot

   # Ubuntu / Debian
   sudo apt install certbot python3-certbot-nginx
   
   # CentOS / RHEL
   sudo yum install certbot python3-certbot-nginx
   

2. 取得憑證

   sudo certbot --nginx -d convertx.example.com
   

3. 自動續約

   sudo certbot renew --dry-run
   

使用自簽憑證（測試用）

# 產生自簽憑證
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"

---

更新與維護

更新至最新版本

# 進入專案目錄
cd ~/convertx-cn

# 停止並更新
docker compose down
docker compose pull
docker compose up -d

# 清理舊映像檔
docker image prune -f

備份資料

# 備份資料目錄
tar -czvf convertx-backup-$(date +%Y%m%d).tar.gz ./data

# 還原資料
tar -xzvf convertx-backup-20260125.tar.gz

查看日誌

# 即時日誌
docker logs -f convertx-cn

# 最近 100 行
docker logs --tail 100 convertx-cn

# 指定時間範圍
docker logs --since "2026-01-25T00:00:00" convertx-cn

重新啟動

# 重新啟動容器
docker restart convertx-cn

# 完全重建
docker compose down
docker compose up -d --force-recreate

---

進階配置

使用外部資料庫

services:
  convertx:
    image: convertx/convertx-cn:latest
    environment:
      - DATABASE_URL=sqlite:///app/data/mydb.sqlite
    volumes:
      - ./data:/app/data

設定 API Server

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

---

⬆️ 回到頂部 | 📚 回到目錄