# devops-agent-deploy

**Repository Path**: RookieJava/devops-agent-deploy

## Basic Information

- **Project Name**: devops-agent-deploy
- **Description**: 🤖 多环境 AI Agent Team CI/CD 自动部署流水线 — 支持 dev/test/prod 三环境，钉钉/飞书/企业微信告警，可配置依赖与质量门禁，MIT 协议开源。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-27
- **Last Updated**: 2026-05-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: AI, devops, CI-CD, Agent, 自动化

## README

# DevOps Agent Team — 多环境自动化部署流水线

> **Platform-agnostic Agent Team CI/CD pipeline** with dev/test/prod environments,
> DingTalk/Feishu/WeCom alerts, configurable dependencies, and automatic rollback.
>
> 支持 dev/test/prod 三环境 · 钉钉/飞书/企业微信告警 · 可配置依赖 · 自动回滚

---

## 目录结构

```
devops-agent-deploy/                     ← Skill 根目录（名称 = skill name）
│
├── SKILL.md                             ← 主 Skill 定义（触发词、架构、流程）
├── README.md                            ← 本文件 / This file
│
├── references/                          ← 参考文档
│   ├── roles.md                         ← Agent 角色定义（Orchestrator/Builder/Reviewer/Ops）
│   └── pipeline.md                      ← 流水线状态机、质量门禁、回滚策略
│
├── config/                              ← 可修改配置（首次使用请复制模板并编辑）
│   ├── env-template.yaml                ← 环境配置模板：dev / test / prod
│   └── alert-template.yaml              ← 告警配置模板：钉钉 / 飞书 / 企业微信
│
├── tasks/                               ← 5 个流水线任务 JSON
│   ├── 1-build.json                     ← [Build] 代码拉取与构建
│   ├── 2-test.json                      ← [Test] 单元测试与集成测试
│   ├── 3-review.json                    ← [Review] 代码审查与安全扫描
│   ├── 4-deploy.json                    ← [Deploy] 多环境部署（dev/test/prod）
│   └── 5-monitor.json                   ← [Monitor] 健康检查 + 告警 + 回滚
│
├── team/
│   └── config-template.json             ← 团队配置模板
│
└── demo-project/                        ← Spring Boot 3.2 演示项目
    ├── pom.xml
    ├── Dockerfile                        ← 多阶段构建 + 非 root 用户
    ├── docker-compose.yml                ← 环境变量驱动
    └── src/
        ├── main/java/com/demo/Application.java    ← /api/health + /api/info
        ├── main/resources/application.yml         ← actuator + prometheus
        └── test/java/com/demo/ApplicationTest.java ← 3 个集成测试
```

---

## 快速开始 / Quick Start

### 1. 配置 / Configuration

```bash
# 复制配置模板
cp config/env-template.yaml config/env.yaml
cp config/alert-template.yaml config/alert.yaml

# 编辑环境配置：改 host、port、部署策略
vim config/env.yaml

# 编辑告警配置：填入 webhook URL，启用需要的渠道
vim config/alert.yaml
```

### 2. 安装到 Agent 平台 / Install

```bash
# 方式 A：npx skills（跨平台通用）
npx skills add ./devops-agent-deploy

# 方式 B：WorkBuddy
cp -r devops-agent-deploy ~/.workbuddy/skills/

# 方式 C：Claude Code
cp -r devops-agent-deploy ~/.claude/skills/
```

### 3. 创建团队和流水线 / Create Team & Pipeline

在你的 Agent 平台中说：

> 创建一个叫 devops-deploy 的团队，导入 tasks/ 目录下的五阶段流水线任务，设置 Build → Test → Review → Deploy → Monitor 依赖链

### 4. 触发部署 / Trigger

```
deploy demo-project to dev        # 开发环境（即时生效）
deploy demo-project to test       # 测试环境（滚动更新）
deploy demo-project to prod       # 正式环境（需审批）
```

---

## 三环境部署 / Multi-Environment

| 特性 | dev | test | prod |
|------|-----|------|------|
| **部署策略** | direct（直接替换） | rolling（滚动更新） | blue-green（蓝绿部署） |
| **容器副本** | 1 | 2 | 3 |
| **JVM 堆内存** | 256m | 512m | 1024m |
| **人工审批** | 否 | 否 | **是**（必须审批后执行） |
| **5xx 容忍率** | 5% | 2% | 1% |
| **健康检查重试** | 3 次 / 3s | 3 次 / 3s | 5 次 / 5s |
| **部署钩子** | 无 | 基础 | 完整（镜像备份 + 冒烟测试） |

所有环境参数在 `config/env.yaml` 中配置，无需修改流水线代码。

---

## 告警通知 / Alert Notifications

三条渠道独立开关，在 `config/alert.yaml` 中配置：

| 渠道 | 配置字段 | Webhook 获取路径 |
|------|---------|----------------|
| **钉钉** | `channels.dingtalk` | 群设置 → 智能群助手 → 添加机器人 → 自定义 |
| **飞书** | `channels.feishu` | 群设置 → 群机器人 → 添加机器人 → 自定义 |
| **企业微信** | `channels.wecom` | 群设置 → 群机器人 → 添加 → Webhook 地址 |

### 通知事件

| 事件 | emoji | 触发时机 |
|------|-------|---------|
| `deploy_start` | 🚀 | 流水线启动 |
| `deploy_success` | ✅ | 部署 + 健康检查通过 |
| `deploy_failure` | ❌ | 任一阶段失败 |
| `rollback` | 🔄 | 自动或手动回滚 |
| `health_check_failure` | ⚠️ | 健康检查失败 |
| `quality_gate_failure` | 🚫 | 质量门禁不通过 |

---

## Agent 角色 / Roles

| 角色 | 负责阶段 | 质量门禁 |
|------|---------|---------|
| **Builder** | Build + Test | 编译零错误 + 测试通过率 >= 95% |
| **Reviewer** | Review | P0 问题 = 0 |
| **Ops** | Deploy + Monitor + Alert | 健康检查通过 + 5xx < 阈值 |

**Orchestrator** 不执行具体操作，只做决策：状态追踪、质量门禁判定、回滚决策、告警调度。

---

## 流水线阶段 / Pipeline Stages

```
Build ──→ Test ──→ Review ──→ Deploy ──→ Monitor
  │        │         │          │           │
  │        │         │     ┌────┴────┐  ┌───┴───┐
  │        │         │     │  dev    │  │ 钉钉   │
  │        │         │     │  test   │  │ 飞书   │──→ Webhook
  │        │         │     │  prod   │  │ 企业微信│
  │        │         │     └─────────┘  └───────┘
  ▼        ▼         ▼
Quality Gates (任一不通过 → 阻断 + 告警)
```

---

## 回滚策略 / Rollback

### 自动触发条件

1. 健康检查连续失败（次数 = 环境配置的 `health_retry_count`）
2. 5xx 错误率超过环境阈值（`max_5xx_rate`）
3. 用户在 Agent 平台中手动触发

### 执行

```bash
# Docker Compose
docker-compose down
docker tag <image>:latest <image>:previous
docker-compose up -d

# Kubernetes
kubectl rollout undo deployment/<name> -n <namespace>
```

### 回滚后

- 发送 `rollback` 告警到所有启用渠道
- 重新验证健康检查
- 通知 Orchestrator 暂停后续部署直到根因修复

---

## 环境依赖（可配置）/ Configurable Dependencies

| 工具 | 配置方式 | 检测命令 |
|------|---------|---------|
| JDK 17+ | `JAVA_HOME` 环境变量 或 `config/env.yaml` → `project.java_version` | `java -version` |
| Maven | `MAVEN_HOME` 或 PATH | `mvn --version` |
| Gradle | `GRADLE_HOME` 或 PATH | `gradle --version` |
| Docker | `DOCKER_HOST` 或默认 socket | `docker ps` |
| Docker Compose | PATH | `docker-compose --version` |
| kubectl | `KUBECONFIG` | `kubectl version` |

流水线启动前自动检查依赖可用性。缺失时提示安装命令，不强制中断。

---

## 自定义 / Customization

| 需求 | 操作 |
|------|------|
| 换项目 | 改 `tasks/*.json` 中的项目路径 + `config/env.yaml` 的 project 信息 |
| 换语言 | 非 Java 项目改 Builder 任务中的构建命令 |
| 换部署方式 | 改 Ops Agent 的 Deploy 策略（docker → k8s） |
| 加环境 | 在 `config/env.yaml` 中新增环境块 |
| 加告警渠道 | 在 `config/alert.yaml` 中新增 channels 条目和消息模板 |
| 加流水线阶段 | 在 `tasks/` 中新增 JSON 文件，设置 blockedBy |
| 改质量门禁 | 改 `references/pipeline.md` 中的 Gate Condition |

---

## 跨平台兼容 / Cross-Platform

| Agent 平台 | 安装方式 | 说明 |
|-----------|---------|------|
| **WorkBuddy** | `cp -r devops-agent-deploy ~/.workbuddy/skills/` | 原生支持 Team/Task |
| **Claude Code** | `cp -r devops-agent-deploy ~/.claude/skills/` | 需手动创建任务流 |
| **npx skills** | `npx skills add ./devops-agent-deploy` | 发布到 skills.sh 后可用 |
| **LangChain** | 复制 SKILL.md 作为 system prompt | 需自行实现 Agent 路由 |
| **通用** | 将 SKILL.md 作为 Agent 上下文注入 | 所有支持 system prompt 的平台 |

---

## 安全最佳实践 / Security

- Dockerfile 使用**非 root 用户**运行（`appuser`）
- 多阶段构建减小镜像体积
- 生产环境**强制人工审批**（`require_approval: true`）
- Webhook 密钥不在仓库中提交（`alert.yaml` 加入 `.gitignore`）
- 环境配置文件（`env.yaml`）加入 `.gitignore`，仅提交模板
- 定期 OWASP 依赖扫描（Review 阶段）

---

## 踩坑记录 / Lessons Learned

- **Git Bash + Maven**：Windows 下 Git Bash 调用 Maven 可能失败，用 `cmd.exe /c mvn.cmd` 替代
- **JDK 版本**：Maven 3.9+ 需要 JDK 17+，检查 `JAVA_HOME`
- **Docker Desktop**：执行前确保 Docker 已启动
- **Webhook 签名**：钉钉/飞书加签需正确计算 HMAC-SHA256，先在测试环境验证
- **蓝绿部署**：需要反向代理（Nginx/Traefik）做流量切换，纯 docker-compose 无法实现真正的蓝绿
- **告警防刷屏**：同一事件在 `rate_limit_seconds` 内去重，避免误刷