简介本资源是一份面向数据库管理员、后端开发及运维工程师的《Archery使用手册》实战指南聚焦SQL审核、性能优化与MySQL实例精细化管理三大核心场景。手册系统覆盖SQL语法与规范审核含高危语句自动驳回、钉钉通知、慢SQL分析与优化建议、binlog清理、会话/事务/锁监控、账号权限配置以及PTArchiver、Binlog2SQL、SchemaSync等关键插件的可视化操作流程特别适配开发测试环境SQL工单闭环管理与线上故障快速排查需求。资源为1个1.2MB的Word文档.doc内容结构清晰含功能详解、审核流程图解、SQL优化前后对比示例、锁等待模拟排障步骤及工具配置实操截图便于按需查阅与落地执行。目前已有1474人学习下载是掌握Archery平台从部署到高阶运维的实用型入门到进阶参考材料。1. Archery 是什么一个能让你的 DBA 从“救火队员”变成“审核守门员”的 SQL 审核平台Archery 不是又一个数据库 GUI 工具也不是简单的 SQL 执行器。它是一个面向企业级 MySQL也支持 PostgreSQL、Oracle、SQL Server 等的开源 SQL 审核与执行平台核心价值在于把「人肉 Review」变成可配置、可审计、可回溯、带风险分级的自动化流程。我见过太多团队开发提 PR 时随手写个UPDATE user SET status1 WHERE id IN (SELECT id FROM order WHERE create_time 2023-01-01)DBA 深夜被电话叫醒 kill 连接、查 undo log、手写 binlog 回滚脚本——这种“血泪经验”不是玄学是没上审核卡点的必然结果。Archery 就是那个卡在 SQL 上线前的“守门员”它能静态分析语法、识别高危操作如无 WHERE 的 UPDATE/DELETE、检测缺失索引、估算影响行数、拦截全表扫描、甚至结合 pt-archiver 或 binlog2sql 做变更预演。适合中小团队 DBA、SRE、以及对数据安全有强诉求的 DevOps 团队——尤其当你开始用 kubesphere 部署 MySQL、或在 centos9 上跑 zabbix 7.0 MySQL 8.0 这类生产环境时Archery 不是锦上添花而是防翻车的后悔药。2. 本地快速部署 Archery用 Docker Compose 跑通最小可用环境含 MySQL 8.0 兼容配置Archery 官方推荐 Docker 部署但直接docker-compose up很容易踩坑——尤其是 MySQL 8.0 默认启用 caching_sha2_password 插件而 Archery 的 Python 后端基于 Django PyMySQL默认不兼容该认证方式。下面这套配置是我在线上灰度验证过的最小可行组合已适配 MySQL 8.0.33 和最新 Archery v1.10.x2024 年主流稳定版。2.1 准备 docker-compose.yml显式声明 MySQL 认证插件与字符集# docker-compose.yml version: 3.8 services: mysql: image: mysql:8.0.33 container_name: archery-mysql restart: unless-stopped environment: MYSQL_ROOT_PASSWORD: archery_root_2024 MYSQL_DATABASE: archery MYSQL_USER: archery MYSQL_PASSWORD: archery_pass_2024 # 关键强制使用 mysql_native_password 插件避免 PyMySQL 连接失败 MYSQL_DEFAULT_AUTHENTICATION_PLUGIN: mysql_native_password command: --character-set-serverutf8mb4 --collation-serverutf8mb4_unicode_ci --default-authentication-pluginmysql_native_password volumes: - ./mysql-data:/var/lib/mysql - ./my.cnf:/etc/mysql/conf.d/my.cnf:ro ports: - 3307:3306 healthcheck: test: [CMD, mysqladmin, ping, -h, localhost, -u, root, -parchery_root_2024] timeout: 20s retries: 10 archery: image: hhyo/Archery:latest container_name: archery-web restart: unless-stopped depends_on: - mysql environment: # 数据库连接字符串注意 host 必须用 service 名mysql不是 localhost DATABASE_URL: mysql://archery:archery_pass_2024mysql:3306/archery?charsetutf8mb4 # 开启 SQL 审核核心功能 ENABLE_SQLAUDIT: true # 指定默认审核规则集后面会细调 AUDIT_RULE_SET: default # 日志级别调试阶段建议 DEBUG LOG_LEVEL: INFO ports: - 9123:9123 volumes: - ./archery-data:/opt/archery/upload - ./archery-logs:/opt/archery/logs提示DATABASE_URL中的host必须填mysqlDocker 内部服务名填localhost或127.0.0.1会导致容器内无法解析这是新手最常翻车的点。PyMySQL 在容器网络中访问宿主机 localhost 会失败必须走 Docker 内网 DNS。2.2 补充 my.cnf解决 MySQL 8.0 默认 strict mode 导致的建表失败Archery 初始化时会执行大量 DDL如创建sql_workflow、workflowauditlog等表MySQL 8.0 默认开启STRICT_TRANS_TABLES而部分 Archery 的建表语句未显式声明NOT NULL或默认值会导致初始化失败。新建my.cnf# my.cnf [mysqld] sql_mode ONLY_FULL_GROUP_BY,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION # 关键关闭 STRICT_TRANS_TABLES否则 Archery 初始化报错 # 注意生产环境请勿长期关闭此处仅为部署通过 sql_mode ONLY_FULL_GROUP_BY,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION2.3 启动并验证基础服务连通性# 1. 创建目录结构 mkdir -p ./mysql-data ./archery-data ./archery-logs # 2. 启动服务首次启动会自动初始化数据库 docker-compose up -d # 3. 等待 MySQL 健康就绪约 30 秒 docker-compose logs -f mysql | grep ready for connections # 4. 查看 Archery 初始化日志关键看是否成功 migrate docker-compose logs archery | grep -i migrate\|success\|running # 5. 检查 Archery 是否监听 9123 端口 curl -I http://localhost:9123 # 应返回 HTTP/1.1 302 Found重定向到 /login逻辑说明docker-compose up -d启动后MySQL 容器先就绪Archery 容器启动时会读取DATABASE_URL自动执行 Django 的migrate命令建表。若看到django.db.utils.InternalError: (1071, Specified key was too long...)说明utf8mb4索引长度超限需确认my.cnf中innodb_large_prefixONMySQL 5.7 默认开启8.0 已移除该参数故无需额外配置。若 Archery 日志卡在Starting development server但无后续大概率是数据库连接失败请docker exec -it archery-web bash进入容器手动执行python manage.py dbshell测试连接。3. 配置第一个 MySQL 实例添加线上库、设置审核规则、触发一次真实 SQL 审核Archery 本身不管理业务数据库它只作为“审核代理”连接你已有的 MySQL 实例。这一步是落地核心——让 Archery 真正开始工作而不是停留在登录页。3.1 通过 Web UI 添加 MySQL 实例以本地 3307 端口为例浏览器打开http://localhost:9123初始账号密码均为admin/admin首次登录强制修改进入【实例管理】→【实例列表】→【新增实例】填写关键字段实例名称prod-mysql-8033建议含版本和用途IP 地址host.docker.internalMac/Windows或172.17.0.1Linux即 Docker0 网桥地址为什么不用 localhost容器内localhost指向自身而 Archery 需要连宿主机上的 MySQL我们映射了 3307 端口。host.docker.internal是 Docker 提供的宿主机别名Mac/Win 原生支持Linux 需在docker-compose.yml的 archery service 下加extra_hosts: - host.docker.internal:host-gateway。端口3307用户名/密码archery/archery_pass_2024即前面 docker-compose 中定义的非 root 用户数据库留空Archery 会自动探测所有库字符集utf8mb4环境类型生产影响审核严格度点击【测试连接】→ 成功后【保存】3.2 配置审核规则集针对 MySQL 8.0 的 3 个必调参数Archery 的审核能力高度依赖规则集。默认default规则集较宽松需根据 MySQL 8.0 特性强化。进入【审核配置】→【规则集管理】→ 编辑default规则集规则 ID规则名称启用风险等级参数说明实际建议值no_where无 WHERE 条件的 DML✅高危检测UPDATE/DELETE是否缺失WHEREtrue必须开limit_rowsDML 语句必须带 LIMIT✅中危防止误操作影响过多行1000根据业务调整大表可设 5000alter_tableALTER TABLE 操作✅高危检测ADD COLUMN/DROP COLUMN等true必须开8.0 支持 INSTANT DDL但仍需审核full_table_scan全表扫描✅中危通过 EXPLAIN 判断是否 Using where; Using filesorttrue开启后需确保 MySQL 已授权PROCESS权限注意若开启full_table_scan后审核失败报Access denied; you need (at least one of) the PROCESS privilege(s)需给 Archery 连接用户授权GRANT PROCESS ON *.* TO archery%; FLUSH PRIVILEGES;3.3 提交第一条审核工单用真实 SQL 触发审核链路进入【SQL 审核】→【提交审核】选择实例prod-mysql-8033输入 SQL故意写一个高危语句-- 危险示例无 WHERE 的 UPDATEArchery 会拦截 UPDATE user SET status 0; -- 安全示例带 WHERE 和 LIMIT应通过 UPDATE user SET last_login_time NOW() WHERE id BETWEEN 1000 AND 1010 LIMIT 10;【提交】→ 系统自动生成工单号如WF20240515001进入【审核列表】查看该工单状态若为自动驳回说明no_where规则生效若为自动通过检查limit_rows是否生效LIMIT 10≤1000点击工单详情可看到每条 SQL 的审核报告影响行数预估、索引建议、执行计划EXPLAIN、风险标签。逻辑说明Archery 对 SQL 的解析不是正则匹配而是调用sqlparse库做语法树解析再结合 MySQL 的EXPLAIN FORMATJSON获取执行计划因此能准确识别WHERE子句是否存在、LIMIT是否合规、是否触发全表扫描。审核报告中的“影响行数预估”来自EXPLAIN的rows字段非真实执行但足够用于风险判断。所有审核记录、操作日志、回滚语句均落库持久化满足等保 2.0 对数据库操作审计的要求。4. 集成 Binlog2SQL 与 PT-Archiver让 Archery 具备“变更回滚”与“历史归档”双能力Archery 的价值不止于“拦”更在于“救”。当高危 SQL 意外执行后能否秒级生成回滚语句当大表需要按时间归档时能否一键生成pt-archiver命令这两项能力需手动集成外部工具但配置一次受益长久。4.1 集成 Binlog2SQL为 Archery 注入“后悔药”能力Binlog2SQL 是网易开源的 binlog 解析工具能将 MySQL binlog 转为可逆 SQLINSERT → DELETEUPDATE → 反向 UPDATE。Archery 通过调用其 API 实现回滚语句生成。步骤 1在宿主机安装 Binlog2SQLArchery 容器内不装避免权限问题# Ubuntu/Debian sudo apt update sudo apt install python3-pip -y sudo pip3 install binlog2sql # CentOS/RHEL sudo yum install python3-pip -y sudo pip3 install binlog2sql步骤 2配置 Archery 调用 Binlog2SQL 的路径与参数编辑 Archery 配置文件需进入容器修改docker exec -it archery-web bash # 修改 /opt/archery/settings.py vi /opt/archery/settings.py找到BINLOG2SQL_CMD配置项若无则新增修改为# settings.py 中追加 BINLOG2SQL_CMD /usr/local/bin/python3 /usr/local/bin/binlog2sql # 指向宿主机上 binlog2sql 的绝对路径pip3 install 后的位置 # 注意Archery 容器需挂载宿主机的 binlog2sql 可执行文件或 Python 环境关键避坑Archery 容器默认无 Python3 环境且binlog2sql依赖PyMySQL版本需与 Archery 一致1.0.2。推荐方案不挂载宿主机二进制而是在 Archery 容器内安装修改 Dockerfile 或用 exec 安装docker exec -it archery-web bash -c pip install binlog2sql1.4.6版本1.4.6兼容 MySQL 8.0 binlog 格式且与 Archery 的 PyMySQL 无冲突。步骤 3在工单详情页触发回滚语句生成找到一条已执行的UPDATE工单需确保该 SQL 真实执行过且 binlog 未过期点击【生成回滚语句】按钮Archery 自动调用binlog2sql解析对应 binlog position输出反向 SQL-- 原 SQL: UPDATE user SET status1 WHERE id1001; -- 回滚 SQL: UPDATE user SET status0 WHERE id1001;原理Archery 通过SHOW MASTER STATUS获取当前 binlog 文件及 position结合工单提交时间戳定位到对应 binlog 区间再交由binlog2sql解析。4.2 集成 PT-Archiver一键生成大表归档命令pt-archiver是 Percona Toolkit 中最成熟的大表归档工具支持按条件归档、删除、分批处理。Archery 本身不执行归档但可生成标准化命令供 DBA 复制执行。配置 Archery 的 PT-Archiver 模板进入【审核配置】→【审核模板】→ 新建模板模板名称pt-archiver-delete-by-date模板内容关键参数可变量化pt-archiver \ --source hINSTANCE_HOST,DDATABASE,tTABLE,uUSER,pPASSWORD \ --where create_time DATE \ --limit 1000 \ --txn-size 1000 \ --sleep 0.1 \ --progress 1000 \ --statistics \ --no-check-charset \ --bulk-delete \ --purge变量说明INSTANCE_HOST→ Archery 实例 IPDATABASE→ 目标库名TABLE→ 目标表名DATE→ 归档截止日期格式2024-01-01USER/PASSWORD→ 实例连接凭据提交后在 SQL 审核页面选择该模板输入DATE2023-01-01即可生成完整命令。DBA 复制到终端执行避免手写错误。为什么不用 Archery 直接执行pt-archiver是重量级工具需在数据库服务器本地运行减少网络 IO且涉及DELETE操作Archery 作为 Web 平台不承担执行风险只做“命令生成器”更安全、更符合职责分离原则。5. 避坑指南Archery 生产部署中 4 个高频翻车点与血泪解决方案Archery 功能强大但部署和配置环节存在多个“静默陷阱”稍不注意就会导致审核失效、连接中断、甚至数据泄露。以下是我在 3 个不同规模团队中踩过的真坑按现象→原因→解法结构整理拒绝模糊描述。5.1 现象审核通过后执行 SQL 报错ERROR 1045 (28000): Access denied for user archery%原因Archery 执行 SQL 时使用的是“审核通过时指定的数据库用户”而非实例配置里的用户。若该用户在目标库无权限执行必然失败。常见于 DBA 为安全起见只给archery用户SELECT权限但审核通过的UPDATE需要UPDATE权限。解决进入【实例管理】→ 编辑对应实例 → 勾选【执行用户】→ 输入一个具备SELECT,INSERT,UPDATE,DELETE,ALTER,CREATE,INDEX权限的专用账号如archery_executor该账号权限需严格限定在业务库禁止GRANT OPTION和SUPER权限授予语句示例CREATE USER archery_executor% IDENTIFIED BY strong_pass_2024; GRANT SELECT,INSERT,UPDATE,DELETE,ALTER,CREATE,INDEX ON business_db.* TO archery_executor%; FLUSH PRIVILEGES;5.2 现象full_table_scan规则始终不生效审核报告里无“全表扫描”警告原因MySQL 8.0 默认关闭performance_schema的events_statements_summary_by_digest表而 Archery 的EXPLAIN分析依赖此表获取执行计划。即使开了PROCESS权限若该表为空也无法解析。解决登录 MySQL执行UPDATE performance_schema.setup_consumers SET ENABLED YES WHERE NAME events_statements_summary_by_digest; UPDATE performance_schema.setup_instruments SET ENABLED YES WHERE NAME statement/sql/explain;重启 MySQL 或执行FLUSH STATUS;刷新验证SELECT * FROM performance_schema.events_statements_summary_by_digest LIMIT 1;应有返回。5.3 现象Docker 容器启动后 Archery Web 页面空白F12 查看 Network 显示GET /static/js/app.js net::ERR_ABORTED 404原因Archery 的静态资源JS/CSS默认由 Nginx 服务提供但官方镜像中 Nginx 配置未正确挂载/static路径或collectstatic命令未执行。Docker 镜像构建时若未预编译静态文件会导致前端资源 404。解决进入 Archery 容器docker exec -it archery-web bash执行静态文件收集cd /opt/archery python manage.py collectstatic --noinput重启容器docker restart archery-web验证ls -l /opt/archery/static/js/应有app.js等文件。5.4 现象审核通过的 SQL 执行后Archery 工单状态卡在执行中无后续更新原因Archery 执行 SQL 是异步任务依赖 Celery Redis。若docker-compose.yml中未配置 Redis 服务或 Celery worker 未启动任务将堆积在队列中永不执行。解决在docker-compose.yml中添加 Redis 服务redis: image: redis:7-alpine container_name: archery-redis restart: unless-stopped ports: - 6379:6379修改 Archery 环境变量指向 Redisenvironment: CELERY_BROKER_URL: redis://redis:6379/1 CELERY_RESULT_BACKEND: redis://redis:6379/2重启全部服务docker-compose down docker-compose up -d查看 Celery 日志docker-compose logs archery | grep celery确认celeryarchery-web ready。6. 进阶技巧用 Archery 的 API 自动化接入 CI/CD 流水线Jenkins/GitLab CI 实战Archery 提供完整的 RESTful API这意味着你可以把它嵌入到 Jenkins Pipeline 或 GitLab CI 中实现“代码提交 → SQL 自动审核 → 通过后自动上线”的闭环。这不是噱头而是我们团队已在生产环境跑了一年的方案日均拦截高危 SQL 12 条。6.1 获取 API Token安全访问的前提Archery 的 API 需 Token 认证且 Token 与用户绑定、可设置有效期。登录 Archery Web → 右上角头像 → 【个人设置】→ 【API Token】→ 【生成 Token】设置 Token 名称如jenkins-cd-token、有效期建议 90 天、权限勾选sqlworkflow和instance复制生成的 Token形如a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6立即存入 Jenkins Credentials 或 GitLab CI Variables切勿硬编码。6.2 Jenkins Pipeline 调用 Archery API 的完整脚本以下是一个精简但可直接复用的 Jenkins Pipeline 示例假设你的 SQL 文件存放在./sql/目录下pipeline { agent any environment { ARCHERY_URL http://your-archery-host:9123 ARCHERY_TOKEN credentials(archery-api-token) // Jenkins Credentials ID INSTANCE_NAME prod-mysql-8033 } stages { stage(SQL Audit) { steps { script { // 1. 读取 SQL 文件内容 def sqlContent readFile(./sql/deploy_v2.1.sql) // 2. 构造 API 请求体 def payload [ workflow_name: CI-${BUILD_NUMBER}-deploy, demand_url: https://gitlab.example.com/project/merge_requests/${env.CHANGE_ID}, group_name: DBA, engineer: jenkins, instance_name: ${INSTANCE_NAME}, db_name: business_db, sql_content: sqlContent, is_backup: true ] // 3. 调用 Archery API 提交审核 def response sh( script: curl -s -X POST ${ARCHERY_URL}/api/v1/sqlworkflow/submit/ \ -H Authorization: Token ${ARCHERY_TOKEN} \ -H Content-Type: application/json \ -d ${JsonOutput.toJson(payload)}, returnStdout: true ).trim() // 4. 解析响应提取 workflow_id def json readJSON text: response if (json.status 0) { env.WORKFLOW_ID json.data.workflow_id echo SQL 审核已提交工单ID: ${env.WORKFLOW_ID} } else { error Archery 审核提交失败: ${json.msg} } } } } stage(Wait for Audit Result) { steps { script { // 轮询 Archery API 获取审核状态最多等 5 分钟 def maxRetry 30 def interval 10 for (int i 0; i maxRetry; i) { def statusResp sh( script: curl -s -X GET ${ARCHERY_URL}/api/v1/sqlworkflow/detail/?workflow_id${env.WORKFLOW_ID} \ -H Authorization: Token ${ARCHERY_TOKEN} , returnStdout: true ).trim() def statusJson readJSON text: statusResp if (statusJson.status 0 statusJson.data.status workflow_reviewed) { if (statusJson.data.audit_status 0) { echo 审核通过准备执行 break } else { error 审核未通过: ${statusJson.data.audit_result} } } sleep(interval) } if (i maxRetry) { error 等待审核超时请登录 Archery 查看工单 ${env.WORKFLOW_ID} } } } } stage(Execute SQL) { steps { script { // 调用执行接口仅当审核通过后 def execResp sh( script: curl -s -X POST ${ARCHERY_URL}/api/v1/sqlworkflow/executesql/ \ -H Authorization: Token ${ARCHERY_TOKEN} \ -H Content-Type: application/json \ -d {workflow_id: ${env.WORKFLOW_ID}}, returnStdout: true ).trim() def execJson readJSON text: execResp if (execJson.status ! 0) { error SQL 执行失败: ${execJson.msg} } echo SQL 执行成功 } } } } }逻辑说明submit接口提交 SQL返回workflow_iddetail接口轮询状态直到status workflow_reviewedaudit_status 0表示通过1驳回2等待人工审核最终调用executesql执行Archery 自动调用 MySQL 执行并记录结果。安全提醒Jenkins 中credentials(archery-api-token)必须使用 Secret Text 类型 Credential禁止明文写 Token。GitLab CI 同理将 Token 存入Settings → CI/CD → VariablesKey 设为ARCHERY_TOKEN勾选Mask variable。6.3 一个真实收益把 MySQL 主从复制异常排查时间从 2 小时压缩到 8 分钟我们曾遇到一次线上事故主库某张大表order_history的UPDATE语句在从库延迟 3 小时。传统排查需SHOW SLAVE STATUS、pt-heartbeat对比、mysqlbinlog解析平均耗时 120 分钟。接入 Archery 后我们做了两件事在 Archery 中为该表配置专属规则alter_table强制要求ALGORITHMINSTANTMySQL 8.0 支持并禁用LOCKSHARED所有 DDL 变更必须走 Archery 审核工单详情页自动关联pt-table-checksum校验结果。当再次出现延迟时DBA 直接打开 Archery → 【审核列表】→ 筛选order_history 时间范围 → 找到最近一条ALTER TABLE工单 → 点击【执行详情】→ 查看pt-table-checksum输出TS ERRORS DIFFS ROWS CHUNKS SKIPPED TIME TABLE 05-15T10:23:41 0 1 12456789 12 0 12.345 order_historyDIFFS1表示主从数据不一致且定位到具体 chunk。8 分钟内完成定位与修复。这就是 Archery 的真实价值它不替代 DBA 的专业能力而是把重复劳动自动化把经验沉淀为规则把救火变成预防。我坚持每天花 10 分钟 review Archery 的审核拦截日志就像医生看体检报告——不是为了找问题而是为了确认防线还在。希望帮到你。本文还有配套的精品资源点击获取