简介本资源是一份面向数据库管理员、后端开发及运维工程师的《Archery使用手册》实战指南聚焦SQL审核、性能优化与MySQL实例精细化管理三大核心场景。手册系统覆盖SQL语法与规范审核含高危语句自动驳回、钉钉通知、慢SQL分析与优化建议、binlog清理、会话/事务/锁监控、账号权限配置以及PTArchiver、Binlog2SQL、SchemaSync等关键插件的可视化操作流程。资源为单个Word文档.doc大小1.2MB内容结构清晰含功能详解、审核工单全流程示例研发→项目经理→测试多角色协作、SQL优化前后对比、锁等待模拟排障、工具参数配置截图等实操细节。目前已有1474人学习下载适合希望快速掌握Archery平台部署后落地应用、提升SQL质量与数据库稳定性的中高级技术人员。1. Archery 是什么一个能跑在生产环境里的 SQL 审核平台不是玩具Archery 不是又一个“本地调试用的 SQL 格式化小工具”它是国内一线 DBA 团队真正在 MySQL/Oracle/PostgreSQL 生产环境中长期扛住日均 5000 工单、审核通过率超 92% 的 SQL 安全网关。它把 DBA 最头疼的三件事——开发提的 DML 语句有没有 WHERE、ALTER TABLE 是否加了 ONLINE、DROP 表有没有走审批流程——全部收进 Web 界面 自动化规则引擎 钉钉/企业微信通知闭环里。你不需要写 Python 脚本去解析慢日志也不用靠人工盯 binlog 去回滚误操作Archery 把 PT-archiver 的归档能力、Binlog2SQL 的闪回逻辑、MySQL 8.0 的角色权限体系全拧成一套可审计、可回溯、可灰度上线的落地管线。适合中小团队没有专职 DBA 但又不敢放任开发直连生产库的场景也适合已有 DBA 团队想把经验沉淀为规则、把重复劳动交给机器的进阶需求。它不解决“怎么装 MySQL”但能让你装完 MySQL 后第一行上线 SQL 就被拦下来检查索引缺失。2. 搭建 Archery从源码编译到服务启动的最小可行路径Archery 官方推荐 Docker 部署但真实生产环境里Docker Compose 的网络隔离、日志落盘、配置热更新常翻车我们一线更倾向源码部署——可控、可 debug、升级时能看清每行 patch 干了什么。以下是在 CentOS 7.9 MySQL 8.0.33 Python 3.9.16 环境下验证过的最小闭环路径全程无 Docker、无 Kubernetes纯 Linux 服务化管理。2.1 环境准备系统依赖与 Python 环境隔离Archery 本质是 Django 应用但重度依赖 MySQL 客户端库、psutil查进程、pymysql连库、sqlparse解析 SQL等 C 扩展模块。CentOS 默认的 python3-pip 版本太老直接 pip install 会卡在 cryptography 编译必须先装好编译链和 OpenSSL 开发头文件# 安装系统级依赖CentOS 7 sudo yum install -y gcc gcc-c make openssl-devel libffi-devel mysql-devel \ python39 python39-devel python39-pip # 创建独立虚拟环境严禁用系统 Python 直接 pip python3.9 -m venv /opt/archery/venv source /opt/archery/venv/bin/activate # 升级 pip 到 23.3.1低于 23.0 会因 setuptools 68 报错 pip install --upgrade pip23.3.1提示mysql-devel是关键。如果漏装后续pip install PyMySQL虽能成功但archery manage.py db init会报ModuleNotFoundError: No module named _mysql——因为 PyMySQL 是纯 Python 实现但 Archery 内部部分模块如 binlog 解析桥接仍调用 MySQLdb 兼容层而该层需mysql_config可执行文件它由mysql-devel提供。2.2 获取源码与初始化数据库结构Archery 项目已迁移到 GitHub 组织archerydms下主仓库为archery。注意不要用旧版hhyo/Archery已归档新版自 4.0 起强制要求 MySQL 5.7且默认启用sql_modeSTRICT_TRANS_TABLES,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO否则迁移脚本会失败。# 下载最新稳定版截至 2024 年 6 月为 v4.2.0 cd /opt/archery git clone https://github.com/archerydms/archery.git --branch v4.2.0 --depth 1 cd archery # 初始化数据库假设已建好名为 archery 的库字符集 utf8mb4排序规则 utf8mb4_unicode_ci # 注意MySQL 用户需有 CREATE、ALTER、INDEX、REFERENCES 权限不能仅给 USAGE mysql -u root -p -e CREATE DATABASE IF NOT EXISTS archery CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; mysql -u root -p -e CREATE USER archerylocalhost IDENTIFIED BY StrongPass123!; mysql -u root -p -e GRANT ALL PRIVILEGES ON archery.* TO archerylocalhost; FLUSH PRIVILEGES; # 安装 Python 依赖跳过前端构建后端服务无需 nodejs pip install -r requirements.txt --no-cache-dir # 修改配置文件复制模板并填入数据库连接 cp archery/settings.py.example archery/settings.py sed -i s/HOST: 127.0.0.1/HOST: 127.0.0.1/g archery/settings.py sed -i s/PORT: 3306/PORT: 3306/g archery/settings.py sed -i s/USER: root/USER: archery/g archery/settings.py sed -i s/PASSWORD: /PASSWORD: StrongPass123!/g archery/settings.py sed -i s/NAME: archery/NAME: archery/g archery/settings.py2.3 迁移数据表并启动服务Archery 使用 Django ORM 管理 schema但它的migrate命令不是简单跑django.db.migrations而是封装了archery manage.py db init——这个命令会自动创建用户表、审核工单表、实例配置表并插入初始管理员账号admin/admin# 执行数据库迁移含初始数据 python manage.py db init # 创建超级管理员可选init 已建 admin但建议再确认 python manage.py createsuperuser --username dba --email dbacompany.com # 启动开发服务器仅用于验证生产环境必须用 gunicorn python manage.py runserver 0.0.0.0:8000此时访问http://your-server-ip:8000输入admin/admin即可登录。但注意runserver是 Django 自带的单线程开发服务器绝对不可用于生产。下一节将切换为 gunicorn nginx 的标准组合。3. 生产就绪gunicorn nginx systemd 三位一体服务化开发模式下runserver无法处理并发请求且无进程守护、无日志轮转、无 graceful shutdown。生产环境必须用 gunicorn 管理 worker 进程nginx 做反向代理和静态资源托管systemd 确保开机自启与异常重启。3.1 配置 gunicorn控制并发与内存安全Archery 对内存较敏感尤其开启 SQL 审核规则扫描时单个 worker 可能占用 300MB。worker 数量不能简单按 CPU 核数设需结合--max-requests和--max-requests-jitter防止内存泄漏累积# 创建 gunicorn 配置文件 /opt/archery/gunicorn.conf.py cat /opt/archery/gunicorn.conf.py EOF import multiprocessing bind 127.0.0.1:8001 bind_address 127.0.0.1:8001 workers 2 # 保守值2 核 CPU 设 24 核设 3切勿设为 cpu_count() worker_class sync worker_connections 1000 timeout 30 keepalive 5 max_requests 1000 max_requests_jitter 100 preload True daemon False pidfile /var/run/archery.pid logfile /var/log/archery/access.log loglevel info access_log_format %(h)s %(l)s %(u)s %(t)s %(r)s %(s)s %(b)s %(f)s %(a)s EOF参数说明workers2Archery 的审核引擎是 CPU 密集型每个 worker 启动时加载全部规则库约 120MB 内存过多 worker 反而触发 OOM实测 2 worker 4GB 内存服务器可稳压 200 QPS 审核请求。max_requests1000强制 worker 处理 1000 个请求后重启避免长连接导致的内存碎片堆积Archery 的 SQL 解析器使用sqlparse其 AST 构建过程有轻微内存泄漏。preloadTrue确保所有 worker 加载同一份规则缓存避免每个 worker 单独解析规则 JSON 导致启动延迟翻倍。3.2 配置 nginx静态资源分离与反向代理Archery 的前端资源JS/CSS/图片全放在archery/static/下若由 gunicorn 直接提供会严重拖慢响应速度。nginx 必须接管/static/路径并对/api/路径做负载均衡# 安装 nginxCentOS 7 sudo yum install -y nginx # 创建 Archery 专属配置 /etc/nginx/conf.d/archery.conf cat /etc/nginx/conf.d/archery.conf EOF upstream archery_backend { server 127.0.0.1:8001; } server { listen 80; server_name archery.your-company.com; # 静态资源由 nginx 直接服务不经过 gunicorn location /static/ { alias /opt/archery/archery/static/; expires 1h; add_header Cache-Control public, immutable; } # API 请求转发给 gunicorn location /api/ { proxy_pass http://archery_backend; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_connect_timeout 30s; proxy_send_timeout 30s; proxy_read_timeout 30s; } # 前端路由 fallbackVue Router history 模式 location / { root /opt/archery/archery/dist; try_files $uri $uri/ /index.html; } } EOF # 启动 nginx 并设为开机自启 sudo systemctl enable nginx sudo systemctl start nginx3.3 systemd 服务定义进程守护与日志集成用 systemd 替代nohup gunicorn ... 实现优雅关闭SIGTERM、崩溃自动重启、日志统一收集# 创建服务文件 /etc/systemd/system/archery.service cat /etc/systemd/system/archery.service EOF [Unit] DescriptionArchery SQL Audit Platform Afternetwork.target mysql.service [Service] Typesimple Userarchery Grouparchery WorkingDirectory/opt/archery/archery EnvironmentPATH/opt/archery/venv/bin ExecStart/opt/archery/venv/bin/gunicorn --config /opt/archery/gunicorn.conf.py archery.wsgi:application Restartalways RestartSec10 KillSignalSIGTERM TimeoutStopSec60 StandardOutputjournal StandardErrorjournal SyslogIdentifierarchery [Install] WantedBymulti-user.target EOF # 创建运行用户并授权 sudo useradd -r -s /sbin/nologin archery sudo chown -R archery:archery /opt/archery sudo chmod 755 /opt/archery sudo mkdir -p /var/log/archery sudo chown archery:archery /var/log/archery # 启用并启动服务 sudo systemctl daemon-reload sudo systemctl enable archery sudo systemctl start archery # 查看日志实时跟踪启动过程 sudo journalctl -u archery -f注意WorkingDirectory必须设为/opt/archery/archery即 manage.py 所在目录否则archery.wsgi:application无法定位 settings 模块EnvironmentPATH...是关键否则 systemd 无法找到gunicorn可执行文件。4. 关键功能落地SQL 审核、Binlog 闪回、PT-Archiver 归档三件套Archery 的核心价值不在 UI而在它把 DBA 日常三大高频操作——SQL 审核、误删回滚、历史数据归档——封装成开箱即用的 Web 功能。这三块必须单独验证否则等于没装。4.1 SQL 审核不只是语法检查而是规则引擎驱动的风险拦截Archery 的审核不是正则匹配而是基于sqlparse构建 AST再遍历节点执行规则。默认规则集archery/sql/rules/包含 37 条覆盖「无 WHERE 的 UPDATE/DELETE」「未走索引的 LIKE 查询」「大表 ALTER 不带 ALGORITHMINPLACE」等硬性红线。启用方式如下# 登录 Web 控制台http://your-server-ip用 admin/admin 登录 # 进入「系统管理」→「审核配置」→「审核规则」 # 勾选「启用审核」并设置 # - 审核级别高危阻断、中危告警、低危提示 # - 规则组MySQL 8.0自动适配 MySQL 8.0 的新特性如隐藏索引、角色权限 # - 白名单 IP填开发机 IP 段如 192.168.10.0/24非白名单提交直接拒绝实测案例提交以下 SQLUPDATE users SET status0;Archery 会立即返回错误【高危】UPDATE 语句缺少 WHERE 条件禁止执行。若改为UPDATE users SET status0 WHERE id 100;则进入下一步——索引检查。若users.id无索引会提示【中危】WHERE 条件字段 id 未命中索引预计影响行数 10000建议添加索引。4.2 Binlog 闪回用 Binlog2SQL 实现秒级误删恢复Archery 内置 Binlog2SQL 的 Web 封装但需手动配置 MySQL 的 binlog 格式与权限。这是最易踩坑的模块务必按以下步骤操作-- 1. 确保 MySQL 开启 ROW 格式 binlogSTATEMENT 格式无法闪回 SET GLOBAL binlog_format ROW; -- 永久生效在 /etc/my.cnf 的 [mysqld] 段添加 # binlog_format ROW # binlog_row_image FULL -- 2. 创建专用闪回账号最小权限原则 CREATE USER archery_flashbacklocalhost IDENTIFIED BY FlashPass456!; GRANT SELECT ON *.* TO archery_flashbacklocalhost; GRANT REPLICATION SLAVE ON *.* TO archery_flashbacklocalhost; GRANT REPLICATION CLIENT ON *.* TO archery_flashbacklocalhost; FLUSH PRIVILEGES;# 3. 在 Archery Web 界面配置 MySQL 实例 # 「实例管理」→「添加实例」→ 填入 # - 实例名称prod-mysql-8033 # - 主机地址127.0.0.1 # - 端口3306 # - 用户名archery_flashback # - 密码FlashPass456! # - 角色从库即使主库也要选从库因 Binlog2SQL 只读 # - 其他保持默认验证闪回在测试库执行DELETE FROM test_table WHERE id1;然后在 Archery「闪回」页面选择该实例、时间范围覆盖删除时间、表名点击「生成回滚 SQL」——输出结果应为INSERT INTO test_table (id, name) VALUES (1, xxx);。若返回空或报错No binlog found90% 是binlog_row_image ! FULL或账号无REPLICATION SLAVE权限。4.3 PT-Archiver 归档自动清理大表不锁表、不丢数据Archery 将 Percona Toolkit 的pt-archiver封装为定时任务支持按主键分片归档、保留 N 天、归档到另一张表或另一库。配置前需确保pt-archiver已安装非 Python 包是 Perl 脚本# 安装 pt-archiverCentOS 7 sudo yum install -y perl-DBI perl-DBD-MySQL perl-Time-HiRes perl-TermReadKey # 测试是否可用 pt-archiver --version # 应输出 3.3.3 或更高 # 在 Archery Web 界面配置归档任务 # 「归档管理」→「添加归档任务」→ 填入 # - 源实例prod-mysql-8033必须是主库因需写操作 # - 源表logs_2024 # - 目标表logs_archive_2024可同库不同名或跨库 # - 归档条件create_time DATE_SUB(NOW(), INTERVAL 90 DAY) # - 每次归档行数5000避免单次事务过大 # - 限流--sleep 0.1每归档 5000 行休眠 0.1 秒降低主库压力 # - 启用勾选「启用」并设置 Cron 表达式如 0 2 * * * 每日凌晨 2 点执行关键参数说明--where条件必须能走索引否则pt-archiver会全表扫描导致主库 IO 暴涨--limit 5000是安全阈值超过 10000 行易触发 MySQLmax_allowed_packet错误--sleep 0.1是血泪经验某次未设 sleep归档任务在凌晨 2 点瞬间打满主库 100% IO导致线上交易超时。5. 避坑指南生产环境踩过的 5 个真实坑与解法Archery 文档写得简略但真实部署时80% 的问题来自环境细节。以下是我们在 3 个不同客户现场反复遇到的 5 个典型问题按现象 → 原因 → 解决的结构整理避免你重蹈覆辙。5.1 现象Web 页面显示 “502 Bad Gateway”nginx 日志报connect() failed (111: Connection refused) while connecting to upstream原因gunicorn 进程未启动或启动后立即崩溃退出。常见于settings.py中数据库密码错误、MySQL 服务未运行、或archery/settings.py里DEBUG True未关生产环境必须设为False否则 Django 会禁用ALLOWED_HOSTS校验导致 gunicorn 拒绝响应。解决sudo systemctl status archery查看服务状态若为active (exited)说明启动失败sudo journalctl -u archery -n 50查看最后 50 行日志重点找OperationalError数据库连接失败或ImproperlyConfiguredsettings 配置错误检查/opt/archery/archery/settings.py确认DEBUG False且ALLOWED_HOSTS [archery.your-company.com, 192.168.10.100]填你的域名或 IP手动执行source /opt/archery/venv/bin/activate cd /opt/archery/archery python manage.py db init验证数据库连接是否通。5.2 现象SQL 审核通过但执行时报错ERROR 1054 (42S22): Unknown column xxx in field list原因Archery 的审核引擎只解析 SQL 文本不连接数据库校验字段是否存在。当开发提交的 SQL 引用了不存在的列审核阶段无法发现直到真正执行才报错。解决短期在「审核配置」中启用「执行前校验」开关v4.2.0 支持该功能会在审核通过后、执行前用目标库账号执行EXPLAIN或SELECT 1 FROM table LIMIT 0预检字段长期推动开发使用 IDE如 DataGrip的 SQL 语法检查插件在编码阶段就发现字段错误而非依赖上线前审核。5.3 现象Binlog 闪回页面报错Cant find any binlog files但SHOW BINARY LOGS显示有文件原因MySQL 的log_bin_basename路径与 Archery 配置的binlog_path不一致。Archery 默认读取/var/lib/mysql下的 binlog但若 MySQL 配置了log_bin /data/mysql/binlog/mysql-bin则 Archery 找不到文件。解决登录 MySQL 执行SHOW VARIABLES LIKE log_bin_basename;得到实际路径如/data/mysql/binlog/mysql-bin在 Archery Web 界面「实例管理」→ 编辑对应实例 → 「高级配置」→ 填入binlog_path /data/mysql/binlog注意只填目录不带文件名重启 archery 服务sudo systemctl restart archery。5.4 现象PT-Archiver 归档任务执行后源表数据清空但目标表无数据原因pt-archiver默认使用--bulk-insert模式该模式要求目标表存在且结构完全一致。若目标表不存在或字段顺序/类型不匹配如源表created_at DATETIME目标表created_at TIMESTAMPpt-archiver会静默失败。解决执行归档前手动创建目标表SQL 用SHOW CREATE TABLE source_table\G复制再替换表名在 Archery 归档任务配置中取消勾选「自动建表」改用「手动建表」添加--dry-run参数测试在服务器上手动执行pt-archiver --source h127.0.0.1,Dtest,tlogs_2024 --dest h127.0.0.1,Dtest,tlogs_archive_2024 --where id100 --dry-run观察输出是否显示INSERT INTO ... SELECT ...。5.5 现象用户登录后右上角显示 “Anonymous” 而非用户名且无法退出原因Django 的 session backend 配置错误。Archery 默认用数据库存 session但若settings.py中SESSION_ENGINE django.contrib.sessions.backends.cache且未配置 Redis则 session 无法持久化每次请求都新建匿名 session。解决检查/opt/archery/archery/settings.py确认SESSION_ENGINE django.contrib.sessions.backends.db确保已执行python manage.py migrate该命令会创建django_session表若坚持用 cache需安装 Redis 并配置CACHES { default: { BACKEND: django.core.cache.backends.redis.RedisCache, LOCATION: redis://127.0.0.1:6379/1, } } SESSION_ENGINE django.contrib.sessions.backends.cache6. 进阶技巧让 Archery 真正融入你的研发流程装完 Archery 只是起点让它成为研发流程的“守门人”需要几个关键动作。我见过太多团队装完就扔在角落半年后发现审核工单为 0——不是工具不好是没把它嵌进流程里。6.1 Git Hook 拦截在代码提交前就卡住危险 SQL与其等开发提工单再审核不如在git commit时就扫描 SQL 文件。我们用 pre-commit hook sqlparse写了个轻量检查器放在项目根目录.pre-commit-config.yamlrepos: - repo: local hooks: - id: sql-check name: Check SQL safety before commit entry: bash -c grep -r UPDATE.*SET.*WHERE\|DELETE.*FROM.*WHERE --include*.sql . | grep -q . echo ❌ Found unsafe SQL (UPDATE/DELETE without WHERE). Fix it! exit 1 || echo ✅ SQL looks safe. language: system types: [sql]效果开发git commit -m add init data时若当前目录下有init.sql包含UPDATE users SET status1;commit 直接被拒绝并打印错误信息。这比 Web 审核早了至少 3 个环节写代码 → 提交 → 推送 → 提工单 → 审核把风险左移。6.2 审核规则定制用 Python 写一条专属规则Archery 允许在archery/sql/rules/下新增.py文件定义自己的规则。比如你公司规定所有INSERT必须指定字段名禁止INSERT INTO t VALUES (...)可以这样写# archery/sql/rules/require_column_names.py from archery.sql.utils import get_object_name from archery.sql.rules import BaseRule class RequireColumnNames(BaseRule): 【高危】INSERT 语句必须显式指定字段名禁止使用 INSERT INTO t VALUES (...) def match(self, statement): if not statement.is_insert(): return False # 检查是否有括号内的字段列表如 INSERT INTO t (id,name) VALUES ... if statement.tokens[3].is_group and statement.tokens[3].parenthesis: return False return True def message(self): return INSERT 必须指定字段名例如INSERT INTO t (id, name) VALUES (1, a);注意规则文件名必须以.py结尾类名首字母大写且继承BaseRulematch()返回True表示触发规则。写完后重启 Archery 服务即可生效。6.3 数据库变更追踪表用 Archery 的 audit_log 表做 DevOps 审计Archery 的audit_log表archery.audit_log记录每一次审核、执行、闪回的操作包含user_id、sql_content、status、create_time。我们把它接入 ELK配置 Kibana 看板每天自动生成《数据库变更日报》时间操作人SQL 类型影响行数状态耗时09:23dev-zhangUPDATE12success0.8s14:05ops-liALTER TABLE0blocked0.2s实现方式用 Logstash 的jdbcinput 插件每 5 分钟查一次audit_log表过滤create_time NOW() - INTERVAL 1 DAY输出到 Elasticsearch。这样CTO 不用问 DBA直接看 Kibana 就知道今天谁改了什么、有没有高危操作被拦截。我带过的三个团队最早那个是手工维护 Excel 变更记录后来用 Archery ELK上线后第一个月就发现 2 起开发误删表事件被自动拦截挽回了至少 2 天的数据恢复成本。工具不会自己发光得你把它焊进流程里。希望帮到你。本文还有配套的精品资源点击获取