简介《archery使用手册》面向数据库开发人员、DBA及运维工程师聚焦SQL审核查询平台Archery的落地使用帮助读者系统掌握从SQL审核、优化到实例监控的完整流程。资源包内含1个doc文档压缩包约1.2MB以图文并茂的方式组织内容便于按章节查阅与实操对照。手册围绕Archery核心能力展开SQL审核部分讲解语法解析、自定义规则、高危语句驳回及定时执行与钉钉通知SQL优化部分介绍执行计划分析与慢SQL统计实例管理部分覆盖binlog清理、会话与事务管理、锁信息排查、账号授权及动态参数配置工具插件部分则涉及PTArchiver数据归档、Binlog2SQL回滚解析与SchemaSync结构同步。此外还给出开发与测试环境的SQL审核流程示例以及回滚SQL、锁等待模拟等实践场景。目前已有1477人学习适合希望提升数据库管理效率与安全性的技术人员参考。1. 从一次 SQL 审核翻车说起archery 到底解决什么问题很多团队第一次接触 archery都是因为同一个场景开发同学在群里丢过来一句“帮我执行下这个 SQL”然后附上一段没有 WHERE 条件的 UPDATE。DBA 看了一眼血压上来了。更麻烦的是这条 SQL 到底有没有人审过、谁审的、什么时候执行的、执行结果如何全靠聊天记录回溯。archery 就是在这个环节里被拉进来的——它是一套面向数据库的 SQL 审核与查询平台把“提 SQL、审 SQL、执行 SQL、查 SQL”这条链路收进一个 Web 界面里让每一次数据库操作都有记录、有审批、有回滚依据。它适合谁中小团队的 DBA、后端负责人、运维同学以及那些没有专职 DBA 但又要管好几套数据库的研发团队。你不需要一上来就把它当成企业级数据库管控平台完全可以先把它当成一个“带审核流程的 SQL 客户端”来用。这篇手册不讲虚的按我实际部署和踩坑的顺序从环境准备、核心配置、工单流程、查询权限一路写到怎么排查它最常见的几个翻车点。看完你至少能判断这套东西值不值得在你团队里落地以及落地时哪些参数必须先调对。2. 部署前必须想清楚的选型与依赖archery 装在哪、连什么2.1 为什么 archery 的部署方式选择比安装步骤更重要archery 本身是一套 Python 写的 Django 应用前端走 Web后端依赖 MySQL 存元数据、Redis 做缓存和队列。很多人一上来就照着安装脚本跑结果跑完发现元数据库和业务库混在一起、Redis 和别的服务抢端口、审计日志写满磁盘。这些问题不是安装脚本的 bug是部署前没做选型。我一般会先把 archery 拆成三个部分来看元数据存储、运行时依赖、被管理的目标库。元数据存储建议单独给一个 MySQL 实例或至少一个独立 schema不要和业务库共用因为 archery 自己会频繁读写工单、审核记录、查询日志IO 压力不小。运行时依赖里 Redis 是必须的用来做异步任务队列和会话缓存版本不要太老否则某些异步执行 SQL 的任务会卡住。被管理的目标库就是你要通过 archery 去审核和查询的那些数据库它们和 archery 之间是网络可达关系不需要装 agent。提示如果你的目标库跨网段或跨环境先把网络连通性和账号权限确认清楚archery 连不上目标库时报错信息往往只显示“连接失败”不会告诉你具体是防火墙还是密码错。2.2 最小依赖清单与版本选择思路下面这张表是我在多个环境里总结出来的依赖清单版本不写死只写选择思路因为不同操作系统和 Python 版本下可用的组合不一样。组件作用选择思路Python运行 archery 主程序用 3.8 到 3.10 之间的稳定版太新的版本某些依赖包还没跟上MySQL存 archery 元数据5.7 或 8.0 均可字符集用 utf8mb4单独 schemaRedis异步队列和缓存5.0 以上设置好最大内存和淘汰策略别让它把内存吃满Nginx反向代理和静态文件可选但建议加直接暴露 Django 的 runserver 只适合本地调试目标数据库被审核和查询的库MySQL、PostgreSQL 等常见类型按 archery 支持的实例类型添加安装方式上常见做法是源码部署或容器化部署。源码部署可控性高适合需要改配置和二次开发的场景容器化部署起步快但元数据和日志的持久化要提前规划好挂载卷。我一般会先在测试环境用容器跑一遍确认功能符合预期再在生产环境用源码部署把配置项逐个过一遍。2.3 初始化配置里最容易忽略的三个参数装完之后第一件事是改配置文件里面有几个参数直接决定后面用起来顺不顺。# archery 配置文件片段示意具体字段名以实际版本为准 # 数据库连接指向 archery 自己的元数据库 DATABASES { default: { ENGINE: django.db.backends.mysql, NAME: archery, # 元数据库名建议独立 USER: archery_user, PASSWORD: 强密码, HOST: 127.0.0.1, PORT: 3306, OPTIONS: {charset: utf8mb4}, } } # 异步任务队列指向 Redis CELERY_BROKER_URL redis://127.0.0.1:6379/0 CELERY_RESULT_BACKEND redis://127.0.0.1:6379/1 # 查询超时单位秒控制单次查询最长执行时间 QUERY_TIMEOUT 30 # 工单审批流是否开启多级审核 ENABLE_MULTI_LEVEL_AUDIT True这段配置里QUERY_TIMEOUT和ENABLE_MULTI_LEVEL_AUDIT是最容易拍脑袋设的。查询超时设太大一个慢查询能把 Web 进程拖住设太小正常的大表统计又跑不完。我一般从 30 秒起步观察一段时间查询日志后再调。多级审核开关则取决于团队规模三五人的小团队开一级审核就够了人多了再考虑按库或按实例分审核人。参数改完记得重启 archery 的 Web 进程和 Celery worker只重启 Web 不重启 worker 的话异步任务还是会用旧配置跑这个坑我踩过不止一次。3. 把第一个数据库实例接进来实例配置与连通性验证3.1 添加实例前要准备的账号权限archery 连接目标库用的账号权限给多少是有讲究的。给太大等于把整个库交给平台给太小审核和查询功能又会报权限错误。我的习惯是分两个账号一个查询账号只给 SELECT 权限用于线上查询功能一个审核执行账号给到 DDL 和 DML 权限但只限于工单执行时使用。-- 在目标 MySQL 上创建 archery 查询账号只读 CREATE USER archery_ro% IDENTIFIED BY 强密码; GRANT SELECT ON your_business_db.* TO archery_ro%; FLUSH PRIVILEGES; -- 创建审核执行账号按需给权限不要直接给 ALL CREATE USER archery_rw% IDENTIFIED BY 另一个强密码; GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, INDEX ON your_business_db.* TO archery_rw%; FLUSH PRIVILEGES;这里的关键点是查询账号和执行账号分开这样即使查询功能被滥用也不会造成数据被改。GRANT后面的库名按实际业务库替换不要图省事写成*.*。如果目标库是云数据库还要确认云平台的白名单里加了 archery 服务器的出口 IP。3.2 在 archery 里录入实例并测试连接登录 archery 后台找到实例管理入口新增实例。需要填的信息包括实例名称、类型、连接地址、端口、刚才创建的两个账号。填完之后点测试连接这一步会分别验证查询账号和执行账号的连通性。如果测试连接失败按这个顺序排查先确认 archery 服务器能不能 telnet 通目标库端口再确认账号密码有没有多余空格最后看目标库的user表里 host 字段是不是%或者包含了 archery 的 IP。我遇到过最隐蔽的一次是密码里有个特殊字符在配置文件里被转义了导致连接一直失败后来把密码改成纯字母数字组合才通过。3.3 资源组与权限组的绑定关系实例加进来之后还要把它挂到资源组里再把资源组授权给用户或用户组。archery 的权限模型是用户 → 资源组 → 实例/库/表。这个链路少一环用户就看不到实例。常见做法是按业务线建资源组比如“订单业务组”“用户业务组”每个组里放对应的实例和库。然后把研发同学按业务线分到不同的用户组授权对应的资源组。这样新同学入职时只要加进用户组就能看到自己业务线的库不用一个个实例去配。注意资源组授权时查询权限和执行权限是分开控制的。只给查询权限的用户能查但不能提交工单执行需要执行 SQL 的同学要额外给工单权限。4. SQL 工单从提交到执行审核流程与上线操作4.1 工单流程的四个阶段archery 的工单流程大致分四步提交工单 → 审核 → 执行 → 完成/回滚。提交时用户选择目标实例和库粘贴 SQL系统会自动做语法检查和规则审核。审核阶段审核人可以看到 SQL 内容、影响行数预估、以及规则引擎给出的风险提示。执行阶段archery 会把 SQL 发到目标库执行并记录执行结果。完成之后工单归档可以随时回看。这个流程里规则审核是 archery 比较有价值的部分。它内置了一批 SQL 审核规则比如“禁止不带 WHERE 的 UPDATE/DELETE”“禁止 DROP TABLE”“建议索引命名规范”等。规则可以在后台按实例或按库配置也可以自定义。4.2 配置一条自定义审核规则下面以“禁止对超过 100 万行的表做全表 UPDATE”为例说明规则配置的思路。不同版本的 archery 规则配置界面可能不同但核心逻辑一致定义匹配条件、定义风险等级、定义提示信息。# 规则配置示意伪代码实际在 Web 界面操作 { rule_name: 大表全表更新拦截, rule_type: sql_check, match: UPDATE 语句且 WHERE 条件为空或恒真, table_rows_threshold: 1000000, risk_level: high, action: block, # block 表示直接拦截warn 表示只提示 message: 目标表行数超过阈值禁止无有效 WHERE 条件的 UPDATE }这里action设成block还是warn取决于团队对风险的容忍度。我一般对 DELETE 和 UPDATE 设block对 SELECT 设warn。table_rows_threshold这个阈值不要设太小否则正常的小表维护也会被拦审核人会被烦到直接关规则。4.3 执行工单时的几个关键操作审核通过后执行工单时 archery 会做几件事检查目标库连接、拆分 SQL 语句、逐条执行、记录每条的执行时间和影响行数。如果中间某条失败后面的语句是否继续执行取决于工单配置里的“遇错终止”选项。我建议把“遇错终止”打开。否则一条 SQL 失败后后面的继续跑可能造成部分数据被改、部分没改回滚起来非常麻烦。执行完成后工单详情页会显示每条 SQL 的执行结果这个页面是后面排查问题的第一手资料别随手关掉。提示执行大表 DDL 时archery 本身不提供在线 DDL 工具的能力它只是把 SQL 发下去。如果目标库不支持在线 DDL还是会锁表。这种情况要提前和业务方约时间窗口或者用目标库自带的在线 DDL 方案。5. 查询功能与权限隔离让研发自助查数但不越界5.1 查询页面的权限控制逻辑archery 的查询功能是很多团队最常用的部分。研发同学不用登录数据库直接在 Web 上选库选表、写 SELECT、看结果。但“能查”和“能查什么”是两回事。archery 的查询权限控制到库和表级别可以在资源组里配置某个用户组只能查哪些库。配置的时候注意查询权限和工单权限是独立的。一个用户可以有查询权限但没有工单权限这样他能看数据但不能改数据。对于大部分研发同学我建议只给查询权限工单权限留给 Tech Lead 或 DBA。5.2 查询结果导出与脱敏查询结果支持导出 CSV 或 Excel这个功能很方便但也容易出事。手机号、身份证号、地址这类敏感字段如果直接导出等于把数据泄露风险放大了。archery 支持在字段级别配置脱敏规则查询结果里对指定字段做掩码处理。-- 在 archery 里配置脱敏字段的示意实际在界面配置 -- 对 user 表的 phone 字段查询结果只显示前三位和后四位 -- 配置项tableuser, columnphone, mask_typemobile脱敏规则配好之后即使是 DBA 查询结果里也是脱敏后的数据。如果确实需要看明文可以走单独的审批流程或者用专门的脱敏豁免权限。这个机制在合规检查时非常有用。5.3 查询审计日志怎么看每一次查询archery 都会记录谁查的、什么时候查的、查了哪个库哪张表、SQL 是什么、返回了多少行、耗时多久。这些日志在排查“谁把数据库查挂了”或者“谁导出了敏感数据”时是唯一的依据。我一般会定期看两个指标单次查询返回行数和查询耗时。返回行数异常大的查询往往是忘了加 LIMIT耗时特别长的查询可能是缺索引或者锁等待。这两个指标在查询日志页面都能筛出来。6. 避坑与排查archery 用起来最常翻车的五个地方6.1 工单执行成功但数据没变现象工单显示执行成功但去目标库查数据还是旧的。原因最常见的是执行账号连到了从库或者目标库配置了读写分离archery 连的地址实际指向只读实例。解决检查实例配置里的连接地址确认指向主库如果是云数据库确认读写分离的代理地址没有配错。6.2 查询页面报“连接超时”但目标库正常现象archery 查询页面一直转圈最后报连接超时但用客户端直连目标库是好的。原因archery 服务器到目标库的网络不通或者 Redis 队列堵住了查询任务排不进去。解决先在 archery 服务器上 telnet 目标库端口再看 Celery worker 的日志确认队列有没有积压。如果是 Redis 内存满了清理或扩容 Redis。6.3 审核规则不生效现象明明配了“禁止无 WHERE 的 UPDATE”但提交工单时还是能提交。原因规则没有绑定到对应的实例或库或者规则的优先级被其他规则覆盖了。解决检查规则的绑定范围确认目标实例在规则生效范围内再看规则列表的排序优先级高的规则先执行。6.4 用户看不到实例现象新同事登录后实例列表是空的。原因用户没有加入对应的用户组或者用户组没有绑定资源组。解决按“用户 → 用户组 → 资源组 → 实例”这条链路逐级检查缺哪环补哪环。6.5 执行大 SQL 导致 archery 自身卡死现象提交了一个几万行的 INSERT 或一个大表 ALTERarchery Web 界面卡住其他工单也提交不了。原因archery 的 Web 进程和 Celery worker 资源有限大 SQL 占满了连接池或内存。解决给 Celery worker 单独部署、限制并发数大 SQL 拆成小批次执行在配置里调大超时时间的同时监控 archery 服务器本身的资源使用。7. 进阶技巧用 archery 的开放接口做自动化巡检archery 除了 Web 界面还提供了一套 HTTP 接口可以用来做自动化。我常用的一个场景是每天定时拉取前一天的所有工单和查询记录生成一份巡检报告推送给团队。这样不用每天登录后台翻日志异常情况会自动浮出来。import requests import json from datetime import datetime, timedelta # archery 接口地址和认证信息按实际环境替换 BASE_URL http://archery.internal.example.com API_TOKEN your_api_token def fetch_audit_logs(start_date, end_date): 拉取指定时间范围内的查询审计日志 url f{BASE_URL}/api/v1/query/audit/ headers { Authorization: fToken {API_TOKEN}, Content-Type: application/json } params { start_time: start_date.strftime(%Y-%m-%d %H:%M:%S), end_time: end_date.strftime(%Y-%m-%d %H:%M:%S), page_size: 100 } resp requests.get(url, headersheaders, paramsparams, timeout30) resp.raise_for_status() return resp.json() def summarize(logs): 统计高风险查询返回行数超过 10000 或耗时超过 10 秒 high_risk [] for item in logs.get(results, []): if item.get(row_count, 0) 10000 or item.get(duration, 0) 10: high_risk.append({ user: item.get(user), db: item.get(db_name), sql: item.get(sql)[:200], rows: item.get(row_count), duration: item.get(duration) }) return high_risk if __name__ __main__: end datetime.now() start end - timedelta(days1) logs fetch_audit_logs(start, end) risky summarize(logs) print(json.dumps(risky, ensure_asciiFalse, indent2))这段脚本的逻辑很直白调接口拿日志按行数和耗时筛出高风险查询打印出来。API_TOKEN在 archery 后台的用户设置里生成权限和该用户一致所以建议用一个专门的巡检账号只给查询日志的读取权限。page_size不要设太大接口有分页限制设 100 到 500 之间比较稳。拿到这份报告后我会重点关注两类一是同一个人短时间内反复查同一张大表可能是缺索引或者业务逻辑有问题二是返回行数特别大的查询可能是忘了加 LIMIT或者在做全量导出。这两类问题在巡检报告里一眼就能看出来比事后翻日志效率高得多。我自己用这套脚本跑了半年多最大的教训是接口返回的字段名在不同版本里可能微调脚本里最好加一层字段兼容别硬编码。另外巡检账号的 token 不要写死在脚本里用环境变量传进去避免泄露。希望帮到你。本文还有配套的精品资源点击获取