mxops（Matrix Ops）是一套运行在 AgentTeams 多 Agent 平台上的国产 GPU 集群运维系统。它以「告警 → 诊断 → 修复 → 回归验证」的自动闭环替代人工值守：Manager 统一编排，doctor 基于可核验的知识库诊断根因，deploy 自动执行修复，bench 压测验证恢复。全程在 Matrix 房间内透明可审计，人类可随时查看、干预、审批。
工具链底座 mxdeploy（Apache-2.0）是独立的国产 GPU 一键部署 CLI，本仓库包含的是围绕它构建的多 Agent 运维编排层。
国产 AI 算力（如曦云 C500 等）加速落地，但推理集群的日常运维仍高度依赖人工专家：
- 环境配置碎片化：MACA 工具链、conda、vLLM 适配包、模型下载镜像等依赖项多且分散，一次部署涉及十多个前置条件
- 根因定位难：同类故障（环境变量缺失、显存不足、精度不匹配）在不同实例上表现相似，但排查路径冗长
- 经验难沉淀：工程师踩过的坑记在个人脑子里，换人即失忆，团队无法积累可复用的排障资产
- 7×24 值守成本高：中小团队无力为推理服务配备全天候运维值班
本项目用多 Agent 协作的方式尝试回答一个问题：国产 GPU 运维经验能否被结构化、自动化、可复用？
| 能力 | 说明 | 对应实现 |
|---|---|---|
| 故障自动发现 | 探针每 60s 巡检实例健康状态，故障触发 Prometheus 告警 | monitoring/ + 探针脚本 |
| 告警自动推送 | Alertmanager 将告警推送到 Manager 房间，无需人工转发 | monitoring/alertmanager.yml |
| 根因诊断 | doctor 基于 mxdeploy 规则知识库（14 条，全部来自真实踩坑）匹配日志，输出修复命令 | skills/mxdeploy-ops/SKILL.md |
| 自动修复 | deploy 通过 SSH 在真实实例上执行修复，并做健康检查与冒烟验证 | skills/mxdeploy-ops/SKILL.md |
| 回归验证 | bench 对恢复后的服务做并发压测，产出吞吐/TTFT/P95 报告 | skills/mxdeploy-ops/bench/SKILL.md |
| 人类可干预 | 全链路消息在 Matrix 房间可见，高危动作可审批 | AgentTeams 平台能力 |
Admin (Matrix)
│ 派单 / 审批 / 监督
▼
Manager (openclaw)
│ 任务分解 / 编排 / 汇总
├──► Worker: mxdeploy-doctor (排障专家)
├──► Worker: mxdeploy-deploy (部署专家)
└──► Worker: mxdeploy-bench (评测专家)
│ SSH 远程执行
▼
国产 GPU 实例 (曦云 C500)
│ mxdeploy CLI
▼
vLLM 服务 / 体检报告 / 压测报告 / 诊断结果
| 角色 | 职责 | 关键输入 | 输出 |
|---|---|---|---|
| Manager | 任务分解、派发、结果汇总 | 告警/任务指令 | 闭环汇总报告 |
| mxdeploy-doctor | 日志根因分析 | 日志文本/文件路径 | 命中规则 ID、严重级别、修复命令 |
| mxdeploy-deploy | 部署与修复执行 | 模型名 + 参数 | 启动命令、服务就绪状态 |
| mxdeploy-bench | 并发压测与指标解读 | 服务地址 + 压测参数 | 吞吐/TTFT/P95/TPOT/显存报告 |
以一次真实故障处置为例（2026-08-14 真实记录，来源：Matrix 房间消息时间戳 + SSH 执行日志）：
09:46 探针检测到 vllm_metax 服务停服（端口 8000 无响应）
09:47 Alertmanager 推送告警到 Manager 房间
09:51:29 Manager 派发修复任务给 mxdeploy-deploy
09:52:10 deploy 完成修复（supervisord 托管服务 + 健康检查 200 + 推理通过），耗时 36 秒
09:55 Manager 输出完整闭环汇总
全自动闭环（无人工参与）于同日上午验证：11:08 探针自动告警 → 11:08:50 Manager 自动派发 → 11:15 闭环汇总，全程零人工干预。
上述为单次验证记录，数据来自真实系统日志；不同故障场景耗时会有差异，详见 docs/human-vs-agent.md。
.
├── docs/
│ ├── architecture.md # 3 Worker 设计文档（角色、技能、创建命令）
│ └── human-vs-agent.md # 人工 vs Agent 排障对比（真实数据）
├── skills/
│ └── mxdeploy-ops/
│ ├── SKILL.md # deploy 角色技能：SSH 执行 + 修复标准流程
│ └── bench/SKILL.md # bench 角色技能：SSH 隧道 + 压测标准流程
├── deploy/
│ ├── worker-entrypoint.sh # worker 容器启动脚本（配置拉取、文件同步、就绪上报）
│ ├── create_workers.sh # 3 个 worker 的创建命令
│ └── gen_worker_configs.py # worker openclaw.json 配置生成器
├── monitoring/
│ ├── prometheus.yml # 指标抓取配置
│ ├── alertmanager.yml # 告警路由到 Matrix 房间
│ └── rules.yml # 告警规则（健康检查失败 → critical）
├── README.md
└── LICENSE # Apache-2.0
| 依赖 | 说明 |
|---|---|
| AgentTeams | Multi-Agent 平台（controller + manager + worker） |
| mxdeploy | 国产 GPU 一键部署 CLI（本项目工具链底座，Apache-2.0） |
| OpenClaw | worker 的 AI 运行时 |
| Docker | 运行 AgentTeams 容器集群 |
- 部署 AgentTeams 平台：启动 controller / manager / worker 容器（参考
deploy/worker-entrypoint.sh的启动与就绪逻辑） - 安装工具链：在可访问 GPU 实例的控制节点安装
mxdeploy（pip install mxdeploy） - 创建 worker：按
deploy/create_workers.sh创建mxdeploy-doctor/mxdeploy-deploy/mxdeploy-bench三个 worker，挂载mxdeploy-ops技能 - 配置实例凭据：在控制节点
/opt/mxops/ssh/<实例名>.env写入实例连接信息（HOST/PORT/SSH_USER/SSH_PASS/AVAILABLE），凭据不进入 worker 代码 - 配置监控：按
monitoring/部署探针（60s 巡检）+ Prometheus + Alertmanager，告警 webhook 指向 Manager 房间 - 验证闭环：向 Manager 发送一条测试告警，观察 诊断 → 修复 → 压测 → 汇总 全流程
- 国产 GPU 平台实例（本项目在曦云 C500 上验证）
- 实例内已具备：MACA 工具链、conda、
torch+metax 适配版、vllm_metax - 非交互 SSH 会话不加载
.bashrc，脚本内需显式export MACA_PATH与export HF_ENDPOINT=https://hf-mirror.com
SSH 凭据不写死在 worker 代码或技能文本中，统一存放于控制节点的 /opt/mxops/ssh/<实例名>.env（HOST/PORT/SSH_USER/SSH_PASS/AVAILABLE）。worker 按实例名读取；AVAILABLE=1 时走真实 SSH 执行，否则回退到模拟执行，并在汇报中明确标注执行方式，避免混淆真实与模拟结果。
- doctor 的诊断依据是 mxdeploy 的规则知识库：14 条故障规则（DEP/ENV/MEM/MISC/NET/PREC 分类），全部来自国产 GPU 真实踩坑记录，随 mxdeploy 开源，每条可核验
- 每次新故障处置中发现的未知问题，可沉淀为新规则回写知识库（本项目在验证过程中已发生过一次：处置中现场发现并沉淀 MACA_CLANG_PATH 相关坑）
- 效果：首次处置需要现场摸坑（约 10 分钟），知识库命中后同类故障处置可缩短到数十秒
无真实实例可用时（如演示环境、资源未就绪），worker 可基于预置故障场景模拟执行，保证闭环流程可演示、可测试；真实实例就绪后无缝切换。汇报中明确区分两种执行方式。
任务输入、拆解、工具调用、验证、审批、结果回写全部发生在 Matrix 房间，消息带时间戳，可作为审计与复盘依据。
以下数据来自真实环境（曦云 C500 vGPU），均为本项目开发过程中的实际执行记录，非合成 benchmark：
| 项 | 数据 | 条件 |
|---|---|---|
| 3B 模型部署吞吐 | 160.99 tokens/s | Qwen2.5-3B-Instruct @ 16G vGPU，并发 8 / 50 请求 / max_tokens 256 |
| 完整闭环（告警→汇总） | 约 9 分钟 | 2026-08-14 真实记录 |
| 知识库命中后单次修复 | 36 秒 | 2026-08-14 真实记录（supervisord 托管 + 健康 200 + 推理通过） |
| 全自动闭环（零人工） | 约 7 分钟 | 2026-08-14 真实记录（11:08 告警 → 11:15 汇总） |
| mxdeploy 测试 | 92 项自动化测试 | 随 mxdeploy 仓库验证（v0.2.2） |
| mxdeploy 知识库 | 14 条规则 | 全部真实踩坑沉淀，随 mxdeploy 开源 |
人工 vs Agent 的详细对比与数据可信度说明见 docs/human-vs-agent.md。
项目在特定环境上验证，以下限制如实说明：
- 环境强依赖：目前仅在曦云 C500（MACA +
vllm_metax）上验证；其他国产 GPU 平台需要重新验证工具链适配 - 模型兼容性：部分社区量化模型（如 GPTQ-Int4 的 GLM 系）缺少
chat_template，需要额外处理；超大模型在 16G vGPU 上受显存限制（如 14B-INT4 需--enforce-eager+ 缩短--max-model-len） - 健康检查语义：
vllm_metax的/health返回 HTTP 200 但 body 为空（content-length: 0），健康检查必须看状态码而非 body——本项目技能已内置该处理 - 非交互 SSH：远程 shell 不加载
.bashrc，所有环境变量需在命令内显式导出（技能中已封装） - 单实例验证：监控告警链路目前针对单实例场景，多实例横向扩展（c500-02/03/04）尚未在真实环境验证
- 知识库覆盖面：14 条规则覆盖本项目实际遇到过的故障；未覆盖的故障仍需要 doctor 结合 LLM 推理，可能给出不确定结论
- mxdeploy — 国产 GPU 一键部署 CLI（init/deploy/bench/doctor），Apache-2.0，本项目的工具链底座与知识库来源