0f81d5e70b
將 Tool_OCR 從 macOS conda 環境轉換為 Docker 單容器部署方案。 前後端整合於同一容器，通過 Nginx 反向代理，僅對外暴露單一端口。 ## 新增功能 - Docker 單容器架構（Frontend + Backend + Nginx） - 多階段構建優化鏡像大小 - Supervisor 進程管理 - 健康檢查機制 - 完整部署文檔 ## 技術細節 - 對外端口：12015（原 12010 已被佔用） - 內部架構：Nginx(12015) → FastAPI(8000) - 前端靜態文件由 Nginx 直接服務 - API 請求通過 Nginx 反向代理 ## 系統依賴完善 - libmagic1：文件類型檢測 - LibreOffice：Office 文檔轉換 - paddlex[ocr]：PP-StructureV3 版面分析 - 中日韓字體支援 ## 配置調整 - 環境變數路徑：macOS 路徑 → 容器絕對路徑 - 前端 API URL：修正為統一端口 12015 - Pip 安裝：延長超時至 600 秒，重試 5 次 - CRLF 轉換：自動處理 Windows 換行符 ## 清理 - 移除臨時文檔（API_FIX_SUMMARY.md 等 7 個文檔） 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
525 lines
11 KiB
Markdown
525 lines
11 KiB
Markdown
# 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: 在項目倉庫提交問題報告
|