2025-08-07 17:09:29 +08:00
parent bb9d7a869d
commit 0c908b128c
5 changed files with 586 additions and 84 deletions
							
							
							
						
@@ -0,0 +1,251 @@
# 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)
### 蓝绿部署
对于零停机部署，可以配置蓝绿部署策略。
### 回滚机制
建议配置自动回滚机制，在部署失败时自动恢复到上一个稳定版本。