feat: 添加 Docker 部署支持和多 OCR 提供商架构

- 添加完整的 Docker 配置 (Dockerfile, docker-compose.yml) - 修复前端硬编码端口 4000，改用相对路径 /api - 实现多 OCR 提供商架构 (Tesseract.js/Baidu/RapidOCR) - 修复 Docker 环境中图片上传路径问题 - 添加用户设置页面和 AI 分析服务 - 更新 Prisma schema 支持 AI 分析结果 - 添加部署文档和 OCR 配置指南 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-02-26 18:20:46 +08:00
parent f8472987f0
commit 358deeb380
39 changed files with 3169 additions and 71 deletions
@@ -0,0 +1,292 @@
+# PicAnalysis Docker 部署指南
+
+本文档介绍如何使用 Docker Compose 部署 PicAnalysis 项目。
+
+## 前置要求
+
+- Docker Engine 20.10+
+- Docker Compose 2.0+
+
+## 快速开始
+
+### 1. 配置环境变量
+
+复制生产环境配置模板：
+
+```bash
+cp .env.production.example .env
+```
+
+编辑 `.env` 文件，**至少**设置以下必填项：
+
+```bash
+# 必须设置！生成强密钥: openssl rand -base64 32
+JWT_SECRET="your-very-strong-random-secret-key"
+```
+
+### 2. 构建并启动服务
+
+```bash
+# 构建并启动所有服务
+docker compose up -d
+
+# 查看服务状态
+docker compose ps
+
+# 查看日志
+docker compose logs -f
+```
+
+### 3. 访问应用
+
+- **前端**: http://localhost:80
+- **后端 API**: http://localhost:80/api
+- **健康检查**: http://localhost:80/api/health
+
+默认测试账号:
+- 用户名: `testuser`
+- 密码: `Password123@`
+
+## 服务架构
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                       Docker Network                    │
+│  ┌──────────────┐    ┌──────────────┐    ┌──────────┐  │
+│  │   Frontend   │───▶│   Backend    │───▶│ RapidOCR │  │
+│  │   (Nginx)    │    │   (Node.js)  │    │          │  │
+│  │    :80       │    │    :4000     │    │   :8080  │  │
+│  └──────────────┘    └──────────────┘    └──────────┘  │
+│                             │                            │
+│                        ┌────▼─────┐                       │
+│                        │  Volumes │                       │
+│                        │  - data  │                       │
+│                        │  - uploads│                      │
+│                        └──────────┘                       │
+└─────────────────────────────────────────────────────────┘
+```
+
+## 常用命令
+
+### 服务管理
+
+```bash
+# 启动服务
+docker compose up -d
+
+# 停止服务
+docker compose stop
+
+# 重启服务
+docker compose restart
+
+# 停止并删除容器
+docker compose down
+
+# 停止并删除容器、卷、镜像
+docker compose down -v --rmi all
+```
+
+### 日志查看
+
+```bash
+# 查看所有日志
+docker compose logs
+
+# 实时跟踪日志
+docker compose logs -f
+
+# 查看特定服务日志
+docker compose logs -f backend
+docker compose logs -f frontend
+docker compose logs -f rapidocr
+```
+
+### 数据库管理
+
+```bash
+# 进入后端容器
+docker compose exec backend sh
+
+# 运行 Prisma 命令
+docker compose exec backend npx prisma studio
+docker compose exec backend npx prisma migrate dev
+docker compose exec backend npx prisma db push
+```
+
+### 备份与恢复
+
+```bash
+# 备份数据库
+docker compose exec backend cp /app/data/prod.db /app/data/backup-$(date +%Y%m%d).db
+
+# 从备份恢复
+docker compose exec backend cp /app/data/backup-20250101.db /app/data/prod.db
+docker compose restart backend
+```
+
+## 配置选项
+
+### OCR Provider 选择
+
+在 `.env` 中设置 `OCR_PROVIDER`：
+
+| Provider | 说明 | 配置要求 |
+|----------|------|----------|
+| `auto` | 自动选择可用（推荐） | 无需配置，会尝试 Tesseract 和 RapidOCR |
+| `tesseract` | 本地轻量 | 已内置，无需额外配置 |
+| `rapidocr` | 本地快速准确 | 需要启动 RapidOCR 服务（已包含在 compose 中） |
+| `baidu` | 云端准确 | 需要 `BAIDU_OCR_API_KEY` 和 `BAIDU_OCR_SECRET_KEY` |
+
+### AI 分析配置（可选）
+
+如果需要使用 AI 分析功能，在 `.env` 中配置相应的 API Key：
+
+```bash
+# GLM (智谱 AI)
+GLM_API_KEY="your-glm-api-key"
+
+# MiniMax
+MINIMAX_API_KEY="your-minimax-api-key"
+
+# DeepSeek
+DEEPSEEK_API_KEY="your-deepseek-api-key"
+```
+
+### 自定义端口
+
+修改 `.env` 中的 `FRONTEND_PORT`：
+
+```bash
+# 前端端口改为 8080
+FRONTEND_PORT="8080"
+```
+
+然后重启服务：
+
+```bash
+docker compose down
+docker compose up -d
+```
+
+## 数据持久化
+
+以下数据通过 Docker Volumes 持久化：
+
+- `backend-data`: 数据库文件（`/app/data/prod.db`）
+- `backend-uploads`: 用户上传的图片（`/app/uploads`）
+
+即使删除容器，数据也不会丢失。要完全清除数据：
+
+```bash
+docker compose down -v
+```
+
+## 生产环境建议
+
+### 1. 安全加固
+
+```bash
+# 生成强密钥
+openssl rand -base64 32
+```
+
+### 2. 反向代理
+
+在生产环境，建议使用 Nginx 或 Traefik 作为反向代理：
+
+```nginx
+# Nginx 配置示例
+server {
+    listen 443 ssl;
+    server_name your-domain.com;
+
+    ssl_certificate /path/to/cert.pem;
+    ssl_certificate_key /path/to/key.pem;
+
+    location / {
+        proxy_pass http://localhost:80;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+}
+```
+
+### 3. 监控
+
+- 使用 `docker compose ps` 检查服务状态
+- 配置日志收集（如 ELK Stack）
+- 设置健康检查告警
+
+### 4. 资源限制
+
+在 `docker-compose.yml` 中添加资源限制：
+
+```yaml
+services:
+  backend:
+    deploy:
+      resources:
+        limits:
+          cpus: '1'
+          memory: 512M
+```
+
+## 故障排查
+
+### 服务无法启动
+
+```bash
+# 查看详细日志
+docker compose logs backend
+
+# 检查容器状态
+docker compose ps -a
+```
+
+### 数据库连接错误
+
+```bash
+# 进入容器检查
+docker compose exec backend ls -la /app/data
+
+# 重建数据库
+docker compose down -v
+docker compose up -d
+```
+
+### OCR 识别失败
+
+```bash
+# 检查 RapidOCR 服务
+docker compose logs rapidocr
+curl http://localhost:8080
+
+# 切换到 Tesseract
+# 在 .env 中设置 OCR_PROVIDER=tesseract
+docker compose restart backend
+```
+
+### 权限问题
+
+```bash
+# 修复上传目录权限
+docker compose exec backend chown -R nodejs:nodejs /app/uploads
+```
+
+## 升级部署
+
+```bash
+# 拉取最新代码
+git pull
+
+# 重新构建并启动
+docker compose up -d --build
+
+# 数据库迁移（如果有 schema 变更）
+docker compose exec backend npx prisma migrate deploy
+```
+
+## 许可证
+
+MIT License