MinIO AIops

MinIO AIops

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

面向 MinIO 对象存储的受治理 AI 运维——适用于 MinIO 实际运行的家庭实验室和小型／中型可自托管部署。它通过 S3 API（官方 minio SDK、SigV4）、管理 API（存储桶配额、服务信息）、无需身份验证的 健康检查端点（/minio/health/live|ready|cluster）以及 集群指标端点（/minio/v2/metrics/cluster，支持持有者令牌或公开身份验证）进行交互，并内置治理机制：统一审计日志、令牌／失控预算防护、撤销令牌记录，以及每条审计记录的描述性风险等级。独立运行：不依赖外部技能系列。

功能

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

• capacity_rca — 容量与已用空间、离线驱动器／节点、每个驱动器的热点和不平衡情况 → 将每项发现整理为原因 + 建议操作（接近满载／已满阈值是具名常量，不是魔法数字）。
• bucket_exposure_audit — 为每个存储桶评分并排序，评估匿名／公开策略声明（读取以及风险更高的写入）、缺少默认加密、未启用版本控制、没有生命周期规则等情况。
• lifecycle_gap_analysis — 存储 ILM 应回收却未回收的空间：没有非当前版本过期规则的版本控制存储桶（旧数据会永久累积）、没有中止规则的未完成分段上传（占用不可见空间）、没有生命周期规则的大型存储桶，并提供明确标注的可回收空间估算。
• healing_health — 修复积压和每个纠删码集的写入仲裁风险：各集还可容忍多少次驱动器故障、哪些集正在修复，以及修复错误集中在哪些位置。
• 受治理的写入操作。 修改存储桶策略／版本控制／生命周期／配额时，会捕获真实的先前状态并记录撤销描述符；除非能够确认存储桶为空（包括版本和删除标记），否则会拒绝 bucket_delete；remove_incomplete_uploads 只会处理超出安全时间窗口的上传。

支持的功能

• CLI（minio-aiops ...）：init、overview、doctor、health check/status、capacity rca/usage、heal status/drives/nodes、bucket ls/info/objects/audit/ilm-gap/uploads，以及受保护的写入操作（bucket versioning-set/policy-set/lifecycle-set/quota-set/purge-uploads/delete）、 secret set/list/rm/migrate/rotate-password、mcp。破坏性命令支持 --dry-run 并要求二次确认。
• MCP 服务（minio-aiops mcp 或 minio-aiops-mcp）：完整的 48 个 工具（29 个读取工具、19 个写入工具），每个工具都由内置的 @governed_tool 治理机制封装。CLI 只是便捷子集；MCP 接口包含全部工具。CLI 写入操作会委托给相同的受治理函数，因此审计方式完全一致。
• 加密凭据：密钥存储在加密存储区 ~/.minio-aiops/secrets.enc（Fernet + scrypt）中——绝不以明文写入磁盘。使用 MINIO_AIOPS_MASTER_PASSWORD 中的主密码解锁（用于 MCP／CI），或在 CLI 中交互式输入。
• 两种指标身份验证模式：运行 MINIO_PROMETHEUS_AUTH_TYPE=public 的服务会直接抓取指标；对于默认的 (jwt) 模式，持有者令牌会根据已存储的凭据派生——无需管理额外密钥。
• 可逆性：可逆写入会捕获先前状态并记录逆向撤销描述符（先前的策略 JSON、先前的生命周期 XML、先前的版本控制状态、先前的配额）。

功能矩阵（48 个 MCP 工具）

分组	工具	数量	读/写
健康状态	health_live、health_ready、health_cluster、cluster_status、fleet_overview	5	读取
容量	capacity_rca（旗舰工具）、usage_by_bucket	2	读取
修复	healing_health（旗舰工具）、drive_status、node_status	3	读取
暴露风险 / ILM	bucket_exposure_audit（旗舰工具）、lifecycle_gap_analysis（旗舰工具）	2	读取
存储桶	bucket_ls、bucket_info、bucket_policy_get、bucket_lifecycle_get、bucket_versioning_get、bucket_quota_get、object_ls、incomplete_uploads_ls、server_info	9	读取
写入	set_bucket_policy（中等风险，可撤销）、delete_bucket_policy（中等风险，可撤销）、set_versioning（中等风险，可撤销）、set_lifecycle（中等风险，可撤销）、delete_lifecycle（中等风险，可撤销）、set_bucket_quota（中等风险，可撤销）	6	写入
	bucket_delete（高风险，试运行、仅限空存储桶、不可逆）、remove_incomplete_uploads（中等风险，试运行，仅限 priorState）	2	写入
对象锁定（WORM）	bucket_lock_config、object_lock_status、diagnose_retention_gaps（旗舰工具）	3	读取
	bucket_create（中等风险，可撤销——启用对象锁定的唯一方式）、set_default_retention（高风险，可撤销）、clear_default_retention（中等风险，可撤销）、set_legal_hold（中等风险，可撤销）	4	写入
	set_object_retention（严重风险，试运行、仅可延长、无法撤销）	1	写入
IAM	iam_users、iam_groups、iam_policies、diagnose_iam_exposure（旗舰工具）	4	读取
	create_user（中等风险，可撤销，密钥已隐藏且不会返回）、set_user_status（中等风险，可撤销）、attach_user_policy（中等风险，可撤销）、detach_user_policy（中等风险，可撤销）——对该工具自身使用的凭据，所有操作均会被拒绝	4	写入
	remove_user（高风险，试运行，无法撤销：MinIO 不会保留可恢复的密钥）	1	写入
撤销	undo_list、undo_apply	2	读取 + 重放

合计：48 个工具——29 个读取（含 undo_list），19 个写入（含 undo_apply）。

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

它准确、高效地执行 MinIO 对象存储操作——读取和写入，并记录每一项操作。它不会决定是否允许执行写入操作。这由 Agent 判断，或由你连接时使用的访问密钥权限决定：为该密钥授予只读 IAM 策略，写入操作就会在服务端失败——权限实际归属之处。

因此，无需配置只读开关、策略文件或审批关卡。此工具唯一能保证的是不会有操作悄无声息：每次调用，无论通过 MCP 还是 CLI，都会写入审计记录，保存到 ~/.minio-aiops/audit.db，可撤销的写入操作仍会捕获实际的先前状态，并记录反向撤销描述符。

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

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

快速开始

作为 Claude Code 插件

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

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

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

作为 OpenClaw 插件

同一捆绑包已发布到 ClawHub，安装一次即可同时安装技能及其 MCP 服务：

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

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

作为 CLI 或独立 MCP 服务

uv tool install minio-aiops         # or: pipx install minio-aiops
minio-aiops init                    # wizard: endpoint + access key; secret key stored encrypted
minio-aiops doctor                  # live/ready + S3 auth + metrics reachability
minio-aiops overview                # health + capacity headline + exposure headline
minio-aiops capacity rca            # why is storage filling up, and what to do
minio-aiops bucket audit            # ranked bucket-exposure findings

作为 MCP 服务运行（stdio）：

export MINIO_AIOPS_MASTER_PASSWORD=...   # unlock secrets non-interactively
minio-aiops-mcp

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

MCP 客户端配置

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

环境变量块注意事项：MCP 客户端启动服务时没有 TTY，也不会加载你的 shell 配置文件，因此无法提示输入主密码，而且 ~/.zshrc 中的 export 也不会生效——必须像上面那样在客户端的 env 块（或客户端进程的环境）中传递密码。其他所有内容（目标、TLS、区域、指标模式）均来自 minio-aiops init 写入的 ~/.minio-aiops/config.yaml。

配置

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

targets:
  - name: lab1
    host: 192.0.2.10
    port: 9000
    access_key: minio-ops        # identifies the account; NOT the secret
    secure: true                 # https (false for plain-http labs)
    verify_ssl: true             # false for self-signed lab certs
    region: ""                   # optional
    metrics_public: false        # true when MINIO_PROMETHEUS_AUTH_TYPE=public

密钥通过 minio-aiops secret set lab1 存储（已加密；旧版 MINIO_LAB1_SECRET_KEY 环境变量会作为后备选项得到支持，并发出迁移警告）。

治理

每个 MCP 工具都会经过捆绑的 @governed_tool 处理框架：

• 审计 — 每次调用（参数、结果、状态、持续时间、风险级别，以及任何 MINIO_AUDIT_APPROVED_BY / MINIO_AUDIT_RATIONALE 注释）都会记录到 ~/.minio-aiops/audit.db（可通过 MINIO_AIOPS_HOME 更改位置）。
• 预算 / 失控防护 — 令牌和调用预算达到上限时会触发断路器。这是安全兜底措施，而非授权机制。
• 风险级别标注 — 每个工具声明的 risk_level 都会作为描述性级别记录在审计行中（bucket_delete 为高风险）。它是供审核者参考的标签，并非门禁：没有只读开关、策略文件或审批门禁；MINIO_AUDIT_APPROVED_BY / MINIO_AUDIT_RATIONALE 是可选注释，仅在设置时记录，绝非必填。
• 撤销记录 — 可逆写入会记录一个基于捕获的先前状态构建的逆向描述符。

支持范围与限制

• 部署：任何较新的 MinIO 服务端（单节点或分布式／纠删码部署），只要可通过其 S3 端口访问即可。管理功能（配额、server_info）需要具备管理员权限的密钥。通用 S3 服务不在支持范围内：此处使用的健康状况、指标和管理接口均为 MinIO 专用。
• 指标：容量／修复 RCA 会读取 v2 集群指标端点；支持 public 和 bearer-token（默认）两种身份验证模式。
• 未完成上传列表使用 SDK 的核心 ListMultipartUploads 调用（SDK 已移除其公开别名）；该功能已通过测试覆盖，并在 connection.py 中记录。
• 验证状态。 已针对真实的单节点 MinIO 服务完成实时验证（2026-07-19）：连接性、读取操作、暴露审计（正确将可匿名写入的存储桶评为 high，并指出 PUBLIC_WRITE_POLICY），以及治理流程（真实的 set_versioning → 撤销操作将其恢复为 Suspended，使用了正确的 S3 逆向操作）。分布式／多节点 MinIO 仍未经验证——从未在真实的故障驱动器或纠删码集上测试修复；生命周期／配额写入以及 TLS 端点也尚未验证。请参阅 docs/VERIFICATION.md；minio-aiops doctor 是最快的实时检查方式。

缺少某项功能？

站点复制状态、IAM 策略编写（创建和编辑策略文档——支持附加）、群组成员关系写入、分层至远程存储——目前尚未提供。欢迎提交 issue 或 PR——我们欢迎反馈和贡献。