# 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 可用磁碟空間

### 一鍵部署
```bash
# 1. 進入專案目錄
cd Document_translator_V2

# 2. 建置並啟動所有服務
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 狀態
docker-compose exec celery-worker celery -A app.celery inspect active
```

## 詳細部署步驟

### 1. 環境準備

**檢查系統資源**
```bash
# 檢查記憶體
free -h

# 檢查磁碟空間
df -h

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

**檢查 Docker 環境**
```bash
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. 建置映像

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

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

### 4. 啟動服務

**使用 Docker Compose (推薦)**
```bash
# 啟動所有服務
docker-compose up -d

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

**手動 Docker 部署**
```bash
# 啟動 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. 服務驗證

**健康檢查**
```bash
# 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"
}
```

**功能測試**
```bash
# 測試 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 檢查**
```bash
# 檢查 Worker 狀態
docker-compose exec app celery -A app.celery inspect active

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

## 監控和維護

### 日誌管理
```bash
# 查看實時日誌
docker-compose logs -f

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

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

### 性能監控
```bash
# 檢查容器資源使用
docker stats

# 檢查服務狀態
docker-compose ps

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

### 備份和恢復
```bash
# 備份上傳檔案
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/
```

## 更新和升級

### 更新應用
```bash
# 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
```

### 滾動更新（零停機時間）
```bash
# 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. 容器無法啟動**
```bash
# 檢查端口占用
sudo netstat -tulpn | grep 12010

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

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

**2. 資料庫連接失敗**
```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}')
"
```

**3. Celery Worker 無法啟動**
```bash
# 檢查 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
```

### 緊急恢復
```bash
# 完全重置並重啟
docker-compose down -v
docker-compose up -d

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

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

## 安全配置

### 防火牆設定
```bash
# 開放必要端口
sudo ufw allow 12010/tcp

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

### SSL/TLS 配置
如需 HTTPS，建議在前端配置 Nginx 反向代理：

```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*