412 lines
9.0 KiB
Markdown
412 lines
9.0 KiB
Markdown
# PANJIT Document Translator V2
|
||
|
||
## 🎯 系統概述
|
||
|
||
企業級文檔翻譯系統，支援多種文檔格式的智能翻譯，包含 OCR 圖像識別和對話上下文連貫性功能。
|
||
|
||
### 核心功能
|
||
- ✅ **多格式支援**：DOCX、DOC、PDF、PPTX、XLSX、XLS 文檔翻譯
|
||
- ✅ **智能 OCR**：掃描 PDF 自動識別，含圖像預處理增強
|
||
- ✅ **對話持續性**：維持翻譯上下文，確保長文檔術語一致性
|
||
- ✅ **多語言輸出**：單語言翻譯檔 + 多語言組合檔
|
||
- ✅ **混合認證**：API 認證為主，LDAP 備援
|
||
- ✅ **異步處理**：Celery + Redis 批量任務隊列
|
||
- ✅ **快取機制**：OCR 快取 + 翻譯快取，避免重複處理
|
||
|
||
### 支援的翻譯語言
|
||
中文(繁體)、中文(簡體)、英文、日文、韓文、法文、德文、西班牙文、俄文、阿拉伯文、葡萄牙文、義大利文、泰文、越南文
|
||
|
||
---
|
||
|
||
## 📋 系統需求
|
||
|
||
### 必要軟體
|
||
| 軟體 | 版本要求 | 下載位置 |
|
||
|------|---------|---------|
|
||
| **Python** | ≥ 3.8 | https://www.python.org/downloads/ |
|
||
| **Node.js** | ≥ 16.0 | https://nodejs.org/ |
|
||
| **Redis** | ≥ 5.0 | https://github.com/tporadowski/redis/releases |
|
||
|
||
### 硬體需求
|
||
- **CPU**: 4 核心以上 (推薦)
|
||
- **記憶體**: ≥ 8GB (推薦 16GB)
|
||
- **硬碟空間**: ≥ 20GB
|
||
|
||
### 網路需求
|
||
- 可連線至外部 MySQL 資料庫 (mysql.theaken.com:33306)
|
||
- 可連線至 Dify API (外部翻譯服務)
|
||
- 可連線至 LDAP 伺服器 (panjit.com.tw:389)
|
||
|
||
---
|
||
|
||
## 🚀 快速部署
|
||
|
||
### 一鍵自動部署（推薦）
|
||
|
||
```batch
|
||
# 執行完整部署腳本
|
||
deploy_venv.bat
|
||
```
|
||
|
||
此腳本會自動完成:
|
||
1. 建立 Python 虛擬環境
|
||
2. 安裝 Python 後端依賴
|
||
3. 安裝前端依賴並建置
|
||
4. 建立必要目錄
|
||
5. 複製前端建置產物
|
||
|
||
### 手動部署步驟
|
||
|
||
```batch
|
||
# 1. 建立虛擬環境
|
||
setup_venv.bat
|
||
|
||
# 2. 安裝 Python 依賴
|
||
install_python_dependencies.bat
|
||
|
||
# 3. 安裝前端依賴並建置
|
||
install_frontend_dependencies.bat
|
||
|
||
# 4. 建立必要目錄
|
||
mkdir uploads cache logs app\static
|
||
|
||
# 5. 複製前端建置產物
|
||
xcopy /E /I /Y frontend\dist app\static
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 環境配置
|
||
|
||
### 1. 環境變數配置 (.env)
|
||
|
||
主要配置項（已預設）：
|
||
|
||
```bash
|
||
# 服務端口
|
||
SERVICE_PORT=12010
|
||
|
||
# 資料庫配置
|
||
DATABASE_URL=mysql+pymysql://A060:WLeSCi0yhtc7@mysql.theaken.com:33306/db_A060
|
||
|
||
# Redis 配置
|
||
REDIS_URL=redis://localhost:6379/0
|
||
|
||
# LDAP 配置
|
||
LDAP_SERVER=panjit.com.tw
|
||
LDAP_PORT=389
|
||
|
||
# SMTP 郵件配置
|
||
SMTP_SERVER=mail.panjit.com.tw
|
||
SMTP_PORT=25
|
||
```
|
||
|
||
💡 **提示**:
|
||
- 專案已包含完整的環境配置，可直接使用
|
||
- 如需修改：`SECRET_KEY` 和 `JWT_SECRET_KEY` 可自訂金鑰
|
||
- API 配置已內建於 `api.txt`，無需額外設定
|
||
|
||
---
|
||
|
||
## 🎬 啟動與停止
|
||
|
||
### 啟動所有服務
|
||
|
||
```batch
|
||
# 一鍵啟動（推薦）
|
||
start_all.bat
|
||
```
|
||
|
||
會自動啟動 4 個服務，每個在獨立終端視窗：
|
||
1. Redis Server (端口 6379)
|
||
2. Flask Backend (端口 12010)
|
||
3. Celery Worker (任務處理器)
|
||
4. Celery Beat (定時任務)
|
||
|
||
啟動後自動開啟瀏覽器: http://localhost:12010
|
||
|
||
### 分別啟動服務
|
||
|
||
```batch
|
||
# 視窗 1: Redis
|
||
start_redis.bat
|
||
|
||
# 視窗 2: 後端
|
||
start_backend.bat
|
||
|
||
# 視窗 3: Worker
|
||
start_celery_worker.bat
|
||
|
||
# 視窗 4: Beat
|
||
start_celery_beat.bat
|
||
```
|
||
|
||
### 停止所有服務
|
||
|
||
```batch
|
||
stop_all.bat
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 系統架構
|
||
|
||
### 服務組成
|
||
|
||
```
|
||
用戶瀏覽器 (http://localhost:12010)
|
||
↓
|
||
Flask Backend (端口 12010)
|
||
├── API 路由處理
|
||
├── 靜態檔案服務
|
||
├── JWT 認證
|
||
└── 檔案上傳管理
|
||
↓
|
||
Redis (端口 6379)
|
||
├── 訊息佇列
|
||
├── 任務快取
|
||
└── 翻譯快取
|
||
↓
|
||
Celery Worker ← 處理翻譯任務
|
||
↓
|
||
MySQL Database (遠端: mysql.theaken.com:33306)
|
||
```
|
||
|
||
### 端口佔用
|
||
|
||
| 服務 | 端口 | 說明 |
|
||
|------|------|------|
|
||
| **Flask Backend** | 12010 | 主要 API 服務與前端 |
|
||
| **Redis** | 6379 | 訊息佇列與快取 |
|
||
| **MySQL** (遠端) | 33306 | 資料庫 |
|
||
| **LDAP** (遠端) | 389 | 認證服務 |
|
||
|
||
---
|
||
|
||
## 📦 技術棧
|
||
|
||
### 後端核心套件
|
||
|
||
```
|
||
Flask==3.0.0 # Web 框架
|
||
Celery==5.3.4 # 異步任務佇列
|
||
redis==5.0.1 # Redis 客戶端
|
||
SQLAlchemy==2.0.23 # ORM
|
||
PyMySQL==1.1.0 # MySQL 驅動
|
||
PyMuPDF>=1.23.0 # PDF 處理
|
||
opencv-python-headless==4.8.1.78 # 圖像處理
|
||
python-docx==1.1.0 # Word 文檔
|
||
python-pptx==0.6.23 # PowerPoint
|
||
openpyxl==3.1.2 # Excel
|
||
ldap3==2.9.1 # LDAP 認證
|
||
```
|
||
|
||
完整清單請參考 `requirements.txt`
|
||
|
||
### 前端核心套件
|
||
|
||
```json
|
||
{
|
||
"vue": "^3.3.4", // Vue.js 3
|
||
"element-plus": "^2.3.8", // UI 組件庫
|
||
"axios": "^1.4.0", // HTTP 客戶端
|
||
"pinia": "^2.1.6", // 狀態管理
|
||
"echarts": "^5.4.3", // 圖表庫
|
||
"vite": "^4.4.0" // 建置工具
|
||
}
|
||
```
|
||
|
||
完整清單請參考 `frontend/package.json`
|
||
|
||
---
|
||
|
||
## 📂 輸出格式說明
|
||
|
||
### 單語言翻譯檔案
|
||
|
||
| 輸入格式 | 輸出格式 | 檔名範例 |
|
||
|---------|---------|---------|
|
||
| `.docx` | `.docx` | `translated_報告_en_20241002.docx` |
|
||
| `.pdf` | `.docx` | `translated_文件_ja_20241002.docx` |
|
||
| `.xlsx` | `.xlsx` | `translated_表格_zh-CN_20241002.xlsx` |
|
||
| `.pptx` | `.pptx` | `translated_簡報_ko_20241002.pptx` |
|
||
|
||
### 組合多語言檔案
|
||
|
||
當選擇多個目標語言時，自動產生組合檔案：
|
||
|
||
**檔名格式**: `combined_{檔名}_multilang_{timestamp}.{副檔名}`
|
||
|
||
**內容結構**:
|
||
```
|
||
原文段落1
|
||
[英文翻譯]
|
||
[日文翻譯]
|
||
|
||
原文段落2
|
||
[英文翻譯]
|
||
[日文翻譯]
|
||
```
|
||
|
||
---
|
||
|
||
## 🗂️ 目錄結構
|
||
|
||
```
|
||
Document_translator_V2_nodocker/
|
||
│
|
||
├── app/ # 後端應用程式
|
||
│ ├── models/ # 資料模型
|
||
│ ├── api/ # API 路由
|
||
│ ├── services/ # 業務邏輯
|
||
│ ├── tasks/ # Celery 任務
|
||
│ ├── utils/ # 工具函數
|
||
│ └── static/ # 前端建置產物
|
||
│
|
||
├── frontend/ # 前端源碼
|
||
│ ├── src/ # 源碼
|
||
│ ├── dist/ # 建置產物
|
||
│ └── package.json # 依賴清單
|
||
│
|
||
├── venv/ # Python 虛擬環境
|
||
├── uploads/ # 檔案上傳目錄
|
||
├── cache/ # 快取目錄
|
||
├── logs/ # 日誌目錄
|
||
│
|
||
├── .env # 環境變數
|
||
├── api.txt # Dify API 配置
|
||
├── requirements.txt # Python 依賴
|
||
├── database_schema.sql # 資料庫建置腳本
|
||
│
|
||
├── deploy_venv.bat # 一鍵部署
|
||
├── setup_venv.bat # 建立虛擬環境
|
||
├── install_python_dependencies.bat
|
||
├── install_frontend_dependencies.bat
|
||
│
|
||
├── start_all.bat # 啟動所有服務
|
||
├── start_redis.bat
|
||
├── start_backend.bat
|
||
├── start_celery_worker.bat
|
||
├── start_celery_beat.bat
|
||
├── stop_all.bat # 停止所有服務
|
||
│
|
||
├── README.md # 本文件
|
||
└── README_VENV_DEPLOYMENT.md # 詳細部署手冊
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ 部署驗證
|
||
|
||
### 檢查服務狀態
|
||
|
||
```batch
|
||
# Redis
|
||
redis-cli ping
|
||
# 預期: PONG
|
||
|
||
# 後端 API
|
||
curl http://localhost:12010/api/health
|
||
# 預期: {"status":"healthy"}
|
||
|
||
# 前端
|
||
# 開啟瀏覽器: http://localhost:12010
|
||
```
|
||
|
||
### 功能測試
|
||
|
||
1. 登入系統 (使用 LDAP 帳號)
|
||
2. 上傳測試文檔
|
||
3. 選擇目標語言
|
||
4. 提交翻譯任務
|
||
5. 檢查任務狀態
|
||
6. 下載翻譯結果
|
||
|
||
---
|
||
|
||
## 🐛 故障排除
|
||
|
||
### Redis 啟動失敗
|
||
|
||
```batch
|
||
# 安裝 Redis (Chocolatey)
|
||
choco install redis-64
|
||
|
||
# 或手動下載
|
||
# https://github.com/tporadowski/redis/releases
|
||
```
|
||
|
||
### 端口被佔用
|
||
|
||
```batch
|
||
# 查找佔用進程
|
||
netstat -ano | findstr :12010
|
||
|
||
# 終止進程
|
||
taskkill /F /PID <PID>
|
||
|
||
# 或停止所有服務
|
||
stop_all.bat
|
||
```
|
||
|
||
### 資料庫連線失敗
|
||
|
||
檢查 `.env` 中資料庫配置，確認網路可連線至 `mysql.theaken.com:33306`
|
||
|
||
### 翻譯任務失敗
|
||
|
||
1. 檢查 `api.txt` 中 Dify API 配置
|
||
2. 查看 Celery Worker 終端的錯誤訊息
|
||
3. 確認網路可連線至 Dify API
|
||
|
||
---
|
||
|
||
## 🔐 安全建議
|
||
|
||
### 生產環境檢查清單
|
||
|
||
- [ ] 修改 `SECRET_KEY` 和 `JWT_SECRET_KEY`
|
||
- [ ] 確認資料庫密碼安全性
|
||
- [ ] 配置防火牆，僅開放必要端口
|
||
- [ ] 定期更新套件依賴
|
||
- [ ] 配置日誌輪替
|
||
- [ ] 定期備份資料庫和檔案
|
||
- [ ] 設定檔案自動清理
|
||
|
||
---
|
||
|
||
## 📞 技術資訊
|
||
|
||
### 系統資訊
|
||
- **版本**: Document Translator V2
|
||
- **服務端口**: 12010
|
||
- **Python**: ≥ 3.8
|
||
- **Node.js**: ≥ 16
|
||
- **核心框架**: Flask 3.0, Vue.js 3, Celery 5.3
|
||
|
||
### 聯絡資訊
|
||
- **管理員**: ymirliu@panjit.com.tw
|
||
- **詳細文件**: README_VENV_DEPLOYMENT.md
|
||
|
||
---
|
||
|
||
## 📝 快速指令
|
||
|
||
```batch
|
||
# 部署
|
||
deploy_venv.bat
|
||
|
||
# 啟動
|
||
start_all.bat
|
||
|
||
# 停止
|
||
stop_all.bat
|
||
|
||
# 訪問
|
||
http://localhost:12010
|
||
```
|
||
|
||
---
|
||
|
||
**🎉 完成部署後，系統即可正式使用！**
|