Document_translator/DEPLOYMENT.md

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

快速部署

# 1) 進入專案目錄
cd Document_translator_V2

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

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

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

驗證健康與前端：

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

檢查 Celery worker：

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

詳細部署步驟

1) 主機檢查

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

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

2) 建置映像

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

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

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

4) 純 Docker 佈署（可選）

# 啟動 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

驗證與健康檢查

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

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

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

擴展與監控

# 觀察資源
docker stats

# 觀察容器狀態
docker-compose ps

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

安全與網路

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

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

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

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

疑難排解（內部）

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

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 連線測試：

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}')
"

重建與清理：

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

維運與更新

# 備份重要資料（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

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

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