PicAnalysis/DEPLOYMENT.md

# 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