Document_translator_1panel/README.md

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 檔案：

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️⃣ 安裝依賴套件

# 賦予執行權限
chmod +x install.sh

# 執行一鍵安裝
./install.sh

安裝腳本會自動：

• ✅ 檢查 Python 版本
• ✅ 升級 pip
• ✅ 安裝所有依賴套件
• ✅ 建立必要目錄
• ✅ 驗證安裝結果

4️⃣ 配置環境變數

# 編輯環境變數（已包含完整配置）
nano .env

必須修改的關鍵項目：

# 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 配置

# 確認 API 金鑰已正確配置
cat api.txt

# 應顯示：
# translation_api: app-SmB3TwVMcp5OyQviYeAoTden
# ocr_api: app-kC5qx2wgMMkn61O77jY4YuPs

⚠️ API 金鑰已預先配置，無需修改

6️⃣ 安裝 Redis（重要）

Redis 用於 Celery 任務隊列，必須安裝：

# 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. 在 命令執行 欄位填入：

   python3 start.py
   

3. 設定 端口映射：12010（如已修改 .env 中的 PORT，請填入相同端口）
4. 啟動服務

8️⃣ 驗證部署

# 檢查服務健康狀態
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	✅	✅

---

🔧 服務管理

啟動服務

# 使用統一啟動腳本（推薦）
python3 start.py

start.py 會自動啟動：

1. Gunicorn + Flask Web 服務 (端口 12010)
   • 生產環境使用 Gunicorn (4 Workers)
   • 開發環境使用 Flask 內建伺服器
2. Celery Worker (翻譯任務處理)
3. Celery Beat (定時任務調度)

停止服務

# 在運行終端按 Ctrl+C
# 或在 1Panel 介面中停止服務

查看日誌

# 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: 通知記錄

---

📊 監控與維護

健康檢查

# 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"

日常維護

# 檢查磁碟空間
df -h

# 清理 30 天前的上傳檔案
find ./uploads -type f -mtime +30 -delete

# 檢查進程狀態
ps aux | grep python3

備份

# 備份上傳檔案
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. 環境變數保護

   chmod 600 .env api.txt
   

2. 防火牆配置

   # 僅允許內網訪問
   sudo ufw allow from 192.168.0.0/16 to any port 12010
   

3. 定期更新

   pip3 install --upgrade -r requirements.txt
   

---

🐛 故障排除

常見問題

1. 服務啟動失敗

# 檢查 Python 版本
python3 --version  # 需要 3.10+

# 檢查依賴安裝
pip3 list | grep -i flask

# 檢查端口佔用
netstat -tuln | grep 12010

2. 翻譯任務無響應

# 檢查 Redis 連線
redis-cli ping

# 檢查 Celery Worker 日誌
tail -f logs/celery_worker.log

# 檢查任務佇列
redis-cli llen celery

3. 資料庫連接失敗

# 測試資料庫連線
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 或翻譯失敗

# 檢查 api.txt 配置
cat api.txt

# 檢查 Dify API 可訪問性
curl -I https://api.dify.ai

# 清空快取重試
redis-cli FLUSHALL

5. 記憶體不足

# 檢查記憶體使用
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.

---

🎉 部署完成後，系統即可正式上線使用！

如有任何問題，請參考故障排除章節或聯繫技術支援團隊。