Files
beabigegg 6599716481 1panel
2025-10-03 08:19:40 +08:00

531 lines
12 KiB
Markdown
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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.
---
**🎉 部署完成後,系統即可正式上線使用!**
如有任何問題,請參考故障排除章節或聯繫技術支援團隊。