This commit is contained in:
beabigegg
2025-10-03 08:19:40 +08:00
commit 6599716481
99 changed files with 28184 additions and 0 deletions

530
README.md Normal file
View File

@@ -0,0 +1,530 @@
# 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)
```
**注意**:本架構不使用 NginxGunicorn 直接處理 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.
---
**🎉 部署完成後,系統即可正式上線使用!**
如有任何問題,請參考故障排除章節或聯繫技術支援團隊。