
简介《archery使用手册》面向数据库开发人员、DBA及运维工程师聚焦SQL审核查询平台Archery的落地使用帮助读者系统掌握从SQL规范审核到MySQL实例运维的完整流程。压缩包内为1个doc文档约1.2MB以图文结合的方式组织内容便于按章节检索与对照操作。目前已有1478人学习下载具备一定的实践参考基础。文档围绕SQL审核、SQL优化、实例管理与工具插件四大模块展开审核部分讲解语法解析、自定义规则校验、高危语句驳回及定时执行与回滚优化部分涵盖执行计划分析与慢SQL统计实例管理涉及binlog清理、会话与事务查看、锁信息排查及账号授权插件部分介绍PTArchiver归档、Binlog2SQL解析与SchemaSync结构同步。文中还给出开发与测试环境的审核流程示例适合需要规范SQL上线、提升数据库运维效率的读者参考。1. 装 Archery 之前先把这套环境账算清楚第一次在一台干净的测试机上装 Archery我按着某篇教程一路pip install下去结果卡在mysqlclient编译报错上整整一个下午——缺libmysqlclient-dev缺python3-devel缺到怀疑人生。Archery 这个 SQL 审核查询平台功能确实全SQL 审核、SQL 优化、实例管理、会话与锁排查、binlog 清理、账号授权还带 pt-archiver、binlog2sql、schemaSync 三个插件。但它的安装门槛不在代码而在环境依赖的版本咬合上。Python 版本、MySQL 版本、Redis、GoInception 审核引擎任何一环版本对不上页面能打开但工单提交就报错。这篇笔记按我实际部署的顺序写先列环境再装依赖再配审核引擎最后验证一条 SQL 工单能不能走通。适合第一次搭 Archery 的开发者也适合装到一半卡住、想对照排查的人。2. 环境准备与版本选型Python、MySQL、Redis 一个都不能错Archery 本质是一个 Django 应用前端页面 后端服务 审核引擎三部分组成。装之前先把版本定死别用「最新版」三个字糊弄自己这是血泪经验。2.1 版本对照表与选型理由我一般按下面这套组合来稳定、资料多、踩坑少组件推荐版本说明操作系统CentOS 7.x / Ubuntu 20.04生产环境常见依赖包好找Python3.6 ~ 3.8Archery 对高版本 Python 兼容性一般3.9 以上容易在依赖编译上翻车MySQL5.7Archery 自身元数据库5.7 最稳8.0 需注意认证插件Redis5.x缓存与异步任务队列依赖GoInception最新稳定版SQL 审核引擎负责语法解析与规则审核Nginx1.18反向代理前端静态资源Python 为什么卡在 3.8 以下Archery 依赖里有一批老包比如某些版本的cryptography、mysqlclient在 3.9 上要么编译失败要么运行时行为不一致。我见过有人硬上 3.10结果pip install阶段就报AttributeError最后退回 3.8 才通。MySQL 选 5.7 是因为 Archery 元数据库建表语句和 8.0 的默认字符集、认证方式有差异8.0 需要额外改default_authentication_plugin新手容易在这里卡住。2.2 基础依赖安装先装系统级依赖这一步漏一个后面就多一次翻车# CentOS 7 环境装编译工具和 MySQL 客户端库 yum install -y gcc gcc-c make \ python3 python3-devel python3-pip \ mysql-devel \ libffi-devel openssl-devel \ redis nginx gitpython3-devel和mysql-devel是编译mysqlclient的前提libffi-devel、openssl-devel是cryptography编译的前提。这四个包缺任何一个pip install -r requirements.txt都会在中途报错。装完确认版本python3 --version # 期望 3.6.x ~ 3.8.x mysql --version # 期望 5.7.x redis-server --version如果python3 --version出来是 3.9 以上别急着往下走先装个 3.8 的虚拟环境或者用pyenv切版本。这一步多花十分钟后面省两小时。2.3 创建虚拟环境与拉取代码# 建虚拟环境隔离依赖 python3 -m venv /opt/venv/archery source /opt/venv/archery/bin/activate # 拉代码到部署目录 cd /opt git clone https://github.com/hhyo/Archery.git cd Archery虚拟环境这一步别省。Archery 依赖的包版本比较老直接装到系统 Python 里容易和系统其他服务打架。激活后pip -V应该指向/opt/venv/archery/bin/pip确认无误再装依赖。3. 安装 Archery 主程序依赖、配置、初始化三步走主程序安装分三块Python 依赖、配置文件、数据库初始化。顺序不能乱配置没改对就初始化后面还得重来。3.1 安装 Python 依赖cd /opt/Archery pip install --upgrade pip pip install -r requirements.txtrequirements.txt里包含 Django、mysqlclient、celery、redis 等核心包。如果卡在mysqlclient编译报mysql_config not found说明mysql-devel没装或没在 PATH 里报Python.h: No such file说明python3-devel缺失。这两个报错我遇到太多次了基本就是系统依赖没装全。装完后验证关键包python -c import MySQLdb; print(mysqlclient ok) python -c import django; print(django.get_version())两条都打印正常依赖这关才算过。3.2 修改配置文件Archery 的配置集中在archery/settings.py需要改数据库连接、Redis 连接、以及审核引擎地址# archery/settings.py 关键配置片段 DATABASES { default: { ENGINE: django.db.backends.mysql, NAME: archery, # 元数据库名需提前创建 USER: archery, # 数据库账号 PASSWORD: your_password, HOST: 127.0.0.1, PORT: 3306, OPTIONS: {charset: utf8mb4}, } } # Redis 配置缓存和 celery 都用它 CACHES { default: { BACKEND: django_redis.cache.RedisCache, LOCATION: redis://127.0.0.1:6379/0, } } # GoInception 审核引擎地址 INCEPTION_HOST 127.0.0.1 INCEPTION_PORT 4000NAME对应的库要先手动建好字符集用utf8mb4否则中文注释会乱码。INCEPTION_HOST和INCEPTION_PORT指向后面要装的 GoInception 服务端口默认 4000。配置改完别急着启动先把元数据库建出来。3.3 初始化数据库与启动服务# 建元数据库 mysql -uroot -p -e CREATE DATABASE archery DEFAULT CHARSET utf8mb4; # 执行 Django 迁移建表 python manage.py makemigrations python manage.py migrate # 创建管理员账号 python manage.py createsuperuser # 启动开发服务验证生产用 uwsgi/nginx python manage.py runserver 0.0.0.0:8000migrate会按 Django 模型建出所有表包括用户、工单、实例、审核规则等。如果这一步报django.db.utils.OperationalError八成是settings.py里的数据库账号密码或库名不对。createsuperuser建的是 Archery 登录账号不是 MySQL 账号别搞混。runserver只是验证用浏览器访问http://IP:8000能看到登录页说明主程序起来了。4. 配置 GoInception 审核引擎SQL 审核能不能跑全看它Archery 页面能打开不代表能审核 SQL。SQL 检测、回滚语句生成、规则校验全靠 GoInception 这个引擎。它没配好工单提交时点「SQL 检测」就会报连接失败。4.1 安装 GoInceptionGoInception 是 Go 写的装起来比 Python 项目省心# 下载对应版本二进制包以 linux amd64 为例 wget https://github.com/hanchuanchuan/goInception/releases/download/v1.3.0/goInception-linux-amd64-v1.3.0.tar.gz tar -zxvf goInception-linux-amd64-v1.3.0.tar.gz -C /usr/local/ cd /usr/local/goInception版本号按实际发布页选别照抄。解压后目录里有config.toml.default复制一份改成config.toml。4.2 修改 GoInception 配置# config.toml 关键项 host 0.0.0.0 port 4000 [inc] backup_host 127.0.0.1 backup_port 3306 backup_user root backup_password your_password [osc] onnline-ddl trueport要和 Archerysettings.py里的INCEPTION_PORT一致。backup_*是回滚语句生成时连接的 MySQL 地址Archery 生成回滚 SQL 依赖它账号需要有相应库的读权限。onnline-ddl开启在线 DDL大表变更时减少锁表时间。4.3 启动并验证引擎# 后台启动 nohup ./goInception -configconfig.toml goInception.log 21 # 验证端口监听 netstat -tlnp | grep 4000 # 用 mysql 客户端连一下能连上说明引擎正常 mysql -h127.0.0.1 -P4000 -uroot -e select 1;GoInception 兼容 MySQL 协议所以能用 mysql 客户端直连测试。select 1返回结果说明引擎在跑。如果连不上看goInception.log常见是端口被占或配置文件路径不对。引擎起来后回 Archery 页面在「实例管理」里添加一个 MySQL 实例然后在「SQL 审核」里提交一条测试 SQL点「SQL 检测」能返回审核结果哪怕是报错提示说明 Archery 和 GoInception 的链路通了。5. 避坑与常见问题装 Archery 最容易翻车的五个地方这一章是我踩过的坑合集每条按「现象 → 原因 → 解决」写照着对号入座。5.1 SQL 检测报「连接审核引擎失败」现象Archery 页面正常提交工单点「SQL 检测」提示连接 GoInception 失败。 原因settings.py里INCEPTION_HOST/INCEPTION_PORT和 GoInception 实际监听不一致或者 GoInception 没启动。 解决先netstat -tlnp | grep 4000确认引擎在监听再用mysql -h127.0.0.1 -P4000 -uroot直连验证。都正常的话检查 Archery 配置里的 IP 是不是写成了localhost而引擎只监听0.0.0.0之外的地址统一改成127.0.0.1最稳。5.2 中文注释乱码现象建表语句里带中文注释审核通过后执行注释变成问号。 原因元数据库或目标实例字符集不是utf8mb4。 解决建 Archery 元数据库时显式指定DEFAULT CHARSET utf8mb4目标 MySQL 实例的库和表也确认字符集。settings.py的OPTIONS里加charset: utf8mb4三处都对齐才不会乱。5.3 回滚 SQL 生成失败现象工单执行后想下载回滚 SQL提示生成失败或为空。 原因GoInception 的backup_user权限不足或者 binlog 格式不是ROW。 解决确认目标实例binlog_formatROW这是回滚语句生成的前提给backup_user对应库的SELECT权限。DDL 操作本身无法回滚这是 binlog2sql 和 GoInception 的共同限制别指望它能回滚ALTER TABLE。5.4 定时执行不生效现象工单选了「定时执行」到点没动静。 原因Celery 异步任务没启动或者 Redis 连接不通。 解决Archery 的定时任务靠 Celery Redis。确认 Redis 在跑然后单独启动 Celery workercelery -A archery worker -l info。生产环境用 supervisor 托管别用nohup裸跑进程挂了没人知道。5.5 页面静态资源 404现象登录页能开但样式全丢控制台一堆 404。 原因DEBUGFalse时 Django 不托管静态文件需要 Nginx 接管。 解决python manage.py collectstatic收集静态文件到指定目录Nginx 配置里把/static/指向该目录。开发阶段图省事可以DEBUGTrue但上线必须关掉否则性能和安全隐患都来了。6. 装完怎么验证一条 SQL 工单走通才算数装完所有组件页面能登录不代表这套环境可用。我的验证习惯是走一条完整的 SQL 工单从提交到执行到回滚全链路跑一遍。这一步过了才算真装好。6.1 全链路验证清单按下面顺序操作每步确认结果步骤操作期望结果1实例管理添加一个测试 MySQL 实例实例列表出现该实例连接测试通过2SQL 审核提交一条SELECT * FROM test_table点「SQL 检测」返回审核结果SELECT *应提示优化建议3提交一条建表语句无主键审核报错提示需主键验证规则生效4提交合规建表语句走完审核审核通过可选立即/定时执行5执行后查看回滚 SQL能下载或查看回滚语句DML 才有6会话管理查看进程能看到当前连接验证实例管理链路第 3 步是关键故意提交一条不合规的 SQL看审核引擎能不能拦住。拦不住说明规则没生效回去检查 GoInception 配置和 Archery 的审核规则集。第 5 步只对 DML 有效DDL 回滚不了这是预期行为别当成 bug。6.2 用命令行快速自检不想点页面的话用命令行验证核心链路# 验证 Archery 服务 curl -I http://127.0.0.1:8000/login/ # 期望 200 # 验证 GoInception 引擎 mysql -h127.0.0.1 -P4000 -uroot -e inception get variables like version; # 验证 Redis redis-cli ping # 期望 PONG # 验证 Celery worker 是否在跑 ps -ef | grep celery | grep -v grep四条都正常说明四个核心组件都在线。inception get variables是 GoInception 的特有语法能返回版本号说明引擎不只是端口通协议层也正常。6.3 我踩过的一个验证盲区有次装完页面、审核、执行都正常我以为万事大吉结果一周后定时工单集体不执行——Celery worker 半夜被 OOM 杀了没人发现。从那以后我每次装完 Archery都强制走一遍「提交定时工单 → 等它到点执行 → 查执行记录」这条链路并且用 supervisor 把 Celery 托管起来配autostarttrue、autorestarttrue。装工具这件事能跑通只是及格线能扛住进程意外退出才算交付。希望这套流程帮到你少走我当年那个下午的弯路。本文还有配套的精品资源点击获取