Document_translator/README.md

# PANJIT Document Translator V2 - 正式生產環境部署指南

## 🎯 系統概述

PANJIT Document Translator V2 是一個企業級文檔翻譯系統，支援多種文檔格式的智能翻譯，包含 OCR 圖像識別和對話上下文連貫性功能。

### 核心功能
- ✅ **多格式支援**：DOCX、DOC、PDF、PPTX、XLSX、XLS 文檔翻譯
- ✅ **智能 OCR**：掃描 PDF 自動識別，含圖像預處理增強
- ✅ **對話持續性**：維持翻譯上下文，確保長文檔術語一致性
- ✅ **多語言輸出**：單語言翻譯檔 + 多語言組合檔
- ✅ **混合認證**：API 認證為主，LDAP 備援
- ✅ **異步處理**：Celery + Redis 批量任務隊列
- ✅ **快取機制**：OCR 快取 + 翻譯快取，避免重複處理

### 支援的翻譯語言
中文(繁體)、中文(簡體)、英文、日文、韓文、法文、德文、西班牙文、俄文、阿拉伯文、葡萄牙文、義大利文、泰文、越南文

---

## 🚀 快速部署

### 1. 系統需求
- **操作系統**：Linux/Windows Server
- **Docker**：≥ 20.10
- **Docker Compose**：≥ 2.0
- **記憶體**：≥ 8GB (推薦 16GB)
- **存儲空間**：≥ 50GB
- **網路**：可訪問外部 Dify API

### 2. 部署步驟

#### Windows 系統
```bash
# 1. 進入專案目錄
cd Document_translator_V2

# 2. 配置環境變數 (已包含正式配置)
# 確認 .env.production 檔案存在

# 3. 執行部署腳本
deploy-production.bat
```

#### Linux 系統
```bash
# 1. 進入專案目錄
cd Document_translator_V2

# 2. 確認環境配置
cat .env.production

# 3. 執行部署腳本
chmod +x deploy-production.sh
./deploy-production.sh
```

### 3. 服務驗證

部署完成後，系統將在 **http://localhost:12010** 提供服務。

```bash
# 檢查所有容器狀態
docker-compose -f docker-compose.prod.yml ps

# 檢查 API 健康狀態
curl http://localhost:12010/api/health

# 預期輸出
{
  "status": "healthy",
  "database": "connected",
  "redis": "connected"
}
```

---

## 📂 文件輸出格式

系統會為每個翻譯任務產生以下檔案：

### 單語言翻譯檔案
- **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` | ✅ | ✅ |

---

## 🔧 生產環境配置

### 資料庫配置 (MySQL)
```bash
MYSQL_HOST=mysql.theaken.com
MYSQL_PORT=33306
MYSQL_USER=A060
MYSQL_PASSWORD=WLeSCi0yhtc7
MYSQL_DATABASE=db_A060
MYSQL_CHARSET=utf8mb4
```

### Redis 配置
```bash
REDIS_URL=redis://redis:6379/0
CELERY_BROKER_URL=redis://redis:6379/0
```

### LDAP 配置
```bash
LDAP_SERVER=panjit.com.tw
LDAP_PORT=389
```

### SMTP 郵件配置
```bash
SMTP_SERVER=mail.panjit.com.tw
SMTP_PORT=25
SMTP_USE_TLS=false
SMTP_AUTH_REQUIRED=false
SMTP_SENDER_EMAIL=translator-system@panjit.com.tw
```

### 重要安全設定

⚠️ **首次部署必須修改以下項目**：

```bash
# 1. 更改預設密鑰 (在 .env 中)
SECRET_KEY=your-production-secret-key-change-this
JWT_SECRET_KEY=your-production-jwt-secret-change-this

# 2. 確認檔案大小限制 (預設 100MB)
MAX_CONTENT_LENGTH=104857600

# 3. 配置檔案保留天數 (預設 30 天)
FILE_RETENTION_DAYS=30
```

---

## 🏗️ 系統架構

### Docker 容器組成
1. **translator-app-prod**: Flask 應用主服務 (Gunicorn)
2. **panjit-translator-worker-prod**: Celery Worker (翻譯任務處理)
3. **panjit-translator-beat-prod**: Celery Beat (定時任務)
4. **panjit-translator-nginx-prod**: Nginx 反向代理
5. **panjit-translator-redis-prod**: Redis 快取/訊息佇列

### 認證架構說明

**混合認證策略**：
- **主要認證**：API 認證 (https://pj-auth-api.vercel.app/)
- **備援認證**：LDAP 認證 (panjit.com.tw)

s
### 資料表結構

系統包含以下核心資料表：
- `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
# 查看所有容器狀態
docker-compose -f docker-compose.prod.yml ps

# 檢查健康狀態
docker inspect --format='{{.State.Health.Status}}' translator-app-prod

# 預期輸出：healthy
```

### 日誌監控

```bash
# 實時查看應用日誌
docker logs -f translator-app-prod

# 查看 Celery Worker 日誌
docker logs -f panjit-translator-worker-prod

# 查看 Nginx 訪問日誌
docker logs -f panjit-translator-nginx-prod
```

### 效能監控指標

- **記憶體使用**：App < 2GB，Worker < 3GB
- **CPU 使用率**：正常負載 < 50%
- **翻譯速度**：平均 2-5 秒/頁 (依文檔複雜度)
- **OCR 處理**：首次 5-10 秒/頁，快取命中 < 0.1 秒

---

## 🔄 維護操作

### 日常維護

```bash
# 重啟所有服務
docker-compose -f docker-compose.prod.yml restart

# 僅重啟應用容器 (不影響其他服務)
docker-compose -f docker-compose.prod.yml restart app

# 更新應用 (重新部署)
docker-compose -f docker-compose.prod.yml up -d --build app

# 查看資源使用
docker stats
```

### 資料庫維護

```bash
# 資料表已在部署時自動建立
# 若需重建資料表，請先備份資料

# 進入容器執行 SQL
docker exec -it translator-app-prod bash
python -c "from app import db; db.create_all()"
```

### 檔案清理

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

# 清理 Docker 未使用映像
docker system prune -af
```

### 備份與恢復

```bash
# 1. 備份上傳檔案
tar -czf uploads-backup-$(date +%Y%m%d).tar.gz uploads/

# 2. 備份資料庫 (需 MySQL 存取權限)
docker exec translator-app-prod mysqldump \
  -h mysql.theaken.com -u A060 -pWLeSCi0yhtc7 db_A060 \
  > backup-$(date +%Y%m%d).sql

# 3. 恢復資料庫
docker exec -i translator-app-prod mysql \
  -h mysql.theaken.com -u A060 -pWLeSCi0yhtc7 db_A060 \
  < backup-20251002.sql
```

---

## 🛡️ 安全考量

### 網路安全
- ✅ 容器間隔離網路 (panjit-translator-network)
- ✅ 僅 Nginx 暴露公開端口 (12010)
- ✅ API 認證 + JWT Token 驗證
- ✅ HTTPS 建議配置 (生產環境需額外設定 SSL)

### 數據安全
- ✅ 敏感資訊使用環境變數管理
- ✅ 資料庫連接加密 (charset=utf8mb4)
- ✅ API 金鑰存儲於配置檔案
- ✅ 檔案定期自動清理機制

### 生產環境檢查清單

- [ ] 修改所有預設密鑰 (SECRET_KEY, JWT_SECRET_KEY)
- [ ] 確認資料庫連接正常
- [ ] 確認 Redis 連接正常
- [ ] 測試 LDAP 認證功能
- [ ] 測試檔案上傳翻譯功能
- [ ] 確認 Nginx 反向代理正常
- [ ] 設定檔案清理排程 (cron)
- [ ] 建立監控和告警機制
- [ ] 準備備份恢復流程
- [ ] 記錄系統存取帳號密碼

---

## 🐛 故障排除

### 常見問題

#### 1. 容器啟動失敗
```bash
# 檢查容器日誌
docker-compose -f docker-compose.prod.yml logs app

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

# 檢查資源使用
docker system df
```

#### 2. 翻譯服務無響應
```bash
# 重啟 Celery Worker
docker-compose -f docker-compose.prod.yml restart celery-worker

# 檢查 Redis 連接
docker exec panjit-translator-redis-prod redis-cli ping
# 預期輸出：PONG

# 檢查任務佇列
docker exec panjit-translator-redis-prod redis-cli llen celery
```

#### 3. 前端無法訪問
```bash
# 檢查 Nginx 狀態
docker-compose -f docker-compose.prod.yml logs nginx

# 測試後端 API
curl http://localhost:12010/api/health

# 檢查靜態檔案
docker exec translator-app-prod ls -la /app/static/
```

#### 4. 資料庫連接失敗
```bash
# 測試資料庫連接
docker exec translator-app-prod python -c "
from app import db
try:
    db.session.execute('SELECT 1')
    print('Database connected!')
except Exception as e:
    print(f'Error: {e}')
"

# 檢查環境變數
docker exec translator-app-prod env | grep MYSQL
```

#### 5. OCR 或翻譯失敗
```bash
# 檢查 Dify API 配置
docker exec translator-app-prod cat /app/app/config.py | grep DIFY

# 查看 Worker 錯誤日誌
docker logs panjit-translator-worker-prod | grep ERROR

# 清空快取重試
docker exec panjit-translator-redis-prod redis-cli FLUSHALL
```

#### 6. 記憶體不足
```bash
# 清理 Docker 系統
docker system prune -af

# 重啟服務
docker-compose -f docker-compose.prod.yml restart

# 增加 Worker 數量 (若資源充足)
docker-compose -f docker-compose.prod.yml up -d --scale celery-worker=2
```

---

## 📞 技術支援

### 系統資訊
- **系統版本**：Document Translator V2 (Production)
- **服務端口**：12010
- **Python 版本**：3.11
- **Node 版本**：18
- **核心框架**：Flask 3.0, Vue.js 3, Celery 5.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
```

---

## 📋 部署檢查清單

### 首次部署前
- [ ] 確認 Docker 和 Docker Compose 已安裝
- [ ] 確認網路可訪問 MySQL 和 Dify API
- [ ] 確認埠號 12010 未被佔用
- [ ] 準備好資料庫連接資訊
- [ ] 準備好 LDAP 連接資訊

### 部署過程中
- [ ] 執行 `deploy-production.bat` 或 `.sh`
- [ ] 確認所有容器成功啟動 (5 個容器)
- [ ] 確認健康檢查全部通過
- [ ] 測試訪問 http://localhost:12010

### 部署完成後
- [ ] 使用測試帳號登入驗證
- [ ] 上傳測試檔案進行翻譯
- [ ] 檢查翻譯輸出檔案格式
- [ ] 確認 OCR 功能正常
- [ ] 驗證多語言組合檔案產生
- [ ] 設定定期備份機制
- [ ] 記錄所有設定和密碼

---

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

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