# Docker Compose 部署

> 一键部署全套服务（前端+后端+数据库+AI），本地与云端通用。

## 🐳 什么是 Docker Compose？

Docker Compose 是一个工具，用于定义和运行多容器 Docker 应用。通过一个 `docker-compose.yml` 文件，你可以一键启动所有相关服务。

## 📋 前提条件

- Docker 20.10+
- Docker Compose 2.0+
- 至少 4GB 内存

## 🚀 快速开始

### 第一步：下载模板

```bash
# 克隆模板仓库
git clone https://github.com/websopy/deploy-templates.git websopy-deploy
cd websopy-deploy

# 选择版本
git checkout v2.3.0
```

### 第二步：配置环境

```bash
# 复制环境变量文件
cp .env.example .env

# 编辑配置
nano .env
```

关键配置：

```env
# 版本
WEBSOPY_VERSION=2.3.0

# 数据库
POSTGRES_DB=websopy
POSTGRES_USER=websopy
POSTGRES_PASSWORD=your-strong-password

# Redis
REDIS_PASSWORD=your-redis-password

# JWT 密钥（生成随机字符串）
JWT_SECRET=$(openssl rand -hex 32)

# 域名（可选）
DOMAIN=your-domain.com
```

### 第三步：启动服务

```bash
# 一键启动所有服务
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f
```

### 第四步：验证部署

```bash
# 检查服务健康状态
curl http://localhost:3000/api/health

# 预期输出
{"status":"ok","version":"2.3.0","services":{"db":"up","redis":"up","ai":"up"}}
```

## 🏗️ 服务架构

```
                    ┌─────────────┐
                    │   Nginx     │
                    │  (反向代理)   │
                    └──────┬──────┘
                           │
           ┌───────────────┼───────────────┐
           │               │               │
      ┌────▼────┐    ┌─────▼────┐    ┌────▼────┐
      │  Web    │    │   API    │    │  Worker │
      │ (前端)   │    │ (后端)    │    │ (异步)   │
      └─────────┘    └─────┬────┘    └─────────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
         ┌────▼───┐  ┌─────▼────┐  ┌───▼────┐
         │Postgres│  │  Redis   │  │  AI    │
         │(数据库) │  │ (缓存)    │  │(AI服务) │
         └────────┘  └──────────┘  └────────┘
```

## 📁 目录结构

```
websopy-deploy/
├── docker-compose.yml     # 服务编排文件
├── .env                   # 环境变量
├── nginx/
│   └── conf.d/           # Nginx 配置
├── postgres/
│   └── init.sql          # 数据库初始化脚本
└── backups/              # 备份目录
```

## 🔧 常用命令

### 启动与停止

```bash
# 启动所有服务
docker-compose up -d

# 停止所有服务
docker-compose down

# 重启所有服务
docker-compose restart

# 重启指定服务
docker-compose restart api
```

### 日志查看

```bash
# 查看所有日志
docker-compose logs -f

# 查看特定服务日志
docker-compose logs -f api
docker-compose logs -f web

# 查看最近 100 行
docker-compose logs --tail=100
```

### 进入容器

```bash
# 进入 API 容器
docker-compose exec api sh

# 进入数据库
docker-compose exec postgres psql -U websopy
```

## 💾 数据持久化

数据存储在 Docker volumes 中：

```bash
# 查看 volumes
docker volume ls | grep websopy

# 备份数据
docker-compose exec postgres pg_dump -U websopy > backup.sql

# 恢复数据
docker exec -i $(docker-compose ps -q postgres) psql -U websopy < backup.sql
```

## 🔄 常用配置

### 调整资源

```yaml
# docker-compose.yml
services:
  api:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 4G

  worker:
    deploy:
      resources:
        limits:
          cpus: '4'
          memory: 8G
```

### 自定义端口

```yaml
services:
  nginx:
    ports:
      - "80:80"
      - "443:443"
  # 改成本地其他端口
  # - "8080:80"
```

### 启用 HTTPS

```bash
# 复制 SSL 证书
mkdir -p nginx/ssl
cp your-cert.crt nginx/ssl/cert.pem
cp your-cert.key nginx/ssl/key.pem

# 编辑 nginx 配置
nano nginx/conf.d/default.conf
```

## 🐛 故障排查

### 服务无法启动

```bash
# 1. 检查 Docker 是否运行
docker info

# 2. 查看详细日志
docker-compose up

# 3. 检查端口占用
lsof -i :80
```

### 数据库连接失败

```bash
# 1. 检查 postgres 是否运行
docker-compose ps postgres

# 2. 查看数据库日志
docker-compose logs postgres

# 3. 测试连接
docker-compose exec postgres psql -U websopy -c "SELECT 1"
```

### 前端无法访问

```bash
# 1. 检查 nginx 日志
docker-compose logs nginx

# 2. 检查 web 容器
docker-compose logs web

# 3. 重建前端
docker-compose up -d --force-recreate web
```

## 🧹 清理

```bash
# 停止并删除容器
docker-compose down

# 删除数据卷（谨慎！）
docker-compose down -v

# 完全清理
docker system prune -a
```

---

**上一步：** [AI 工作流配置](./workflow.md)  
**下一步：** [版本升级与回滚](./upgrade.md)