373 lines
7.9 KiB
Markdown
373 lines
7.9 KiB
Markdown
# 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* |