Container Host AIops

Container Host AIops

免责声明：由社区维护的开源项目。与 Docker, Inc.、Portainer.io 或任何容器平台供应商均无关联，也未获得其认可或赞助。“Docker”、“Portainer”及所有产品／商标名称均归其各自所有者所有。采用 MIT 许可。

面向非编排器容器主机的治理型 AI 运维——包括 Docker Engine API（通过本地 unix 套接字或 TCP 主机）、Portainer（其管理 API，也可代理 Docker）和 Podman（通过 rootful/rootless 服务套接字提供 Docker 兼容 API 及 libpod 原生端点）——并内置治理机制：统一记录 MCP 和 CLI 的审计日志、失控／预算安全防护，以及撤销令牌记录。它会记录每项操作；但不会决定是否允许写入——这由 Agent 或账户决定。从设计上支持多平台：以 platform 为键的注册表意味着，每个目标的 platform 字段（docker / portainer / podman）会选择对应的 API 形式；以后也可以添加其他主机类型，无需改动 ops/CLI/MCP 层。已在运行中的 Docker Engine 27.5.1 守护进程上进行测试（doctor、overview、三项旗舰分析，以及记录了审计和撤销信息的受治理 stop_container）；Portainer 和 Podman API 路径仅由模拟测试套件覆盖。

功能

三项旗舰特色分析，以及围绕它们提供的受保护读取和写入操作：

• 重启循环根因分析 — 检查容器的重启次数和退出码，标记陷入崩溃循环的容器（restartCount 超过阈值，或处于 restarting/dead 状态，或退出码非零），并根据退出码为每个容器匹配可能原因及处理措施（137 OOM/SIGKILL、143 SIGTERM、139 段错误、127 入口点错误，……），同时附上日志末尾内容。每项排序结果都包含具体数据，而非黑箱结论。
• 资源压力分析 — 对每个运行中的容器采集一次 CPU%／内存% 样本，并与其配置限制进行比较；标记每项是“接近”（≥ 阈值的 80%）还是“超出”，并给出建议（提高限制、设置缺失的内存限制、横向扩展）。
• 镜像和卷膨胀分析 — 汇总 system/df 中的悬空镜像、悬空卷和构建缓存，列为可清理对象并统计可回收字节数。

支持的功能

• CLI（container-host-aiops ...）：init、overview、container、image、volume、network、system、stack、pod、analyze、manage、secret、doctor、mcp。
• MCP 服务（container-host-aiops mcp 或 container-host-aiops-mcp）：38 个工具（29 个只读，9 个写入），每个工具都由内置的 @governed_tool 机制封装。
• 连接层：Docker 可通过 unix 套接字（httpx.HTTPTransport(uds=...)）或 TCP 主机连接；Portainer 通过 HTTPS 连接，使用 X-API-Key 令牌，该令牌还可代理受管理端点的 Docker API；Podman 通过其 rootful/rootless 服务套接字连接（自动检测：先查找 $XDG_RUNTIME_DIR/podman/podman.sock，再查找 /run/podman/podman.sock），使用 Docker 兼容层（完整复用路径）及 libpod 原生端点。本地 Docker/Podman 套接字无需密钥——套接字的文件权限就是安全边界。
• 加密凭据：Portainer API 令牌保存在加密存储 ~/.container-host-aiops/secrets.enc 中（Fernet + scrypt）——绝不会以明文形式存储在磁盘上。通过 CONTAINER_HOST_AIOPS_MASTER_PASSWORD 提供主密码解锁（MCP/CI），或通过交互式提示输入（CLI）。
• 可逆性：执行变更的写入操作前，会先获取真实的变更前状态，并记录准确的逆向操作（stop↔start；update_container 会恢复先前的 CPU／内存限制）。不可逆操作（remove_container、prune_images、prune_volumes、recreate_stack）会记录变更前状态以供审计，但不会声明可撤销操作。
• 安全性：每个会改变状态的 CLI 操作都支持 --dry-run，并要求二次确认；每个写入型 MCP 工具都接受 dry_run 预览参数——清理预览会列出将要删除的内容及可回收字节数，之后才会执行。

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

它能够准确、高效地执行容器主机操作——读取和写入——并记录每一项操作。它不会决定是否允许执行写入操作。是否执行由 Agent 判断，或由你连接的账户权限决定：如果连接的是以只读方式挂载的 Docker socket，或没有写入权限的 Portainer 账户，写入操作就会在服务端失败——因为权限由服务端实际管理。

因此，无需配置只读开关、策略文件或审批关卡。此工具唯一能保证的是，不会有任何操作悄无声息：每次调用，无论通过 MCP 还是命令行，都会写入一条审计记录，保存至 ~/.container-host-aiops/audit.db；破坏性写入仍会捕获操作前状态，并在存在逆向操作时记录该操作。

每个工具都会声明一个 risk_level，并通过测试确保它与 [READ]／[WRITE] 文档标签一致；该级别也会作为描述性等级写入审计记录，因此审核者可以一眼看出某条记录对应高风险删除操作。它只是一个标签，不是关卡。

功能矩阵（38 个 MCP 工具）

领域	工具	数量	读／写
概览	overview	1	读取
容器	list_containers、inspect_container、container_logs、container_stats、container_top、container_restart_summary	6	读取
镜像	list_images、inspect_image、dangling_images、image_disk_usage	4	读取
卷	list_volumes、inspect_volume、dangling_volumes	3	读取
网络	list_networks、inspect_network	2	读取
系统	system_info、system_version、system_df、system_events	4	读取
堆栈	list_endpoints、list_stacks、stack_detail（Portainer）、list_compose_stacks（docker+podman）	4	读取
Pod（Podman）	list_pods	1	读取
分析（旗舰功能）	restart_loop_rca、resource_pressure_analysis、image_and_volume_bloat	3	读取
写入	remove_container、prune_images、prune_volumes、recreate_stack	4	写入（高）
	restart_container、stop_container、start_container、update_container	4	写入（中）

三种分析既可接受注入数据以进行离线分析，也可从已配置的目标获取实时数据。list_endpoints／list_stacks／stack_detail 需要 portainer 目标；list_compose_stacks（按 com.docker.compose.project 标签汇总 Compose 项目，并提供每个堆栈的健康状态）适用于 docker 或 podman；list_pods 需要 podman 目标（Docker／Portainer 没有 Pod 概念）。

平台支持矩阵

功能	docker	portainer	podman
容器／镜像／卷／网络／系统读取	✅	✅（代理）	✅（兼容）
旗舰分析（重启循环根因分析、资源压力、膨胀分析）	✅	✅	✅（兼容）
生命周期与清理写入（停止／启动／重启／移除／更新／清理）	✅	✅	✅（兼容）
Compose 堆栈汇总（list_compose_stacks）	✅	✅（代理）	✅
Portainer 端点／堆栈／recreate_stack	—	✅	—
Podman Pod（list_pods、libpod）	—	—	✅

快速开始

作为 Claude Code 插件

安装一次，即可让 Agent 同时获得技能和 MCP 服务：

/plugin marketplace add AIops-tools/marketplace
/plugin install container-host-aiops@aiops-tools

MCP 服务通过 uv 获取，并固定为此插件声明的软件包版本，因此可以将审计记录追溯到生成该记录的代码。凭据仍需通过 container-host-aiops init 配置——详见下文。

作为 OpenClaw 插件

同一套软件包也发布在 ClawHub 上，一次 安装即可同时安装技能及其 MCP 服务：

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

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

作为 CLI 或独立 MCP 服务

uv tool install container-host-aiops          # or: pipx install container-host-aiops
container-host-aiops init                      # wizard: add a Docker/Podman socket or Portainer target
container-host-aiops doctor                    # verify config, secrets, connectivity
container-host-aiops overview                  # one-shot host health
container-host-aiops analyze restart-loop      # crash-looping containers + cause/action
container-host-aiops container list --running  # running containers

作为 MCP 服务运行（stdio）：

export CONTAINER_HOST_AIOPS_MASTER_PASSWORD=...   # only needed for Portainer targets
container-host-aiops-mcp

之后密码会存在哪里：导出的变量可被此 shell 启动的 每个进程读取，也会记录在 shell 历史记录中。在 共享或长期运行的主机上，建议使用交互式提示，或在 需要该密码的单条命令运行期间，从密钥管理器注入密码。

治理

每项操作——无论通过 MCP 还是 CLI——都经过内置的 @governed_tool 框架。它负责记录，不负责授权（见上文）。

• 审计 — 每次调用（参数、结果、状态、耗时、风险等级，以及操作员提供的任何审批人／理由）都会记录到 ~/.container-host-aiops/audit.db（可通过 CONTAINER_HOST_AIOPS_HOME 更改位置）。CLI 写入的记录与 MCP 路径相同——不存在未经审计的入口。
• 失控保护 — 这是安全后备机制，不是授权关卡：如果在紧密循环中反复触发相同调用，就会触发断路器，避免卡住的 Agent 无限制地消耗调用次数／时间。可通过 CONTAINER_HOST_RUNAWAY_MAX=0 禁用；还可选择设置硬性上限 CONTAINER_HOST_MAX_TOOL_CALLS／CONTAINER_HOST_MAX_TOOL_SECONDS。
• 撤销记录 — 对可逆写入操作，会根据获取的操作前状态记录逆向描述符。
• 风险等级 — 根据 risk_level 得出的描述性标签，记录在审计记录中；不用于限制任何操作。

范围

这是 AIops-tools 系列（带审计、预算和撤销功能的受治理 AI 运维工具）中的 container-host 成员，适用于单主机 Docker / Portainer / Podman。它刻意不适用于集群编排器、虚拟机管理程序、存储设备、备份产品或 OT／工业边缘场景——这些由其他工具／产品线负责。

缺少某项功能？

本工具有意只精选覆盖 Docker Engine + Portainer + Podman（libpod）API 的一部分。缺少某项调用，或想支持其他容器主机系列？请提交 issue 或 PR——欢迎贡献。

验证状态

• Docker — 已通过真实运行中的 Docker Engine 27.5.1 守护进程进行测试：doctor 和 overview 通过本地套接字连接；restart-loop 和镜像／卷的 bloat 分析已针对真实的崩溃循环容器和真实的可回收数据运行；受治理的 stop_container 已写入审计数据库记录，并记录了有效的撤销描述符。
• Portainer 和 Podman — 仅通过模拟验证。这些 API 路径根据 各项目的公开 API 结构建模，尚未在真实运行的服务上进行测试。
• 完整清单——模拟测试套件保证的内容、Docker 测试已满足的要求，以及 Portainer／Podman 测试仍需验证的内容——见 docs/VERIFICATION.md。container-host-aiops doctor 是在任何平台上进行实时检查的最快方式。