Postgres AIops

Postgres AIops

免责声明：由社区维护的开源项目。与 PostgreSQL Global Development Group 或任何供应商均无关联、未获其认可或赞助。“PostgreSQL”和大象徽标是 PostgreSQL Community Association 的商标；所有产品名称和商标名称均归其各自所有者所有。采用 MIT 许可证。

面向 PostgreSQL DBA 运维 的治理型 AI 运维工具 — 通过 psycopg 3 连接服务，并读取系统目录和 pg_stat_* 视图 — 内置 治理框架：统一审计日志、令牌/失控预算防护、撤销令牌记录，以及描述性的风险等级标签。除了模拟测试套件外，我们还在实时 PostgreSQL 16.14 实例上测试了读取、受治理的写入及其撤销 — 参见 docs/VERIFICATION.md。

功能

三项标志性分析，以及围绕它们的受保护读取和写入：

• 慢查询根因分析 — 获取最差的 pg_stat_statements 条目（以及可选的 EXPLAIN 执行计划），并将其指标 — 平均耗时、缓存命中率、临时文件溢写、 调用次数、计划节点类型 — 映射到有依据的原因和具体操作。每项发现都附有 实测数值，而非黑箱结论。
• 膨胀与清理分析 — 综合每个表的死元组比例和 autovacuum 最近执行时间， 提供排序后的、有依据的建议（VACUUM / 调整 autovacuum）。
• 阻塞锁链根因分析 — 根据 pg_blocking_pids 构建等待树，指出 根阻塞者 （阻塞其他进程且自身不等待），并给出操作建议；检测到循环时会标记为可能存在死锁。

可用功能

• CLI（postgres-aiops ...）：init、overview、server、activity、query、index、table、repl、analyze、remediate、secret、doctor、mcp。
• MCP 服务（postgres-aiops mcp 或 postgres-aiops-mcp）：35 个工具（25 个读取工具、10 个写入工具），每个工具都由捆绑的 @governed_tool 框架封装。
• 加密凭据：角色密码存储在加密存储 ~/.postgres-aiops/secrets.enc（Fernet + scrypt）中 — 绝不会以明文存储在磁盘上。可通过 POSTGRES_AIOPS_MASTER_PASSWORD（MCP/CI）提供主密码解锁，或在 CLI 中交互式输入。
• 可逆性：变更性写入会先获取 真实的变更前状态，并记录精确的逆向操作 — create_index↔drop_index；drop_index 会捕获 pg_get_indexdef，以便撤销时原样重建；update_setting 会捕获原值，以便撤销时恢复。不可逆操作（terminate_backend、cancel_query、run_vacuum、run_analyze、reindex、reset_query_stats）会记录先前的统计信息用于审计，但不声明可撤销操作。
• 安全性：每项会改变状态的 CLI 操作都支持 --dry-run，并要求双重确认；每个写入 MCP 工具都支持 dry_run 预览。所有无法参数化的标识符（表名/索引名/GUC 名称）都会经过验证并加引号；所有值均使用绑定查询参数。

能力矩阵（35 个 MCP 工具）

领域	工具	数量	读/写
概览	overview	1	读取
服务端	server_version, show_settings, list_extensions, list_databases, list_roles	5	读取
活动	list_activity, long_running_queries, list_locks	3	读取
查询	top_queries, explain_query	2	读取
索引	unused_indexes, missing_index_hints, index_bloat, invalid_indexes	4	读取
表	table_sizes, table_bloat, autovacuum_status	3	读取
复制	replication_status, replication_slots, wal_status	3	读取
分析（旗舰功能）	slow_query_rca, bloat_and_vacuum_analysis, blocking_lock_chain_rca	3	读取
写入	terminate_backend, cancel_query, drop_index	3	写入（高）
	run_vacuum, run_analyze, create_index, reindex, update_setting, reset_query_stats	6	写入（中）
撤销	undo_list	1	读取
	undo_apply	1	写入（中）

旗舰分析功能接受注入的记录，用于纯离线分析；也可以从已配置的目标拉取实时数据。top_queries/slow_query_rca 需要 pg_stat_statements 扩展；读取角色应具有 pg_monitor 权限。

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

它能准确、高效地执行 PostgreSQL DBA 操作——读取和写入——并记录每一项操作。它不会决定是否允许执行写入。这取决于 Agent 的判断，或你用来连接的账户权限：使用没有写入权限的 PostgreSQL 角色（只读角色，或没有 INSERT/UPDATE/DELETE/DDL 权限的角色）连接，写入操作会在服务器端失败——因为权限由服务器实际控制。

因此，无需配置只读开关、策略文件或审批关卡。此工具保证的一件事是，所有操作都有迹可循：无论通过 MCP 还是 CLI 进行的每次调用，都会在 ~/.postgres-aiops/audit.db 中生成一条审计记录；破坏性写入仍会捕获操作前的状态，并在存在逆操作时记录该操作。

每个工具都会声明一个 risk_level，并以描述性等级（none/confirm/review）的形式写入审计记录——审阅者可以一眼看出某条记录对应的是高风险删除。这只是标签，不是关卡。

正在运行较小型或本地模型？请参阅 agent-guardrails.md——其中列出了此工具现在会为你强制执行的防护措施（因此你无需耗费提示词预算重述这些内容），并提供了可直接使用的系统提示词，用于处理剩余事项。

快速开始

作为 Claude Code 插件

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

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

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

作为 OpenClaw 插件

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

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

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

作为 CLI 或独立 MCP 服务

uv tool install postgres-aiops             # or: pipx install postgres-aiops
postgres-aiops init                        # wizard: add a target + store the password (encrypted)
postgres-aiops doctor                      # verify config, secrets, connectivity
postgres-aiops overview                    # one-shot cluster health snapshot
postgres-aiops analyze slow-query          # RCA the worst pg_stat_statements entry
postgres-aiops table bloat                 # dead-tuple bloat proxy per table

作为 MCP 服务运行（stdio）：

export POSTGRES_AIOPS_MASTER_PASSWORD=...  # unlock secrets non-interactively
postgres-aiops-mcp

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

治理

每个 MCP 工具都会通过内置的 @governed_tool 执行框架：

• 审计 — 每次调用（参数、结果、状态、耗时、风险等级，以及操作员提供的审批者／理由）都会记录到 ~/.postgres-aiops/audit.db （可通过 POSTGRES_AIOPS_HOME 更改位置）。CLI 写入的记录与 MCP 路径写入的相同——不存在未经审计的入口。
• 失控防护 — 这是一道安全后备措施，而非授权门槛：在短时间内反复执行相同调用会触发熔断器。使用 POSTGRES_RUNAWAY_MAX=0 可禁用；还可设置可选的硬性上限 POSTGRES_MAX_TOOL_CALLS / POSTGRES_MAX_TOOL_SECONDS。
• 撤销记录 — 对可逆写入操作，会根据获取的变更前状态记录一个逆向描述符。
• 风险等级 — 审计记录中根据 risk_level 得出的描述性标签；不用于门控任何操作。

适用范围

这是 AIops-tools 系列中的 PostgreSQL DBA 运维成员（受治理的 AI 运维，包含审计 + 预算 + 撤销 + 风险等级）。不要将其用于 OT / 工业边缘场景（Modbus、OPC-UA、PROFINET）——请参阅单独的 industrial-aiops 系列；也不要将其用于应用程序架构迁移或 ORM 管理。

缺少某项功能？

覆盖范围有意限定为 PostgreSQL 系统目录和维护功能的精选子集。缺少某个视图、指标或维护命令？请提交 issue 或 PR——欢迎贡献。

状态

模拟测试套件还辅以一次实机运行：目录／pg_stat_* 读取、bloat_and_vacuum_analysis RCA，以及 create_index / drop_index 受治理写入路径（审计 + 撤销；drop_index 会先捕获 pg_get_indexdef），均已在 Docker 中运行的 PostgreSQL 16.14 实例上进行测试。docs/VERIFICATION.md 记录了具体的测试覆盖范围和未覆盖内容。postgres-aiops doctor 是最快的实机检查方式。