MySQL AIops

MySQL AIops

免责声明：由社区维护的开源项目。与 Oracle Corporation 或 MariaDB Foundation 无关联，未获其认可或赞助。“MySQL”是 Oracle Corporation 的商标；“MariaDB”是 MariaDB plc 的商标；所有产品和商标名称均归其各自所有者所有。采用 MIT 许可证。

面向 MySQL 8.x 和 MariaDB 10.6+ DBA 运维的治理式 AI 运维——通过 PyMySQL 连接到服务并读取 information_schema / performance_schema——并内置治理框架：统一审计日志、令牌／失控操作预算保护、撤销令牌记录，以及描述性风险等级标签。服务的类型（mysql 或 mariadb）会根据 version() 检测，并自动切换依赖类型的语句（SHOW REPLICA STATUS 与 SHOW SLAVE STATUS）。

功能

四项标志性分析，以及围绕它们提供的受控读取和写入：

• 慢查询根因分析——获取 events_statements_summary_by_digest 中最严重的条目（以及可选的 EXPLAIN FORMAT=JSON 执行计划），并根据其数据——无索引占比（SUM_NO_INDEX_USED）、锁等待时间占比、检查行数／发送行数比、临时表磁盘溢出、调用次数、计划访问类型——给出有依据的原因和具体操作。每条发现都附有测量值，而非黑盒判定。
• InnoDB 锁等待与死锁链根因分析——根据 performance_schema.data_lock_waits 构建等待关系树（MariaDB：information_schema.innodb_lock_waits），指出根阻塞者（阻塞其他事务且自身不等待），并解析 SHOW ENGINE INNODB STATUS 中的最近一次死锁。
• 复制延迟根因分析——根据副本的 IO／SQL 线程状态、Seconds_Behind_Source 和错误字段，给出有依据的原因和操作（IO 线程已停止、应用器语句失败、应用器延迟、主动设置的 SQL_Delay）。
• 表碎片分析——根据 information_schema.tables 中可回收的 data_free 对表进行排序，列出有依据的 OPTIMIZE TABLE 候选项。

支持的功能

• CLI（mysql-aiops ...）：init、overview、server、activity、query、index、table、repl、analyze、remediate、secret、doctor、mcp。
• MCP 服务（mysql-aiops mcp 或 mysql-aiops-mcp）：35 个工具（26 个读取，9 个写入），每个工具都由内置的 @governed_tool 框架封装。
• 加密凭据：账户密码存储在加密存储中：~/.mysql-aiops/secrets.enc（Fernet + scrypt）——绝不以明文形式存储在磁盘上。可通过 MYSQL_AIOPS_MASTER_PASSWORD（MCP／CI）或交互式提示词（CLI）输入主密码解锁。
• 可逆性：执行变更的写入操作会先获取实际的变更前状态，并记录准确的逆向操作——create_index↔drop_index；drop_index 会从 SHOW CREATE TABLE 中获取索引定义，以便撤销时准确重建；set_global_variable 会从 SHOW GLOBAL VARIABLES 中获取先前的值，以便撤销时恢复。不可逆操作（kill_session、kill_query、optimize_table、analyze_table、reset_query_stats）会记录先前状态以供审计，但不声明可撤销。
• 安全性：每个会更改状态的 CLI 操作都支持 --dry-run，并要求二次确认；每个 MCP 写入工具都提供 dry_run 预览。所有无法参数化的标识符（架构／表／索引／列／变量名称）都会根据严格字符集进行验证，并用反引号括起；所有值都会作为绑定查询参数传入。

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

它能够准确、高效地执行 MySQL / MariaDB DBA 操作——包括读取和写入——并记录每一项操作。它不会决定是否允许执行写入。这个判断由 Agent 作出，或者由你连接时使用的账户权限决定：将它指向一个仅获授 SELECT / PROCESS / REPLICATION CLIENT 权限、没有任何写入权限（无 INSERT/UPDATE/DELETE/DDL）的 MySQL/MariaDB 账户，写入操作就会在服务器端失败——权限实际由服务器管理。

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

每个工具都会声明一个 risk_level，并将其作为描述性级别（none/confirm/review）写入审计记录，这样审核者一眼就能看出某条记录对应的是高风险删除操作。这只是标签，不是门槛。

如果运行的是较小型 / 本地模型，请参阅 agent-guardrails.md——其中列出了此工具现在会为你强制执行的防护措施（这样你就不用在提示词预算中重复说明），并提供了一个可直接使用的系统提示词，用于处理剩余事项。

能力矩阵（35 个 MCP 工具）

领域	工具	数量	读/写
概览	overview	1	读取
服务器	server_version、show_variables、show_status、list_databases、list_engines、connection_stats	6	读取
活动	list_sessions、long_running_queries、list_transactions、lock_waits	4	读取
查询	top_queries、explain_query	2	读取
索引	unused_indexes、redundant_indexes、index_stats	3	读取
表	table_sizes、table_fragmentation、table_status	3	读取
复制	replica_status、binlog_status	2	读取
分析（旗舰功能）	slow_query_rca、lock_wait_rca、replication_lag_rca、fragmentation_analysis	4	读取
写入	kill_session、kill_query、drop_index	3	写入（高风险）
	optimize_table、analyze_table、create_index、set_global_variable、reset_query_stats	5	写入（中风险）
撤销	undo_list、undo_apply	2	读取 / 写入

旗舰分析工具可接受注入的记录，以执行纯离线分析；也可以从已配置的目标实时提取数据。top_queries/slow_query_rca 要求 performance_schema=ON；读取账户应具有 PROCESS、REPLICATION CLIENT 权限，以及对 performance_schema 的 SELECT 权限。

支持范围

平台	状态
MySQL 8.0 / 8.4	目标平台（SHOW REPLICA STATUS、performance_schema.data_lock_waits）
MariaDB 10.6+ / 11.x	目标平台（SHOW SLAVE STATUS、information_schema.innodb_lock_waits）
MySQL 5.7 及更早版本	非目标平台（已 EOL；未测试 8.0 之前的摘要 / 锁视图）
云托管 MySQL（RDS/Aurora/Cloud SQL 类型）	兼容协议的读取操作应可正常工作；托管限制（KILL、SET GLOBAL）仍然适用——未经测试

快速开始

作为 Claude Code 插件使用

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

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

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

作为 OpenClaw 插件

同一套软件包也发布在 ClawHub 上，安装一次即可同时获得 skill 和 MCP 服务：

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

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

作为 CLI 或独立 MCP 服务

uv tool install mysql-aiops             # or: pipx install mysql-aiops
mysql-aiops init                        # wizard: add a target + store the password (encrypted)
mysql-aiops doctor                      # verify config, secrets, connectivity, flavor, perf-schema
mysql-aiops overview                    # one-shot server health snapshot
mysql-aiops analyze slow-query          # RCA the worst statement digest
mysql-aiops analyze fragmentation       # OPTIMIZE TABLE candidates

作为 MCP 服务运行（stdio）：

export MYSQL_AIOPS_MASTER_PASSWORD=...  # unlock secrets non-interactively
mysql-aiops-mcp

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

Claude Desktop / MCP 客户端配置：

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

env 块注意事项：上面的 env 块是 MCP 服务能看到的唯一环境变量——通过 GUI 启动的客户端不会继承你的 shell 配置文件。请将 MYSQL_AIOPS_MASTER_PASSWORD（以及在使用时的 MYSQL_AIOPS_HOME / MYSQL_AUDIT_APPROVED_BY）放入其中，否则服务无法解锁密钥存储。

治理

每个 MCP 工具都会经过捆绑的 @governed_tool 管理层：

• 审计 — 每次调用（参数、结果、状态、耗时、风险等级，以及操作员提供的任何批准人/理由）都会记录到 ~/.mysql-aiops/audit.db（可通过 MYSQL_AIOPS_HOME 更改位置）。CLI 写入的记录与 MCP 路径相同——不存在未经审计的入口。
• 失控防护 — 这是安全后备机制，而非授权门禁：短时间内反复调用同一工具会触发断路器。使用 MYSQL_RUNAWAY_MAX=0 可禁用；也可通过 MYSQL_MAX_TOOL_CALLS / MYSQL_MAX_TOOL_SECONDS 设置硬性上限。
• 撤销记录 — 可逆写入会根据获取的变更前状态记录逆向操作描述符。
• 风险等级 — 根据 risk_level 得出的描述性标签，会写入审计记录；它不会限制任何操作。

范围

这是 AIops-tools 系列中面向 MySQL / MariaDB DBA 运维的成员 （具备审计 + 预算 + 撤销 + 风险等级治理的 AI 运维）。请勿将其用于 PostgreSQL——请使用 postgres-aiops。请勿将其用于 OT / 工业 边缘场景——请参阅单独的 industrial-aiops 系列——也不要用于应用架构 迁移或 ORM 管理。

缺少某项功能？

此工具有意仅覆盖 MySQL 目录和维护功能中的精选子集。缺少某个视图、指标或维护命令？欢迎提交 issue 或 PR。缺功能提 issue/PR 欢迎留言。

验证状态

已针对 MySQL 8.4.10 和 MariaDB 11.8.8 进行实时验证（2026-07-19/20）。 已在真实服务上测试连接、读取操作、针对实际全表扫描的 analyze slow-query，以及完整治理流程（实际执行 create_index → 写入审计记录 → 撤销操作确实删除索引）。测试发现并修复了一个模拟测试套件无法发现的真实问题：SUM() 聚合结果会以 Decimal 类型返回，而该类型无法进行 JSON 序列化。

MariaDB 分支现也已通过验证，包括针对真实行争用执行 analyze lock-waits（它正确识别了根本阻塞因素和测得的等待时间）。 尚未通过真实副本验证复制功能。

docs/VERIFICATION.md 详细记录了已检查的内容和仍待处理的事项。mysql-aiops doctor 是最快的实时检查方式（连接、数据库类型、performance_schema、副本角色）。