Skip to content

devops-system.md

Latest commit

 

History

History
643 lines (483 loc) · 15.3 KB

devops-system.md

File metadata and controls

643 lines (483 loc) · 15.3 KB
Raw

DevOps 系统 - @devops 代理完整指南

代理： Gage (运维者) 版本： 2.0.0 最后更新： 2026-02-04

目录

  1. 概述
  2. 完整文件列表
  3. 流程图：完整系统
  4. 命令到任务的映射
  5. 代理之间的集成
  6. 配置
  7. 最佳实践
  8. 故障排除
  9. 参考
  10. 摘要

概述

@devops (Gage) 代理是 AIOX 框架的基础设施和运维专家。负责：

  • MCP 治理：MCP（模型上下文协议）服务器的独家管理
  • CI/CD：持续集成和交付管道的配置和维护
  • 发布：版本管理和发布发布
  • 仓库：维护、清理和代码质量
  • 安全：安全审计和扫描
  • 环境：新项目引导和环境配置

角色

名称: Gage
角色: 运维者
专业: DevOps、基础设施、CI/CD、MCP
理念: "自动化一切可以自动化的"

关键规则

重要： 所有 MCP 基础设施操作由 DevOps 代理独家管理。其他代理（Dev、Architect 等）是 MCP 的消费者，而非管理员。

完整文件列表

代理文件

文件 路径 描述
代理定义 .aiox-core/development/agents/devops.md 角色、命令和行为

任务文件

任务 路径 命令
推送前质量门禁 .aiox-core/development/tasks/github-devops-pre-push-quality-gate.md *push
版本管理 .aiox-core/development/tasks/github-devops-version-management.md *version-check
仓库清理 .aiox-core/development/tasks/github-devops-repository-cleanup.md *cleanup
CI/CD 配置 .aiox-core/development/tasks/ci-cd-configuration.md *ci-cd
发布管理 .aiox-core/development/tasks/release-management.md *release
环境引导 .aiox-core/development/tasks/environment-bootstrap.md *environment-bootstrap
搜索 MCP .aiox-core/development/tasks/search-mcp.md *search-mcp
添加 MCP .aiox-core/development/tasks/add-mcp.md *add-mcp
设置 MCP Docker .aiox-core/development/tasks/setup-mcp-docker.md *setup-mcp-docker
设置 GitHub .aiox-core/development/tasks/setup-github.md *setup-github
安全审计 .aiox-core/development/tasks/security-audit.md *security-audit
安全扫描 .aiox-core/development/tasks/security-scan.md *security-scan

配置和规则文件

文件 路径 目的
MCP 规则 .claude/rules/mcp-usage.md MCP 治理和使用
N8N 规则 .claude/rules/n8n-operations.md N8N 基础设施操作

流程图：完整系统

DevOps 整体架构

flowchart TB
    subgraph "DevOps 代理 (Gage)"
        A[/"@devops"/]
    end

    subgraph "MCP 管理"
        MCP1["*search-mcp"]
        MCP2["*add-mcp"]
        MCP3["*list-mcps"]
        MCP4["*remove-mcp"]
        MCP5["*setup-mcp-docker"]
    end

    subgraph "Git/GitHub 操作"
        GIT1["*push"]
        GIT2["*setup-github"]
        GIT3["*cleanup"]
    end

    subgraph "CI/CD 和发布"
        CI1["*ci-cd"]
        CI2["*release"]
        CI3["*version-check"]
    end

    subgraph "安全"
        SEC1["*security-scan"]
        SEC2["*security-audit"]
    end

    subgraph "环境"
        ENV1["*environment-bootstrap"]
    end

    A --> MCP1 & MCP2 & MCP3 & MCP4 & MCP5
    A --> GIT1 & GIT2 & GIT3
    A --> CI1 & CI2 & CI3
    A --> SEC1 & SEC2
    A --> ENV1
Loading

推送前质量门禁流程

flowchart TD
    START[/"*push"/] --> LINT["执行 Lint"]
    LINT --> LINT_OK{通过？}
    LINT_OK -->|是| TEST["执行测试"]
    LINT_OK -->|否| FIX_LINT["修复 Lint 错误"]
    FIX_LINT --> LINT

    TEST --> TEST_OK{通过？}
    TEST_OK -->|是| TYPE["检查类型"]
    TEST_OK -->|否| FIX_TEST["修复测试"]
    FIX_TEST --> TEST

    TYPE --> TYPE_OK{通过？}
    TYPE_OK -->|是| BUILD["验证构建"]
    TYPE_OK -->|否| FIX_TYPE["修复类型"]
    FIX_TYPE --> TYPE

    BUILD --> BUILD_OK{通过？}
    BUILD_OK -->|是| PUSH["git push"]
    BUILD_OK -->|否| FIX_BUILD["修复构建"]
    FIX_BUILD --> BUILD

    PUSH --> SUCCESS[/"推送完成"/]
Loading

发布管理流程

flowchart TD
    START[/"*release"/] --> ANALYZE["分析提交"]
    ANALYZE --> BUMP["确定版本号"]

    BUMP --> MAJOR{Major？}
    MAJOR -->|是| V_MAJOR["X.0.0"]
    MAJOR -->|否| MINOR{Minor？}
    MINOR -->|是| V_MINOR["x.Y.0"]
    MINOR -->|否| V_PATCH["x.y.Z"]

    V_MAJOR & V_MINOR & V_PATCH --> CHANGELOG["生成 CHANGELOG"]
    CHANGELOG --> TAG["创建 Git Tag"]
    TAG --> RELEASE["创建 GitHub Release"]
    RELEASE --> NOTIFY["通知团队"]
    NOTIFY --> END[/"发布已发布"/]
Loading

MCP 治理流程

flowchart TD
    subgraph "搜索和选择"
        SEARCH[/"*search-mcp"/] --> CATALOG["查询目录"]
        CATALOG --> FILTER["按类别过滤"]
        FILTER --> SELECT["选择 MCP"]
    end

    subgraph "安装"
        SELECT --> ADD[/"*add-mcp"/]
        ADD --> SCOPE{"范围？"}
        SCOPE -->|用户| GLOBAL["~/.claude.json"]
        SCOPE -->|项目| PROJECT[".mcp.json"]
        SCOPE -->|本地| LOCAL["settings.local.json"]
    end

    subgraph "Docker 配置"
        ADD --> DOCKER{Docker MCP？}
        DOCKER -->|是| SETUP[/"*setup-mcp-docker"/]
        SETUP --> TOOLKIT["Docker MCP Toolkit"]
        TOOLKIT --> SECRETS["配置 Secrets"]
    end

    GLOBAL & PROJECT & LOCAL --> VALIDATE["验证安装"]
    SECRETS --> VALIDATE
    VALIDATE --> READY[/"MCP 就绪"/]
Loading

CI/CD 配置流程

flowchart TD
    START[/"*ci-cd"/] --> DETECT["检测平台"]

    DETECT --> PLATFORM{平台？}
    PLATFORM -->|GitHub| GHA["GitHub Actions"]
    PLATFORM -->|GitLab| GLC["GitLab CI"]
    PLATFORM -->|CircleCI| CCI["CircleCI"]

    GHA --> CONFIG_GHA["生成 .github/workflows/"]
    GLC --> CONFIG_GLC["生成 .gitlab-ci.yml"]
    CCI --> CONFIG_CCI["生成 .circleci/config.yml"]

    CONFIG_GHA & CONFIG_GLC & CONFIG_CCI --> STAGES["配置阶段"]

    STAGES --> LINT_STAGE["阶段：Lint"]
    STAGES --> TEST_STAGE["阶段：Test"]
    STAGES --> BUILD_STAGE["阶段：Build"]
    STAGES --> DEPLOY_STAGE["阶段：Deploy"]

    LINT_STAGE & TEST_STAGE & BUILD_STAGE & DEPLOY_STAGE --> CODERABBIT["集成 CodeRabbit"]
    CODERABBIT --> COMMIT["提交配置"]
    COMMIT --> END[/"CI/CD 已配置"/]
Loading

环境引导流程

flowchart TD
    START[/"*environment-bootstrap"/] --> ELICIT["收集信息"]

    ELICIT --> Q1["项目名称？"]
    Q1 --> Q2["技术栈？"]
    Q2 --> Q3["项目类型？"]

    Q3 --> INSTALL["安装 CLI 工具"]
    INSTALL --> CLI1["Node.js/npm"]
    INSTALL --> CLI2["GitHub CLI"]
    INSTALL --> CLI3["Docker"]

    CLI1 & CLI2 & CLI3 --> GIT_SETUP["配置 Git"]
    GIT_SETUP --> REPO["创建仓库"]
    REPO --> STRUCTURE["创建结构"]

    STRUCTURE --> DIR1["apps/"]
    STRUCTURE --> DIR2["packages/"]
    STRUCTURE --> DIR3["docs/"]
    STRUCTURE --> DIR4[".aiox-core/"]

    DIR1 & DIR2 & DIR3 & DIR4 --> TEMPLATES["应用模板"]
    TEMPLATES --> DEPS["安装依赖"]
    DEPS --> VALIDATE["验证设置"]
    VALIDATE --> END[/"环境就绪"/]
Loading

命令到任务的映射

MCP 命令

命令 任务 描述 模式
*search-mcp search-mcp.md 在目录中搜索 MCP 交互式
*add-mcp add-mcp.md 安装 MCP 服务器 交互式
*list-mcps (内联) 列出已启用的 MCP YOLO
*remove-mcp (内联) 移除 MCP 服务器 交互式
*setup-mcp-docker setup-mcp-docker.md 配置 Docker MCP Toolkit 交互式

Git/GitHub 命令

命令 任务 描述 模式
*push github-devops-pre-push-quality-gate.md 推送前质量门禁 交互式
*setup-github setup-github.md 配置 GitHub 仓库 交互式
*cleanup github-devops-repository-cleanup.md 清理分支和文件 交互式

CI/CD 和发布命令

命令 任务 描述 模式
*ci-cd ci-cd-configuration.md 配置 CI/CD 管道 交互式
*release release-management.md 创建带 changelog 的发布 交互式
*version-check github-devops-version-management.md 分析并建议版本 YOLO

安全命令

命令 任务 描述 模式
*security-scan security-scan.md 漏洞扫描 交互式
*security-audit security-audit.md 完整安全审计 交互式

环境命令

命令 任务 描述 模式
*environment-bootstrap environment-bootstrap.md 新项目引导 交互式

代理之间的集成

集成图

flowchart LR
    subgraph "DevOps (Gage)"
        DEVOPS["@devops"]
    end

    subgraph "开发"
        DEV["@dev"]
        QA["@qa"]
    end

    subgraph "管理"
        PM["@pm"]
        PO["@po"]
        SM["@sm"]
    end

    subgraph "架构"
        ARCH["@architect"]
    end

    DEV -->|"请求 MCP"| DEVOPS
    DEV -->|"触发 *push"| DEVOPS
    QA -->|"请求安全扫描"| DEVOPS
    PM -->|"请求发布"| DEVOPS
    ARCH -->|"定义 CI/CD"| DEVOPS
    DEVOPS -->|"通知部署"| SM
    DEVOPS -->|"报告漏洞"| PO
Loading

责任矩阵

操作 DevOps Dev QA Architect PM
管理 MCP 负责人 消费者 消费者 消费者 -
CI/CD 配置 负责人 审查者 - 批准者 -
发布 负责人 - 验证者 - 请求者
安全扫描 负责人 - 共同负责人 - -
仓库设置 负责人 - - 审查者 -
环境引导 负责人 请求者 - - -

委派流程

  1. Dev 需要 MCP：@dev -> @devops *add-mcp
  2. QA 需要安全：@qa -> @devops *security-scan
  3. PM 请求发布：@pm -> @devops *release
  4. Architect 定义管道：@architect -> @devops *ci-cd

配置

全局 MCP 配置

文件：~/.claude.json

{
  "mcpServers": {
    "context7": {
      "type": "sse",
      "url": "https://mcp.context7.com/sse"
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-playwright"]
    },
    "desktop-commander": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-desktop-commander"]
    }
  }
}

项目配置

文件：.mcp.json

{
  "mcpServers": {
    "project-specific-mcp": {
      "command": "node",
      "args": ["./mcp-server/index.js"]
    }
  }
}

Docker MCP 配置

文件：~/.docker/mcp/catalogs/docker-mcp.yaml

exa:
  env:
    - name: EXA_API_KEY
      value: '你的密钥'

apify:
  env:
    - name: APIFY_TOKEN
      value: '你的令牌'

环境变量

# GitHub
GITHUB_TOKEN=ghp_xxxxxxxxxxxx

# CI/CD
CI_ENVIRONMENT=production

# MCP
MCP_DEBUG=true

最佳实践

MCP 治理

  1. 最小权限原则

    • 测试 MCP 使用 local 范围
    • 共享 MCP 使用 project 范围
    • 个人工具使用 user 范围

  2. 文档

    • 记录添加到项目的所有 MCP
    • 保持 README 更新所需的 MCP

  3. 安全

    • 永不在 .mcp.json 中提交 API 密钥
    • 使用环境变量存储凭据
    • 定期轮换令牌

CI/CD

  1. 管道阶段

    lint -> test -> build -> deploy

  2. 质量门禁

    • 要求 80%+ 测试覆盖率
    • lint 错误时构建失败
    • 集成 CodeRabbit 进行自动代码审查

  3. 发布

    • 使用语义版本控制（SemVer）
    • 自动生成 CHANGELOG
    • 创建签名标签

仓库

  1. 定期清理

    • 每月执行 *cleanup
    • 移除合并超过 30 天的分支
    • 清理临时文件

  2. 分支保护

    • 保护 main 和 develop
    • 合并前要求审查
    • 启用状态检查

安全

  1. 定期扫描

    • 每周执行 *security-scan
    • 使用 npm audit 审计依赖
    • 检查暴露的机密

  2. 漏洞响应

    • 优先处理关键 CVE
    • 记录修复措施
    • 通知利益相关者

故障排除

MCP 问题

MCP 无法连接

# 检查状态
claude mcp list

# 检查日志（如果可用）
tail -f ~/.claude/logs/mcp*.log

# 手动测试服务器
npx -y @package/mcp-server

Docker MCP 没有工具

症状： docker mcp tools ls 显示 "(N prompts)" 而不是 "(N tools)"

原因： Docker MCP Toolkit 的 secrets bug

解决方案：

  1. 编辑 ~/.docker/mcp/catalogs/docker-mcp.yaml
  2. 将模板替换为硬编码值
  3. 重启 MCP 容器

CI/CD 问题

管道无明确原因失败

# 本地验证日志
npm run lint
npm run test
npm run build

# 检查配置
cat .github/workflows/ci.yml

CodeRabbit 不评论

  1. 验证 app 已安装在仓库中
  2. 检查 GitHub App 权限
  3. 检查 .coderabbit.yaml 文件

发布问题

标签已存在

# 检查现有标签
git tag -l

# 删除本地和远程标签（如有必要）
git tag -d v1.0.0
git push origin :refs/tags/v1.0.0

CHANGELOG 未生成

  1. 检查提交格式（Conventional Commits）
  2. 检查自上次发布是否有提交
  3. 手动执行：npx conventional-changelog

安全扫描问题

npm audit 失败

# 强制解决
npm audit fix --force

# 忽略特定漏洞（谨慎使用）
npm audit --ignore-advisories=ADVISORY_ID

参考

AIOX 文档

外部文档

相关任务

任务 描述
推送前质量门禁 推送前验证
版本管理 版本管理
CI/CD 配置 管道配置
发布管理 发布管理
环境引导 环境引导

摘要

方面 详情
代理 Gage (运维者)
激活 @devops
命令总数 14
任务总数 12
作用领域 MCP、CI/CD、发布、安全、仓库
主要规则 MCP 基础设施独家治理
默认模式 交互式
版本 2.0.0

快速命令

# MCP
@devops *search-mcp "browser automation"
@devops *add-mcp playwright -s user

# Git/GitHub
@devops *push
@devops *cleanup

# CI/CD
@devops *ci-cd github-actions
@devops *release minor

# 安全
@devops *security-scan

文档由 AIOX 系统生成 - 2026-02-04 维护者：@devops