PANJIT Document Translator V2 - 正式生產環境部署指南
🎯 系統概述
PANJIT Document Translator V2 是一個企業級文檔翻譯系統，支援多種文檔格式的智能翻譯，包含 OCR 圖像識別和對話上下文連貫性功能。
核心功能
- ✅ 多格式支援：DOCX、DOC、PDF、PPTX、XLSX、XLS 文檔翻譯
- ✅ 智能 OCR：掃描 PDF 自動識別，含圖像預處理增強
- ✅ 對話持續性：維持翻譯上下文，確保長文檔術語一致性
- ✅ 多語言輸出：單語言翻譯檔 + 多語言組合檔
- ✅ 混合認證：API 認證為主，LDAP 備援
- ✅ 異步處理：Celery + Redis 批量任務隊列
- ✅ 快取機制：OCR 快取 + 翻譯快取，避免重複處理
支援的翻譯語言
中文(繁體)、中文(簡體)、英文、日文、韓文、法文、德文、西班牙文、俄文、阿拉伯文、葡萄牙文、義大利文、泰文、越南文
🚀 快速部署
1. 系統需求
- 操作系統：Linux/Windows Server
- Docker：≥ 20.10
- Docker Compose：≥ 2.0
- 記憶體：≥ 8GB (推薦 16GB)
- 存儲空間：≥ 50GB
- 網路：可訪問外部 Dify API
2. 部署步驟
Windows 系統
# 1. 進入專案目錄
cd Document_translator_V2
# 2. 配置環境變數 (已包含正式配置)
# 確認 .env.production 檔案存在
# 3. 執行部署腳本
deploy-production.bat
Linux 系統
# 1. 進入專案目錄
cd Document_translator_V2
# 2. 確認環境配置
cat .env.production
# 3. 執行部署腳本
chmod +x deploy-production.sh
./deploy-production.sh
3. 服務驗證
部署完成後，系統將在 http://localhost:12010 提供服務。
# 檢查所有容器狀態
docker-compose -f docker-compose.prod.yml ps
# 檢查 API 健康狀態
curl http://localhost:12010/api/health
# 預期輸出
{
"status": "healthy",
"database": "connected",
"redis": "connected"
}
📂 文件輸出格式
系統會為每個翻譯任務產生以下檔案：
單語言翻譯檔案
- DOCX/DOC →
translated_{檔名}_{語言}_*.docx - XLSX/XLS →
translated_{檔名}_{語言}_*.xlsx - PPTX →
translated_{檔名}_{語言}_*.pptx - PDF →
translated_{檔名}_{語言}_*.docx(輸出為 Word 格式)
組合多語言檔案 (多語言時自動產生)
- 檔名格式：
combined_{檔名}_multilang_*.{副檔名} - 內容結構：
原文段落1 [譯文1 - 語言A] [譯文2 - 語言B] 原文段落2 [譯文1 - 語言A] [譯文2 - 語言B]
支援格式總覽
| 輸入格式 | 輸出格式 | OCR 支援 | 組合檔案 |
|---|---|---|---|
.docx |
.docx |
- | ✅ |
.doc |
.docx |
- | ✅ |
.xlsx |
.xlsx |
- | ✅ |
.xls |
.xlsx |
- | ✅ |
.pptx |
.pptx |
- | ✅ |
.pdf |
.docx |
✅ | ✅ |
🔧 生產環境配置
資料庫配置 (MySQL)
MYSQL_HOST=mysql.theaken.com
MYSQL_PORT=33306
MYSQL_USER=A060
MYSQL_PASSWORD=WLeSCi0yhtc7
MYSQL_DATABASE=db_A060
MYSQL_CHARSET=utf8mb4
Redis 配置
REDIS_URL=redis://redis:6379/0
CELERY_BROKER_URL=redis://redis:6379/0
LDAP 配置
LDAP_SERVER=panjit.com.tw
LDAP_PORT=389
SMTP 郵件配置
SMTP_SERVER=mail.panjit.com.tw
SMTP_PORT=25
SMTP_USE_TLS=false
SMTP_AUTH_REQUIRED=false
SMTP_SENDER_EMAIL=translator-system@panjit.com.tw
重要安全設定
⚠️ 首次部署必須修改以下項目：
# 1. 更改預設密鑰 (在 .env 中)
SECRET_KEY=your-production-secret-key-change-this
JWT_SECRET_KEY=your-production-jwt-secret-change-this
# 2. 確認檔案大小限制 (預設 100MB)
MAX_CONTENT_LENGTH=104857600
# 3. 配置檔案保留天數 (預設 30 天)
FILE_RETENTION_DAYS=30
🏗️ 系統架構
Docker 容器組成
- translator-app-prod: Flask 應用主服務 (Gunicorn)
- panjit-translator-worker-prod: Celery Worker (翻譯任務處理)
- panjit-translator-beat-prod: Celery Beat (定時任務)
- panjit-translator-nginx-prod: Nginx 反向代理
- panjit-translator-redis-prod: Redis 快取/訊息佇列
認證架構說明
混合認證策略：
- 主要認證：API 認證 (https://pj-auth-api.vercel.app/)
- 備援認證：LDAP 認證 (panjit.com.tw)
s
資料表結構
系統包含以下核心資料表：
sys_user: 系統使用者 (API/LDAP 混合認證)login_logs: 登入日誌dt_users: 文檔翻譯使用者dt_translation_jobs: 翻譯任務dt_job_files: 任務檔案dt_translation_cache: 翻譯快取dt_ocr_cache: OCR 快取dt_system_logs: 系統日誌dt_notifications: 通知記錄
📊 監控與維護
容器健康檢查
# 查看所有容器狀態
docker-compose -f docker-compose.prod.yml ps
# 檢查健康狀態
docker inspect --format='{{.State.Health.Status}}' translator-app-prod
# 預期輸出：healthy
日誌監控
# 實時查看應用日誌
docker logs -f translator-app-prod
# 查看 Celery Worker 日誌
docker logs -f panjit-translator-worker-prod
# 查看 Nginx 訪問日誌
docker logs -f panjit-translator-nginx-prod
效能監控指標
- 記憶體使用：App < 2GB，Worker < 3GB
- CPU 使用率：正常負載 < 50%
- 翻譯速度：平均 2-5 秒/頁 (依文檔複雜度)
- OCR 處理：首次 5-10 秒/頁，快取命中 < 0.1 秒
🔄 維護操作
日常維護
# 重啟所有服務
docker-compose -f docker-compose.prod.yml restart
# 僅重啟應用容器 (不影響其他服務)
docker-compose -f docker-compose.prod.yml restart app
# 更新應用 (重新部署)
docker-compose -f docker-compose.prod.yml up -d --build app
# 查看資源使用
docker stats
資料庫維護
# 資料表已在部署時自動建立
# 若需重建資料表，請先備份資料
# 進入容器執行 SQL
docker exec -it translator-app-prod bash
python -c "from app import db; db.create_all()"
檔案清理
# 清理 30 天前的上傳檔案
find ./uploads -type f -mtime +30 -delete
# 清理 Docker 未使用映像
docker system prune -af
備份與恢復
# 1. 備份上傳檔案
tar -czf uploads-backup-$(date +%Y%m%d).tar.gz uploads/
# 2. 備份資料庫 (需 MySQL 存取權限)
docker exec translator-app-prod mysqldump \
-h mysql.theaken.com -u A060 -pWLeSCi0yhtc7 db_A060 \
> backup-$(date +%Y%m%d).sql
# 3. 恢復資料庫
docker exec -i translator-app-prod mysql \
-h mysql.theaken.com -u A060 -pWLeSCi0yhtc7 db_A060 \
< backup-20251002.sql
🛡️ 安全考量
網路安全
- ✅ 容器間隔離網路 (panjit-translator-network)
- ✅ 僅 Nginx 暴露公開端口 (12010)
- ✅ API 認證 + JWT Token 驗證
- ✅ HTTPS 建議配置 (生產環境需額外設定 SSL)
數據安全
- ✅ 敏感資訊使用環境變數管理
- ✅ 資料庫連接加密 (charset=utf8mb4)
- ✅ API 金鑰存儲於配置檔案
- ✅ 檔案定期自動清理機制
生產環境檢查清單
- 修改所有預設密鑰 (SECRET_KEY, JWT_SECRET_KEY)
- 確認資料庫連接正常
- 確認 Redis 連接正常
- 測試 LDAP 認證功能
- 測試檔案上傳翻譯功能
- 確認 Nginx 反向代理正常
- 設定檔案清理排程 (cron)
- 建立監控和告警機制
- 準備備份恢復流程
- 記錄系統存取帳號密碼
🐛 故障排除
常見問題
1. 容器啟動失敗
# 檢查容器日誌
docker-compose -f docker-compose.prod.yml logs app
# 檢查端口佔用
netstat -tulpn | grep 12010
# 檢查資源使用
docker system df
2. 翻譯服務無響應
# 重啟 Celery Worker
docker-compose -f docker-compose.prod.yml restart celery-worker
# 檢查 Redis 連接
docker exec panjit-translator-redis-prod redis-cli ping
# 預期輸出：PONG
# 檢查任務佇列
docker exec panjit-translator-redis-prod redis-cli llen celery
3. 前端無法訪問
# 檢查 Nginx 狀態
docker-compose -f docker-compose.prod.yml logs nginx
# 測試後端 API
curl http://localhost:12010/api/health
# 檢查靜態檔案
docker exec translator-app-prod ls -la /app/static/
4. 資料庫連接失敗
# 測試資料庫連接
docker exec translator-app-prod python -c "
from app import db
try:
db.session.execute('SELECT 1')
print('Database connected!')
except Exception as e:
print(f'Error: {e}')
"
# 檢查環境變數
docker exec translator-app-prod env | grep MYSQL
5. OCR 或翻譯失敗
# 檢查 Dify API 配置
docker exec translator-app-prod cat /app/app/config.py | grep DIFY
# 查看 Worker 錯誤日誌
docker logs panjit-translator-worker-prod | grep ERROR
# 清空快取重試
docker exec panjit-translator-redis-prod redis-cli FLUSHALL
6. 記憶體不足
# 清理 Docker 系統
docker system prune -af
# 重啟服務
docker-compose -f docker-compose.prod.yml restart
# 增加 Worker 數量 (若資源充足)
docker-compose -f docker-compose.prod.yml up -d --scale celery-worker=2
📞 技術支援
系統資訊
- 系統版本：Document Translator V2 (Production)
- 服務端口：12010
- Python 版本：3.11
- Node 版本：18
- 核心框架：Flask 3.0, Vue.js 3, Celery 5.3
核心依賴套件版本
Flask==3.0.0
Celery==5.3.4
Redis==5.0.1
SQLAlchemy==2.0.23
PyMySQL==1.1.0
PyMuPDF>=1.23.0
opencv-python-headless==4.8.1.78
numpy>=1.24.0,<2.0.0
📋 部署檢查清單
首次部署前
- 確認 Docker 和 Docker Compose 已安裝
- 確認網路可訪問 MySQL 和 Dify API
- 確認埠號 12010 未被佔用
- 準備好資料庫連接資訊
- 準備好 LDAP 連接資訊
部署過程中
- 執行
deploy-production.bat或.sh - 確認所有容器成功啟動 (5 個容器)
- 確認健康檢查全部通過
- 測試訪問 http://localhost:12010
部署完成後
- 使用測試帳號登入驗證
- 上傳測試檔案進行翻譯
- 檢查翻譯輸出檔案格式
- 確認 OCR 功能正常
- 驗證多語言組合檔案產生
- 設定定期備份機制
- 記錄所有設定和密碼
🎉 部署完成後，系統即可正式上線使用！
如有任何問題，請參考故障排除章節或聯繫技術支援團隊。