531 lines
12 KiB
Markdown
531 lines
12 KiB
Markdown
# PANJIT Document Translator V2 - 部署指南
|
||
|
||
## 🎯 系統概述
|
||
|
||
PANJIT Document Translator V2 是一個企業級文檔翻譯系統,支援多種文檔格式的智能翻譯,包含 OCR 圖像識別和對話上下文連貫性功能。
|
||
|
||
### 核心功能
|
||
- ✅ **多格式支援**:DOCX、DOC、PDF、PPTX、XLSX、XLS 文檔翻譯
|
||
- ✅ **智能 OCR**:掃描 PDF 自動識別,含圖像預處理增強
|
||
- ✅ **對話持續性**:維持翻譯上下文,確保長文檔術語一致性
|
||
- ✅ **多語言輸出**:單語言翻譯檔 + 多語言組合檔
|
||
- ✅ **混合認證**:API 認證為主,LDAP 備援
|
||
- ✅ **異步處理**:Celery + Redis 批量任務隊列
|
||
- ✅ **快取機制**:OCR 快取 + 翻譯快取,避免重複處理
|
||
|
||
### 支援的翻譯語言
|
||
中文(繁體)、中文(簡體)、英文、日文、韓文、法文、德文、西班牙文、俄文、阿拉伯文、葡萄牙文、義大利文、泰文、越南文
|
||
|
||
---
|
||
|
||
## 🚀 1Panel 環境快速部署
|
||
|
||
### 系統需求
|
||
- **操作系統**:Ubuntu 20.04+ (1Panel 虛擬環境)
|
||
- **Python**:3.10 或更高版本
|
||
- **記憶體**:≥ 4GB (推薦 8GB)
|
||
- **存儲空間**:≥ 20GB
|
||
- **Redis**:用於任務隊列(需額外安裝)
|
||
- **MySQL**:外部資料庫服務
|
||
- **網路**:可訪問外部 Dify API
|
||
|
||
### 🔌 使用端口清單
|
||
|
||
| 服務 | 預設端口 | 說明 | 可否修改 |
|
||
|------|---------|------|---------|
|
||
| **Flask Web 服務** | 12010 | 對外訪問端口,瀏覽器訪問入口 | ✅ 可修改(建議 12010-12019) |
|
||
| **Redis** | 6379 | 本地任務隊列和快取 | ⚠️ 不建議修改 |
|
||
| **MySQL** | 33306 | 外部資料庫(mysql.theaken.com) | ❌ 不可修改(外部服務) |
|
||
| **LDAP** | 389 | 認證服務(panjit.com.tw) | ❌ 不可修改(外部服務) |
|
||
| **SMTP** | 25 | 郵件服務(mail.panjit.com.tw) | ❌ 不可修改(外部服務) |
|
||
|
||
#### 如何修改 Web 服務端口
|
||
|
||
編輯 `.env` 檔案:
|
||
```bash
|
||
nano .env
|
||
|
||
# 修改以下行(例如改為 12015)
|
||
PORT=12015
|
||
```
|
||
|
||
然後在 1Panel 介面中同步修改端口映射為 `12015`
|
||
|
||
### 部署步驟
|
||
|
||
#### 1️⃣ 準備環境
|
||
|
||
在 1Panel 管理介面中:
|
||
1. 建立新的 **運行環境**
|
||
2. 選擇 **Python 3.10**
|
||
3. 記錄分配的工作目錄路徑
|
||
|
||
#### 2️⃣ 上傳專案檔案
|
||
|
||
將以下檔案上傳到 1Panel 分配的目錄:
|
||
|
||
```
|
||
Document_translator_1panel/
|
||
├── app/ # 應用程式主目錄
|
||
├── frontend/ # 前端檔案(已編譯)
|
||
├── migrations/ # 資料庫遷移腳本
|
||
├── app.py # Flask 應用入口
|
||
├── celery_app.py # Celery Worker 配置
|
||
├── start.py # ⭐ 統一啟動腳本
|
||
├── install.sh # ⭐ 一鍵安裝腳本
|
||
├── requirements.txt # Python 依賴清單
|
||
├── .env # ⭐ 環境變數(已配置)
|
||
├── api.txt # ⭐ Dify API 金鑰(已配置)
|
||
└── README.md # 本文檔
|
||
```
|
||
|
||
#### 3️⃣ 安裝依賴套件
|
||
|
||
```bash
|
||
# 賦予執行權限
|
||
chmod +x install.sh
|
||
|
||
# 執行一鍵安裝
|
||
./install.sh
|
||
```
|
||
|
||
安裝腳本會自動:
|
||
- ✅ 檢查 Python 版本
|
||
- ✅ 升級 pip
|
||
- ✅ 安裝所有依賴套件
|
||
- ✅ 建立必要目錄
|
||
- ✅ 驗證安裝結果
|
||
|
||
#### 4️⃣ 配置環境變數
|
||
|
||
```bash
|
||
# 編輯環境變數(已包含完整配置)
|
||
nano .env
|
||
```
|
||
|
||
**必須修改的關鍵項目:**
|
||
|
||
```bash
|
||
# 1. 安全金鑰(務必修改!)
|
||
SECRET_KEY=your-production-secret-key-change-this
|
||
JWT_SECRET_KEY=your-production-jwt-secret-change-this
|
||
|
||
# 2. 服務端口(可選修改,預設 12010)
|
||
PORT=12010
|
||
HOST=0.0.0.0
|
||
|
||
# ========================================
|
||
# 以下配置已預設好,通常不需修改
|
||
# ========================================
|
||
|
||
# 資料庫配置(已配置)
|
||
DATABASE_URL=mysql+pymysql://A060:WLeSCi0yhtc7@mysql.theaken.com:33306/db_A060
|
||
MYSQL_HOST=mysql.theaken.com
|
||
MYSQL_PORT=33306
|
||
|
||
# Redis 配置(已配置)
|
||
REDIS_HOST=localhost
|
||
REDIS_PORT=6379
|
||
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
|
||
```
|
||
|
||
#### 5️⃣ 驗證 Dify API 配置
|
||
|
||
```bash
|
||
# 確認 API 金鑰已正確配置
|
||
cat api.txt
|
||
|
||
# 應顯示:
|
||
# translation_api: app-SmB3TwVMcp5OyQviYeAoTden
|
||
# ocr_api: app-kC5qx2wgMMkn61O77jY4YuPs
|
||
```
|
||
|
||
⚠️ **API 金鑰已預先配置,無需修改**
|
||
|
||
#### 6️⃣ 安裝 Redis(重要)
|
||
|
||
Redis 用於 Celery 任務隊列,必須安裝:
|
||
|
||
```bash
|
||
# Ubuntu/Debian
|
||
sudo apt update
|
||
sudo apt install redis-server
|
||
|
||
# 啟動 Redis
|
||
sudo systemctl start redis
|
||
sudo systemctl enable redis
|
||
|
||
# 驗證 Redis
|
||
redis-cli ping
|
||
# 預期輸出:PONG
|
||
```
|
||
|
||
#### 7️⃣ 在 1Panel 介面配置
|
||
|
||
1. 進入 **運行環境** 設定
|
||
2. 在 **命令執行** 欄位填入:
|
||
```bash
|
||
python3 start.py
|
||
```
|
||
3. 設定 **端口映射**:`12010`(如已修改 .env 中的 PORT,請填入相同端口)
|
||
4. 啟動服務
|
||
|
||
#### 8️⃣ 驗證部署
|
||
|
||
```bash
|
||
# 檢查服務健康狀態
|
||
curl http://localhost:12010/api/health
|
||
|
||
# 預期輸出:
|
||
{
|
||
"status": "healthy",
|
||
"timestamp": "2025-10-03T...",
|
||
"service": "PANJIT Document Translator API",
|
||
"version": "1.0.0"
|
||
}
|
||
```
|
||
|
||
訪問 Web 介面:
|
||
```
|
||
http://your-server-ip:12010
|
||
```
|
||
|
||
---
|
||
|
||
## 📋 檔案輸出格式
|
||
|
||
系統會為每個翻譯任務產生以下檔案:
|
||
|
||
### 單語言翻譯檔案
|
||
- **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` | ✅ | ✅ |
|
||
|
||
---
|
||
|
||
## 🔧 服務管理
|
||
|
||
### 啟動服務
|
||
|
||
```bash
|
||
# 使用統一啟動腳本(推薦)
|
||
python3 start.py
|
||
```
|
||
|
||
`start.py` 會自動啟動:
|
||
1. **Gunicorn + Flask Web 服務** (端口 12010)
|
||
- 生產環境使用 Gunicorn (4 Workers)
|
||
- 開發環境使用 Flask 內建伺服器
|
||
2. **Celery Worker** (翻譯任務處理)
|
||
3. **Celery Beat** (定時任務調度)
|
||
|
||
### 停止服務
|
||
|
||
```bash
|
||
# 在運行終端按 Ctrl+C
|
||
# 或在 1Panel 介面中停止服務
|
||
```
|
||
|
||
### 查看日誌
|
||
|
||
```bash
|
||
# Flask 應用日誌
|
||
tail -f logs/app.log
|
||
|
||
# Celery Worker 日誌
|
||
tail -f logs/celery_worker.log
|
||
|
||
# Celery Beat 日誌
|
||
tail -f logs/celery_beat.log
|
||
|
||
# 訪問日誌(如使用 Gunicorn)
|
||
tail -f logs/access.log
|
||
```
|
||
|
||
### 重啟服務
|
||
|
||
在 1Panel 介面中:
|
||
1. 停止運行環境
|
||
2. 等待幾秒
|
||
3. 重新啟動
|
||
|
||
---
|
||
|
||
## 🏗️ 系統架構
|
||
|
||
### 服務組成
|
||
1. **Gunicorn + Flask**: Web 應用主服務(生產環境,端口 12010)
|
||
- 4 個 Worker 進程(可在 .env 中調整)
|
||
- 直接對外提供服務(無 Nginx 反向代理)
|
||
2. **Celery Worker**: 異步任務處理(翻譯、OCR)
|
||
3. **Celery Beat**: 定時任務調度(檔案清理等)
|
||
4. **Redis**: 訊息佇列和快取(本地端口 6379)
|
||
5. **MySQL**: 外部資料庫服務(mysql.theaken.com:33306)
|
||
|
||
### 網路架構
|
||
```
|
||
用戶瀏覽器
|
||
↓
|
||
[端口 12010] Gunicorn (4 Workers) + Flask
|
||
↓
|
||
Redis (localhost:6379) ← Celery Worker/Beat
|
||
↓
|
||
MySQL (mysql.theaken.com:33306)
|
||
```
|
||
|
||
**注意**:本架構不使用 Nginx,Gunicorn 直接處理 HTTP 請求
|
||
|
||
### 認證架構
|
||
- **主要認證**:API 認證 (https://pj-auth-api.vercel.app/)
|
||
- **備援認證**:LDAP 認證 (panjit.com.tw)
|
||
|
||
### 資料表結構
|
||
系統包含以下核心資料表:
|
||
- `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
|
||
# API 健康檢查
|
||
curl http://localhost:12010/api/health
|
||
|
||
# Redis 連線檢查
|
||
redis-cli ping
|
||
|
||
# 資料庫連線檢查
|
||
mysql -h mysql.theaken.com -P 33306 -u A060 -pWLeSCi0yhtc7 db_A060 -e "SELECT 1"
|
||
```
|
||
|
||
### 日常維護
|
||
|
||
```bash
|
||
# 檢查磁碟空間
|
||
df -h
|
||
|
||
# 清理 30 天前的上傳檔案
|
||
find ./uploads -type f -mtime +30 -delete
|
||
|
||
# 檢查進程狀態
|
||
ps aux | grep python3
|
||
```
|
||
|
||
### 備份
|
||
|
||
```bash
|
||
# 備份上傳檔案
|
||
tar -czf uploads-backup-$(date +%Y%m%d).tar.gz uploads/
|
||
|
||
# 備份資料庫(需 MySQL 存取權限)
|
||
mysqldump -h mysql.theaken.com -P 33306 -u A060 -pWLeSCi0yhtc7 db_A060 \
|
||
> backup-$(date +%Y%m%d).sql
|
||
```
|
||
|
||
---
|
||
|
||
## 🛡️ 安全考量
|
||
|
||
### 生產環境檢查清單
|
||
|
||
- [ ] 修改所有預設密鑰 (SECRET_KEY, JWT_SECRET_KEY)
|
||
- [ ] 確認資料庫連接正常
|
||
- [ ] 確認 Redis 連接正常
|
||
- [ ] 測試 LDAP 認證功能
|
||
- [ ] 測試檔案上傳翻譯功能
|
||
- [ ] 確認端口僅內網可訪問(或配置防火牆)
|
||
- [ ] 設定檔案清理排程
|
||
- [ ] 建立監控和告警機制
|
||
- [ ] 準備備份恢復流程
|
||
- [ ] 記錄所有設定和密碼
|
||
|
||
### 安全建議
|
||
|
||
1. **環境變數保護**
|
||
```bash
|
||
chmod 600 .env api.txt
|
||
```
|
||
|
||
2. **防火牆配置**
|
||
```bash
|
||
# 僅允許內網訪問
|
||
sudo ufw allow from 192.168.0.0/16 to any port 12010
|
||
```
|
||
|
||
3. **定期更新**
|
||
```bash
|
||
pip3 install --upgrade -r requirements.txt
|
||
```
|
||
|
||
---
|
||
|
||
## 🐛 故障排除
|
||
|
||
### 常見問題
|
||
|
||
#### 1. 服務啟動失敗
|
||
|
||
```bash
|
||
# 檢查 Python 版本
|
||
python3 --version # 需要 3.10+
|
||
|
||
# 檢查依賴安裝
|
||
pip3 list | grep -i flask
|
||
|
||
# 檢查端口佔用
|
||
netstat -tuln | grep 12010
|
||
```
|
||
|
||
#### 2. 翻譯任務無響應
|
||
|
||
```bash
|
||
# 檢查 Redis 連線
|
||
redis-cli ping
|
||
|
||
# 檢查 Celery Worker 日誌
|
||
tail -f logs/celery_worker.log
|
||
|
||
# 檢查任務佇列
|
||
redis-cli llen celery
|
||
```
|
||
|
||
#### 3. 資料庫連接失敗
|
||
|
||
```bash
|
||
# 測試資料庫連線
|
||
python3 -c "
|
||
import pymysql
|
||
try:
|
||
conn = pymysql.connect(
|
||
host='mysql.theaken.com',
|
||
port=33306,
|
||
user='A060',
|
||
password='WLeSCi0yhtc7',
|
||
database='db_A060'
|
||
)
|
||
print('Database connected!')
|
||
conn.close()
|
||
except Exception as e:
|
||
print(f'Error: {e}')
|
||
"
|
||
```
|
||
|
||
#### 4. OCR 或翻譯失敗
|
||
|
||
```bash
|
||
# 檢查 api.txt 配置
|
||
cat api.txt
|
||
|
||
# 檢查 Dify API 可訪問性
|
||
curl -I https://api.dify.ai
|
||
|
||
# 清空快取重試
|
||
redis-cli FLUSHALL
|
||
```
|
||
|
||
#### 5. 記憶體不足
|
||
|
||
```bash
|
||
# 檢查記憶體使用
|
||
free -h
|
||
|
||
# 減少 Worker 並發數(編輯 start.py)
|
||
# 將 '--concurrency=2' 改為 '--concurrency=1'
|
||
```
|
||
|
||
---
|
||
|
||
## 📞 技術支援
|
||
|
||
### 系統資訊
|
||
- **系統版本**:Document Translator V2 (1Panel 部署版)
|
||
- **服務端口**:12010
|
||
- **Python 版本**:3.10+
|
||
- **核心框架**:Flask 3.0, Celery 5.3, Vue.js 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
|
||
```
|
||
|
||
### 聯絡方式
|
||
- **管理員郵箱**:ymirliu@panjit.com.tw
|
||
- **技術團隊**:PANJIT IT Team
|
||
|
||
---
|
||
|
||
## 📝 更新日誌
|
||
|
||
### v2.0 (2025-10-03)
|
||
- ✅ 支援 1Panel 環境部署
|
||
- ✅ 新增一鍵安裝腳本 (install.sh)
|
||
- ✅ 新增統一啟動腳本 (start.py)
|
||
- ✅ 移除 Docker 依賴
|
||
- ✅ 優化環境變數配置
|
||
- ✅ 完善部署文檔
|
||
|
||
### v1.0
|
||
- ✅ 初始版本(Docker 部署)
|
||
|
||
---
|
||
|
||
## 📄 授權
|
||
|
||
© 2025 PANJIT Group. All rights reserved.
|
||
|
||
---
|
||
|
||
**🎉 部署完成後,系統即可正式上線使用!**
|
||
|
||
如有任何問題,請參考故障排除章節或聯繫技術支援團隊。
|