Ceph AIops

Ceph AIops

免责声明：由社区维护的开源项目。**与 Ceph 项目或任何存储供应商均无关联、未获其认可，也未受其赞助。**产品名称和商标名称均归其所有者所有。采用 MIT 许可证。

面向 Ceph 的治理型 AI 运维工具——通过 内置治理框架，与原生 ceph-mgr Dashboard REST API 通信（HTTPS :8443，使用用户名和密码交换短时有效的 JWT，调用 POST /api/auth）：统一审计日志、令牌／失控预算防护、撤销令牌记录，以及描述性风险等级。可用于原生 ceph-mgr——cephadm、虚拟机管理程序捆绑的 Ceph 或 MicroCeph——无需依赖 croit 或 Kubernetes。独立运行：不依赖外部技能系列。

功能

旗舰级分析，以及与之配套的受保护读取和写入操作：

• cluster_health — HEALTH_WARN/ERR 根因分析。 不只是复述原始检查代码（PG_DEGRADED、OSD_NEARFULL、SLOW_OPS、MON_DOWN、LARGE_OMAP_OBJECTS……），而是将每项活动检查转换为通俗易懂的说明：含义、可能的原因和建议的后续操作。这正是它与只代理 ceph -s 的业余 Ceph MCP 工具的区别。
• 受治理的破坏性操作。 运维人员最担心的操作——osd_purge、pool_delete、set_pool_size、rbd_image_delete——都带有 dry-run + 二次确认，并归为 high 风险等级；可逆的调优操作（osd_reweight、throttle_recovery、cluster_flag_set、池配额／pg_num／自动伸缩）会记录撤销描述符，保存操作前的状态。

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

它能够准确、高效地执行 Ceph 运维读取和写入操作，并记录每一项操作。它不会决定是否允许执行写入操作。这由 Agent 自行判断，或取决于你用于连接的账户权限：为其提供具有只读角色的 ceph-mgr Dashboard 账户，写入操作就会在 mgr 处失败——权限实际由 mgr 管理。

因此，无需配置只读开关、策略文件或审批门禁。此工具唯一保证的是不会有任何操作悄然发生：无论通过 MCP 还是 CLI 发起，每次调用都会在 ~/.ceph-aiops/audit.db 中生成一条审计记录；破坏性写入仍会捕获操作前的状态，并在存在逆向操作时予以记录。

每个工具都会声明 risk_level；测试会确保它与 [READ]／[WRITE] 文档标签一致，并将其作为描述性等级写入审计记录——审核者可以一眼看出某条记录对应的是高风险删除操作。它只是一个标签，并非门禁。

支持的功能

• CLI（ceph-aiops ...）：init、overview、health detail／health status、osd tree/df/reweight/out/purge、secret set/list/rm/migrate/rotate-password、doctor、mcp。osd out 和 osd purge 需要 --dry-run + 二次确认。
• MCP 服务（ceph-aiops mcp 或 ceph-aiops-mcp）：完整的 37 个工具（17 个读取工具、18 个写入工具、2 个撤销工具），每个工具均由内置的 @governed_tool 框架封装。CLI 仅提供便捷的部分功能；MCP 提供完整工具集。
• 加密凭据：Dashboard 密码保存在加密存储中 ~/.ceph-aiops/secrets.enc（Fernet + scrypt）——不会以明文形式存储在磁盘上。通过 CEPH_AIOPS_MASTER_PASSWORD（MCP/CI）或交互式提示词（CLI）输入主密码来解锁。
• 可逆性：可逆写入会捕获操作前的状态，并记录逆向操作撤销描述符（例如，osd_reweight → 操作前的权重，set_pool_quota → 操作前的配额，throttle_recovery → 操作前的回填／恢复设置）。
• 安全性：破坏性操作（osd_purge、osd_mark_out、pool_delete、set_pool_size、rbd_image_delete、rbd_snapshot_delete）均属于 high 风险，执行时需要 dry_run 和 CLI 二次确认。

能力矩阵（37 个 MCP 工具）

分组	工具	数量	读/写
健康状况	cluster_health（旗舰级 RCA）、cluster_status	2	读取
OSD	osd_tree、osd_df、osd_perf	3	读取
	cluster_flag_set（低风险，可撤销）、osd_reweight（中风险，可撤销）、osd_mark_in（中风险，可撤销）	3	写入
	osd_mark_out（高风险，试运行）、osd_purge（高风险，试运行）	2	写入
PG	pg_summary、pg_dump_stuck、scrub_status	3	读取
	trigger_scrub（低风险）、trigger_deep_scrub（低风险）	2	写入
存储池	pool_ls、pool_df	2	读取
	set_pool_quota（中风险，可撤销）、set_pool_pg_num（中风险，可撤销）、set_pool_autoscale（中风险，可撤销）、pool_create（中风险）	4	写入
	set_pool_size（高风险，试运行）、pool_delete（高风险，试运行）	2	写入
RBD	rbd_ls	1	读取
	rbd_image_create（中风险）、rbd_snapshot_create（低风险）	2	写入
	rbd_image_delete（高风险，试运行）、rbd_snapshot_delete（高风险，试运行）	2	写入
CephFS / RGW	cephfs_status、rgw_status	2	读取
集群运维	mon_status、mgr_status、slow_ops、capacity_forecast	4	读取
	throttle_recovery（中风险，可撤销）	1	写入
撤销	undo_list、undo_apply	2	撤销

总计：37 个工具——17 个读取、18 个写入、2 个撤销。

快速开始

作为 Claude Code 插件

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

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

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

作为 OpenClaw 插件

同一捆绑包发布在 ClawHub 上，安装一次即可同时获得技能和 MCP 服务：

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

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

作为 CLI 或独立 MCP 服务

uv tool install ceph-aiops          # or: pipx install ceph-aiops
ceph-aiops init                     # wizard: add a mgr target + store the Dashboard password (encrypted)
ceph-aiops doctor                   # JWT login + mgr-dashboard reachability
ceph-aiops overview                 # HEALTH status + active checks + OSD up/in
ceph-aiops health detail            # decode the active HEALTH_WARN/ERR checks (RCA)
ceph-aiops osd df                   # per-OSD utilization, most-full first, near/backfill-full flags

作为 MCP 服务运行（stdio）：

export CEPH_AIOPS_MASTER_PASSWORD=...   # unlock secrets non-interactively
ceph-aiops-mcp

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

治理

每项操作——无论通过 MCP 还是 CLI——都会经过捆绑的 @governed_tool 机制。它负责记录，不负责授权（见上文）。

• 审计——每次调用（参数、结果、状态、耗时、风险等级，以及任何由操作员提供的审批人/理由）都会记录到 ~/.ceph-aiops/audit.db（可通过 CEPH_AIOPS_HOME 更改位置）。CLI 写入的记录与 MCP 路径相同——不存在未经审计的入口。
• 失控保护——这是安全兜底措施，而非授权关卡：同一调用在紧密循环中反复触发时，会触发断路器，防止卡住的 Agent 无限制地消耗调用次数/时间。使用 CEPH_RUNAWAY_MAX=0 禁用；也可通过 CEPH_MAX_TOOL_CALLS / CEPH_MAX_TOOL_SECONDS 设置硬上限。
• 撤销记录——可逆写入会记录根据获取的操作前状态构建的逆向描述符。
• 风险等级——审计记录中的描述性标签，根据 risk_level 得出；不用于限制任何操作。

支持范围与限制

• 部署方式：启用了 dashboard 模块的原生 ceph-mgr——cephadm、虚拟机管理程序捆绑的 Ceph 或 MicroCeph。不依赖 croit 或 Kubernetes。
• Ceph 的 Dashboard API 不支持 ETag / 分页，因此此工具也不提供这些功能——并非有所遗漏，而是上游 API 本身不支持。
• 验证状态：测试套件通过模拟 Dashboard 响应验证行为；尚未在真实集群上测试多节点重新平衡和写入操作。成本最低的真实环境检查方式是运行 ceph-aiops doctor 的单节点 MicroCeph（snap install microceph → 引导集群 → 使用 loop 文件创建 OSD）；3 节点 Vagrant 集群可用于测试真实的重新平衡行为。完整的真实环境验证清单请参阅 docs/VERIFICATION.md。

缺少某项功能？

RGW 多站点、各守护进程的配置管理、NFS-Ganesha 导出、编排器（cephadm）主机管理——这些功能尚未提供。欢迎提交 issue 或 PR，我们期待收到反馈和贡献。