Archery SQL审核与MySQL运维落地：工单流程、回滚与避坑

简介：《archery使用手册》是一份面向数据库开发人员、DBA和运维工程师的实操型文档，聚焦SQL审核查询平台Archery的落地使用，适合正在搭建或使用SQL工单流程、需要规范数据库变更与实例运维的团队参考。压缩包内共1个doc文件，约1.2MB，以图文步骤形式系统梳理Archery的功能与实践路径。内容覆盖SQL审核的语法与规范校验（主键、注释、高危语句驳回、定时或立即执行、钉钉通知）、SQL分析与慢日志优化建议、实例管理中的binlog清理、会话与事务查看、锁信息排查及账号授权，并演示PTArchiver归档、Binlog2SQL回滚解析、SchemaSync结构比对三类插件的具体用法；实践案例部分完整给出开发与测试环境的SQL审核流程、回滚工单下载及常见阻塞问题的处理思路。已有1478人学习，可作为团队内部推广Archery时的操作参照与培训材料。

1. 从一条没写主键的建表语句说起：archery 要接住的是哪类事故

某公司的一次版本上线，开发同学提交的建表语句既没主键也没写注释，DBA 在群里来回问了三轮才发现问题，等改完已经错过了发版窗口。这类事故不是技术难度问题，而是流程里少了一道机器把关的闸。这份 archery 使用手册要讲的，就是把「建表必须有主键、表和列必须有注释、高危语句必须拦下来」这些口头约定，变成一套可执行、可回滚、可追溯的 SQL 审核流程。archery 定位在 SQL 审核查询平台，同时带一整套 MySQL 运维功能，从工单流转到实例会话排查再到数据归档插件都在里面。它适合三类人：要给团队搭 SQL 上线流程的运维和开发、需要独立完成数据库课程设计或毕设的学生、以及接手了一套没人管的 MySQL 实例、想先把巡检和变更管起来的人。

2. 平台能力边界与角色分工：四块功能各管一段链路

在动手配流程之前，先得清楚 archery 到底管哪几段。很多人一上来就盯着「SQL 审核」这一个功能，配完规则就以为完事了，结果真正出问题时发现会话查不了、binlog 清不掉、数据归档还得另找脚本。把平台的四块能力摊开看：SQL 审核管变更入口，SQL 优化管性能，实例管理管运行时状态，工具插件管数据生命周期。四块拼起来才是一条完整的 MySQL 运维链路，缺哪块都会在某个具体场景里卡住。

2.1 SQL 审核引擎的能力边界：语法解析加自定义规则

审核这件事的实现方式，是对提交上来的 SQL 做语法解析，拿到语法树之后逐条套用规则集，最后按规则级别返回 error 和 warning。语法解析这一层能挡住的是写错的 SQL，比如关键字拼错、引号不闭合、字段列表和值列表数量对不上；规则这一层挡的是「语法没错但不合规范」的语句，这才是审核平台真正的价值所在。

规则覆盖面通常包括这几类：建表必须有主键、表必须有注释、每个列必须有注释、禁止使用某些字段类型、单表索引数量上限、字符集统一、禁止 SELECT *。高危语句则走单独的拦截通道，常见的如不带 WHERE 条件的 UPDATE 和 DELETE、DROP TABLE、TRUNCATE，这类语句在检测阶段就直接驳回，不给提交入口。

下面这段是典型的会被打回的建表语句，可以拿来验证规则有没有配到位：

-- 提交到审核工单的原始语句，预期被规则拦截 CREATE TABLE `order_detail` ( `order_no` varchar(32) DEFAULT NULL, `sku_id` bigint DEFAULT NULL, `amount` decimal(10,2) DEFAULT NULL, `create_time` datetime DEFAULT NULL ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

这段语句本身语法完全正确，数据库也能建出来，但会同时触发三条规则：没有主键、表没有 COMMENT、四个列都没有 COMMENT。审核结果里会逐条列出命中的规则名和级别，提交人按提示改完再提交一次即可。改成下面这样就能通过：

-- 补主键、补表注释、补列注释后的版本 CREATE TABLE `order_detail` ( `id` bigint NOT NULL AUTO_INCREMENT COMMENT '主键', `order_no` varchar(32) NOT NULL COMMENT '订单号', `sku_id` bigint NOT NULL COMMENT '商品ID', `amount` decimal(10,2) NOT NULL DEFAULT '0.00' COMMENT '金额', `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', PRIMARY KEY (`id`), KEY `idx_order_no` (`order_no`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='订单明细表';

规则级别要分清楚：error 级别的一律不允许提交，warning 级别的允许提交但会在工单里留痕。我一般会把「无主键」「无注释」「高危语句」设成 error，把「索引命名不规范」「字段类型偏大」设成 warning。全设成 error 会让小团队寸步难行，全设成 warning 等于没设，这个度需要按团队当前的 SQL 水平调一两次才能稳定下来。

审核通过之后还有两个动作容易忽略。一是「快速上线其他实例」，同一条 DDL 要在多个实例上执行时，不用重复走一遍工单，直接从已通过的工单复制过去，改一下目标实例就行。二是执行方式的选择，立即执行和定时执行各有适用场景，定时执行适合把变更压到业务低峰期，但只要定时任务排在同一时刻，就会在数据库上形成一波并发压力，这一点后面避坑章节还会展开。

2.2 四类能力的职责划分：谁在什么阶段用哪块

把四块能力按角色和使用阶段对齐，流程设计才不会乱：

权限上有个默认设定要提前说清楚：实例管理这一块默认只有管理员账号有权限。这个设计是对的，会话终止、账号增删、动态参数修改都属于高影响操作，随手放开给所有人，迟早会有人在生产库上误杀一个正在跑批的会话。合理的做法是给 DBA 和值班运维开管理员，研发只给审核和查询权限。

职责划分里最容易出问题的是「SQL 优化」这块。它既不属于变更流程，也不属于故障处理，处在中间地带，结果就是谁都能用、谁都不主动用。我的建议是把它挂到慢查询治理的例行动作上，每周固定看一次慢 SQL 统计，挑出 TOP 几条用优化功能跑一遍执行计划，把建议落到具体的索引或者 SQL 改写上，而不是等业务方来投诉页面变慢。

3. SQL 工单流程设计：开发与测试两条链路的差异

同一个平台，开发环境和测试环境的审核流程不该长一个样。开发环境要的是「有人复核」，测试环境要的是「快速自证」。把两条链路拆开设计，是这套流程能不能真正跑起来的关键——如果测试环境也要走两级审批，测试同学会直接绕过平台手工执行，那前面配的规则全白费。

3.1 开发环境链路：研发工程师到项目经理的两级流转

开发环境的链路是两个角色：研发工程师发起，项目经理审核。发起人的动作分三步，准备 SQL 文件、填工单信息、点「SQL 检测」。检测这一步是硬门槛，只要结果是 error，工单就提不上去，必须按提示改完 SQL 重新检测。检测通过后点「SQL 提交」，工单进入待审核队列。

项目经理这一侧不需要盯着平台刷新，右上角的通知按钮会汇总待办事项，点进去就是待自己处理的工单列表。这里有个细节值得单独讲：审核人看到的不只是 SQL 原文，还有检测阶段命中的规则明细，以及系统自动生成的回滚语句。审核动作实际上是在确认三件事——业务逻辑对不对、规则告警能不能接受、回滚方案是否成立。第三件事最容易被跳过，但恰恰是出事时唯一能救命的东西。

最后一级审核通过后，工单进入执行环节，可以选择立即执行或定时执行。立即执行适合紧急修复，定时执行适合计划和发版窗口对齐的变更。两条路径走完之后，工单状态会同步到通知渠道，钉钉通知这类集成在这里的作用不是提醒「有人提交了工单」，而是让审核人知道「有一条工单卡在你这儿超过 N 小时了」，这两种通知的价值差得很远。

工单提交时需要的字段不多，但每个都要填准，尤其是目标实例和目标库，填错一个就是变更打到别的环境去了。下面是一个工单参数的示意结构，实际界面里是表单，理解字段含义比记字段名更重要：

{ "workflow_name": "订单明细表新增字段", "instance": "prod-order-01", "db_name": "order_center", "sql_content": "ALTER TABLE order_detail ADD COLUMN remark varchar(200) NOT NULL DEFAULT '' COMMENT '备注';", "execute_mode": "scheduled", "schedule_time": "2024-06-15 02:00:00", "notify_channel": "dingtalk" }

instance和db_name决定了变更落到哪台机器的哪个库，这两个字段是整个工单里风险最高的部分；execute_mode取immediate或scheduled，定时执行时schedule_time必须落在业务低峰期；sql_content建议一次只放一个逻辑变更，把建表和改表混在一个工单里，回滚的时候会非常难受。

3.2 测试环境链路：从 Git 取件到测试同事自审自执

测试环境的链路只有两个角色：测试同事从 Git 上取开发提交的 SQL 文件，然后在测试环境发起审核、自己审核、自己执行。看起来像是把审批环节砍掉了，实际上是换了把关方式——把关人从「另一个人」变成「审核规则本身」。

这条链路成立的前提有两个。第一，SQL 文件必须走 Git，不能靠聊天工具传，否则测试拿到的版本和开发提交的版本对不上，测试环境验证通过的东西上生产就变样。第二，测试环境的规则集不能比生产松太多，至少高危语句拦截、无主键、无注释这几条要和生产保持一致。见过一些团队测试环境规则全关，理由是「测试库随便造」，结果开发在测试环境养成了不带 WHERE 就 UPDATE 的习惯，上了生产一提交就被拦，反而抱怨平台碍事。

自审自执的模式下，回滚语句的生成同样要保留。测试环境的价值之一就是先演练一遍回滚，确认回滚 SQL 能正常执行、执行后数据回到预期状态。这条演练在测试环境做成本几乎为零，在生产环境做就是事故现场。

3.3 回滚语句的生成与留存：出事时唯一能救命的东西

回滚语句不是工单的附属品，是工单的组成部分。平台在执行前会根据 SQL 类型自动生成对应的反向语句：INSERT 对应 DELETE、UPDATE 对应反向 UPDATE、DELETE 对应 INSERT、DDL 则生成反向的 ALTER。工单详情里可以直接「查看回滚 SQL」，也可以「下载回滚 SQL」存档。

回滚语句有两个必须讲清楚的边界。第一，DDL 的反向语句依赖当前表结构快照，如果生成回滚语句之后表结构又被别的工单改过，这条回滚语句可能执行失败，所以回滚要在变更后尽快完成，别拖到几天之后。第二，也是血泪经验里最常见的一条：删除表、删除列这类操作，反向语句只能把结构建回来，数据回不来。DROP COLUMN 之后想恢复那一列的数据，只能靠备份或者 binlog 解析，平台帮不了你。所以凡是涉及删数据的变更，执行前先做一次表级备份，这一步没有捷径。

留存策略上，工单记录不要定期清理。审核记录、执行人、执行时间、回滚语句这几样东西，在事后复盘和责任界定时的作用远超它占用的存储。我一般会要求工单记录至少保留一个完整的发版周期以上，跨季度的变更记录也尽量留着。

4. SQL 优化与实例运维落地：从执行计划到会话终止

审核管的是「变更能不能进」，优化和实例运维管的是「进去之后跑得好不好」。这两块功能在实际使用中经常被割裂开——优化是开发在用，实例管理是 DBA 在用，中间没有交接。真正有效的用法是把它们串成一条排查路径：先看慢日志定位问题 SQL，再用优化功能看执行计划，最后到会话视图里确认这条 SQL 是不是正在拖垮实例。

4.1 SQL 分析与慢日志：把 SELECT * 改成字段列表

SQL 优化功能的输入是一条具体的 SQL，输出是执行计划和优化建议。拿一条最常见的低效语句做例子：

-- 待分析的原始语句 SELECT * FROM baidd.emp WHERE ename = 'dan_1';

分析结果里会给出执行计划，重点看三列：访问类型是全表扫描还是索引查找、预估扫描行数、是否出现临时表和文件排序。这条语句在ename上没有索引时，访问类型是全表扫描，扫描行数等于表的总行数；加上索引后变成索引查找，扫描行数降到个位数。优化建议里通常还会提一条：把SELECT *改成具体字段列表，避免把不需要的大字段一起读出来。

改写成SELECT id, ename, dept_no FROM baidd.emp WHERE ename = 'dan_1'之后再跑一次分析，结果会变成 OK。这个前后对比很适合拿来做团队内的案例讲解，因为它足够简单，任何人都能立刻理解「读的列少了，网络传输和内存占用就少了」这件事。

慢日志这块提供的是统计视角，能按时间段看哪些 SQL 出现次数最多、平均耗时最长、扫描行数最大。三个维度要分开看：出现次数多的往往是高频小查询，优化收益靠加索引或者加缓存；平均耗时长的通常是个别复杂查询，优化收益靠改写 SQL 或者调整执行计划；扫描行数大的基本都是缺索引或者索引失效。三个榜单混在一起看，很容易把精力花在一条一天只跑一次、耗时 2 秒的报表 SQL 上，而忽略了那条一天跑十万次、每次 50 毫秒的接口查询。

4.2 会话、事务、锁三张视图的联动排查

实例管理里最实用的功能是会话管理和锁信息，这两个视图配合起来，能解决大部分「数据库突然变慢」的问题。排查顺序我一般是这样走的：

第一步看进程状态。右上角选好实例，command 类型默认是 query，只能看到正在执行查询的会话；怀疑有别的操作在拖后腿时切到 All，把 Sleep 状态之外的都过一遍。这里有个必须做的前置动作：勾上「完整 INFO」，否则 SQL 文本会被截断成一行，你只能看到前半句，判断不了它到底在干什么。

第二步看锁信息。锁视图里会明确列出等待中的事务和被阻塞的 SQL，以及阻塞方的线程 ID。光看这一屏还不够，得把阻塞方的线程 ID 拿到进程状态里去搜，找到对应会话再决定要不要终止。

第三步看事务信息。事务视图展示当前正在运行的事务，其中的trx_mysql_thread_id和进程状态里的 THREAD ID 是同一个东西，这个对应关系是排查时最关键的锚点。想杀掉某个长时间不提交的事务，就是拿这个 ID 去进程状态里搜，选中后点终止会话。

下面这段 SQL 可以在测试库上复现一次锁等待，用来熟悉整个排查路径：

-- 会话 1：开启事务并更新一行，不提交 BEGIN; UPDATE baidd.t2 SET ename = 'baidd' WHERE id = 2; -- 会话 2：更新同一行，会被阻塞 UPDATE baidd.t2 SET ename = 'dan' WHERE id = 2;

执行完这两段之后，会话 2 会一直挂在那里等锁。此时打开锁信息视图，能看到等待事务的 SQL 就是会话 2 那条 UPDATE，阻塞方是会话 1 的线程 ID。顺着线程 ID 去进程状态里定位，终止会话 1，会话 2 立刻放行。这套动作建议每个接手 MySQL 的人都手动练一遍，真出事的时候再去翻文档就来不及了。

顺带提一句表空间视图，它列出的是当前实例里占用最大的几张表。磁盘告警时先看这一屏，往往能立刻找到那个被忘了清理的日志表或者临时表。这个视图不解决根本问题，但能把排查范围从「整个实例」缩到「三张表」。

4.3 账号管理与动态参数：把高频操作从命令行搬到界面

账号管理提供的是图形化的创建、删除、授权、改密。创建账号之后必须单独授权，这一步不能省，新建的账号默认没有任何库权限。授权粒度按业务需要给，常见的组合是增删改查加改表结构，对应的是 SELECT、INSERT、UPDATE、DELETE、CREATE、ALTER、DROP 这一组。给权限时遵循最小化原则，一个只读报表账号不该带上 DELETE。

动态参数配置允许在界面上修改实例的运行参数，并且会记录修改历史。修改历史这个功能的价值在于事后追溯——某个参数被谁在什么时候改过，改前改后是什么值，一目了然。参数改动影响面很大，改之前先确认这个参数是动态生效还是需要重启，需要重启的参数不要在业务时段碰。

4.4 binlog 清理与磁盘空间：删之前先确认恢复窗口

磁盘空间不足是 MySQL 实例最常见的告警之一，binlog 往往占了大部分空间。实例列表里可以对单个实例执行 binlog 清理，操作逻辑是「选中某个 binlog，该文件之前的所有 binlog 一并删除」。这个设计要格外注意：它不是删一个，是删一批。

清理之前必须先确认两件事。一是主从架构下，从库是不是已经消费完这些 binlog，删早了从库会直接断掉同步。二是数据恢复窗口，如果团队约定「可以用 binlog 恢复最近 7 天的数据」，那这 7 天内的 binlog 一个都不能少。我见过最典型的事故是磁盘告警了，值班同学看都不看选了最早的那一个，结果把当天备份恢复正好需要的那批 binlog 一起删了，磁盘是腾出来了，可恢复能力也没了。

正确的做法是先算出保留窗口对应的最早 binlog 位置，从那个位置之前的文件开始删，删完再确认磁盘水位。同时把 binlog 保留时长这个参数配好，让系统自动轮转清理，比人工盯着磁盘告警要可靠得多。

5. 落地避坑：五类最容易翻车的操作与排查

配好规则不等于跑顺流程，真正让人头疼的问题都出现在具体操作里。下面五条是这类平台落地时踩坑频率最高的，每条都按现象、原因、解决的顺序写，遇到对得上的直接照着处理。

5.1 检测通过但执行报错：规则和实例状态不同步

现象是工单在检测阶段全绿，点了执行之后返回建表失败或者字段不存在。原因通常是审核规则只看 SQL 文本本身，不校验目标实例的真实现状——表已经被别的工单改过、字段名拼写和库里的对不上、执行账号缺少对应权限，这些都不在语法解析的覆盖范围内。解决办法分两层：执行前在目标库上做一次结构确认，把涉及的表结构和工单里的假设对一遍；执行账号的权限单独建一个检查清单，新实例接入时先跑一遍，别等第一次变更失败才发现账号只给了只读。

5.2 变更打错环境：工单参数填错一个字段

现象是本该改测试库的工单落到了生产库。原因几乎都是提交时实例或库名选错，而审核人在看 SQL 内容时没有回头确认目标实例。这类问题的破坏力最大，因为它绕过了所有关于「这条 SQL 写得对不对」的检查。解决办法是把目标实例做成审核时的必看项，审核人第一眼先看实例名，再看 SQL；同时测试环境和生产环境的实例命名要有明显区分，别弄成db-01和db-01-test这种容易看串的组合。

5.3 定时任务扎堆：低峰期变成了新的高峰

现象是几个工单都设了凌晨两点执行，结果那一时段数据库负载飙高，慢查询暴增。原因很直白，所有人都把变更往同一个「业务低峰」压，低峰期被人为制造成高峰。解决办法是给定时执行排一个时间窗，同一个实例上的工单间隔至少十几分钟，或者在执行前由 DBA 统一看一遍当天的定时队列，把冲突的错开。另外，DDL 类变更和大批量 DML 不要排在一起，前者锁表、后者占 IO，叠加起来的等待时间远超预期。

5.4 把回滚语句当成万能后悔药

现象是执行出问题后想回滚，发现回滚 SQL 跑不通或者数据回不来。原因有两个：一是 Binlog2SQL 这类工具只能回滚 DML，DDL 操作无法通过解析 binlog 反向还原；二是回滚语句基于生成时刻的表结构快照，中间表结构又被改过的情况下，反向语句可能直接报错。解决办法是把回滚当成一次独立的操作来验证，测试环境先跑一遍；涉及删列、删表的变更，执行前做表级备份，别指望回滚语句兜底。

5.5 把结构同步当成数据同步

现象是用 SchemaSync 比对完两个库，执行了生成的 DDL，以为两边数据也一致了，结果业务查询报数据缺失。原因是这个工具只比对表结构，不比对数据，生成的是让目标库结构追上源库的 DDL 以及对应的回滚 SQL。解决办法是在流程里写清楚它的定位：结构同步归结构同步，数据迁移另走数据导出或者归档任务。什么人容易踩这个坑？大多是第一次用、看到「同步」两个字就想当然的人，所以接入新人的时候，这条要单独讲一次。

6. 验收与交付：怎么证明这条审核链路真的有用

方案交付的时候，最怕听到的一句话是「平台装好了」。装好和有用是两件事。验收要拿得出证据，证明这条链路确实挡下了本该被挡的东西，也确实在出问题时能救回来。我一般会按下面这张清单走一遍，每一项都要有可复现的操作和可留存的记录。

验收里最容易被跳过、但价值最高的是回滚演练。拿一条真实的 UPDATE 工单，在测试环境执行完立刻下载回滚 SQL 跑一遍，看数据是不是回到了原状。这一步花不了十分钟，但能提前暴露回滚语句失效、权限不足、表结构已变这三类问题。演练做完把回滚 SQL 和演练记录一起存档，答辩或者交付讲解的时候，这份材料比任何功能截图都有说服力。

答辩环节还有一个小技巧：不要按功能菜单一项一项讲，按「一条 SQL 从提交到执行再到回滚」的时间线讲。先说这条 SQL 进来时被哪几条规则拦了、怎么改的；再说审核人看到什么、点了什么；最后说出问题后怎么用回滚语句和会话视图把状态拉回来。评委或者主管听到的是一条完整的链路，而不是一堆孤立的功能点，这两种讲法的效果差得很远。

提示：验收前把审核规则、权限分配、定时执行时间窗这三样配好再开始演练，规则临时改来改去，验收记录就对不上号了。

讲个自己的教训。早些年推第一版审核流程，我只顾着配规则，回滚演练一次没做，结果第一次真实回滚就翻车——表结构在两次工单之间被改过，生成的回滚语句直接报字段不存在。从那以后我每次上线审核流程，都强制走一遍「提交、拦截、审核、执行、回滚」的完整演练，哪怕只有一条测试数据。流程这东西，纸上跑通不算通，真跑一遍才知道哪一环会断。希望这套结构能帮你少走一段弯路。

本文还有配套的精品资源，点击获取