feat: Docker化部署 - 單容器架構轉換

將 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>
2025-11-13 13:12:59 +08:00
parent 57cf91271c
commit 0f81d5e70b
26 changed files with 1166 additions and 2985 deletions
--- a/DOCKER_DEPLOYMENT.md
+++ b/DOCKER_DEPLOYMENT.md
@@ -0,0 +1,524 @@
+# 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: 在項目倉庫提交問題報告