
简介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 enamedan_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实例地址,Dbaidd,t流水表 \ --dest h实例地址,Dbaidd,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_Master0或确认所有从库的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 用明白也祝你的项目上线顺顺利利。本文还有配套的精品资源点击获取