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

---

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

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