# PANJIT 文件翻譯系統 - 部署指南

本指南說明如何在公司內部以 Docker 方式部署系統至生產環境，並提供日常維運要點。

## 生產最佳化更新（重要）
- 後端以 Gunicorn + eventlet 啟動（WSGI 入口：`wsgi:app`），提升併發與穩定性。
- Socket.IO 啟用 Redis message queue（`REDIS_URL`），支援多進程/多副本一致廣播。
- Celery worker 預設併發提高至 8，可依 CPU 與佇列長度再水平擴展。
- Redis 僅供容器內部使用，Compose 預設不再對外暴露 6379。
- 新增套件內根路由提供 SPA 與 `/api`、`/api/health`（`/api/v1/health` 仍由健康檢查藍圖提供）。

## 系統架構

- 前端：Vue（Vite 打包後為靜態檔，容器內由後端服務）
- 後端：Flask + Flask-SocketIO（eventlet）+ SQLAlchemy + JWT
- 佇列：Celery（Redis broker/result）
- 資料庫：MySQL（透過 SQLAlchemy 連線池）

## 需求與準備

- Docker 20.10+、Docker Compose 1.28+
- 4GB 以上可用記憶體、20GB 以上可用磁碟空間
- 內部網路可存取 MySQL、LDAP、SMTP、Dify API

## 快速部署

```bash
# 1) 進入專案目錄
cd Document_translator_V2

# 2) 建置並啟動（首次執行會自動 build）
docker-compose up -d

# 3) 檢查服務狀態
docker-compose ps

# 4) 追蹤應用日誌
docker-compose logs -f app
```

驗證健康與前端：

```bash
curl http://localhost:12010/api/v1/health
curl http://localhost:12010/
```

檢查 Celery worker：

```bash
docker-compose exec celery-worker celery -A celery_app inspect active
```

## 詳細部署步驟

### 1) 主機檢查

```bash
# 記憶體 / 磁碟 / 埠使用
free -h
df -h
netstat -tulpn | grep 12010 || ss -lntp | grep 12010

# Docker 狀態
docker --version
docker-compose --version
docker system info
```

### 2) 建置映像

```bash
docker build -t panjit-translator:latest .
docker images panjit-translator
```

### 3) 使用 Docker Compose 啟動（推薦）

```bash
docker-compose up -d
docker-compose ps
docker-compose logs app
docker-compose logs celery-worker
docker-compose logs redis
```

### 4) 純 Docker 佈署（可選）

```bash
# 啟動 Redis（內部使用，無需對外開放）
docker run -d --name panjit-redis \
  -v redis_data:/data \
  redis:7-alpine

# 啟動主應用（Gunicorn + eventlet, 12010）
docker run -d --name panjit-translator \
  -p 12010:12010 \
  -v $(pwd)/uploads:/app/uploads \
  -v $(pwd)/cache:/app/cache \
  -v $(pwd)/logs:/app/logs \
  --link panjit-redis:redis \
  -e REDIS_URL=redis://redis:6379/0 \
  panjit-translator:latest

# 啟動 Celery Worker（可調整並行度）
docker run -d --name panjit-worker \
  -v $(pwd)/uploads:/app/uploads \
  -v $(pwd)/cache:/app/cache \
  --link panjit-redis:redis \
  -e REDIS_URL=redis://redis:6379/0 \
  panjit-translator:latest \
  celery -A celery_app worker --loglevel=info --concurrency=8
```

## 驗證與健康檢查

```bash
# 健康檢查（API 藍圖）
curl http://localhost:12010/api/v1/health

# 前端/靜態頁
curl http://localhost:12010/

# WebSocket（瀏覽器端透過前端頁面測試）
```

## 擴展與監控

```bash
# 觀察資源
docker stats

# 觀察容器狀態
docker-compose ps

# 擴展 Celery Worker 副本（例如 3 副本）
docker-compose up -d --scale celery-worker=3
```

## 安全與網路

```bash
# 僅開放必要端口（應用 12010）
sudo ufw allow 12010/tcp

# Redis 預設不對外開放；如需遠端維運才開放 6379 並限管理網段
# sudo ufw allow from <管理網段> to any port 6379 proto tcp
```

如需 HTTPS，建議於前端加 Nginx/Traefik 反向代理：

```nginx
server {
    listen 443 ssl;
    server_name translator.panjit.com.tw;

    ssl_certificate /path/to/certificate.crt;
    ssl_certificate_key /path/to/private.key;

    location / {
        proxy_pass http://localhost:12010;
        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;
    }
}
```

## 疑難排解（內部）

資料庫連線測試（內部憑證）：

```bash
docker-compose exec app python -c "
import pymysql
try:
    conn = pymysql.connect(
        host='mysql.theaken.com',
        port=33306,
        user='A060',
        password='WLeSCi0yhtc7',
        database='db_A060'
    )
    print('資料庫連線成功')
    conn.close()
except Exception as e:
    print(f'資料庫連線失敗: {e}')
"
```

Redis 連線測試：

```bash
docker-compose exec app python -c "
import redis
try:
    r = redis.Redis.from_url('redis://redis:6379/0')
    r.ping()
    print('Redis 連線成功')
except Exception as e:
    print(f'Redis 連線失敗: {e}')
"
```

重建與清理：

```bash
docker-compose down -v
docker system prune -f
docker-compose build --no-cache
docker-compose up -d
```

## 維運與更新

```bash
# 備份重要資料（uploads/cache/logs）
docker-compose exec app tar -czf /app/backup_$(date +%Y%m%d).tar.gz uploads/ cache/

# 更新程式碼與重建
docker-compose down
git pull origin main
docker-compose build
docker-compose up -d

# 驗證
curl http://localhost:12010/api/v1/health
```

零停機滾動更新（僅針對單一服務重新拉起）：

```bash
docker-compose up -d --no-deps app
docker-compose up -d --no-deps celery-worker
```

## 聯繫支援

PANJIT IT Team（內部）
- Email: it-support@panjit.com.tw
- 分機: 2481
- 緊急支援: 24/7 待命

---
本文件適用於 PANJIT 文件翻譯系統 v2.1.0