Proxy AIops

Proxy AIops

面向 Traefik、Caddy 和 HAProxy 反向代理 / 负载均衡器的受治理、可审计 AI 运维——供 AI Agent（通过 MCP）和人类（通过 CLI）使用。

免责声明：由社区维护的开源项目。与 Traefik Labs、Caddy 项目、HAProxy Technologies 或 HAProxy 项目均无关联，也未获其认可或赞助。 Traefik、Caddy 和 HAProxy 均为其各自所有者的商标。采用 MIT 许可证。

proxy-aiops 通过一个 MCP 服务连接到三种代理平台——Traefik （其 /api/... 下的 API，以及通过 /metrics 提供的 metrics-text 计数器）、Caddy（管理 API，默认地址为 localhost:2019）和 HAProxy（/v2/... 下的 Data Plane API v2，采用 HTTP Basic auth）——且相同的工具适用于这三者。配置中的每个目标都会指定自己的 platform；按名称索引的平台注册表会选择 API 形态（身份验证 + 资源路径），而明确的支持矩阵会对平台确实无法执行的运维操作给出说明性错误——例如，Traefik 写入操作会提示你使用其 providers（文件、容器标签、编排器 CRD），绝不会静默空操作。

每个工具都会通过一个内置治理机制运行（随附 vendored 代码，不依赖外部依赖项）：审计日志、令牌 / 调用预算及失控断路器、描述性风险等级标记、撤销令牌记录，以及输出净化。

为什么要做这个项目

• 一个服务，三种代理——Traefik、Caddy 和 HAProxy，可用于混合边缘环境，并通过相同的工具名称进行操作。以后添加其他代理只需新增平台描述符，无需重写。
• 读取整个边缘环境——版本、入口点 / 监听器、路由（routers / caddy routes / frontends），并解析主机和路径；服务和服务器级上游健康状态、中间件、TLS 域名清单、流量 / 错误计数器，以及实时配置树（快照 + 搜索）。
• 旗舰级 RCA 分析——透明启发式分析，展示所依据的数据，绝不提供黑箱判定：backend_health_rca（上游故障 → 原因类别 L4/L6/L7/DNS/维护 + 操作建议）、cert_expiry_sweep（按到期剩余天数分桶 + 各平台续期提示）、error_rate_rca（5xx 占比与整个集群的基线对比，主导错误码 → 502/503/504/500 原因），以及 route_conflict_analysis（被遮蔽的路由、无效路由、重定向循环）。
• 受治理的写入操作——Caddy 配置的 set / delete / 完整 load（会先获取原有子树 / 配置，以便记录的撤销操作能够真正还原）和 HAProxy 运行时服务器的 state（ready/drain/maint）及 weight（撤销时恢复先前的值）——所有操作均支持 dry_run 预览；delete / load 属于高风险操作，在 CLI 中需要双重确认。

此工具会做什么，以及不会决定什么

它会准确、高效地执行代理运维操作——读取和写入——并记录每一项操作。它不会决定是否允许执行写入操作。那取决于 Agent 的判断，或你所连接账户的权限：为 HAProxy Data Plane API 分配只读角色，或缩小你所指向的 Traefik / Caddy 管理 API 的权限范围，那么写入操作就会在服务器端失败——因为权限由服务器实际管理。

因此，无需配置只读开关、策略文件或审批关卡。此工具唯一保证的是绝不会静默操作：通过 MCP 或 CLI 执行的每次调用，都会在 ~/.proxy-aiops/audit.db 中生成一条审计记录，可撤销的写入操作也仍会捕获操作前状态并记录反向操作。

每个工具都会声明一个 risk_level，测试会确保它与工具文档中的 [READ] / [WRITE] 标签一致；该等级还会作为描述性层级写入审计记录，因此审查人员可以一眼看出某条记录属于高风险删除操作。它只是一个标签，不是关卡。

正在运行较小型 / 本地模型？请参阅 agent-guardrails.md——其中列出了此工具现在会为你强制执行的防护规则（因此你无需在提示词预算中重复说明），并提供了适用于剩余事项的现成系统提示词。

工具清单（28 个）

领域	工具	#	类型
状态	proxy_overview、version_info、list_entrypoints	3	读取
路由	list_routes、route_detail、find_route	3	读取
服务	list_services、service_detail、list_upstreams、upstream_detail、list_middlewares	5	读取
证书	list_certificates	1	读取
流量	traffic_stats、error_counters	2	读取
配置	config_snapshot、search_config、get_config_value	3	读取
旗舰分析	backend_health_rca、cert_expiry_sweep、error_rate_rca、route_conflict_analysis	4	读取
写入（caddy）	set_config_value	1	写入（中）
写入（caddy）	delete_config_path、load_config	2	写入（高）
写入（haproxy）	set_server_state、set_server_weight	2	写入（中）
撤销	undo_list、undo_apply	2	读取 / 写入

可逆写入会记录一个反向 撤销描述符，该描述符根据实际获取的操作前状态构建（set_config_value 会恢复先前的子树；delete_config_path 会重新创建该子树；load_config 会重新加载已快照的配置；服务器状态/权重会恢复先前的值）。撤销参数与各工具自身的签名一致，因此描述符可以原样重放。

各平台支持矩阵

功能	traefik	caddy	haproxy
路由 / 服务 / 上游健康状况	✅	✅	✅
中间件列表	✅	教学提示（内联处理程序）	教学提示（haproxy.cfg）
TLS 证书清单 + 到期扫描	✅	✅	教学提示（.pem 文件）
错误计数器 / 错误率根因分析	✅（/metrics）	教学提示（无按路由统计的计数器）	✅（stats）
配置快照 / 搜索	✅（rawdata，只读）	✅	教学提示
配置写入	教学错误 → 编辑 provider	✅（写入接口）	教学错误 → 运行时写入
运行时服务器状态 / 权重	教学错误 → provider	教学错误 → 配置树	✅

不支持的组合会 引发教学错误，说明应改用什么，而不会静默返回空结果。

安装

uv tool install proxy-aiops        # or: pipx install proxy-aiops

快速开始

作为 Claude Code 插件

一次安装即可为 Agent 同时提供技能和 MCP 服务：

/plugin marketplace add AIops-tools/marketplace
/plugin install proxy-aiops@aiops-tools

MCP 服务通过 uv 获取，并固定到此插件声明的软件包版本，因此可以追溯审计记录是由哪段代码写入的。凭据仍通过 proxy-aiops init 配置——请参见下文。

作为 OpenClaw 插件

同一套插件也发布在 ClawHub，安装一次即可同时获取技能和 MCP 服务：

openclaw plugins install clawhub:@zw008/proxy-aiops
openclaw skills info proxy-aiops          # expect: Visible to model: yes

之后请重启 OpenClaw 网关，使其加载插件。MCP 服务通过 uv 获取，并固定到此确切发行版本，因此 uvx 必须位于 PATH 中——若缺少它，技能仍会安装，但会报告 Visible to model: no。凭据按下文说明配置。

作为 CLI 或独立 MCP 服务

proxy-aiops init                     # wizard: pick platform (traefik/caddy/haproxy) + optional encrypted secret
proxy-aiops doctor                   # verify config, secrets, and connectivity
proxy-aiops overview                 # one-shot: version + route/service counts + upstream health
proxy-aiops routes list              # normalised route table
proxy-aiops services upstreams       # server-level upstream health
proxy-aiops analyze health           # backend/upstream health RCA
proxy-aiops analyze errors           # 5xx error-rate RCA
proxy-aiops analyze conflicts        # shadowed/dead routes, redirect loops
proxy-aiops certs --sweep            # TLS cert expiry sweep (traefik/caddy)
proxy-aiops server state app web1 drain --dry-run   # governed haproxy write preview
proxy-aiops config set apps/http/servers/srv0 '{"listen":[":8080"]}' --dry-run

为 Agent 运行 MCP 服务（stdio）：

proxy-aiops mcp                      # or: proxy-aiops-mcp

MCP 客户端配置

{
  "mcpServers": {
    "proxy-aiops": {
      "command": "uvx",
      "args": ["--from", "proxy-aiops", "proxy-aiops-mcp"],
      "env": { "PROXY_AIOPS_MASTER_PASSWORD": "your-master-password" }
    }
  }
}

环境变量块注意事项：仅在存储了凭据时才需要 env 块（haproxy 始终需要；traefik/caddy 仅在 Basic 身份验证后面时需要）。MCP 客户端不会继承你的 shell 配置文件——请在客户端配置中显式设置 PROXY_AIOPS_MASTER_PASSWORD（如果迁移了 PROXY_AIOPS_CONFIG / PROXY_AIOPS_HOME，也请设置它们），否则服务无法解锁 secrets.enc。

配置

~/.proxy-aiops/config.yaml（仅包含非机密连接详情）：

targets:
  - name: edge1
    platform: traefik        # traefik | caddy | haproxy
    base_url: http://192.0.2.10:8080
    verify_ssl: true
  - name: caddy1
    platform: caddy
    base_url: http://127.0.0.1:2019
  - name: lb1
    platform: haproxy
    base_url: http://192.0.2.20:5555
    username: dpapi          # Data Plane API user

机密信息——HAProxy Data Plane API 密码，或 Traefik/Caddy 前端可选的 Basic-auth 密码——以加密形式存储在 ~/.proxy-aiops/secrets.enc 中（Fernet + scrypt 派生密钥），绝不会以明文形式 存储在磁盘上。Traefik 和 Caddy 通常在 localhost 上不启用身份验证，因此它们的 机密信息是可选的（类似本地套接字）；HAProxy 的则是必需的。使用 proxy-aiops secret set <target> 或 init 向导设置。通过 PROXY_AIOPS_MASTER_PASSWORD（非交互式/MCP/CI）提供主密码以解锁存储，或者 在交互式提示中输入（TTY 上的 CLI）。旧版明文环境变量 PROXY_<TARGET>_SECRET 也可作为回退方式使用（使用 proxy-aiops secret migrate 迁移）。

治理

每个 MCP 工具——以及通过相同受治理函数调用的每次 CLI 写入——都会经过 @governed_tool。它负责记录，不负责授权 （见上文）。

• 审计——每次调用都会记录到 ~/.proxy-aiops/audit.db（工具、已脱敏的 参数、状态、持续时间、风险级别，以及操作员提供的审批人/理由）。CLI 写入的 记录与 MCP 路径相同——不存在未经审计的入口。
• 预算 / 失控防护——这是安全后备机制，而非授权关卡： 每个进程的令牌/调用上限和重复调用断路器可防止失控的 Agent 无限制地消耗调用/ 时间（PROXY_MAX_TOOL_CALLS、PROXY_RUNAWAY_MAX、 …；设置 PROXY_RUNAWAY_MAX=0 可禁用断路器）。
• 撤销记录——可逆写入会根据获取的操作前状态，将反向操作描述符记录到 ~/.proxy-aiops/undo.db（仅记录；由外部编排器执行）。撤销参数与目标工具自身 的签名一致，因此描述符可直接重放。
• 风险级别——审计记录中根据 risk_level 派生的描述性标签； 不执行任何门控。
• 清理——所有代理返回的文本在传递给 Agent 之前，都会进行长度限制并清理 控制字符。

平台支持与验证状态

• 平台：Traefik（API + /metrics）、Caddy（管理 API）、HAProxy（Data Plane API v2）。
• 测试覆盖率：通过模拟的 JSON/metrics 响应验证行为——每个模块都能导入， 每个 MCP 工具都带有治理标记，四项旗舰分析都通过合成遥测数据进行单元测试， 支持矩阵经过断言，会引发说明性错误（绝不会静默无操作），并且可逆写入经过断言， 会记录正确的反向撤销描述符。具体 REST 路径根据各项目的公开 API 建模，尚未 在实际运行的代理上测试。请参阅 docs/VERIFICATION.md，了解实际运行必须满足的检查清单。 这三个平台均免费且可自托管（使用 traefik + caddy + haproxy/dataplaneapi 搭建小型容器编排实验环境，一个晚上即可完成）；proxy-aiops doctor——针对 每个平台的健康状况/信息探测工具——是最快的实际运行检查方式。
• 路由说明：此工具用于反向代理/负载均衡器。请勿将其用于防火墙规则—— 请使用 firewall-aiops。
• **缺少某项功能？**请在 github.com/AIops-tools/Proxy-AIops 提交 issue 或 PR——欢迎贡献和反馈。

许可证

MIT——参见 LICENSE。