248 lines
5.4 KiB
Markdown
248 lines
5.4 KiB
Markdown
# 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
|
||
|