简介：Archery使用手册是一份系统讲解SQL审核与查询平台Archery的实用文档，主要面向数据库管理员、开发工程师和运维人员，旨在帮助读者掌握从SQL审核、SQL优化到MySQL实例管理的完整工作流，落实日常数据库规范化与安全运维。资源为1个doc格式文档，压缩包整体约1.2MB，虽是单文件但目录结构完整、便于按需查阅。该手册已有1477人学习，内容覆盖SQL审核、SQL优化、实例管理、工具插件四大模块。审核模块支持自定义规则解析SQL语法与规范，可自动驳回高危SQL并生成回滚语句，同时支持立即执行、定时执行与钉钉通知；SQL优化模块能展示执行计划、优化建议及慢SQL统计。实例管理模块涵盖binlog清理、会话终止、锁信息排查、事务管理、账号授权与动态参数配置等实用功能；插件工具还演示了PTArchiver数据归档、Binlog2SQL回滚解析、SchemaSync结构同步等具体用法。最后结合开发与测试环境的实践案例，完整呈现SQL工单从提交、审核、执行到回滚的流程，适合需要快速上手Archery并提升数据库运维效率的读者参考。
1. Archery 到底能解决什么问题
先讲一个真实场景。某公司的开发环境里，研发顺手写了一条DELETE FROM orders WHERE create_time < '2024-01-01'，没有 limit，没有事务包裹，提交给 DBA 执行。DBA 看了一眼，高危语句直接驳回。但问题是——这句话如果发生在半夜的定时任务里，或者发生在没有 DBA 审核的小团队里，可能就直接把线上表清掉一大片。这就是 SQL 审核平台存在的意义：把“人盯人”变成“规则盯人”。Archery 定位于 SQL 审核查询平台，同时支持丰富的 MySQL 运维功能，它解决的不是“能不能连上数据库”的问题，而是“这条 SQL 能不能上、上了之后怎么回滚、出了事怎么排查”的问题。适合谁用？三类人：一是被研发频繁提交 SQL 工单的 DBA，二是需要把开发/测试环境 SQL 流程规范化的团队负责人，三是正在做数据库运维平台类毕设或课设、需要一套完整功能参考的学生。这篇方案会从总体设计、核心功能实现、工具插件、常见问题排查到验收答辩，把 Archery 的完整使用方案拆开讲透。
2. 总体架构设计：Archery 的三层结构与核心模块职责
2.1 为什么先把流程角色理清楚比部署更重要
很多团队部署 Archery 之后发现用不起来，原因往往不在工具本身，而在流程没理清。Archery 的审核流程天然带着“发起人、审核人、执行人”的角色区分，如果不先把这些角色对应到实际团队里，工具上线后只会变成“又多了一个要填的系统”。
我一般会先画一张角色表：研发工程师负责提交 SQL 文件并发起审核，项目经理或测试工程师负责审核，DBA 负责实例管理和高危操作兜底。开发环境走“研发→项目经理”两级，测试环境走“测试同事从 git 取 SQL 文件→测试同事发起审核→测试同事自己审核并执行”。这个设计的好处在于：测试环境的流程闭环在测试侧，不依赖 DBA 实时响应；生产环境的高危操作则被规则引擎拦截，必须人工介入。
提示：流程设计的原则是“让最懂业务的人发起，让最懂风险的人把关，让最接近环境的人执行”。
2.2 Archery 的模块划分与数据流
从功能模块上看，Archery 可以拆成五个核心部分：SQL 审核模块负责语法解析和规则检查；SQL 优化模块提供执行计划和慢日志分析；实例管理模块覆盖 binlog 清理、会话管理、事务与锁信息、账号管理；工具插件模块整合 PTArchiver、Binlog2SQL、SchemaSync 三个外部工具；通知模块对接钉钉，把工单状态推送给审核人。
数据流大概是这样的：研发提交 SQL 工单 → Archery 调用解析引擎做语法和规则检查 → 返回审核结果（通过/错误/驳回）→ 审核人收到钉钉通知并处理待办 → 审核通过后选择立即执行或定时执行 → 执行结果写回工单，同时生成回滚 SQL 供下载。
这里要特别说一句，Archery 的审核不是简单地“能不能执行”，而是会按自定义规则检查“建表有没有主键、表注释和列注释写没写、是不是高危语句”。也就是说，它同时管语法和规范两层。比如SELECT *这种写法在语法上完全没问题，但规范层面会被优化建议提示改成显式字段列表。
2.3 部署层面的最小化配置参考
Archery 部署起来最核心的是要有一个可用的 MySQL 实例来存元数据，以及一个能访问目标实例的账号。目标实例的账号建议只授予业务需要的权限，不要用 root。通常的做法是单独建一个archery账号，授权SELECT、INSERT、UPDATE、DELETE加上SUPER（用于终止会话），这样既能完成审核和运维操作，又不会因为权限过大带来安全隐患。
配置完成后，第一件事不是急着建工单，而是先录入实例。在“实例管理→实例列表”里添加 MySQL 实例，填好连接信息后，Archery 会自动拉取实例的基础状态。这一步做完，后续的会话管理、锁信息、binlog 清理才能在同一套界面里操作。
3. 核心功能实战：SQL 审核、SQL 优化与实例管理的落地操作
3.1 SQL 审核流程：从检测到回滚的完整链路
SQL 审核是 Archery 最核心的模块，它的设计思路是“先检测、再提交、后审核、可回滚”。实际操作里，我把这个流程拆成四个步骤。
第一步是准备好要审核的 SQL 文件。文件内容要按环境区分，开发环境由研发工程师维护，测试环境由测试同事从 git 上拉取。注意一个容易犯的错：把多条语句写在一个文件里没问题，但一定要用分号分隔，Archery 的解析引擎是按语句拆分的。
第二步是发起审核。研发工程师登录 Archery，选择目标实例，填入工单信息，然后将 SQL 文件内容粘贴或上传，点击“SQL 检测”。这里有一个关键反馈：如果检测结果是error，说明存在语法错误或硬性规则不满足，比如建表没有主键。此时需要根据提示修改 SQL 后重新检测，直到通过为止。检测通过后点击“SQL 提交”，工单进入审核队列。
第三步是项目经理审核。审核人登录后，点击右上角的通知按钮查看待办事项。审核通过后，工单状态变为待执行。这里我给一个建议：审核界面里能看到完整的 SQL 内容和检测报告，审核人不要只看待办标题就点通过，至少扫一遍 SQL 里有没有DROP、TRUNCATE、无WHERE的DELETE/UPDATE。
第四步是执行与回滚。最后一级审核通过后，可以选“立即执行”或“定时执行”。定时执行的场景一般是大表 DDL 放在低峰期，这时要注意时区设置，避免定时时间差出问题。
回滚是整个流程里最容易让新人困惑的地方。Archery 对 DML 语句会自动生成回滚 SQL，操作路径是：在已执行的工单详情里，点击“下载回滚 SQL”或“查看回滚 SQL”。但要注意：DDL 操作（比如ALTER TABLE）无法生成回滚 SQL，这在使用 Binlog2SQL 插件时也一样。所以上大 DDL 之前，我习惯先做备份或确认有最近的物理备份兜底，这是血泪经验。
注意：回滚 SQL 不是“后悔药”，它只能基于 binlog 解析还原数据变更，DDL 不在范围内。执行回滚前务必在测试环境先验证一遍。
3.2 SQL 分析与慢日志：优化建议怎么读
Archery 的 SQL 优化功能定位是“给建议，不强制改”。选中一条 SQL 后，点击分析，平台会返回执行计划和优化建议。最经典的示例是把SELECT * FROM baidd.emp WHERE ename='dan_1'改成SELECT 字段列表 FROM ...，分析结果就会从 warning 变成 OK。
这里的底层逻辑是减少回表次数和网络传输量。SELECT *在 InnoDB 引擎下如果查询列不全在二级索引里，会触发回表；而显式列出字段后，优化器有机会走覆盖索引。实际生产里，我一般会引导研发按三个层次优化：先看是不是SELECT *，再看WHERE条件里的列有没有索引，最后看 JOIN 的关联列类型是否一致。Archery 的分析报告会把执行计划展示出来，其中type字段从ALL变成ref或const就是优化生效的直接证据。
慢日志功能则更适合 DBA 使用。在实例管理里开启慢日志收集后，Archery 会定期抓取慢查询记录并做统计。观察重点有两个：一是执行频率高且平均耗时长的 SQL，这类是“慢性毒药”；二是单次执行特别长的 SQL，这类往往是没有 WHERE 条件或者 JOIN 了多张大表。慢日志的统计信息可以帮助快速定位需要优先治理的 SQL 集合。
3.3 实例管理：从清 binlog 到杀会话的排查手册
实例管理是 Archery 里 DBA 使用频率最高的模块，它把 MySQL 的运维命令图形化，降低操作门槛，但同时也要求操作者理解背后的原理。
先看 binlog 清理。场景很常见：磁盘空间告警，登录服务器一看/data分区快满了，十有八九是 binlog 堆积。在“实例列表”里选择对应实例，会看到 binlog 文件列表。选中某个 binlog 后，它之前的所有 binlog 都会被删除。这里有一个坑：如果实例配置了从库，并且从库的relay log还没应用完，提前清理 binlog 会导致主从同步中断。所以清理前先看SHOW SLAVE STATUS的Seconds_Behind_Master，确认从库追平后再操作。Archery 只是把删除动作简化了，但它不会替你做主从状态检查，这个决定必须由人来下。
再看会话管理。排查阻塞问题的标准路径是：点开“进程状态”，选择数据库实例，command 类型默认是query，先把“完整 INFO”勾选上，否则显示的 SQL 文本会被截断，看不到全貌。如果定位到某个 SQL 导致阻塞，点击“终止会话”即可。当年我第一次排查锁等待时，就是因为没勾“完整 INFO”，看到的 SQL 只有前 50 个字符，找了半天才定位到是一条漏了WHERE的UPDATE，白折腾了半小时。
事务信息和锁信息是配合使用的。在“事务信息”里能看到当前运行的事务，其中的trx_mysql_thread_id对应“进程状态”里的 THREAD ID。排查死锁或锁等待时，操作路径是：先看锁信息里哪个事务在等待（waiting），然后看它对应的trx_mysql_thread_id，再到“进程状态”里搜索该线程 ID，确认 SQL 内容后终止会话。如果看到的是“阻塞方线程 id”，那就顺着这个 id 找阻塞源头，杀掉源头才能解开等待链。
账号管理则是一个提效功能。建完账号后可以勾选权限，比如只给某应用账号SELECT、INSERT、UPDATE、DELETE，不给DDL权限；也可以修改密码、删除用户。这个模块解决的问题是：研发临时要一个测试库账号，DBA 不用再登录 MySQL 敲GRANT语句，在界面上点几下就行，而且操作记录留痕，出问题能回溯。
3.4 参数配置：动态参数修改与历史记录
实例管理的“参数配置”功能支持修改 MySQL 实例的动态参数，并且会记录修改历史。它的价值不在于“能改参数”，而在于“改了什么有据可查”。实际场景中，最常见的操作是把sql_mode调整成不带ONLY_FULL_GROUP_BY，或者把max_allowed_packet调大以支持更大的 SQL 提交。每次修改都会写入历史记录，这对于公司和安全审计场景很重要——将来如果有人问“这个参数是谁在什么时候改的”，可以直接从 Archery 里拉出记录，不用再去翻 MySQL 的日志。需要注意的是，静态参数（比如innodb_buffer_pool_size）改了不生效，需要配合修改配置文件并重启实例，Archery 界面上通常会有提示，不要误以为改了就生效了。
4. 工具插件的工程化落地：PTArchiver、Binlog2SQL、SchemaSync 的配置要点
4.1 PTArchiver：流水表归档的推荐参数写法
PTArchiver 插件的价值在于把 pt-archiver 的复杂命令行参数封装成界面化配置。典型场景是线上流水表只保留最近 3 个月的数据，3 个月前的数据归档到历史表。直接删数据有风险，因为大表DELETE会长时间锁行、产生大量 binlog；而 pt-archiver 是分批小事务地把数据搬到归档表，对线上影响小得多。
在 Archery 里配置 PTArchiver 时，核心参数有这几项：源表名、归档表名、WHERE条件、批量行数、执行方式。我一般会这样写：
pt-archiver \ --source h=实例地址,D=baidd,t=流水表 \ --dest h=实例地址,D=baidd,t=流水表_archive \ --where "create_time < DATE_SUB(NOW(), INTERVAL 3 MONTH)" \ --limit 1000 \ --commit-each \ --purge参数含义如下：--source和--dest分别指定源表和归档目标表，--where是归档的过滤条件，--limit 1000表示每批处理 1000 行，--commit-each表示每批独立提交一个事务，--purge表示从源表删除已归档的数据。不要小看--commit-each，如果去掉它，整个归档过程会变成一个超大事务，binlog 暴涨，从库延迟会非常难看。这个配置还可以保存为自动任务，Archery 支持定时触发，后续就不用人工干预了。
4.2 Binlog2SQL：把位点解析变成可视化的数据恢复手段
Binlog2SQL 插件解决的是“如何从 binlog 里找回误操作的数据”。它的交互方式很直观：选择实例和 binlog 文件，填起始位置和结束位置，点击“获取 SQL”，平台会解析出这段时间内执行的 SQL。支持三种输出模式：原始 SQL、回滚 SQL、去除主键的 INSERT SQL。
举个例子，想看master-bin.000009从位置 857 到 1183 之间的 SQL，就在界面上填这个位点范围。如果误操作是一个UPDATE，点击“--flashback”按钮再获取一次，得到的就是反向的UPDATE语句，把被改动的数据改回去。这里要强调一个使用前提：binlog 格式必须是ROW，如果是STATEMENT格式，解析出的回滚 SQL 可能不准确。Archery 不会主动告诉你 binlog 格式不对，但解析结果会跟预期不符，这个需要 DBA 心里有数。
注意：Binlog2SQL 不支持回滚 DDL。
DROP TABLE、ALTER TABLE这类操作解析不出回滚语句，只能依赖备份恢复。所以生产环境的 DDL 变更一定要走审核流程，并且提前确认备份策略，别等数据没了才想起来找后悔药。
4.3 SchemaSync：表结构比对与自动化同步
SchemaSync 是三个插件里最容易理解但最容易误用的一个。它读取源库和目标库的 schema，自动生成同步 SQL 和回滚 SQL，但只比对表结构，不比对数据。适用场景是：你的 249 库和 251 库需要保持一致的表结构，但数据可以不同——比如 249 是测试库，251 是预发库，上线前要把 251 的 schema 变更同步到 249 上跑一轮回归测试。
实际比对结果会显示：源库有哪些表、目标库缺哪些表、哪些表需要执行ALTER TABLE。生成的 SQL 分两部分：同步 SQL 用于让目标库追赶源库结构，回滚 SQL 用于变更后反悔。这个设计很实用，因为结构变更最怕的就是“改了之后想回去，却忘了原来长什么样”。SchemaSync 等于自动帮你保存了一份“结构快照”。
使用上有一个常见误用：把 SchemaSync 当成数据同步工具。如果目标是让两个库的数据一致，SchemaSync 帮不上忙，得用 pt-archiver 或专门的数据同步方案。另外，比对结果里如果出现大量差异，先别急着执行，逐条确认是不是预期的变更——我有一次比对完发现目标库少了一个索引，执行同步 SQL 时却报错，原因是源库索引名在目标库已存在但列不同，这种“同名不同列”的情况需要先手工处理掉再同步。
5. 常见问题与排查：Archery 上线后最容易翻车的五个场景
5.1 SQL 检测一直 error，但本地执行没问题
现象：研发在本地 MySQL 里执行同一条 SQL 完全正常，提交到 Archery 却报error，于是怀疑平台“误判”。
原因：Archery 的审核引擎对 SQL 的检查包含语法和规范两层，本地能执行不代表满足规范。最常见的是建表语句缺少主键或表注释、列注释，还有DELETE无WHERE条件被高危规则拦截。
解决：点击检测结果里的错误详情，看具体是语法层还是规范层。规范层问题按提示补齐主键、注释后重新检测；高危语句则要联系 DBA 调整规则或拆分语句。不要试图绕过检测，这是平台存在的意义。
5.2 回滚 SQL 生成出来执行却报错
现象：工单执行完成后下载回滚 SQL，在目标库执行时报“Unknown column”或主键冲突。
原因：生成回滚 SQL 和实际执行之间有时间差。如果这期间表结构被其他工单改了，回滚 SQL 里引用的列可能已不存在。另一种情况是回滚 SQL 里包含主键值，而目标表中已有插入相同主键的数据。
解决：回滚之前先对比当前表结构和回滚 SQL 的字段列表。主键冲突的话需要先清理后续插入的数据，或者改用 Binlog2SQL 按更精确的位点重新生成回滚语句。一句话：回滚 SQL 执行前，把目标表现状拍个照。
5.3 清理 binlog 后从库同步中断
现象：磁盘告警后清理了 binlog，没过多久从库告警Got fatal error 1236，主从同步中断。
原因：从库还没应用完被清理的 binlog。Archery 的 binlog 清理是“选中某个 binlog 后，之前的全部删除”，它不感知从库消费进度。
解决：清理前通过SHOW SLAVE STATUS确认从库Seconds_Behind_Master=0，或确认所有从库的Master_Log_File和Exec_Master_Log_Pos都超前于要删除的位点。如果已经中断，且被删的 binlog 还有备份就用备份补，没有备份就得重新做从库。从那以后，我每次清理 binlog 之前都强制看一眼从库状态，哪怕只花十秒钟。
5.4 终止会话时杀错了进程
现象：排查锁等待时，在“进程状态”里搜到一个疑似阻塞源头的线程，直接终止，结果发现杀的是业务核心查询，反而引发更大范围超时。
原因：锁等待的阻塞方不一定就是执行时间最长的那个，也可能是某个持有锁但处于 sleep 状态的事务。只看Command为Query的进程容易漏掉真凶。
解决：先切到“事务信息”看trx_mysql_thread_id和事务状态，再结合“锁信息”里的等待关系判断。Lock 信息里标明了等待事务和被等待的线程 id，按那个 id 去找进程才相对准确。杀掉之前再看一眼这条 SQL 属于哪个应用，确认不影响核心链路再动手。
5.5 定时执行的任务没有按预期触发
现象：设置了凌晨 2 点定时执行 DDL，早上来发现工单还是“待执行”状态。
原因：Archery 所在服务器时区和目标实例时区不一致，或者定时任务依赖的调度进程没启动。后者在重启服务器后尤其常见。
解决：统一服务器和目标实例的时区，检查任务调度服务是否在运行，然后手动触发一次验证链路。定时执行这种功能，上线前一定要用一条无害 SQL（比如SELECT 1工单）测一遍完整流程，不要等到真正需要时才第一次用。
6. 方案验收与答辩：怎么让这套 Archery 方案经得起追问
验收的核心是“把流程走一遍，把证据留一份”。我建议按三个层次准备：环境准备、功能验证、故障演练。
环境准备阶段，准备好一个开发实例和一个测试实例，两个实例里预置一张带主键、带注释的业务表，再准备两条 SQL——一条合规的INSERT，一条带DELETE无WHERE的高危语句，用来验证审核拦截能力。
功能验证阶段，按这个清单逐项演示：走一遍“发起检测→提交→审核→立即执行→下载回滚 SQL”的完整工单链路；用SELECT *和显式字段两条等价 SQL 分别做优化分析，对比执行计划差异；在测试实例上模拟一个锁等待场景，用 Archery 查看锁信息并终止会话。每个动作都截图留底，答辩时直接按截图讲，比现场操作稳得多。
故障演练最关键，模拟三个场景：模拟一个无WHERE的UPDATE工单被驳回，演示规则拦截；模拟两个事务互相锁等待，演示定位和终止；用 Binlog2SQL 解析一段 binlog 生成回滚 SQL，演示数据恢复链路。演练过程中把日志和输出保存下来，答辩时有人质疑“能不能真回滚”，直接展示生成的回滚 SQL 和执行结果，比说十句都有用。
这里给一个答辩技巧：讲到 SQL 审核流程时，主动画出“研发→项目经理→执行→回滚”的链路，强调“不仅管上线，还管反悔”；讲到实例管理时，主动把事务的trx_mysql_thread_id和进程状态的 THREAD ID 对应关系讲出来，这一句就能证明你真操作过，而不是念文档。这些细节在验收报告里对应“功能完整度”一节，逐条列出验证结果，验收人不需要自己摸索就能判断方案是否成立。
最后说一个习惯。Archery 这类 SQL 审核平台，最大的价值不是把审核人换掉，而是让每次变更都有记录、可追溯、能回滚。从那以后，我每次给团队交付这类平台方案，都强制自己走一遍“从提交到回滚”的完整闭环再写验收报告，即使时间紧张，也至少跑通一条UPDATE的工单和一条 binlog 回滚链路。因为一次没跑通的流程，放在线上就是一次事故；而跑通一次，你就知道这套方案在真实环境里靠不靠谱。希望这篇方案能帮你把 Archery 用明白，也祝你的项目上线顺顺利利。
本文还有配套的精品资源，点击获取
