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 密钥对：

ssh-keygen -t rsa -b 4096 -C "deploy@your-project"

2. 将公钥添加到服务器的 ~/.ssh/authorized_keys：

cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys

3. 将私钥内容复制到 DEPLOY_KEY secret 中：

cat ~/.ssh/id_rsa

部署环境配置

服务器目录结构

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

Docker Compose 配置示例

docker-compose.yml

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

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 需要手动触发）

版本标签规范

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

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)

蓝绿部署

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

回滚机制

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