OCR/DOCKER_DEPLOYMENT.md

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:

cp .env.docker .env

Windows (PowerShell):

Copy-Item .env.docker .env

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

# 修改為安全的密鑰
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:

mkdir -p data/{uploads,storage,models,logs}

Windows (PowerShell):

mkdir -p data/uploads, data/storage, data/models, data/logs

或使用跨平台命令：

mkdir -p data/uploads data/storage data/models data/logs

3. 構建並啟動容器

# 構建映像
docker compose build

# 啟動服務
docker compose up -d

# 查看日誌
docker compose logs -f

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

4. 驗證部署

Linux/Mac:

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

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

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

Windows (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。

查看狀態

# 查看容器狀態
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

重啟服務

# 重啟容器
docker compose restart

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

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

停止和清理

# 停止服務
docker compose stop

# 停止並移除容器
docker compose down

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

進入容器調試

# 進入容器 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:

# 備份所有數據
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):

# 備份所有數據（需要安裝 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:

# 停止容器
docker compose stop

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

# 啟動容器
docker compose up -d

Windows (PowerShell):

# 停止容器
docker compose stop

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

# 啟動容器
docker compose up -d

1Panel 部署指南

1. 準備項目文件

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

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

更新部署

更新代碼

# 停止容器
docker compose stop

# 拉取最新代碼
git pull

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

# 啟動容器
docker compose up -d

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

數據庫遷移

如果有數據庫結構變更：

# 進入容器
docker compose exec tool_ocr bash

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

# 退出容器
exit

故障排除

1. 容器無法啟動

# 查看詳細錯誤
docker compose logs

檢查端口占用：

Linux/Mac:

netstat -tuln | grep 12010
# 或
lsof -i :12010

Windows (PowerShell):

netstat -ano | findstr 12010
# 或
Get-NetTCPConnection -LocalPort 12010

檢查磁碟空間：

Linux/Mac:

df -h

Windows (PowerShell):

Get-PSDrive

2. Nginx 無法啟動

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

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

3. Backend API 無法訪問

# 檢查 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. 數據庫連接失敗

# 測試數據庫連接
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 處理失敗

# 檢查 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. 前端頁面無法訪問

# 檢查前端文件是否存在
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 核心數調整：

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

2. 調整 Nginx Worker 進程數

編輯 docker/nginx.conf：

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

3. 優化 Upload 大小限制

根據實際需求調整：

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

同時修改 docker/nginx.conf：

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	-

日誌輪轉

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

# 創建 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: 在項目倉庫提交問題報告