Archery SQL审核平台实践：部署、规则配置与工单流转避坑指南

简介Archery是SQL审核与查询平台同时提供丰富的MySQL运维功能。本手册面向数据库开发人员与DBA系统讲解SQL审核规范、执行方式、回滚SQL、钉钉通知以及SQL优化、慢日志分析、binlog清理、会话与事务管理、账号和参数配置等实用功能。手册结合实践案例详细演示开发与测试环境的SQL审核流程、优化建议生成、阻塞排查与锁信息处理并介绍PTArchiver数据归档、Binlog2SQL解析、SchemaSync结构同步三个插件帮助读者在真实场景中灵活运用。资源为1个doc文档压缩包约1.2MB内容按功能介绍与实战案例组织便于按需查阅。目前已有1476人学习下载适合正在引入或使用Archery的团队参考。手册配有完整操作步骤和示例可帮助读者快速上手在业务中落地自动化SQL审核与数据库运维提升效率与安全性。1. Archery是什么SQL审核平台的定位与解决问题先设想一个场景你负责的MySQL实例已经有几十个业务接入每周的变更工单排着队等审核。开发提交上来的SQL有的忘了where条件有的在几亿行的大表上直接加列还有的干脆把索引删了重建。你把规则在群里发了一遍又一遍嘴上说着“注意点啊”结果该踩的坑一个没落下。等出了线上故障翻半天查不到是谁在什么时间执行了什么语句。Archery就是冲着这个痛点来的它把SQL审核、上线执行、查询审计、权限管理这一套DBA日常操作做成了统一平台。开发提交SQL工单系统自动按规则跑审核DBA在线看结果、给意见审核通过后点了执行由平台统一操作全程留痕。适合那些已经过了“一把梭”阶段、想把数据库变更管起来的团队——不管你是专职DBA还是后端同学兼职管库Archery都能把“人肉审核、口头沟通”变成“工单化、平台化”。2. 部署Archery用Docker Compose拉起最小可运行环境2.1 为什么选Docker Compose而不是源码部署Archery官方提供了源码部署和容器化两种方式。我接触过的大多数团队最后都走Docker Compose原因很现实Archery依赖的组件比想象中多除了自身的Web服务还得有MySQL存元数据、Redis存会话和异步任务。源码部署意味着你还要自己处理Python环境、pip依赖、Node前端构建光是版本对齐就能耗掉半天。容器化之后一台2核4G的机器就能跑起来先让流程通起来后面再慢慢加固。常见做法是套一个nginx反代放在前面但第一天上手没必要。直接在服务器上装好Docker和docker-compose-plugin然后拉一份Archery的docker-compose.yml。如果你已经用docker方式管理其他服务这个方案几乎不用额外学习成本。2.2 最小拓扑MySQL Redis Archery三个容器一份能用的docker-compose.yml长这样。我建议按你自己的镜像仓库地址替换image字段版本Tag选稳定版即可不要追最新。version: 3 services: mysql: image: mysql:5.7 container_name: archery-mysql environment: MYSQL_ROOT_PASSWORD: archery-root-pass MYSQL_DATABASE: archery volumes: - ./mysql-data:/var/lib/mysql ports: - 3307:3306 command: --character-set-serverutf8mb4 --collation-serverutf8mb4_unicode_ci redis: image: redis:6 container_name: archery-redis ports: - 6380:6379 volumes: - ./redis-data:/data archery: image: archerysec/archery:latest container_name: archery-app depends_on: - mysql - redis ports: - 8000:8000 environment: MYSQL_HOST: mysql MYSQL_PORT: 3306 MYSQL_USER: root MYSQL_PASSWORD: archery-root-pass REDIS_HOST: redis REDIS_PORT: 6379 REDIS_DB: 0 DJANGO_SECRET_KEY: your-random-secret-key用docker compose up -d启动后先去容器里确认两个依赖的连通性登录到archery容器里尝试连mysql和redis通了再继续初始化。这段逻辑值得停下来解释Archery本身是一个Django应用启动时会先做数据库迁移如果MySQL没就绪初始化过程会直接报错退出。所以depends_on只能保证启动顺序不能保证MySQL可用。我一般会加一个健康检查或者干脆启动后睡30秒再初始化。参数方面注意三点。第一mysql端口我映射到宿主的3307、redis到6380是不想跟宿主机已有的实例冲突你自己按环境改。第二MYSQL_DATABASE: archery会自动建库但Archery需要的是它的管理库不是业务库别把同一个MySQL既当存储又当审核目标。第三DJANGO_SECRET_KEY随便生成一段长字符串不要用默认值。2.3 初始化流程迁移脚本、创建管理员、打开页面容器起来之后需要手工执行建表和初始数据导入。Archery官方把这一步放在容器内完成命令如下docker exec -it archery-app /bin/bash cd /opt/archery source /opt/venv/bin/activate python3 manage.py makemigrations sql python3 manage.py migrate python3 manage.py createsuperuser这里每一条命令各司其职。makemigrations sql只会为sql这个应用生成迁移文件Archery把工单、审核历史这些模型都放在sql应用下migrate是真正把表结构落到MySQL里同时会把内置的菜单、权限点、默认配置项一并初始化。createsuperuser会交互式问你用户名、邮箱、密码这个账号就是后续登录管理后台的入口。初始化完成后浏览器访问http://服务器IP:8000用刚创建的账号登录进入的就是Archery的主界面左侧是工单列表、SQL审核、查询、资源组这些菜单。到这一步最小环境就通了。如果你看到页面能打开但样式加载不出来多半是容器里静态文件没collectArchery比较老的版本有这个问题新版本基本都处理了。3. SQL审核规则配置把公司规范变成平台规则3.1 审核规则从哪来从检查项到规则模板Archery的SQL审核能力核心是基于goInception做语法解析和规则检查。goInception是一个独立的SQL审核工具Archery通过RPC接口把提交的SQL语句送过去等它返回一个JSON格式的检查报告再把报告展示到前端。这就解释了为什么Archery部署时要多一个组件——它自己不做语法分析只做流程编排和结果展示。规则模板的概念是goInception内置了几十种检查项从“禁用的语法”“表名大小写”“索引数量限制”到“影响行数预估”每一项可以单独开关。Archery把这些检查项组织成“模板”一个模板绑定一个环境实例比如“生产库用严格模板”“测试库用宽松模板”。模板里还可以配置审核级别的阈值比如max_tables_count设置为30超过就报错max_keys_count设置5业务说“我要建8个索引”直接打回。3.2 配置一个可用的SQL审核规则模板我们以最常见的MySQL生产库为例说清楚怎么配。登录Archery后台在“系统管理”菜单下找到“审核规则”或“goInception参数”不同版本菜单位置略有差异但逻辑一样。你会看到一长串参数项不是每一项都值得动我一般只调这几个参数建议值说明max_update_rows1000单条UPDATE影响行数超过1000直接拒绝max_select_rows100000SELECT返回行数上限防止全表扫描拖垮业务check_table_nameON强制表名小写且不能带保留字check_autoincrementON检查自增列是否设置了合理的初始值enable_pk_ukON强制每张表必须有主键或唯一键max_index_keys5单表索引数上限超出报错保存模板之后注意要把“资源组”和“实例”绑定到这套模板上。算是Archery设计里容易绕晕的地方实例是物理的MySQL连接串资源组是权限边界模板是规则集三者通过关联关系协作。新加入的数据库实例如果没绑定模板审核结果会走默认值可能比你的预期宽松得多。这是一个常见盲区。配置完成后可以做一个验证提交一条会造成全表更新的SQL比如update user_info set status 1;看审核结果是否命中行数限制。如果命中说明规则已经生效。3.3 资源组与权限谁能提交、谁能审核、谁能上线Archery的权限模型大致可以理解为三层用户、资源组、角色。用户就是登录账号资源组是逻辑边界一般按“业务线/应用”划分比如“订单中心实例组”“用户中心实例组”角色决定了你能干什么——只读查询、提交工单、审核工单、执行上线、管理员。DBA通常属于“审核执行”角色开发属于“提交查询”角色这样各司其职。配权限时值得注意的一个坑是Archery对“查询”和“工单”走的是两套权限体系。查询权限绑定在你个人账号上按资源组授权授权后才能看到对应实例的“查询”入口工单提交流程则受“资源组-用户组”关联约束。如果不小心只配了查询权限没配工单权限开发会发现能查数据但提不了变更工单。这个阶段的目标是把“规则集”和“人”对应起来——哪些实例用严格规则哪些人负责审核哪些人只能执行。配清楚后后续的工单流转才有意义。4. 从提交到上线走通一次SQL变更工单4.1 流程引擎提交、审核、执行三段状态Archery把一次SQL变更拆成“提交申请→DBA审核→平台执行”三段每一段都有独立的状态和操作入口。开发提交一个工单后工单进入“待审核”状态DBA打开看审核报告没问题就点“审核通过”有问题的写上修改意见打回。审核通过的工单进入“待执行”状态由有执行权限的人在工单操作区选择“执行”或“定时执行”。执行完成之后平台返回执行日志包括每一条SQL的ROW_COUNT和影响行数。这套流程本身没有特别新颖的地方关键在于Archery把“谁在什么时候做了什么操作”全程都记下来了。从提交人、审核人到执行人每一步都有时间戳和操作记录后续回溯问题时直接翻工单省去了“你跑一下binlog看看”这种低效沟通。4.2 走通一条工单从SQL提交到执行回显假设业务同学要在一张名为user_wallet的表上新增一个字段。在Archery界面里步入“SQL审核”菜单选择目标实例填写变更说明然后在SQL输入框里粘贴下面这条语句ALTER TABLE user_wallet ADD COLUMN total_bonus DECIMAL(12,2) NOT NULL DEFAULT 0.00 COMMENT 累计红包金额;提交后Archery会把这条语句送到goInception做语法解析和规则检查。审核结果出来会逐条列出语句语法是否正确是否命中表名规范是否涉及大表DDL风险影响行数预估是多少。正常情况下系统会提示“审核通过”或给出一个风险等级。审核通过后DBA在“我的待办”里找到这个工单点击“通过”然后到工单详情页点击“执行”。执行页面上可以选择“直接执行”或者“定时执行”我建议第一次使用先选直接执行方便观察返回结果。执行完成后界面会返回类似下面的执行回显执行结果 【1】ALTER TABLE user_wallet ... ROW_COUNT 0, 执行成功 耗时: 120ms到这里一次最小流程就跑通了。你回头看整个过程会发现开发没有直连生产库的账号所有变更动作都发生在Archery平台内平台账号和数据库账号分离中间多了一道有审计的隔离层。4.3 查询审批与脱敏读权限怎么收敛Archery的“查询”功能容易被当成一个普通的在线SQL执行工具用但它真正的价值在于可控的在线查询。运维同学可以在“查询”入口里直接写SELECT语句平台会记录查询人、查询语句、执行时间和返回行数。同时支持脱敏配置——比如身份证、手机号这些字段可以配置成只看前几位和后几位防止敏感数据在界面上完整暴露。脱敏配置在实例级别的“敏感字段设置”或者管理后台的“脱敏规则”里维护。常见做法是把常用的敏感列名配置成脱敏模式比如手机号字段统一脱敏为138****1234。需要注意的一点是Archery的脱敏是展示层的脱敏——SQL结果集返回后前端做处理而非SQL解析时拦截。这意味着通过Archery API直接拿结果的方式不受脱敏约束有高安全要求的团队需要再评估一层面。如果你所在的团队还没有数据库查询的统一入口Archery这一步相当于把“裸奔的数据库客户端”收拢成了可审计的在线工具。查询即留痕这六个字在后续追责和合规检查时能省掉大量麻烦。5. 避坑Archery部署与使用中常见的5个问题5.1 启动后前端页面打不开或样式错乱现象docker compose up -d之后8000端口能连通但返回的是空白页或纯文本。原因Archery的Django应用需要在启动时collectstatic收集静态文件同时需要检查前端静态文件是否挂载到容器内正确路径。部分版本镜像中静态文件打包不完整或者启动脚本没执行这一步。解决进入容器手动执行静态文件收集然后重启容器。docker exec -it archery-app /bin/bash cd /opt/archery python3 manage.py collectstatic --no-input exit docker restart archery-app这里尤其要留意如果用了自定义的STATIC_ROOT路径需要确认该路径已挂载到宿主机卷否则重启后静态文件又丢失。5.2 审核结果“永久待审核”或超时现象提交SQL后审核状态一直停在“等待审核中”等几分钟也没结果。原因Archery调用goInception的RPC接口是同步的如果goInception服务没有正确注册或网络不通审核请求会挂起。另一个常见原因是Redis连接异常请求队列没有正常触发。解决先看Archery后端的worker日志。如果是RPC连接问题检查goInception的地址和端口是否配置正确如果是Redis的问题重新确认REDIS_HOST和REDIS_PORT。一个隐蔽的坑是Redis密码——如果Redis设置了密码而配置里没写整个异步任务链表面正常但实际全部失败。5.3 原有数据库账号与平台账号混用现象通过Archery执行工单时报权限不足但用同样的账号在命令行里可以执行成功。原因平台执行语句时使用的不是你自己配的数据库账号而是实例连接串里配置的账号。比如你的实例连接串用的是archery_ro只读账号那工单里的UPDATE和DDL自然执行失败。解决为Archery配置独立的数据库账号并授予它SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, INDEX等权限同时单独配置查询账号给只读场景。设计职责分离时可以配两个实例连接一个只读实例给“查询”功能用一个读写实例给“工单执行”用。5.4 工单通过但执行时翻车DDL锁表导致业务超时现象一条ALTER TABLE在生产库执行后业务写入超时报警。原因Archery默认在事务内执行DDLMySQL 5.7及更早版本里ALTER TABLE会锁表虽然执行时间短但大表上锁的时间足以让一批写入请求堆积。解决在Archery的实例配置里打开“执行参数”选项给DDL语句加ALGORITHMINPLACE, LOCKNONE。这类MariaDB特有的语法选项需要确认你的审核链路支持否则会被goInception拦截。对超大表我倾向于把变更拆成小批次或者先加列再统一刷数据而不是靠平台一口气执行完整DDL。5.5 升级版本后原有工单查询报错现象从旧版本升级到新版本后历史工单打开显示异常或工单列表打不开。原因Archery升级通常涉及数据库迁移部分版本对表结构做了较大调整。如果升级前没有备份或者跳过了中间版本迁移脚本可能不完整。解决升级前备份Archery的元数据库并且按版本号逐级升级不要从1.x直接跳到2.x。备份命令很简单mysqldump -h127.0.0.1 -P3307 -uroot -p archery archery_backup_$(date %Y%m%d).sql恢复时用同一份文件导入即可。升级完成后建议跑一遍现有的审核规则模板因为新版本有时会重置某些系统配置。6. 从会用到用好巡检、权限收敛与工具链整合6.1 每天早上看什么三个巡检维度Archery上线后我对它的定位不是“装完就完事”而是把它当成每天打开的第一个平台。我一般会看三块内容昨天提交的SQL工单审核通过率、待办里有没有滞留的审核任务、资源组里哪些实例的账号权限有变动。通过率能反馈出开发整体的SQL书写质量滞留待办意味着流程断点可能是审核人请假但没做好工作交接也可能是工单状态卡住了需要人工介入调整。Archery自带简单的数据统计页面能看到工单数量趋势、审核耗时分布但维度有限。有自动化习惯的团队可以把Archery的MySQL元数据库接进Grafana做一些自定义看板。我个人觉得数值不重要重要的是形成每天巡检的习惯让变更不再是“通知一声就上了”而是“每天有交代”。6.2 权限收敛把账号体系接入LDAP/SSO部署初期大家为了方便直接用createsuperuser建的账号分发给所有人用。这个做法起步可以长期用下去会越来越难管——有人离职了账号不清理或者一口共享账号变成谁都能登的后门。好在Archery支持对接LDAP和企业SSO登录。配置路径在“系统管理”→“认证设置”里常见做法是把登录模式切换为LDAP填入你的LDAP服务器地址和搜索基DN然后把用户的邮箱前缀与LDAP账号绑定。配置完成后新员工入职自动获得登录资格离职后LDAP侧禁用平台侧也随之失效。如果你所在公司有统一的运维平台更推荐走SSO方案把Archery的登录操作合并到自己的统一入口里减少一次独立登录。这个改造对日常使用几乎无感但对权限审计的价值是质的提升。6.3 与自动化平台整合API调用与工单自动创建Archery的最终价值是融入研发流程而不只是给DBA用。它暴露了一套HTTP API可以创建工单、查询工单状态、执行已审核工单。这意味着你可以把SQL变更接入自家的持续交付流水线里开发在代码仓库里发PRCI构建通过后自动调Archery API提交SQL工单DBA在Archery平台上审核审核通过后由流水线里的定时任务触发执行。我自己在一个发布系统里这样实现过“先审后发”的卡点发布单里关联了数据库变更只有对应的Archery工单状态是“执行成功”发布流程才允许继续。整合之后开发几乎感觉不到Archery的存在但每一次数据库变更都自动留痕、自动走审核。从这个角度看Archery真正值得投入的地方不在于它的界面做得多好看而在于它把一个团队最重要的安全底线——数据库变更——变成了有约束的流程。用了这么久Archery我最大的教训就是工具只是把流程固化了它不会替你思考规则本身合不合理。模板里的阈值设得太严开发会被你逼得写绕过审核的SQL设得太松它又形同虚设。我建议你每季度回头看一眼规则命中率和审核驳回原因把那些“总在犯的低级错误”单独捞出来同步给开发团队顺便把规则模板调一版。审核工具的价值不在“拦了多少问题”而在于“让问题在形成故障之前就变得可见”。希望帮到你。本文还有配套的精品资源点击获取