改用API驗證

2025-10-02 17:13:24 +08:00
parent 0a89c19fc9
commit adecdf0cce
48 changed files with 6136 additions and 1239 deletions
--- a/README.md
+++ b/README.md
@@ -1,340 +1,455 @@
-# PANJIT 文件翻譯系統
+# PANJIT Document Translator V2 - 正式生產環境部署指南

-## 專案簡介
+## 🎯 系統概述

-PANJIT 文件翻譯系統是一個企業級的多語言文件翻譯平台，支持多種文件格式的自動翻譯。系統採用 Flask + Vue.js 架構，整合 LDAP 認證、Celery 異步處理、通知系統等企業功能。
+PANJIT Document Translator V2 是一個企業級文檔翻譯系統，支援多種文檔格式的智能翻譯，包含 OCR 圖像識別和對話上下文連貫性功能。

-### 主要功能
+### 核心功能
+- ✅ **多格式支援**：DOCX、DOC、PDF、PPTX、XLSX、XLS 文檔翻譯
+- ✅ **智能 OCR**：掃描 PDF 自動識別，含圖像預處理增強
+- ✅ **對話持續性**：維持翻譯上下文，確保長文檔術語一致性
+- ✅ **多語言輸出**：單語言翻譯檔 + 多語言組合檔
+- ✅ **混合認證**：API 認證為主，LDAP 備援
+- ✅ **異步處理**：Celery + Redis 批量任務隊列
+- ✅ **快取機制**：OCR 快取 + 翻譯快取，避免重複處理

- **多格式翻譯**：支援 Word (.docx)、PowerPoint (.pptx)、Excel (.xlsx)、PDF 文件翻譯
- **多語言支援**：支援繁體中文、簡體中文、英語、日語、韓語、越南語等
- **LDAP 認證**：整合企業 Active Directory 用戶系統
- **異步處理**：使用 Celery + Redis 處理翻譯任務
- **即時通知**：WebSocket 即時狀態更新 + 郵件通知
- **檔案管理**：支援單檔下載、批量下載、合併檔案下載
- **管理後台**：系統統計、用戶管理等功能
+### 支援的翻譯語言
+中文(繁體)、中文(簡體)、英文、日文、韓文、法文、德文、西班牙文、俄文、阿拉伯文、葡萄牙文、義大利文、泰文、越南文

-## 技術架構
+---

-**後端**
- Python 3.8+
- Flask 3.0 + SQLAlchemy 2.0
- MySQL 資料庫
- Celery 4.5 + Redis
- LDAP3 認證
- Socket.IO 即時通信
+## 🚀 快速部署

-**前端**
- Vue.js 3.0 + Composition API
- Element Plus UI 框架
- Pinia 狀態管理
- Vite 建置工具
+### 1. 系統需求
+- **操作系統**：Linux/Windows Server
+- **Docker**：≥ 20.10
+- **Docker Compose**：≥ 2.0
+- **記憶體**：≥ 8GB (推薦 16GB)
+- **存儲空間**：≥ 50GB
+- **網路**：可訪問外部 Dify API

-## 系統需求
-
- Python 3.8+
- Node.js 16+
- Redis Server
- MySQL 資料庫（已配置）
- Windows 10+ 或 Linux 系統
-
-## 快速啟動
-
-### 生產部署（推薦）
-
-**使用 Docker Compose 一鍵部署：**
+### 2. 部署步驟

+#### Windows 系統
 ```bash
 # 1. 進入專案目錄
 cd Document_translator_V2

-# 2. 建置並啟動所有服務（強制重建以確保使用最新代碼）
-docker-compose up -d --build
+# 2. 配置環境變數 (已包含正式配置)
+# 確認 .env.production 檔案存在

-# 3. 檢查服務狀態
-docker-compose ps
-
-# 4. 訪問系統
-curl http://localhost:12010/api/v1/health
-
-# 5. 停止服務
-docker-compose down
-
-# 6. 查看日誌
-docker-compose logs -f
+# 3. 執行部署腳本
+deploy-production.bat
 ```

-詳細部署說明請參考 [DEPLOYMENT.md](DEPLOYMENT.md)
+#### Linux 系統
+```bash
+# 1. 進入專案目錄
+cd Document_translator_V2

-### 開發環境
+# 2. 確認環境配置
+cat .env.production

-1. **克隆專案**
-   ```bash
-   cd Document_translator_V2
-   ```
-
-2. **手動啟動後端**
-   ```bash
-   # 建立虛擬環境
-   python -m venv venv
-   venv\Scripts\activate
-   
-   # 安裝依賴
-   pip install -r requirements.txt
-   
-   # 啟動應用
-   python app.py
-   ```
-
-3. **手動啟動前端**（另開命令視窗）
-   ```bash
-   cd frontend
-   npm install
-   npm run dev
-   ```
-
-4. **手動啟動 Celery Worker**（另開命令視窗）
-   ```bash
-   venv\Scripts\activate
-   celery -A celery_app worker --loglevel=info --pool=solo
-   ```
-
-### 系統訪問
-
- **前端界面**: http://127.0.0.1:5173 (開發模式)
- **後端 API**: http://127.0.0.1:12010 (生產模式)
- **API 文檔**: http://127.0.0.1:12010/api
- **健康檢查**: http://127.0.0.1:12010/api/v1/health
-
-## 專案結構
-
-```
-Document_translator_V2/
-├── app/                    # 後端應用
-│   ├── api/               # API 路由
-│   ├── models/            # 資料模型
-│   ├── services/          # 業務邏輯
-│   ├── tasks/             # Celery 任務
-│   └── utils/             # 工具函數
-├── frontend/              # 前端應用
-│   ├── src/
-│   │   ├── components/    # Vue 組件
-│   │   ├── views/         # 頁面視圖
-│   │   ├── stores/        # Pinia 狀態
-│   │   └── utils/         # 工具函數
-│   └── package.json
-├── uploads/               # 檔案上傳目錄
-├── logs/                  # 日誌目錄
-├── app.py                # 主應用入口
-├── celery_app.py         # Celery 配置
-├── requirements.txt      # Python 依賴
-└── .env                  # 環境變數
+# 3. 執行部署腳本
+chmod +x deploy-production.sh
+./deploy-production.sh
 ```

-## 配置說明
+### 3. 服務驗證

-### 環境變數 (.env)
+部署完成後，系統將在 **http://localhost:12010** 提供服務。

-系統需要以下環境變數配置：
+```bash
+# 檢查所有容器狀態
+docker-compose -f docker-compose.prod.yml ps

-```env
-# 資料庫配置
-DATABASE_URL=mysql+pymysql://user:pass@host:port/db_name
+# 檢查 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)
+```bash
 MYSQL_HOST=mysql.theaken.com
 MYSQL_PORT=33306
 MYSQL_USER=A060
+MYSQL_PASSWORD=WLeSCi0yhtc7
 MYSQL_DATABASE=db_A060
+MYSQL_CHARSET=utf8mb4
+```

-# LDAP 配置
+### Redis 配置
+```bash
+REDIS_URL=redis://redis:6379/0
+CELERY_BROKER_URL=redis://redis:6379/0
+```
+
+### LDAP 配置
+```bash
 LDAP_SERVER=panjit.com.tw
 LDAP_PORT=389
-LDAP_BIND_USER_DN=CN=LdapBind,CN=Users,DC=PANJIT,DC=COM,DC=TW
+```

-# SMTP 配置
+### SMTP 郵件配置
+```bash
 SMTP_SERVER=mail.panjit.com.tw
 SMTP_PORT=25
-SMTP_SENDER_EMAIL=todo-system@panjit.com.tw
-
-# Redis 配置
-REDIS_URL=redis://localhost:6379/0
+SMTP_USE_TLS=false
+SMTP_AUTH_REQUIRED=false
+SMTP_SENDER_EMAIL=translator-system@panjit.com.tw
 ```

-### API 配置 (api.txt)
+### 重要安全設定

-系統使用 Dify API 進行翻譯，需要配置：
-
-```
-base_url:YOUR_DIFY_API_BASE_URL
-api:YOUR_DIFY_API_KEY
-```
-
-## 部署指南
-
-### Docker 部署
-
-1. **建置映像**
-   ```bash
-   docker build -t panjit-translator .
-   ```
-
-2. **啟動服務**
-   ```bash
-   docker-compose up -d
-   ```
-
-3. **檢查狀態**
-   ```bash
-   docker-compose ps
-   docker logs panjit-translator
-   ```
-
-### 生產環境
-
-1. **使用 Gunicorn 啟動**
-   ```bash
-   pip install gunicorn
-   gunicorn -w 4 -b 0.0.0.0:12010 app:app
-   ```
-
-2. **前端建置**
-   ```bash
-   cd frontend
-   npm run build
-   ```
-
-3. **配置 Web 服務器**
-   將 `frontend/dist` 部署到 Nginx 或 Apache
-
-## API 文檔
-
-### 認證相關
- `POST /api/v1/auth/login` - 用戶登入
- `POST /api/v1/auth/logout` - 用戶登出
- `GET /api/v1/auth/me` - 獲取當前用戶
-
-### 檔案上傳
- `POST /api/v1/files/upload` - 上傳檔案
-
-### 任務管理
- `GET /api/v1/jobs` - 獲取任務列表
- `GET /api/v1/jobs/{uuid}` - 獲取任務詳情
- `POST /api/v1/jobs/{uuid}/retry` - 重試任務
-
-### 檔案下載
- `GET /api/v1/files/{uuid}/download/{lang}` - 下載指定語言版本
- `GET /api/v1/files/{uuid}/download/batch` - 批量下載 (ZIP)
- `GET /api/v1/files/{uuid}/download/combine` - 下載合併檔案
-
-### 通知系統
- `GET /api/v1/notifications` - 獲取通知列表
- `POST /api/v1/notifications/{id}/read` - 標記已讀
-
-### 系統管理
- `GET /api/v1/admin/stats` - 系統統計
- `GET /api/v1/health` - 健康檢查
-
-## 故障排除
-
-### 常見問題
-
-1. **Redis 連接失敗**
-   - 確認 Redis 服務是否運行
-   - 檢查 REDIS_URL 設定
-
-2. **資料庫連接失敗**
-   - 確認 MySQL 連接參數
-   - 檢查網路連接
-
-3. **LDAP 認證失敗**
-   - 確認 LDAP 服務器設定
-   - 檢查服務帳號權限
-
-4. **檔案上傳失敗**
-   - 檢查 uploads 目錄權限
-   - 確認磁碟空間充足
-
-### 日誌查看
+⚠️ **首次部署必須修改以下項目**：

 ```bash
-# 應用日誌
-tail -f logs/app.log
+# 1. 更改預設密鑰 (在 .env 中)
+SECRET_KEY=your-production-secret-key-change-this
+JWT_SECRET_KEY=your-production-jwt-secret-change-this

-# Celery 日誌
-tail -f logs/celery.log
+# 2. 確認檔案大小限制 (預設 100MB)
+MAX_CONTENT_LENGTH=104857600

-# 查看錯誤日誌
-grep ERROR logs/app.log
+# 3. 配置檔案保留天數 (預設 30 天)
+FILE_RETENTION_DAYS=30
 ```

-## 維護指南
+---
+
+## 🏗️ 系統架構
+
+### Docker 容器組成
+1. **translator-app-prod**: Flask 應用主服務 (Gunicorn)
+2. **panjit-translator-worker-prod**: Celery Worker (翻譯任務處理)
+3. **panjit-translator-beat-prod**: Celery Beat (定時任務)
+4. **panjit-translator-nginx-prod**: Nginx 反向代理
+5. **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`: 通知記錄
+
+---
+
+## 📊 監控與維護
+
+### 容器健康檢查
+
+```bash
+# 查看所有容器狀態
+docker-compose -f docker-compose.prod.yml ps
+
+# 檢查健康狀態
+docker inspect --format='{{.State.Health.Status}}' translator-app-prod
+
+# 預期輸出：healthy
+```
+
+### 日誌監控
+
+```bash
+# 實時查看應用日誌
+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 秒
+
+---
+
+## 🔄 維護操作
+
+### 日常維護
+
+```bash
+# 重啟所有服務
+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
+```

 ### 資料庫維護

 ```bash
-# 備份資料庫
-mysqldump -u A060 -p db_A060 > backup_$(date +%Y%m%d).sql
+# 資料表已在部署時自動建立
+# 若需重建資料表，請先備份資料

-# 清理舊檔案（90天前）
-find uploads/ -mtime +90 -delete
+# 進入容器執行 SQL
+docker exec -it translator-app-prod bash
+python -c "from app import db; db.create_all()"
 ```

-### 日誌清理
+### 檔案清理

 ```bash
-# 清理應用日誌（保留30天）
-find logs/ -name "*.log" -mtime +30 -delete
+# 清理 30 天前的上傳檔案
+find ./uploads -type f -mtime +30 -delete
+
+# 清理 Docker 未使用映像
+docker system prune -af
 ```

-## Docker 部署
-
-### 快速部署
+### 備份與恢復

 ```bash
-# 1. 建置 Docker 映像
-docker build -t panjit-translator .
+# 1. 備份上傳檔案
+tar -czf uploads-backup-$(date +%Y%m%d).tar.gz uploads/

-# 2. 運行容器
-docker run -d -p 12010:12010 --name panjit-translator panjit-translator
+# 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 ps
-docker logs panjit-translator
+# 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. 容器啟動失敗
 ```bash
-# 停止服務
-docker stop panjit-translator
+# 檢查容器日誌
+docker-compose -f docker-compose.prod.yml logs app

-# 啟動服務
-docker start panjit-translator
+# 檢查端口佔用
+netstat -tulpn | grep 12010
+
+# 檢查資源使用
+docker system df
+```
+
+#### 2. 翻譯服務無響應
+```bash
+# 重啟 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. 前端無法訪問
+```bash
+# 檢查 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. 資料庫連接失敗
+```bash
+# 測試資料庫連接
+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 或翻譯失敗
+```bash
+# 檢查 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. 記憶體不足
+```bash
+# 清理 Docker 系統
+docker system prune -af

 # 重啟服務
-docker restart panjit-translator
+docker-compose -f docker-compose.prod.yml restart
+
+# 增加 Worker 數量 (若資源充足)
+docker-compose -f docker-compose.prod.yml up -d --scale celery-worker=2
 ```

-### 部署方式
+---

-```bash
-# Docker 部署 (推薦)
-docker build -t panjit-translator .
-docker run -d -p 12010:12010 --name panjit-translator panjit-translator
+## 📞 技術支援
+
+### 系統資訊
+- **系統版本**：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
 ```

-## 支援與聯絡
+---

-**PANJIT IT Team**
- Email: it-support@panjit.com.tw
- 內線電話: 2481
- 辦公時間: 週一至週五 9:00-18:00
+## 📋 部署檢查清單

-## 版本資訊
+### 首次部署前
+- [ ] 確認 Docker 和 Docker Compose 已安裝
+- [ ] 確認網路可訪問 MySQL 和 Dify API
+- [ ] 確認埠號 12010 未被佔用
+- [ ] 準備好資料庫連接資訊
+- [ ] 準備好 LDAP 連接資訊

- **版本**: v2.0.0
- **發布日期**: 2025-09-04
- **維護人員**: PANJIT IT Team
+### 部署過程中
+- [ ] 執行 `deploy-production.bat` 或 `.sh`
+- [ ] 確認所有容器成功啟動 (5 個容器)
+- [ ] 確認健康檢查全部通過
+- [ ] 測試訪問 http://localhost:12010

-## 授權條款
+### 部署完成後
+- [ ] 使用測試帳號登入驗證
+- [ ] 上傳測試檔案進行翻譯
+- [ ] 檢查翻譯輸出檔案格式
+- [ ] 確認 OCR 功能正常
+- [ ] 驗證多語言組合檔案產生
+- [ ] 設定定期備份機制
+- [ ] 記錄所有設定和密碼

-此軟體為 PANJIT 集團內部使用系統，版權歸 PANJIT 所有，僅供公司內部使用。
+---
+
+**🎉 部署完成後，系統即可正式上線使用！**
+
+如有任何問題，請參考故障排除章節或聯繫技術支援團隊。