# Tool_OCR Docker 部署指南

## 架構說明

Tool_OCR 使用統一容器架構，將前端和後端封裝在同一個容器中：

```
┌─────────────────────────────────────┐
│  Container (tool_ocr)               │
│                                     │
│  ┌──────────────────────────────┐  │
│  │  Nginx :12010 (External)     │  │
│  │  - Frontend Static Files     │  │
│  │  - Reverse Proxy for API     │  │
│  └─────────┬────────────────────┘  │
│            │ proxy_pass             │
│            ▼                        │
│  ┌──────────────────────────────┐  │
│  │  FastAPI :8000 (Internal)    │  │
│  │  - OCR Processing            │  │
│  │  - File Management           │  │
│  │  - Export Services           │  │
│  └──────────────────────────────┘  │
│                                     │
│  Supervisor manages both services   │
└─────────────────────────────────────┘
         │
         │ Port 12010 only!
         ▼
    External Access
```

### 優勢

1. **單一端口**: 只需要暴露一個端口 (12010)
2. **簡化部署**: 一個容器包含完整應用
3. **統一管理**: Supervisor 管理所有服務
4. **生產就緒**: Nginx 提供高性能靜態文件服務和反向代理

## 快速開始

### 前置要求

- Docker Engine 20.10+
- Docker Compose 2.0+
- 至少 4GB 可用內存
- 至少 10GB 可用磁碟空間

### 1. 準備環境配置

**複製環境配置範本：**

Linux/Mac:
```bash
cp .env.docker .env
```

Windows (PowerShell):
```powershell
Copy-Item .env.docker .env
```

**編輯 `.env` 文件，至少修改以下重要配置：**

```bash
# 修改為安全的密鑰
SECRET_KEY=your-very-secure-random-key-here

# 根據需要調整端口
FRONTEND_PORT=12010

# 根據實際情況配置 CORS
CORS_ORIGINS=http://your-domain.com:12010,http://localhost:12010
```

### 2. 創建數據目錄

Linux/Mac:
```bash
mkdir -p data/{uploads,storage,models,logs}
```

Windows (PowerShell):
```powershell
mkdir -p data/uploads, data/storage, data/models, data/logs
```

或使用跨平台命令：
```bash
mkdir -p data/uploads data/storage data/models data/logs
```

### 3. 構建並啟動容器

```bash
# 構建映像
docker compose build

# 啟動服務
docker compose up -d

# 查看日誌
docker compose logs -f
```

> 注意：舊版本 Docker 使用 `docker-compose`（帶連字符），新版本使用 `docker compose`（無連字符）。兩者都支持。

### 4. 驗證部署

Linux/Mac:
```bash
# 檢查健康狀態
curl http://localhost:12010/health

# 訪問 API 文檔
open http://localhost:12010/docs

# 訪問前端界面
open http://localhost:12010
```

Windows (PowerShell):
```powershell
# 檢查健康狀態
curl http://localhost:12010/health

# 在瀏覽器中打開
Start-Process "http://localhost:12010"
Start-Process "http://localhost:12010/docs"
```

## 管理命令

> 提示：以下命令在 Windows、Linux 和 Mac 上通用。如果您使用舊版 Docker，將 `docker compose` 替換為 `docker-compose`。

### 查看狀態

```bash
# 查看容器狀態
docker compose ps

# 查看實時日誌
docker compose logs -f

# 查看特定服務日誌
docker compose exec tool_ocr tail -f /var/log/nginx/tool_ocr_access.log
docker compose exec tool_ocr tail -f /app/backend/logs/app.log
```

### 重啟服務

```bash
# 重啟容器
docker compose restart

# 重啟 Nginx (容器內)
docker compose exec tool_ocr supervisorctl restart nginx

# 重啟 Backend (容器內)
docker compose exec tool_ocr supervisorctl restart backend
```

### 停止和清理

```bash
# 停止服務
docker compose stop

# 停止並移除容器
docker compose down

# 完全清理（包括數據卷）⚠️ 慎用
docker compose down -v
```

### 進入容器調試

```bash
# 進入容器 shell
docker compose exec tool_ocr bash

# 查看 Supervisor 狀態
docker compose exec tool_ocr supervisorctl status

# 查看進程
docker compose exec tool_ocr ps aux
```

## 數據持久化

以下目錄會持久化到主機的 `./data/` 目錄：

| 容器內路徑 | 主機路徑 | 說明 |
|-----------|---------|------|
| `/app/backend/uploads` | `./data/uploads` | 上傳文件 |
| `/app/backend/storage` | `./data/storage` | 處理結果 |
| `/app/backend/models` | `./data/models` | OCR 模型 |
| `/app/backend/logs` | `./data/logs` | 應用日誌 |

### 備份數據

Linux/Mac:
```bash
# 備份所有數據
tar -czf tool_ocr_backup_$(date +%Y%m%d).tar.gz data/

# 只備份重要數據
tar -czf tool_ocr_data_$(date +%Y%m%d).tar.gz data/uploads data/storage
```

Windows (PowerShell):
```powershell
# 備份所有數據（需要安裝 7-Zip 或使用 Compress-Archive）
$date = Get-Date -Format "yyyyMMdd"
Compress-Archive -Path data -DestinationPath "tool_ocr_backup_$date.zip"

# 只備份重要數據
Compress-Archive -Path data/uploads, data/storage -DestinationPath "tool_ocr_data_$date.zip"
```

### 恢復數據

Linux/Mac:
```bash
# 停止容器
docker compose stop

# 恢復數據
tar -xzf tool_ocr_backup_20250113.tar.gz

# 啟動容器
docker compose up -d
```

Windows (PowerShell):
```powershell
# 停止容器
docker compose stop

# 恢復數據
Expand-Archive -Path tool_ocr_backup_20250113.zip -DestinationPath . -Force

# 啟動容器
docker compose up -d
```

## 1Panel 部署指南

### 1. 準備項目文件

在 1Panel 的應用目錄中創建項目：

```bash
cd /opt/1panel/apps
mkdir -p tool_ocr
cd tool_ocr

# 上傳項目文件
# - Dockerfile
# - docker-compose.yml
# - docker/ 目錄
# - backend/ 目錄
# - frontend/ 目錄
# - requirements.txt
# - .env
```

### 2. 在 1Panel 中創建應用

1. 登入 1Panel 管理面板
2. 進入「應用商店」→「自定義應用」
3. 選擇「Docker Compose」
4. 上傳或粘貼 `docker-compose.yml` 內容
5. 配置環境變量
6. 點擊「創建」

### 3. 配置反向代理（可選）

如果需要通過域名訪問：

1. 在 1Panel 中創建網站
2. 配置反向代理：
   - 目標地址: `http://127.0.0.1:12010`
   - 啟用 WebSocket 支援（如需要）

### 4. 配置 SSL 證書（可選）

1. 在 1Panel 網站設置中
2. 申請或上傳 SSL 證書
3. 啟用 HTTPS

## 更新部署

### 更新代碼

```bash
# 停止容器
docker compose stop

# 拉取最新代碼
git pull

# 重新構建映像
docker compose build --no-cache

# 啟動容器
docker compose up -d

# 查看日誌確認啟動成功
docker compose logs -f
```

### 數據庫遷移

如果有數據庫結構變更：

```bash
# 進入容器
docker compose exec tool_ocr bash

# 運行遷移
cd /app/backend
alembic upgrade head

# 退出容器
exit
```

## 故障排除

### 1. 容器無法啟動

```bash
# 查看詳細錯誤
docker compose logs
```

檢查端口占用：

Linux/Mac:
```bash
netstat -tuln | grep 12010
# 或
lsof -i :12010
```

Windows (PowerShell):
```powershell
netstat -ano | findstr 12010
# 或
Get-NetTCPConnection -LocalPort 12010
```

檢查磁碟空間：

Linux/Mac:
```bash
df -h
```

Windows (PowerShell):
```powershell
Get-PSDrive
```

### 2. Nginx 無法啟動

```bash
# 檢查 Nginx 配置語法
docker compose exec tool_ocr nginx -t

# 查看 Nginx 錯誤日誌
docker compose exec tool_ocr cat /var/log/nginx/error.log
```

### 3. Backend API 無法訪問

```bash
# 檢查 Backend 是否運行
docker compose exec tool_ocr supervisorctl status backend

# 查看 Backend 日誌
docker compose exec tool_ocr cat /app/backend/logs/app.log

# 重啟 Backend
docker compose exec tool_ocr supervisorctl restart backend
```

### 4. 數據庫連接失敗

```bash
# 測試數據庫連接
docker compose exec tool_ocr python -c "
from app.core.database import engine
try:
    with engine.connect() as conn:
        print('Database connection successful!')
except Exception as e:
    print(f'Database connection failed: {e}')
"
```

### 5. OCR 處理失敗

```bash
# 檢查 PaddleOCR 模型
docker compose exec tool_ocr ls -la /app/backend/models/paddleocr/

# 測試 OCR 功能
docker compose exec tool_ocr python -c "
from paddleocr import PaddleOCR
ocr = PaddleOCR(lang='ch')
print('PaddleOCR initialized successfully!')
"
```

### 6. 前端頁面無法訪問

```bash
# 檢查前端文件是否存在
docker compose exec tool_ocr ls -la /app/frontend/dist/

# 檢查 Nginx 配置
docker compose exec tool_ocr cat /etc/nginx/conf.d/default.conf
```

## 性能優化

### 1. 調整 OCR 工作進程數

根據 CPU 核心數調整：

```bash
# 在 .env 中設置
MAX_OCR_WORKERS=8  # 建議設置為 CPU 核心數
```

### 2. 調整 Nginx Worker 進程數

編輯 `docker/nginx.conf`：

```nginx
worker_processes auto;  # 自動根據 CPU 核心數
```

### 3. 優化 Upload 大小限制

根據實際需求調整：

```bash
# 在 .env 中設置（以字節為單位）
MAX_UPLOAD_SIZE=104857600  # 100MB
```

同時修改 `docker/nginx.conf`：

```nginx
client_max_body_size 100M;
```

## 監控和日誌

### 日誌位置

| 服務 | 容器內路徑 | 主機路徑 |
|------|-----------|---------|
| Nginx Access | `/var/log/nginx/tool_ocr_access.log` | - |
| Nginx Error | `/var/log/nginx/tool_ocr_error.log` | - |
| Backend | `/app/backend/logs/app.log` | `./data/logs/app.log` |
| Supervisor | `/var/log/supervisor/supervisord.log` | - |

### 日誌輪轉

建議配置日誌輪轉以防止日誌文件過大：

```bash
# 創建 logrotate 配置（主機上）
cat > /etc/logrotate.d/tool_ocr << 'EOF'
/path/to/tool_ocr/data/logs/*.log {
    daily
    rotate 7
    compress
    delaycompress
    notifempty
    create 0644 root root
}
EOF
```

## 安全建議

1. **修改默認密鑰**: 務必修改 `.env` 中的 `SECRET_KEY`
2. **使用 HTTPS**: 在生產環境中啟用 SSL/TLS
3. **限制 CORS**: 只允許可信的來源
4. **定期更新**: 及時更新 Docker 映像和依賴
5. **備份數據**: 定期備份重要數據
6. **監控日誌**: 定期檢查日誌中的異常活動

## 常見問題

### Q: 如何修改對外端口？

A: 修改 `.env` 中的 `FRONTEND_PORT` 和 `docker-compose.yml` 中的端口映射。

### Q: 如何增加上傳文件大小限制？

A: 修改 `.env` 中的 `MAX_UPLOAD_SIZE` 和 `docker/nginx.conf` 中的 `client_max_body_size`。

### Q: 如何連接外部 MySQL 數據庫？

A: 在 `.env` 中配置正確的數據庫連接信息。

### Q: 如何查看詳細的錯誤信息？

A: 設置 `.env` 中的 `LOG_LEVEL=DEBUG` 並重啟容器。

## 聯繫支援

如果遇到問題，請：

1. 查看日誌: `docker-compose logs -f`
2. 檢查配置: 確認 `.env` 文件正確
3. 查看文檔: 參考本文檔的故障排除部分
4. 提交 Issue: 在項目倉庫提交問題報告