Archery SQL审核平台部署与运维避坑指南

简介《Archery使用手册》是一份面向MySQL DBA、研发与测试工程师的实操型文档系统讲解SQL审核查询平台Archery的部署使用思路。内容涵盖SQL审核与优化、实例管理、PTArchiver、Binlog2SQL、SchemaSync等插件并给出开发/测试环境审核流程、慢SQL分析、binlog清理、会话与锁排查、账号授权等实践案例适合需要规范SQL上线和提升数据库运维效率的团队参考。资源为doc文档共1个文件压缩包约1.2MB方便本地查阅和按章节检索。已有1476人学习下载。读者可从中掌握从提交SQL检测、审核到执行回滚的完整链路并能直接参照示例操作实例管理及工具插件减少踩坑、提升日常运维与协作效率。1. 这篇 archery 使用手册写给被 SQL 变更流程折磨过的人如果只是要一份“下一步下一步”的安装教程网上已经有很多截图了。这篇 archery 使用手册想做的是把一个开源 SQL 审核查询平台从部署、配置到日常运维讲成一套能直接落地的方法资源组怎么划分、实例怎么接进来、上线工单怎么流转、哪些配置改完会翻车。它解决的是研发提 SQL 没人把关、DBA 靠肉眼审变更、上线后查不到谁改了什么这些实际问题。适合 DBA、研发负责人以及所有被“先帮我看下这条 SQL 能不能上”这类消息淹没的人。2. 把 Archery 部署起来docker-compose 最小可用方案2.1 先理解 Archery 由哪几个进程组成再决定怎么部署Archery 前后端拆开后组件不算少浏览器访问的 Vue 静态资源由一个 nginx 容器托管真正处理请求的 Django 服务跑在同一个应用容器里元数据库存放工单、用户、权限这些平台自身的状态Redis 用来做任务队列配合 Celery 完成慢日志抓取、通知推送一类异步任务。普通使用不需要自己写前端编译它的官方镜像把前端和 Django 打包在一起部署复杂度被降下来不少。我一般直接用 docker compose 而不是二进制包安装理由是组件依赖关系清楚升级时容器隔离换机器时整个目录拷过去就能恢复。这里有一个容易踩的概念坑Archery 的元数据库和它管理的业务实例数据库是两回事。元数据库只存平台自己的数据千万别图省事把元数据库指向业务库否则后面查工单、查权限会得到一堆混在业务表里的无用数据恢复起来极其痛苦。容器化部署还有一个隐藏收益Archery 本身对操作系统不挑剔只要 Docker 环境正常无论是裸机 CentOS 还是内网虚拟机都能跑。后面排查问题时docker compose logs能把所有进程的日志集中拉出来比在宿主机上翻 systemd 日志直观得多。这也是我坚持用它做交付形态的原因。2.2 用 docker-compose 实现最小可用部署下面这段 compose 是我在测试环境常用的最小写法三个服务就能把平台拉起来services: mysql: image: mysql:5.7 container_name: archery-mysql restart: always environment: MYSQL_ROOT_PASSWORD: RootChangeMe MYSQL_DATABASE: archery MYSQL_USER: archery MYSQL_PASSWORD: ArcheryChangeMe volumes: - ./data/mysql:/var/lib/mysql healthcheck: test: [CMD, mysqladmin, ping, -h, localhost] interval: 5s timeout: 3s retries: 20 redis: image: redis:6 container_name: archery-redis restart: always archery: image: hhyo/archery:latest container_name: archery restart: always environment: MYSQL_HOST: mysql MYSQL_PORT: 3306 MYSQL_DATABASE: archery MYSQL_USER: archery MYSQL_PASSWORD: ArcheryChangeMe ports: - 9123:9123 depends_on: mysql: condition: service_healthy redis: condition: service_started把 MySQL 放在第一个是有原因的Archery 启动时如果连不上元数据库应用容器会反复重启日志里全是 connection refused。这里给 mysql 加了 healthcheck通过 mysqladmin ping 确认元数据库真正 ready 才启动 archery。compose 里的 MYSQL_HOST、MYSQL_PORT 是容器内 Django 读取数据库连接的环境变量实际字段名以你拉取的镜像内 settings 为准。要改元数据库地址时同时改环境变量和ports映射即可。启动命令很简单docker compose up -d docker compose ps docker compose logs -f archeryup -d拉镜像并后台启动ps看三个服务是否都在运行logs -f跟踪应用日志。如果ps里 archery 的状态是 Restarting优先怀疑元数据库没准备好而不是应用代码问题。image 用 latest 第一次部署很方便但它有个隐患Archery 版本升级如果涉及数据库表结构直接拉 latest 再 up 会把旧元数据库顶坏。建议跑通后给三个镜像固定明确的版本 tag升级前先看 CHANGELOG 再动手。2.3 初始化数据库和管理员账号第一次登录要做的事容器起来后需要手动把 Django 的数据表建到元数据库里这一步不做后面页面会报各种 500docker compose exec archery python manage.py migrate docker compose exec archery python manage.py createsuperusermigrate 把 Archery 的 ORM 模型映射成元数据库里的物理表createsuperuser 按提示输入用户名、邮箱和密码创建的是平台里的超级管理员。后续分配资源组、录入实例、配置审核权限都以这个账号为起点。部分镜像的初始化脚本会自动建默认管理员无论是否存在这个默认账号登录成功后第一件事都应该是改密码并把邮箱、手机号补上避免工单通知发到假地址。第一次登录后别急着录业务库我的固定顺序是改密码 → 确认页面正常 → 建资源组 → 录实例 → 建普通用户。为什么资源组要排这么靠前因为 Archery 的权限模型几乎全部挂在资源组上先有组才能把实例和用户挂进去这个顺序能省掉大量重新授权的返工。浏览器访问http://服务器IP:9123能看到登录页说明 nginx 和 Django 之间已经通了如果页面空白或接口一直报错回到docker compose logs -f archery看启动日志绝大多数问题在这一步就能定位。3. 配置第一个可用环境资源组、实例与权限角色3.1 资源组为什么推荐先建组再建库资源组在 Archery 里的作用类似一个权限容器。同一个 MySQL 集群可以拆出“生产订单”和“测试环境”两个组也可以把不同引擎的实例归到同一个“订单核心库”组里。开发人员只能看到自己被授权资源组里的实例提交上线单和查询都受这个边界约束。也就是说资源组既是数据面的隔离单元也是管理面的授权单元。实际划分时我遵循两个原则一是环境分离测试和生产永远不放进同一个资源组二是职责分离一个资源组只对应一条业务线和一组固定的审批人。例如“交易中台-生产”这个组里面放着交易库、订单库审批人是交易团队的负责人和 DBA开发提交的工单默认就得在这几个人手里走流程。这样划分的优点是规则配置可以跟着资源组走比如交易组要求所有 DDL 必须二次审核而内部报表组可以放宽互不干扰。特别提醒一下root 等超级账号不要直接录进 Archery 作为实例账号。我在多个环境里看到有人图方便把业务库的 root 密码填进去结果 Archery 的 SQL 查询模块等于给所有有查询权限的人发了一把万能钥匙。正确做法是为 Archery 单独创建账号查询和只读任务用只读账号DDL 执行用最小权限账号密码统一由 DBA 保管。平台自身的元数据库账号和生产业务账号也要严格分开这是 Archery 安全使用的一条底线。3.2 录入 MySQL 实例并验证连通性进入菜单里的“实例管理”点击新增实例核心字段如下配置项值示例说明实例类型MySQL决定 SQL 解析和审核规则实例名称生产-交易库工单和查询页面显示的名字地址192.168.10.5必须从 Archery 容器内可达端口3306默认端口按实际情况改账号arc_sync建议使用最小权限专用账号密码填写后加密存储不显示明文资源组交易中台-生产决定哪些用户能访问地址和端口这两项是新手最容易填错的常见错误是填localhost或127.0.0.1。要理解 Archery 容器和宿主机的网络栈是隔离的宿主机上的 localhost 指向宿主机自身容器里的 localhost 指向容器自身所以业务库地址必须写成 Archery 容器能访问到的内网 IP。保存实例前平台通常会做一次连通性测试如果测试失败先在容器内手动验证docker compose exec archery bash -c mysql -h 192.168.10.5 -P 3306 -u arc_sync -pYourPassword -e select version();这条命令直接在 Archery 容器里尝试连接目标库能排除掉一大半网络层面的玄学问题。如果命令返回版本号说明网络和账号都通问题出在平台的配置格式如果报 Access denied说明账号权限或密码不对如果超时就要查安全组、防火墙和路由。密码里有特殊字符时命令行里记得用单引号包住否则 shell 会把$、#之类字符吃掉这也是一个常见翻车点。3.3 把用户放进角色Archery 的权限边界怎么画实例录好之后下一步是建普通用户并分配权限。Archery 的用户权限不是简单的“管理员/普通用户”两级而是“用户 角色 资源组”的组合关系。一个用户可以在资源组 A 里是提交者在资源组 B 里是审核人这种矩阵在业务上非常实用但也意味着配置时不能只创建一个账号就完事。我的配置套路是这样先把团队里的 DBA 设为“资源组管理员”负责这个组里的实例和工单管理再让业务负责人承担“审核人”角色对提交上来的 SQL 做业务层审批开发人员统一分配到“提交工单 查询授权”的角色。这样一条线上三类人各司其职SQL 能不能上既看规则检查也看业务审批DBA 只在最后执行前把关。创建用户时注意把用户放进正确的资源组并勾选对应角色。很多团队部署完发现“登录后一片空白”八成因就是这步漏了账号创建了但没绑资源组也没有任何角色平台不知道该给它展示什么菜单。超级管理员账号不受资源组限制所以测试时用 admin 一切正常换成普通用户就什么都看不到——这不是 bug是权限隔离在起作用。建完用户后建议用普通用户重新登录一次确认菜单、实例列表都和预期一致再开始走工单流程。4. 把日常研发流程搬进 Archery上线审核、查询与慢日志4.1 上线审核一次 SQL 提交需要经过哪几道关卡Archery 最常用的功能是上线工单它把一次数据库变更从“口头说一声”变成一条有记录、有状态、可追踪的执行链。开发提交一个上线单时需要选择目标资源组、目标实例、填 SQL 语句然后平台先做一轮静态审核有没有禁用语法、有没有高风险操作、DDL 是否符合规范。审核通过后工单进入待审批状态审批人通常是业务负责人或 DBA批完由有执行权限的人在界面上点击执行整个过程每一步都有操作记录。工单状态一般有提交、审核通过、排队执行、执行成功、执行失败几档。这里要提醒一点Archery 的审核规则检查是“规则命中即提示或拦截”它不替代人的判断。比如一条 SQL 命中“禁止 DELETE 不带 WHERE”会被直接拦下但一条“SELECT 全表大字段”可能只给出警告是否放行还是要审批人决定。规则配置越严格漏网之鱼越少但也要给紧急变更留一条可解释的通道避免业务卡在流程上。执行过程中还有一个容易被忽略的选项备份。部分变更支持先备份受影响数据再执行这在生产环境是比较实用的后悔药功能。建议在执行 UPDATE 或 DELETE 之前勾选备份表虽然会多花一点存储但一旦执行结果偏离预期可以快速回滚而不是靠 binlog 手工恢复。备份策略属于越早配置越好的那种等真出了事再去翻菜单就来不及了。4.2 查询权限与 SQL 安全检查开发自己查库的前提研发最常找 DBA 的事由就是“帮我查一下数据”。Archery 的 SQL 查询模块允许开发在授权范围内自助查询但默认不是放开所有权限。查询使用的账号通常是实例录入时配置的那个账号如果给的是只读账号那么查询模块最多只能跑 SELECT天然挡住了误操作。为了保险我在录入实例时会给查询场景单独配一个只读账号并把 DML 权限从 MySQL 账号层面就收掉。查询模块还支持结果集限制和超时控制。默认结果集行数可以设置成 1000 行防止一次 SELECT 拉爆内存超时时间建议设置在 30 到 60 秒避免长查询挂在数据库上不释放。字段级脱敏在这里也有用比如手机号、身份证号可以配置成只显示前几位这对查询账号不可避免要暴露真实数据的情况是一个很好的兜底。查询语句本身会进入审计记录谁在什么时间查过什么库都能追溯。在给开发开查询权限前最好先和团队确认一个原则查询模块只解决“看数据”不解决“改数据”。所有变更一律走上线工单不允许用查询模块跑 update。这个约定写进资源组的规则里再配合只读账号基本可以杜绝“开发在 Archery 里顺手改了生产”这类事故。权限边界清晰之后DBA 的日常负担会明显下降这也是 Archery 最直接的收益。4.3 慢查询与会话管理DBA 的日常监控入口除了审核和查询Archery 还能承担一部分 DBA 的监控工作。对 MySQL 实例它会读取 performance_schema 和 sys 库的数据把慢语句、长事务、当前活跃会话展示在界面上。也就是说Archery 本身不主动采集性能数据它做的是把 MySQL 自带的诊断信息可视化所以录入实例的账号至少要有访问sys库和performance_schema的权限否则慢查询面板会一直空白。我平时排查线上性能问题时习惯先把慢查询列表导出来看前三名SELECT DIGEST_TEXT, COUNT_STAR, AVG_LATENCY, SUM_LATENCY FROM sys.statement_analysis ORDER BY SUM_LATENCY DESC LIMIT 10;DIGEST_TEXT 是归一化之后的 SQL 文本COUNT_STAR 是执行次数AVG_LATENCY 是平均延迟SUM_LATENCY 是总延迟。按总延迟排序能快速找到“虽然单次不快但被调用无数遍”的语句这类问题通常比单条慢 SQL 对系统影响更大。Archery 会把这张表做成列表但自己掌握这条 SQL 的好处是任何环境都能用不依赖平台是否部署。会话管理模块用来处理“会话卡死”的情况。看到某个连接长时间处于 Sleep 或执行中可以选中会话执行 kill。这个操作要谨慎最好先确认会话对应的业务线程盲目 kill 可能导致业务侧报错。我更推荐的做法是先在慢日志里确认问题语句再在会话列表里 kill 对应连接双端对照避免误杀正常请求。5. Archery 避坑指南5 个部署落地常见问题5.1 容器全起来了9123 却打不开现象是docker compose ps里三个容器都在运行但浏览器访问 9123 端口一直转圈或直接拒绝连接。这时先检查宿主机防火墙和云安全组是否放行了 9123内网环境经常是安全组漏配置导致外部访问不到其次是看浏览器访问的地址是否写成了容器 IP正确地址是宿主机 IP 加映射端口。如果本机 curl 也失败进容器内部看 nginx 是否在监听docker compose exec archery curl -I http://127.0.0.1:9123能返回 200 说明服务正常问题出在端口映射或防火墙返回拒绝连接说明容器内进程没起来此时看docker compose logs archery | tail -n 50最常见的是 Django 启动时报数据库连接失败或静态资源路径错误。另一个隐蔽原因是端口冲突9123 被宿主机其他进程占用换一个映射端口即可。5.2 admin 登录后看不到资源组和实例有些团队用默认账号或自行创建的普通用户登录后菜单里根本没有“资源组”“实例管理”入口第一反应是平台装坏了。实际多数情况是权限问题Archery 的菜单根据角色动态渲染只有超级管理员才能看到全部管理菜单普通用户即使被授权了一个资源组也只能看到该组内的实例和工单功能。解决方法是确认你登录的是不是 createsuperuser 创建的账号如果是普通用户联系管理员把角色调整为资源组管理员再去对应资源组里看实例列表。还有一种情况是浏览器缓存了旧版前端资源导致新角色没有生效强刷一次再重新登录通常就好。如果超级管理员账号也看不到管理菜单检查一下是不是同时打开了多个 Archery 标签页切换账号时没有刷新会话退出重登即可。这个坑虽然不深但会让人误以为部署失败花不少时间做无用排查。5.3 上线工单卡在审核人环节没人能审工单提交后状态一直是“待审核”查看详情发现审核人列表为空或审核人就是自己。原因通常在用户配置工单提交后系统要找到该资源组下有审核权限的用户作为审核人如果这个角色没分配到任何人工单就会挂在半空无人处理。检查资源组设置里绑定的审核人是谁以及这些账号是否仍处于启用状态。另一个常见原因是开发提交工单时自己选了一位审批人但这位审批人已经离职或被停用工单就卡住了。解决方法是给资源组配置“默认审核人”并保持至少两位活跃审核人避免单点。同时把通知方式配置好让审核人能第一时间收到提醒而不是隔几天打开 Archery 才发现有一堆工单待审批。邮件或钉钉机器人看团队习惯来选这个配置在运维中价值很高能显著减少“工单长时间无人处理”的情况。5.4 查询模块显示连接失败现象是录入实例时测试连通性通过但在 SQL 查询界面点击执行时报连接失败或 Access denied。先排除账号权限问题录入实例时使用的账号可能在查询模块中不具备目标库的 SELECT 权限或被 MySQL 的 host 白名单限制。查询模块用的连接池和录入时的连通性测试走的不是同一条链路录入时用的专用账号可能通了但实际查询时平台会按资源组或查询账号配置重新连接因此这个“录入时成功”不等于“查询时也成功”。排查方法是在容器内手动执行一次同样的查询确认账号权限和网络都通畅然后检查实例配置里的查询账号是否单独填写如果和录入账号混用很容易出现权限不符。密码含特殊字符时确认平台是否正确转义我遇到过一次密码含#导致连接串被截断的案例最后在密码前后加引号才解决。这一类问题定位起来不难但现象容易和网络问题混淆所以优先用容器内命令验证。5.5 升级时数据库迁移失败平台起不来很多人把镜像 tag 从旧版本改成 latest 后直接docker compose up -d结果容器起来了页面却报 500 或登录直接失败。原因是新代码需要新的表结构而旧元数据库还是老结构迁移脚本没有自动执行。Django 应用一般都需要手动执行 migrate拉了新镜像后必须补上这一步docker compose exec archery python manage.py migrate执行前一定先备份元数据库用 mysqldump 把 archery 库导出到安全位置迁移失败时至少能回滚。更稳妥的操作是升级前先查新版本的 CHANGELOG确认是否有破坏性变更再决定是否升级。我见过升级失败后整个平台不可用、最后靠备份恢复的案例所以现在每次升级前都强制先备份、再拉镜像、再 migrate、最后验证登录和查询功能这套顺序一次都不能省。6. 进阶用法从规则配置到一次完整的验证Archery 真正拉开使用水平差距的地方是 SQL 规则的自定义。默认规则能满足基础拦截但每个团队的规范不一样有的不允许 DELETE 不带 WHERE有的要求 INSERT 必须显式指定列名有的限制单条 SQL 影响行数。这些都可以在参数配置或规则管理里调整把规则保存到资源组后该资源组下的所有工单都会自动执行检查。我通常会先配三条最刚性的规则禁止无 WHERE 的 UPDATE/DELETE、禁止 TRUNCATE、INSERT 操作必须限定影响行数上限这三条能挡住绝大多数“手滑级”事故。规则配好之后要主动验证而不是等上线时才发现没生效。我的做法是在测试资源组里故意提交三条 SQL一条不带 WHERE 的 DELETE一条超过行数限制的 INSERT一条完全正常的 SELECT。理想结果是前两条被平台拦截或警告第三条顺利走到审批环节。如果预期拦截的 SQL 直接通过说明规则没有绑定到当前资源组或者规则的执行等级设成了“警告”而不是“禁止”去改规则级别再重新提交一次工单。最后讲一个我的个人习惯每次改完规则或者升级完平台我都会用普通账号重新走一遍“提交→审核→执行”的最小流程而不是只用 admin 看一眼界面。普通账号走流程才能暴露角色配置、资源组绑定这些真实环境问题。Archery 这类平台属于典型的“配好以后很省心配之前到处是坑”的工具把初始化配置和权限矩阵理顺日常运维量会明显下降希望这篇手册能帮你少走一段弯路也祝你一次部署成功。本文还有配套的精品资源点击获取