rust-user-api/docs/ci-cd-setup.md

# CI/CD 配置指南

本项目支持在 GitHub、Gitea 和 GitLab 三个平台上运行 CI/CD 流水线。

## 文件说明

- `.github/workflows/deploy.yml` - GitHub Actions / Gitea Actions 配置
- `.gitlab-ci.yml` - GitLab CI/CD 配置

## 平台兼容性

### ✅ GitHub
- 完全支持所有功能
- 使用 GitHub Actions 生态
- 支持 GitHub Container Registry (ghcr.io)

### ✅ Gitea
- 兼容 GitHub Actions 语法
- 支持大部分常用 Actions
- 需要配置自定义镜像仓库

### ✅ GitLab
- 使用 GitLab CI/CD 语法
- 支持 GitLab Container Registry
- 手动部署到生产环境

## 必需的 Secrets 配置

### GitHub / Gitea

在仓库设置 → Secrets 中添加：

```
REGISTRY_USER    # 镜像仓库用户名
REGISTRY_PASS    # 镜像仓库密码
DEPLOY_KEY       # SSH 私钥（用于部署）
DEPLOY_USER      # 部署服务器用户名
DEPLOY_HOST      # 部署服务器地址
```

### GitLab

在项目设置 → CI/CD → Variables 中添加：

```
REGISTRY_USER    # 镜像仓库用户名
REGISTRY_PASS    # 镜像仓库密码
DEPLOY_KEY       # SSH 私钥（用于部署）
DEPLOY_USER      # 部署服务器用户名
DEPLOY_HOST      # 部署服务器地址
```

## 可选的 Variables 配置

### GitHub / Gitea

在仓库设置 → Variables 中添加：

```
REGISTRY         # 自定义镜像仓库地址（默认: docker.io）
```

### GitLab

GitLab 会自动提供 `CI_REGISTRY` 变量，指向项目的容器仓库。

## 镜像仓库配置

### Docker Hub
```
REGISTRY_USER = your-dockerhub-username
REGISTRY_PASS = your-dockerhub-token
REGISTRY = docker.io  # 可选，默认值
```

### GitHub Container Registry
```
REGISTRY_USER = your-github-username
REGISTRY_PASS = your-github-token
REGISTRY = ghcr.io
```

### 私有仓库
```
REGISTRY_USER = your-username
REGISTRY_PASS = your-password
REGISTRY = your-registry.com
```

## SSH 密钥配置

1. 在部署服务器上生成 SSH 密钥对：
```bash
ssh-keygen -t rsa -b 4096 -C "deploy@your-project"
```

2. 将公钥添加到服务器的 `~/.ssh/authorized_keys`：
```bash
cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys
```

3. 将私钥内容复制到 `DEPLOY_KEY` secret 中：
```bash
cat ~/.ssh/id_rsa
```

## 部署环境配置

### 服务器目录结构
```
/opt/rust-api/
├── docker-compose.yml          # 开发/默认配置
├── docker-compose.prod.yml     # 生产配置（可选）
└── data/                       # 数据目录
    └── production.db           # 生产数据库
```

### Docker Compose 配置示例

**docker-compose.yml**
```yaml
version: '3.8'
services:
  rust-user-api:
    image: docker.io/your-username/rust-user-api:latest
    ports:
      - "8080:8080"
    volumes:
      - ./data:/app/data
    environment:
      - RUST_LOG=info
      - DATABASE_URL=/app/data/production.db
    restart: unless-stopped
```

**docker-compose.prod.yml**
```yaml
version: '3.8'
services:
  rust-user-api:
    image: docker.io/your-username/rust-user-api:latest
    ports:
      - "8080:8080"
    volumes:
      - ./data:/app/data
    environment:
      - RUST_LOG=warn
      - DATABASE_URL=/app/data/production.db
    restart: always
    deploy:
      resources:
        limits:
          memory: 512M
        reservations:
          memory: 256M
```

## 流水线触发条件

### 测试阶段
- 推送到 `main` 或 `master` 分支
- 创建 Pull Request / Merge Request

### 构建阶段
- 推送到 `main` 或 `master` 分支
- 推送标签（如 `v1.0.0`）

### 部署阶段
- **测试环境**: 推送到 `main` 或 `master` 分支时自动部署
- **生产环境**: 推送版本标签时部署（GitLab 需要手动触发）

## 版本标签规范

使用语义化版本标签来触发生产部署：

```bash
git tag v1.0.0
git push origin v1.0.0
```

标签格式：`v<major>.<minor>.<patch>`

## 健康检查

流水线会在部署后进行健康检查，访问以下端点：
- `http://localhost:8080/health`
- `http://localhost/health`

确保您的应用提供健康检查端点。

## 故障排除

### 常见问题

1. **Rust 安装失败**
   - 检查网络连接
   - 确保有足够的磁盘空间

2. **Docker 构建失败**
   - 检查 Dockerfile 语法
   - 确保所有依赖都已正确配置

3. **部署失败**
   - 检查 SSH 密钥配置
   - 确保部署服务器可访问
   - 检查服务器磁盘空间

4. **镜像推送失败**
   - 检查镜像仓库凭据
   - 确保有推送权限

### 调试技巧

1. 查看流水线日志
2. 在本地测试 Docker 构建
3. 手动测试 SSH 连接
4. 检查服务器日志

## 安全建议

1. 定期轮换 SSH 密钥
2. 使用最小权限原则配置部署用户
3. 定期更新镜像仓库凭据
4. 启用双因素认证
5. 监控部署日志

## 扩展配置

### 添加通知

可以在流水线中添加通知功能，如：
- Slack 通知
- 邮件通知
- 钉钉通知
- 企业微信通知

### 多环境部署

可以配置多个环境：
- 开发环境 (dev)
- 测试环境 (staging)
- 预生产环境 (pre-prod)
- 生产环境 (production)

### 蓝绿部署

对于零停机部署，可以配置蓝绿部署策略。

### 回滚机制

建议配置自动回滚机制，在部署失败时自动恢复到上一个稳定版本。