PicAnalysis/DEPLOYMENT.md

PicAnalysis Docker 部署指南

本文档介绍如何使用 Docker Compose 部署 PicAnalysis 项目。

前置要求

• Docker Engine 20.10+
• Docker Compose 2.0+

快速开始

1. 配置环境变量

复制生产环境配置模板：

cp .env.production.example .env

编辑 .env 文件，至少设置以下必填项：

# 必须设置！生成强密钥: openssl rand -base64 32
JWT_SECRET="your-very-strong-random-secret-key"

2. 构建并启动服务

# 构建并启动所有服务
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│                      │
│                        └──────────┘                       │
└─────────────────────────────────────────────────────────┘

常用命令

服务管理

# 启动服务
docker compose up -d

# 停止服务
docker compose stop

# 重启服务
docker compose restart

# 停止并删除容器
docker compose down

# 停止并删除容器、卷、镜像
docker compose down -v --rmi all

日志查看

# 查看所有日志
docker compose logs

# 实时跟踪日志
docker compose logs -f

# 查看特定服务日志
docker compose logs -f backend
docker compose logs -f frontend
docker compose logs -f rapidocr

数据库管理

# 进入后端容器
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

备份与恢复

# 备份数据库
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：

# 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：

# 前端端口改为 8080
FRONTEND_PORT="8080"

然后重启服务：

docker compose down
docker compose up -d

数据持久化

以下数据通过 Docker Volumes 持久化：

• backend-data: 数据库文件（/app/data/prod.db）
• backend-uploads: 用户上传的图片（/app/uploads）

即使删除容器，数据也不会丢失。要完全清除数据：

docker compose down -v

生产环境建议

1. 安全加固

# 生成强密钥
openssl rand -base64 32

2. 反向代理

在生产环境，建议使用 Nginx 或 Traefik 作为反向代理：

# 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 中添加资源限制：

services:
  backend:
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 512M

故障排查

服务无法启动

# 查看详细日志
docker compose logs backend

# 检查容器状态
docker compose ps -a

数据库连接错误

# 进入容器检查
docker compose exec backend ls -la /app/data

# 重建数据库
docker compose down -v
docker compose up -d

OCR 识别失败

# 检查 RapidOCR 服务
docker compose logs rapidocr
curl http://localhost:8080

# 切换到 Tesseract
# 在 .env 中设置 OCR_PROVIDER=tesseract
docker compose restart backend

权限问题

# 修复上传目录权限
docker compose exec backend chown -R nodejs:nodejs /app/uploads

升级部署

# 拉取最新代码
git pull

# 重新构建并启动
docker compose up -d --build

# 数据库迁移（如果有 schema 变更）
docker compose exec backend npx prisma migrate deploy

许可证

MIT License