Document_Translator/DEPLOYMENT.md

PANJIT 文件翻譯系統 - 部署手冊

部署概述

本系統已完成生產環境準備，包含完整的 Docker 配置和環境設定。系統使用 12010 端口，符合公司端口規範 (12010-12019)。

系統架構

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend      │    │   Backend       │    │   Celery        │
│   (Vue.js)      │    │   (Flask)       │    │   (Worker)      │
│   Port: 12010   │────│   Port: 12010   │────│   Background    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                    ┌─────────────────┐
                    │     Redis       │
                    │   (Queue/Cache) │
                    │   Port: 6379    │
                    └─────────────────┘

快速部署

前置需求

• Docker 20.10+
• Docker Compose 1.28+
• 至少 4GB 可用記憶體
• 至少 20GB 可用磁碟空間

一鍵部署

# 1. 進入專案目錄
cd Document_translator_V2

# 2. 建置並啟動所有服務
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 app.celery inspect active

詳細部署步驟

1. 環境準備

檢查系統資源

# 檢查記憶體
free -h

# 檢查磁碟空間
df -h

# 檢查端口占用
netstat -tulpn | grep 12010

檢查 Docker 環境

docker --version
docker-compose --version
docker system info

2. 配置文件檢查

系統已包含完整的生產環境配置：

資料庫配置

• MySQL 主機：mysql.theaken.com:33306
• 資料庫：db_A060
• 連接已內建在 Docker 映像中

郵件配置

• SMTP 服務器：mail.panjit.com.tw
• 端口：25 (無認證)

LDAP 配置

• 服務器：panjit.com.tw
• 認證已配置完成

3. 建置映像

# 建置主應用映像
docker build -t panjit-translator:latest .

# 檢查映像大小
docker images panjit-translator

4. 啟動服務

使用 Docker Compose (推薦)

# 啟動所有服務
docker-compose up -d

# 分別檢查各服務
docker-compose ps
docker-compose logs app
docker-compose logs celery-worker
docker-compose logs redis

手動 Docker 部署

# 啟動 Redis
docker run -d --name panjit-redis \
  -p 6379:6379 \
  -v redis_data:/data \
  redis:7-alpine

# 啟動主應用
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 app.celery worker --loglevel=info

5. 服務驗證

健康檢查

# API 健康檢查
curl -f http://localhost:12010/api/v1/health

# 預期回應：
{
  "status": "healthy",
  "timestamp": "2025-09-04T12:00:00Z",
  "service": "PANJIT Document Translator API",
  "version": "2.0.0"
}

功能測試

# 測試 LDAP 連接 (需要有效帳號)
curl -X POST http://localhost:12010/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "test@panjit.com.tw", "password": "password"}'

# 測試檔案上傳端點
curl -f http://localhost:12010/api/v1/files/supported-formats

Celery 檢查

# 檢查 Worker 狀態
docker-compose exec app celery -A app.celery inspect active

# 檢查佇列狀態
docker-compose exec app celery -A app.celery inspect reserved

監控和維護

日誌管理

# 查看實時日誌
docker-compose logs -f

# 查看特定服務日誌
docker-compose logs -f app
docker-compose logs -f celery-worker

# 查看錯誤日誌
docker-compose logs app | grep ERROR

性能監控

# 檢查容器資源使用
docker stats

# 檢查服務狀態
docker-compose ps

# 檢查健康狀況
docker inspect panjit-translator-app --format='{{json .State.Health}}'

備份和恢復

# 備份上傳檔案
tar -czf uploads_backup_$(date +%Y%m%d).tar.gz uploads/

# 備份快取
tar -czf cache_backup_$(date +%Y%m%d).tar.gz cache/

# 備份日誌
tar -czf logs_backup_$(date +%Y%m%d).tar.gz logs/

更新和升級

更新應用

# 1. 備份重要數據
docker-compose exec app tar -czf /app/backup_$(date +%Y%m%d).tar.gz uploads/ cache/

# 2. 停止服務
docker-compose down

# 3. 更新代碼和重新建置
git pull origin main
docker-compose build

# 4. 啟動服務
docker-compose up -d

# 5. 驗證更新
curl http://localhost:12010/api/v1/health

滾動更新（零停機時間）

# 1. 建置新映像
docker build -t panjit-translator:v2.1.0 .

# 2. 更新 docker-compose.yml 中的映像版本
# 3. 逐一重啟服務
docker-compose up -d --no-deps app
docker-compose up -d --no-deps celery-worker

故障排除

常見問題

1. 容器無法啟動

# 檢查端口占用
sudo netstat -tulpn | grep 12010

# 檢查映像是否存在
docker images panjit-translator

# 檢查容器日誌
docker-compose logs app

2. 資料庫連接失敗

# 測試資料庫連接
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}')
"

3. Celery Worker 無法啟動

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

# 重啟 Worker
docker-compose restart celery-worker

緊急恢復

# 完全重置並重啟
docker-compose down -v
docker-compose up -d

# 清理未使用的映像和容器
docker system prune -f

# 重新建置
docker-compose build --no-cache
docker-compose up -d

安全配置

防火牆設定

# 開放必要端口
sudo ufw allow 12010/tcp

# 限制 Redis 端口（僅本機）
sudo ufw deny 6379/tcp

SSL/TLS 配置

如需 HTTPS，建議在前端配置 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;
    }
}

聯繫支援

如遇到部署問題，請聯繫：

PANJIT IT Team

• Email: it-support@panjit.com.tw
• 內線電話: 2481
• 緊急支援: 24/7 待命

系統資訊

• 版本：v2.0.0
• 部署日期：2025-09-04
• 維護人員：System Administrator

---

本部署手冊適用於 PANJIT 文件翻譯系統 v2.0.0