# 部署指南

詳細說明 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)