# CI/CD部署文档

## 架构概览

本项目采用Forgejo + Woodpecker CI + Docker Registry的CI/CD架构，通过docker-compose进行容器化部署。

```
┌─────────────────────────────────────────────────────────────┐
│                    Forgejo (代码仓库)                        │
│                    Woodpecker CI (CI/CD)                    │
│                    Docker Registry (镜像仓库)                │
└─────────────────────────────────────────────────────────────┘
                              ↓
                    构建Docker镜像并推送
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                  docker-compose 部署                        │
├─────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐    │
│  │   API容器     │  │  Admin容器    │  │ UniApp容器   │    │
│  │ (Spring Boot) │  │   (Nginx)    │  │   (Nginx)    │    │
│  └──────────────┘  └──────────────┘  └──────────────┘    │
│  ┌──────────────┐                                           │
│  │ PostgreSQL   │                                           │
│  └──────────────┘                                           │
└─────────────────────────────────────────────────────────────┘
```

## 项目结构

```
everything-is-suitable/
├── everything-is-suitable-api/          # Spring Boot API
│   ├── Dockerfile                      # API镜像构建文件
│   └── pom.xml                        # Maven配置
├── everything-is-suitable-admin/        # Vue 3 Admin
│   ├── Dockerfile                      # Admin镜像构建文件
│   ├── nginx.conf                      # Nginx配置
│   └── package.json                   # npm配置
├── everything-is-suitable-uniapp/      # UniApp移动端
│   ├── Dockerfile                      # UniApp镜像构建文件
│   ├── nginx.conf                      # Nginx配置
│   └── package.json                   # npm配置
├── docker-compose.yml                  # 生产环境部署编排
└── .woodpecker.yml                    # Woodpecker CI配置
```

## 本地开发

### 前置要求

- Docker 20.10+
- Docker Compose 2.0+
- Node.js 20+
- Java 21+
- Maven 3.9+

### 启动开发环境

```bash
# 启动数据库
docker-compose up -d postgres

# 启动API
cd everything-is-suitable-api
mvn spring-boot:run -Dspring-boot.run.profiles=local

# 启动Admin
cd ../everything-is-suitable-admin
npm run dev

# 启动UniApp
cd ../everything-is-suitable-uniapp
npm run dev:h5
```

## CI/CD流程

### Woodpecker CI流水线

Woodpecker CI在每次代码提交时自动执行以下步骤：

1. **代码检查**
   - API: `mvn spotless:check`
   - Admin: `npm run lint`
   - UniApp: `npm run lint`

2. **单元测试**
   - API: `mvn test`
   - Admin: `npm run test`
   - UniApp: `npm run test`

3. **E2E测试**
   - Admin: `npm run test:e2e`
   - UniApp: `npm run test:e2e`

4. **构建Docker镜像**
   - 推送到Docker Registry
   - 标签: `latest` 和 `${CI_COMMIT_SHA:0:8}`

5. **部署**
   - SSH连接到部署服务器
   - 拉取最新镜像
   - 重启容器

### Woodpecker Secrets配置

在Forgejo仓库设置中配置以下Secrets：

| Secret名称 | 说明 | 示例 |
|-----------|------|------|
| `DOCKER_REGISTRY` | Docker Registry地址 | `registry.example.com` |
| `DOCKER_USERNAME` | Docker用户名 | `your-username` |
| `DOCKER_PASSWORD` | Docker密码 | `your-password` |
| `SSH_PRIVATE_KEY` | SSH私钥 | `-----BEGIN RSA PRIVATE KEY-----...` |
| `DEPLOY_HOST` | 部署服务器地址 | `deploy.example.com` |
| `DEPLOY_USER` | 部署服务器用户名 | `deploy` |
| `DEPLOY_PATH` | 部署路径 | `/opt/everything-is-suitable` |

## 生产部署

### 1. 准备部署环境

```bash
# 安装Docker和Docker Compose
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

# 创建部署目录
mkdir -p /opt/everything-is-suitable
cd /opt/everything-is-suitable

# 复制配置文件
cp docker-compose.yml .
cp .env.example .env
```

### 2. 配置环境变量

编辑 `.env` 文件：

```bash
# 数据库密码
POSTGRES_PASSWORD=your_secure_password

# Docker Registry配置
DOCKER_REGISTRY=registry.example.com
DOCKER_USERNAME=your-username
DOCKER_PASSWORD=your-password
```

### 3. 启动服务

```bash
# 拉取镜像
docker-compose pull

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

# 查看服务状态
docker-compose ps

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

### 4. 验证部署

```bash
# 检查API健康状态
curl http://localhost:8080/actuator/health

# 检查Admin页面
curl http://localhost/

# 检查UniApp页面
curl http://localhost:8081/
```

## 服务端口

| 服务 | 端口 | 说明 |
|------|------|------|
| Admin | 80 | 管理后台 |
| API | 8080 | 后端API |
| UniApp | 8081 | 移动端H5 |
| PostgreSQL | 5432 | 数据库 |

## 常用命令

### Docker Compose

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

# 停止所有服务
docker-compose down

# 重启服务
docker-compose restart

# 查看日志
docker-compose logs -f [service-name]

# 查看服务状态
docker-compose ps

# 更新镜像并重启
docker-compose pull && docker-compose up -d
```

### 容器管理

```bash
# 查看运行中的容器
docker ps

# 查看容器日志
docker logs -f [container-id]

# 进入容器
docker exec -it [container-id] sh

# 重启容器
docker restart [container-id]
```

## 监控和日志

### 日志查看

```bash
# API日志
docker-compose logs -f api

# Admin日志
docker-compose logs -f admin

# UniApp日志
docker-compose logs -f uniapp

# 数据库日志
docker-compose logs -f postgres

# 所有服务日志
docker-compose logs -f
```

### 健康检查

```bash
# 检查所有服务健康状态
docker-compose ps

# 检查API健康端点
curl http://localhost:8080/actuator/health

# 检查数据库连接
docker-compose exec postgres pg_isready -U postgres
```

## 备份和恢复

### 数据库备份

```bash
# 备份数据库
docker-compose exec postgres pg_dump -U postgres everything_is_suitable > backup.sql

# 恢复数据库
docker-compose exec -T postgres psql -U postgres everything_is_suitable < backup.sql
```

### 数据卷备份

```bash
# 备份PostgreSQL数据卷
docker run --rm -v everything-is-suitable_postgres_data:/data -v $(pwd):/backup alpine tar czf /backup/postgres_data_backup.tar.gz -C /data .

# 恢复PostgreSQL数据卷
docker run --rm -v everything-is-suitable_postgres_data:/data -v $(pwd):/backup alpine tar xzf /backup/postgres_data_backup.tar.gz -C /data
```

## 故障排查

### 容器无法启动

```bash
# 查看容器日志
docker-compose logs [service-name]

# 检查容器状态
docker-compose ps

# 检查资源使用
docker stats
```

### 网络问题

```bash
# 检查网络连接
docker network ls
docker network inspect everything-is-suitable_app-network

# 测试容器间连接
docker-compose exec api ping postgres
```

### 性能问题

```bash
# 查看资源使用
docker stats

# 查看容器资源限制
docker inspect [container-id] | grep -A 10 Memory
```

## 安全建议

1. **修改默认密码**
   - 修改PostgreSQL密码

2. **网络隔离**
   - 使用Docker网络隔离服务
   - 只暴露必要的端口

3. **定期更新**
   - 定期更新Docker镜像
   - 更新依赖包

4. **备份策略**
   - 定期备份数据库
   - 备份配置文件

5. **监控告警**
   - 配置Prometheus监控
   - 配置Grafana仪表盘
   - 设置告警规则

## 扩展阅读

- [Docker Compose文档](https://docs.docker.com/compose/)
- [Woodpecker CI文档](https://woodpecker-ci.org/docs/)
- [Spring Boot Docker部署](https://spring.io/guides/topicals/spring-boot-docker/)
- [Nginx配置指南](https://nginx.org/en/docs/)