简介《archery使用手册》面向数据库开发人员、DBA及运维工程师聚焦SQL审核查询平台Archery的落地使用帮助读者系统掌握从SQL规范审核到MySQL实例运维的完整流程。资源包共1个文件为doc格式文档压缩包约1.2MB内容围绕功能详解与实践案例两条主线组织便于按模块查阅。手册先梳理SQL审核的语法解析与自定义规则机制涵盖主键与注释检查、高危语句驳回、定时执行及钉钉通知继而展开SQL优化建议、慢SQL统计、binlog清理、会话与事务管理、锁信息排查、账号授权及动态参数配置并介绍PTArchiver归档、Binlog2SQL解析回滚、SchemaSync结构同步等插件用法。实践部分以开发与测试环境的审核流程为例演示提交、检测、审批、执行与回滚操作配合SQL分析报告与锁等待排查示例帮助读者把功能对应到真实运维场景。目前已有1478人学习适合需要规范SQL上线流程、提升实例排障效率的读者参考。1. 装 Archery 之前先把这套环境盘清楚第一次在一台干净的测试机上装 Archery我按着记忆里的步骤走结果docker-compose up之后容器起起落落页面一直 502。翻日志才发现是 MySQL 字符集没配对utf8和utf8mb4混着来初始化脚本直接报错退出。这类翻车在 Archery 部署里太常见了——它不是一个单体应用而是 Django 后端、Vue 前端、MySQL 元数据库、Redis 缓存、Inception 审核引擎几块拼起来的组合体任何一块版本或参数不对整个平台就起不来。Archery 定位于 SQL 审核查询平台同时带一堆 MySQL 运维功能适合研发、测试和 DBA 在同一个工单流里协作。这篇笔记按我实际装过几套环境的顺序写先列版本和依赖再走 Docker 和源码两条安装路径然后配审核规则和实例最后落到怎么验证跑通、装坏了怎么救。2. 环境准备与版本选型MySQL、Redis、Inception 各装哪个版本装 Archery 最容易忽略的一步是把周边依赖的版本先钉死。官方仓库的requirements.txt和docker-compose.yml里其实已经给了参考版本但很多人直接拉最新镜像结果 Django 版本和 Python 版本对不上pip install阶段就卡住。我一般会先确认三件事Python 用 3.6 还是 3.8、MySQL 用 5.7 还是 8.0、Inception 要不要单独编译。这三件事定下来后面的安装才有确定性。2.1 版本对照表与选型理由下面这张表是我在几套环境里验证过的组合左边是组件右边是推荐版本和原因。注意 Archery 本身对 MySQL 8.0 的支持要看具体分支老版本分支在 8.0 上会因为默认认证插件caching_sha2_password连不上所以元数据库我倾向 5.7。组件推荐版本选型说明操作系统CentOS 7.9 / Ubuntu 20.04内核和 glibc 稳定编译 Inception 少踩坑Python3.6.8与 Archery 依赖的 Django 2.2 匹配3.8 以上部分包编译失败MySQL元数据库5.7.36避开 8.0 默认认证插件问题字符集统一 utf8mb4Redis5.0.14只做缓存和 Celery broker5.x 足够Inception官方 master 编译SQL 审核引擎必须单独编译安装Archery1.8.x 分支功能完整社区文档对应得上选 Python 3.6 不是保守是血泪经验。Archery 依赖里有个别包在 3.8 上需要额外打补丁新手照着 README 走很容易在mysqlclient编译那一步翻车。如果机器上已经有 3.8建议用pyenv或 conda 单独建一个 3.6 环境别动系统自带的 Python。2.2 系统依赖与基础软件安装先把编译工具和 MySQL 客户端库装上后面pip install mysqlclient才不会报mysql_config not found。CentOS 和 Ubuntu 的命令略有差别我按 CentOS 写Ubuntu 把yum换成apt即可。# CentOS 7 安装编译依赖和 MySQL 开发库 yum install -y gcc gcc-c make cmake \ ncurses-devel bison openssl-devel \ mysql-devel python3-devel git wget # 确认 python3 版本必须是 3.6.x python3 --version这段命令里mysql-devel提供mysql_configpython3-devel提供 Python 头文件缺一个mysqlclient就装不上。cmake和bison是后面编译 Inception 用的现在一起装掉省得回头补。装完用python3 --version确认版本如果输出 3.8 以上先别急着往下走用虚拟环境隔离。Redis 和 MySQL 元数据库我一般用 Docker 起省得配一堆配置文件。但要注意 MySQL 容器启动时必须带字符集参数否则初始化 Archery 表结构时中文注释会乱码。# 启动 MySQL 5.7 元数据库强制 utf8mb4 docker run -d --name archery-mysql \ -p 3306:3306 \ -e MYSQL_ROOT_PASSWORDarchery123 \ -e MYSQL_DATABASEarchery \ --character-set-serverutf8mb4 \ --collation-serverutf8mb4_unicode_ci \ mysql:5.7 # 启动 Redis docker run -d --name archery-redis -p 6379:6379 redis:5.0--character-set-server和--collation-server这两个参数是重点很多人只设了MYSQL_DATABASE就以为够了结果 Archery 建表时LONGTEXT字段存中文报错。MYSQL_ROOT_PASSWORD自己换掉后面 Archery 的settings.py里要填同样的密码。2.3 Inception 编译安装Inception 是 Archery 做 SQL 审核的核心引擎它不在 pip 源里必须从源码编译。这一步是整套安装里最容易卡住的地方因为 Inception 依赖老版本的 MySQL 源码库编译参数写错就报链接错误。# 拉取 Inception 源码并编译 git clone https://github.com/mysql-inception/inception.git cd inception # 依赖已在上一步装好直接 cmake cmake -DCMAKE_INSTALL_PREFIX/usr/local/inception \ -DWITH_DEBUGOFF \ -DCMAKE_BUILD_TYPERelease make make installCMAKE_INSTALL_PREFIX指定安装目录后面 Archery 配置里要指向这里的bin/inception。WITH_DEBUGOFF关掉调试符号编译快一半。编译完成后检查/usr/local/inception/bin/inception是否存在再写一个最小配置文件/etc/inception.cnf里面至少要有inception_magic_start和inception_magic_commit两个标记Archery 靠它们包裹待审核的 SQL。提示Inception 编译对 gcc 版本敏感CentOS 7 自带的 gcc 4.8 一般能过如果报undefined reference一类错误先确认mysql-devel装的是 5.7 而不是 8.08.0 的头文件不兼容。3. Archery 主体安装Docker Compose 与源码两条路环境备齐后装 Archery 本身有两条路Docker Compose 一把梭适合快速验证和测试环境源码安装适合要改代码或深度定制审核规则的生产环境。两条路我都走过Docker 快但排错黑匣子多源码慢但每一步都看得见。下面分别写你按自己的场景选。3.1 Docker Compose 方式最快跑起来Archery 官方仓库带docker-compose.yml但直接up之前要改几个环境变量尤其是数据库连接和SECRET_KEY。我一般先 clone 下来改.env再起。git clone https://github.com/hhyo/Archery.git cd Archery # 复制环境变量模板并修改 cp .env.example .env.env里重点改这几项DATABASE_URL指向前面起的 MySQLREDIS_URL指向 RedisSECRET_KEY随便生成一串长随机字符。改完执行# 构建并后台启动所有服务 docker-compose up -d --build # 查看容器状态确认 archery 和 celery 都是 Up docker-compose ps--build会重新构建镜像第一次跑要拉基础镜像时间比较长。docker-compose ps里如果archery容器状态是Restarting别急着看页面先docker-compose logs archery看日志八成是数据库连不上或迁移没跑完。Docker 方式下数据库迁移是容器启动时自动执行的如果 MySQL 还没 ready迁移会失败容器就反复重启。常见做法是等 MySQL 容器日志出现ready for connections再起 Archery。3.2 源码安装可控但步骤多源码安装适合需要调审核规则或接内部通知系统的场景。步骤是建虚拟环境、装依赖、改配置、迁移数据库、起服务。# 建 Python 3.6 虚拟环境 python3 -m venv /opt/venv/archery source /opt/venv/archery/bin/activate # 安装依赖国内建议加清华源 pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simplerequirements.txt里mysqlclient编译最耗时前面装好mysql-devel就不会报错。依赖装完后复制archery/settings.py的模板改数据库和 Redis 配置# archery/settings.py 关键片段 DATABASES { default: { ENGINE: django.db.backends.mysql, NAME: archery, USER: root, PASSWORD: archery123, HOST: 127.0.0.1, PORT: 3306, OPTIONS: {charset: utf8mb4}, } } # Redis 作为 Celery broker CELERY_BROKER_URL redis://127.0.0.1:6379/0OPTIONS里的charset必须写utf8mb4和元数据库保持一致。改完执行迁移和静态文件收集python manage.py makemigrations python manage.py migrate python manage.py collectstatic --noinputmigrate会建一堆表如果中途报字段长度或字符集错误回头检查 MySQL 的character_set_server。collectstatic把前端静态资源归到static/目录后面 Nginx 要指向这里。最后起服务开发环境用runserver验证生产用gunicorn加 Nginx这里先验证# 开发模式起后端确认能访问 python manage.py runserver 0.0.0.0:8000浏览器打开http://机器IP:8000能看到登录页就说明主体通了。默认管理员账号在迁移时创建用户名admin密码看settings.py里的初始化配置或首次登录强制修改。3.3 前端资源与 Nginx 反代源码方式下前端是单独构建的collectstatic只处理 Django 的静态文件Vue 前端要npm run build后把dist交给 Nginx。如果只验证后端可以先用runserver顶着要完整跑通工单流Nginx 配置不能少。server { listen 80; server_name archery.local; location / { root /opt/Archery/dist; try_files $uri $uri/ /index.html; } location /api/ { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }try_files那行是给 Vue 的 history 路由用的不加的话刷新页面 404。/api/反代到 Django前后端就接上了。Nginx 改完nginx -t测配置再reload别直接重启生产上重启会断连接。4. 配置审核规则与实例接入让工单流真正跑起来装完能登录只是第一步Archery 的价值在审核规则和实例接入。规则配松了高危语句直接放行配紧了正常建表都被驳回这个度要按团队规范调。实例接入则是把要管理的 MySQL 纳进来后面会话管理、binlog 清理、账号管理才有对象。4.1 SQL 审核规则配置Archery 的审核规则在后台「规则管理」里配底层是 Inception 的检查项。常见做法是先启用基础规范建表必须有主键、表和列必须有注释、禁止SELECT *、禁止DROP TABLE无备份执行。这些规则对应 Inception 的参数在 Archery 里是勾选加阈值。规则项建议值作用建表必须有主键开启避免无主键表导致复制延迟表/列注释开启规范元数据方便后续维护SELECT *开启强制写明字段减少回表DML 影响行数1000超过走工单审批防误更新高危语句自动驳回DROP/TRUNCATE 直接拦阈值不是拍脑袋定的DML 影响行数我一般按业务表规模设流水表可以放宽到 5000配置表设 100。规则改完要找一条测试 SQL 走一遍「SQL 检测」确认 error 和 warning 的提示符合预期别等研发提工单了才发现规则把正常语句也拦了。4.2 实例接入与连接测试实例接入在「实例管理」里新增填主机、端口、账号密码。这里有个坑Archery 连实例用的账号需要足够权限至少要有PROCESS、REPLICATION CLIENT才能看会话和 binlog只给SELECT的话会话管理页面是空的。-- 为 Archery 创建专用监控账号 CREATE USER archery_mon% IDENTIFIED BY Mon123456; GRANT SELECT, PROCESS, REPLICATION CLIENT ON *.* TO archery_mon%; -- 如果要走账号管理功能再加创建用户和授权权限 GRANT CREATE USER ON *.* TO archery_mon% WITH GRANT OPTION; FLUSH PRIVILEGES;PROCESS是看SHOW PROCESSLIST的前提REPLICATION CLIENT才能读 binlog 列表。WITH GRANT OPTION只在需要 Archery 代建账号时加安全要求高的环境可以不给账号管理功能手动关掉。加完实例点「测试连接」通了再保存不通先查网络和账号 host 限制。4.3 工单流程与通知配置工单流按环境分开发环境研发提、项目经理审测试环境测试提、测试审。这个在「工作流」里配审批链每一级指定角色。配完别忘了通知Archery 支持钉钉机器人在「通知配置」里填 webhook 地址工单提交和审核通过都会推消息。# 测试钉钉机器人是否可达替换成自己的 webhook curl -X POST https://oapi.dingtalk.com/robot/send?access_token你的token \ -H Content-Type: application/json \ -d {msgtype:text,text:{content:Archery 通知测试}}返回errcode: 0说明通不通先查 token 和机器人安全设置里的 IP 白名单。通知配好后提一条测试工单走完整流程确认每一级审批人都能收到待办别等上线当天才发现通知没发出去。5. 常见问题排查装完起不来、审核报错、连接失败怎么救这套环境装下来报错集中在几个固定位置。下面五条是我踩过或帮人处理过的按「现象 → 原因 → 解决」写遇到对得上的直接照方抓药。5.1 容器反复重启日志报数据库连接拒绝现象docker-compose ps里 archery 容器状态Restarting日志刷Cant connect to MySQL server。原因MySQL 容器还没初始化完Archery 启动时迁移就连了连不上直接退出。解决先单独起 MySQL等日志出现ready for connections再docker-compose up archery或者给 archery 服务加depends_on加健康检查等 MySQL healthy 再启动。5.2 页面能开但登录报 500日志提示表不存在现象登录页正常输账号密码后 500日志Table archery.django_session doesnt exist。原因数据库迁移没执行或执行到一半失败表没建全。解决进容器或虚拟环境执行python manage.py migrate看具体哪条迁移报错常见是字符集问题导致建表失败修好 MySQL 字符集后删库重建再迁移。5.3 SQL 检测一直报 Inception 连接失败现象提工单点「SQL 检测」提示无法连接审核引擎。原因settings.py里 Inception 配置的主机端口不对或 Inception 服务没起。解决确认/usr/local/inception/bin/inception进程在跑ps -ef | grep inception能看到再核对 Archery 配置里INCEPTION_HOST和INCEPTION_PORT默认 6669防火墙要放行。5.4 会话管理页面空白看不到进程现象实例接入了会话管理点进去没数据。原因监控账号缺PROCESS权限或者实例配置里没勾选「慢查询/会话」相关选项。解决按 4.2 的授权语句补PROCESS权限FLUSH PRIVILEGES后重进页面还不行就看实例编辑页的「查询权限」是否开启。5.5 Binlog2SQL 解析报错提示 binlog 文件不存在现象用 Binlog2SQL 插件解析某个 binlog报文件找不到。原因实例的 binlog 已经被清理或者 Archery 连的账号没有读 binlog 的权限。解决先在实例上SHOW BINARY LOGS确认文件还在不在就只能从备份恢复在的话补REPLICATION CLIENT权限并确认 Archery 配置的 binlog 路径和实例实际路径一致。6. 装完怎么验证跑通一条工单走到底才算数验证 Archery 装没装好别只看登录页能不能开。我的标准是一条带建表和更新的 SQL 工单从提交、检测、审批到执行、回滚全流程走通中间通知能收到回滚 SQL 能下载。这套走完平台才算真正可用。先准备一条测试 SQL故意带一个规范问题比如建表不写主键看检测能不能拦-- 测试用故意缺主键和注释 CREATE TABLE verify_t1 ( id INT, name VARCHAR(32) );提交工单点「SQL 检测」预期返回 error提示缺主键。把 SQL 改成带主键和注释的版本再检测应该通过。然后提交用审批账号登录右上角通知里能看到待办审批通过后选「立即执行」。执行完去实例上SHOW CREATE TABLE verify_t1确认表建出来了。接着验证回滚在工单详情里点「查看回滚 SQL」应该能看到DROP TABLE语句点「下载回滚 SQL」拿到文件。这一步很多人不测等真出事要回滚才发现回滚语句没生成那就被动了。再验证一个运维功能比如会话管理。在实例上开一个长事务-- 在测试实例上执行制造一个长事务 BEGIN; UPDATE verify_t1 SET nameblock WHERE id1; -- 不提交保持会话然后去 Archery 会话管理选对应实例command 选All勾选「完整 INFO」应该能看到这条UPDATE处于Sleep或Query状态。点「终止会话」回实例上确认连接被 kill。这一步通了说明监控账号权限和会话管理链路都没问题。最后核对通知整个流程里钉钉应该收到提交和审批两条消息。没收到就回 4.3 查 webhook。验证项预期结果不通过先查SQL 检测拦截缺主键报 error审核规则是否启用工单审批审批人收到待办工作流角色配置立即执行表成功创建实例执行账号权限回滚 SQL能查看和下载Inception 回滚配置会话管理能看到并终止会话监控账号 PROCESS 权限钉钉通知收到两条消息webhook 和 IP 白名单这套验证我每次装新环境都强制走一遍哪怕只是升级了个小版本。有一次图省事只测了登录结果上线后研发提工单发现回滚 SQL 生成不了回头查是 Inception 配置里少了个参数耽误半天。从那以后我每次装完 Archery都拿这条verify_t1工单从头到尾跑一遍六项全绿才敢交给团队用。希望帮到你。本文还有配套的精品资源点击获取 
长河君 · 2026/10/27 3:17:36 · 阅读 1.2k Archery SQL审核平台部署实战：环境准备、安装配置与工单验证全流程
简介《archery使用手册》面向数据库开发人员、DBA及运维工程师聚焦SQL审核查询平台Archery的落地使用帮助读者系统掌握从SQL规范审核到MySQL实例运维的完整流程。资源包共1个文件为doc格式文档压缩包约1.2MB内容围绕功能详解与实践案例两条主线组织便于按模块查阅。手册先梳理SQL审核的语法解析与自定义规则机制涵盖主键与注释检查、高危语句驳回、定时执行及钉钉通知继而展开SQL优化建议、慢SQL统计、binlog清理、会话与事务管理、锁信息排查、账号授权及动态参数配置并介绍PTArchiver归档、Binlog2SQL解析回滚、SchemaSync结构同步等插件用法。实践部分以开发与测试环境的审核流程为例演示提交、检测、审批、执行与回滚操作配合SQL分析报告与锁等待排查示例帮助读者把功能对应到真实运维场景。目前已有1478人学习适合需要规范SQL上线流程、提升实例排障效率的读者参考。1. 装 Archery 之前先把这套环境盘清楚第一次在一台干净的测试机上装 Archery我按着记忆里的步骤走结果docker-compose up之后容器起起落落页面一直 502。翻日志才发现是 MySQL 字符集没配对utf8和utf8mb4混着来初始化脚本直接报错退出。这类翻车在 Archery 部署里太常见了——它不是一个单体应用而是 Django 后端、Vue 前端、MySQL 元数据库、Redis 缓存、Inception 审核引擎几块拼起来的组合体任何一块版本或参数不对整个平台就起不来。Archery 定位于 SQL 审核查询平台同时带一堆 MySQL 运维功能适合研发、测试和 DBA 在同一个工单流里协作。这篇笔记按我实际装过几套环境的顺序写先列版本和依赖再走 Docker 和源码两条安装路径然后配审核规则和实例最后落到怎么验证跑通、装坏了怎么救。2. 环境准备与版本选型MySQL、Redis、Inception 各装哪个版本装 Archery 最容易忽略的一步是把周边依赖的版本先钉死。官方仓库的requirements.txt和docker-compose.yml里其实已经给了参考版本但很多人直接拉最新镜像结果 Django 版本和 Python 版本对不上pip install阶段就卡住。我一般会先确认三件事Python 用 3.6 还是 3.8、MySQL 用 5.7 还是 8.0、Inception 要不要单独编译。这三件事定下来后面的安装才有确定性。2.1 版本对照表与选型理由下面这张表是我在几套环境里验证过的组合左边是组件右边是推荐版本和原因。注意 Archery 本身对 MySQL 8.0 的支持要看具体分支老版本分支在 8.0 上会因为默认认证插件caching_sha2_password连不上所以元数据库我倾向 5.7。组件推荐版本选型说明操作系统CentOS 7.9 / Ubuntu 20.04内核和 glibc 稳定编译 Inception 少踩坑Python3.6.8与 Archery 依赖的 Django 2.2 匹配3.8 以上部分包编译失败MySQL元数据库5.7.36避开 8.0 默认认证插件问题字符集统一 utf8mb4Redis5.0.14只做缓存和 Celery broker5.x 足够Inception官方 master 编译SQL 审核引擎必须单独编译安装Archery1.8.x 分支功能完整社区文档对应得上选 Python 3.6 不是保守是血泪经验。Archery 依赖里有个别包在 3.8 上需要额外打补丁新手照着 README 走很容易在mysqlclient编译那一步翻车。如果机器上已经有 3.8建议用pyenv或 conda 单独建一个 3.6 环境别动系统自带的 Python。2.2 系统依赖与基础软件安装先把编译工具和 MySQL 客户端库装上后面pip install mysqlclient才不会报mysql_config not found。CentOS 和 Ubuntu 的命令略有差别我按 CentOS 写Ubuntu 把yum换成apt即可。# CentOS 7 安装编译依赖和 MySQL 开发库 yum install -y gcc gcc-c make cmake \ ncurses-devel bison openssl-devel \ mysql-devel python3-devel git wget # 确认 python3 版本必须是 3.6.x python3 --version这段命令里mysql-devel提供mysql_configpython3-devel提供 Python 头文件缺一个mysqlclient就装不上。cmake和bison是后面编译 Inception 用的现在一起装掉省得回头补。装完用python3 --version确认版本如果输出 3.8 以上先别急着往下走用虚拟环境隔离。Redis 和 MySQL 元数据库我一般用 Docker 起省得配一堆配置文件。但要注意 MySQL 容器启动时必须带字符集参数否则初始化 Archery 表结构时中文注释会乱码。# 启动 MySQL 5.7 元数据库强制 utf8mb4 docker run -d --name archery-mysql \ -p 3306:3306 \ -e MYSQL_ROOT_PASSWORDarchery123 \ -e MYSQL_DATABASEarchery \ --character-set-serverutf8mb4 \ --collation-serverutf8mb4_unicode_ci \ mysql:5.7 # 启动 Redis docker run -d --name archery-redis -p 6379:6379 redis:5.0--character-set-server和--collation-server这两个参数是重点很多人只设了MYSQL_DATABASE就以为够了结果 Archery 建表时LONGTEXT字段存中文报错。MYSQL_ROOT_PASSWORD自己换掉后面 Archery 的settings.py里要填同样的密码。2.3 Inception 编译安装Inception 是 Archery 做 SQL 审核的核心引擎它不在 pip 源里必须从源码编译。这一步是整套安装里最容易卡住的地方因为 Inception 依赖老版本的 MySQL 源码库编译参数写错就报链接错误。# 拉取 Inception 源码并编译 git clone https://github.com/mysql-inception/inception.git cd inception # 依赖已在上一步装好直接 cmake cmake -DCMAKE_INSTALL_PREFIX/usr/local/inception \ -DWITH_DEBUGOFF \ -DCMAKE_BUILD_TYPERelease make make installCMAKE_INSTALL_PREFIX指定安装目录后面 Archery 配置里要指向这里的bin/inception。WITH_DEBUGOFF关掉调试符号编译快一半。编译完成后检查/usr/local/inception/bin/inception是否存在再写一个最小配置文件/etc/inception.cnf里面至少要有inception_magic_start和inception_magic_commit两个标记Archery 靠它们包裹待审核的 SQL。提示Inception 编译对 gcc 版本敏感CentOS 7 自带的 gcc 4.8 一般能过如果报undefined reference一类错误先确认mysql-devel装的是 5.7 而不是 8.08.0 的头文件不兼容。3. Archery 主体安装Docker Compose 与源码两条路环境备齐后装 Archery 本身有两条路Docker Compose 一把梭适合快速验证和测试环境源码安装适合要改代码或深度定制审核规则的生产环境。两条路我都走过Docker 快但排错黑匣子多源码慢但每一步都看得见。下面分别写你按自己的场景选。3.1 Docker Compose 方式最快跑起来Archery 官方仓库带docker-compose.yml但直接up之前要改几个环境变量尤其是数据库连接和SECRET_KEY。我一般先 clone 下来改.env再起。git clone https://github.com/hhyo/Archery.git cd Archery # 复制环境变量模板并修改 cp .env.example .env.env里重点改这几项DATABASE_URL指向前面起的 MySQLREDIS_URL指向 RedisSECRET_KEY随便生成一串长随机字符。改完执行# 构建并后台启动所有服务 docker-compose up -d --build # 查看容器状态确认 archery 和 celery 都是 Up docker-compose ps--build会重新构建镜像第一次跑要拉基础镜像时间比较长。docker-compose ps里如果archery容器状态是Restarting别急着看页面先docker-compose logs archery看日志八成是数据库连不上或迁移没跑完。Docker 方式下数据库迁移是容器启动时自动执行的如果 MySQL 还没 ready迁移会失败容器就反复重启。常见做法是等 MySQL 容器日志出现ready for connections再起 Archery。3.2 源码安装可控但步骤多源码安装适合需要调审核规则或接内部通知系统的场景。步骤是建虚拟环境、装依赖、改配置、迁移数据库、起服务。# 建 Python 3.6 虚拟环境 python3 -m venv /opt/venv/archery source /opt/venv/archery/bin/activate # 安装依赖国内建议加清华源 pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simplerequirements.txt里mysqlclient编译最耗时前面装好mysql-devel就不会报错。依赖装完后复制archery/settings.py的模板改数据库和 Redis 配置# archery/settings.py 关键片段 DATABASES { default: { ENGINE: django.db.backends.mysql, NAME: archery, USER: root, PASSWORD: archery123, HOST: 127.0.0.1, PORT: 3306, OPTIONS: {charset: utf8mb4}, } } # Redis 作为 Celery broker CELERY_BROKER_URL redis://127.0.0.1:6379/0OPTIONS里的charset必须写utf8mb4和元数据库保持一致。改完执行迁移和静态文件收集python manage.py makemigrations python manage.py migrate python manage.py collectstatic --noinputmigrate会建一堆表如果中途报字段长度或字符集错误回头检查 MySQL 的character_set_server。collectstatic把前端静态资源归到static/目录后面 Nginx 要指向这里。最后起服务开发环境用runserver验证生产用gunicorn加 Nginx这里先验证# 开发模式起后端确认能访问 python manage.py runserver 0.0.0.0:8000浏览器打开http://机器IP:8000能看到登录页就说明主体通了。默认管理员账号在迁移时创建用户名admin密码看settings.py里的初始化配置或首次登录强制修改。3.3 前端资源与 Nginx 反代源码方式下前端是单独构建的collectstatic只处理 Django 的静态文件Vue 前端要npm run build后把dist交给 Nginx。如果只验证后端可以先用runserver顶着要完整跑通工单流Nginx 配置不能少。server { listen 80; server_name archery.local; location / { root /opt/Archery/dist; try_files $uri $uri/ /index.html; } location /api/ { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }try_files那行是给 Vue 的 history 路由用的不加的话刷新页面 404。/api/反代到 Django前后端就接上了。Nginx 改完nginx -t测配置再reload别直接重启生产上重启会断连接。4. 配置审核规则与实例接入让工单流真正跑起来装完能登录只是第一步Archery 的价值在审核规则和实例接入。规则配松了高危语句直接放行配紧了正常建表都被驳回这个度要按团队规范调。实例接入则是把要管理的 MySQL 纳进来后面会话管理、binlog 清理、账号管理才有对象。4.1 SQL 审核规则配置Archery 的审核规则在后台「规则管理」里配底层是 Inception 的检查项。常见做法是先启用基础规范建表必须有主键、表和列必须有注释、禁止SELECT *、禁止DROP TABLE无备份执行。这些规则对应 Inception 的参数在 Archery 里是勾选加阈值。规则项建议值作用建表必须有主键开启避免无主键表导致复制延迟表/列注释开启规范元数据方便后续维护SELECT *开启强制写明字段减少回表DML 影响行数1000超过走工单审批防误更新高危语句自动驳回DROP/TRUNCATE 直接拦阈值不是拍脑袋定的DML 影响行数我一般按业务表规模设流水表可以放宽到 5000配置表设 100。规则改完要找一条测试 SQL 走一遍「SQL 检测」确认 error 和 warning 的提示符合预期别等研发提工单了才发现规则把正常语句也拦了。4.2 实例接入与连接测试实例接入在「实例管理」里新增填主机、端口、账号密码。这里有个坑Archery 连实例用的账号需要足够权限至少要有PROCESS、REPLICATION CLIENT才能看会话和 binlog只给SELECT的话会话管理页面是空的。-- 为 Archery 创建专用监控账号 CREATE USER archery_mon% IDENTIFIED BY Mon123456; GRANT SELECT, PROCESS, REPLICATION CLIENT ON *.* TO archery_mon%; -- 如果要走账号管理功能再加创建用户和授权权限 GRANT CREATE USER ON *.* TO archery_mon% WITH GRANT OPTION; FLUSH PRIVILEGES;PROCESS是看SHOW PROCESSLIST的前提REPLICATION CLIENT才能读 binlog 列表。WITH GRANT OPTION只在需要 Archery 代建账号时加安全要求高的环境可以不给账号管理功能手动关掉。加完实例点「测试连接」通了再保存不通先查网络和账号 host 限制。4.3 工单流程与通知配置工单流按环境分开发环境研发提、项目经理审测试环境测试提、测试审。这个在「工作流」里配审批链每一级指定角色。配完别忘了通知Archery 支持钉钉机器人在「通知配置」里填 webhook 地址工单提交和审核通过都会推消息。# 测试钉钉机器人是否可达替换成自己的 webhook curl -X POST https://oapi.dingtalk.com/robot/send?access_token你的token \ -H Content-Type: application/json \ -d {msgtype:text,text:{content:Archery 通知测试}}返回errcode: 0说明通不通先查 token 和机器人安全设置里的 IP 白名单。通知配好后提一条测试工单走完整流程确认每一级审批人都能收到待办别等上线当天才发现通知没发出去。5. 常见问题排查装完起不来、审核报错、连接失败怎么救这套环境装下来报错集中在几个固定位置。下面五条是我踩过或帮人处理过的按「现象 → 原因 → 解决」写遇到对得上的直接照方抓药。5.1 容器反复重启日志报数据库连接拒绝现象docker-compose ps里 archery 容器状态Restarting日志刷Cant connect to MySQL server。原因MySQL 容器还没初始化完Archery 启动时迁移就连了连不上直接退出。解决先单独起 MySQL等日志出现ready for connections再docker-compose up archery或者给 archery 服务加depends_on加健康检查等 MySQL healthy 再启动。5.2 页面能开但登录报 500日志提示表不存在现象登录页正常输账号密码后 500日志Table archery.django_session doesnt exist。原因数据库迁移没执行或执行到一半失败表没建全。解决进容器或虚拟环境执行python manage.py migrate看具体哪条迁移报错常见是字符集问题导致建表失败修好 MySQL 字符集后删库重建再迁移。5.3 SQL 检测一直报 Inception 连接失败现象提工单点「SQL 检测」提示无法连接审核引擎。原因settings.py里 Inception 配置的主机端口不对或 Inception 服务没起。解决确认/usr/local/inception/bin/inception进程在跑ps -ef | grep inception能看到再核对 Archery 配置里INCEPTION_HOST和INCEPTION_PORT默认 6669防火墙要放行。5.4 会话管理页面空白看不到进程现象实例接入了会话管理点进去没数据。原因监控账号缺PROCESS权限或者实例配置里没勾选「慢查询/会话」相关选项。解决按 4.2 的授权语句补PROCESS权限FLUSH PRIVILEGES后重进页面还不行就看实例编辑页的「查询权限」是否开启。5.5 Binlog2SQL 解析报错提示 binlog 文件不存在现象用 Binlog2SQL 插件解析某个 binlog报文件找不到。原因实例的 binlog 已经被清理或者 Archery 连的账号没有读 binlog 的权限。解决先在实例上SHOW BINARY LOGS确认文件还在不在就只能从备份恢复在的话补REPLICATION CLIENT权限并确认 Archery 配置的 binlog 路径和实例实际路径一致。6. 装完怎么验证跑通一条工单走到底才算数验证 Archery 装没装好别只看登录页能不能开。我的标准是一条带建表和更新的 SQL 工单从提交、检测、审批到执行、回滚全流程走通中间通知能收到回滚 SQL 能下载。这套走完平台才算真正可用。先准备一条测试 SQL故意带一个规范问题比如建表不写主键看检测能不能拦-- 测试用故意缺主键和注释 CREATE TABLE verify_t1 ( id INT, name VARCHAR(32) );提交工单点「SQL 检测」预期返回 error提示缺主键。把 SQL 改成带主键和注释的版本再检测应该通过。然后提交用审批账号登录右上角通知里能看到待办审批通过后选「立即执行」。执行完去实例上SHOW CREATE TABLE verify_t1确认表建出来了。接着验证回滚在工单详情里点「查看回滚 SQL」应该能看到DROP TABLE语句点「下载回滚 SQL」拿到文件。这一步很多人不测等真出事要回滚才发现回滚语句没生成那就被动了。再验证一个运维功能比如会话管理。在实例上开一个长事务-- 在测试实例上执行制造一个长事务 BEGIN; UPDATE verify_t1 SET nameblock WHERE id1; -- 不提交保持会话然后去 Archery 会话管理选对应实例command 选All勾选「完整 INFO」应该能看到这条UPDATE处于Sleep或Query状态。点「终止会话」回实例上确认连接被 kill。这一步通了说明监控账号权限和会话管理链路都没问题。最后核对通知整个流程里钉钉应该收到提交和审批两条消息。没收到就回 4.3 查 webhook。验证项预期结果不通过先查SQL 检测拦截缺主键报 error审核规则是否启用工单审批审批人收到待办工作流角色配置立即执行表成功创建实例执行账号权限回滚 SQL能查看和下载Inception 回滚配置会话管理能看到并终止会话监控账号 PROCESS 权限钉钉通知收到两条消息webhook 和 IP 白名单这套验证我每次装新环境都强制走一遍哪怕只是升级了个小版本。有一次图省事只测了登录结果上线后研发提工单发现回滚 SQL 生成不了回头查是 Inception 配置里少了个参数耽误半天。从那以后我每次装完 Archery都拿这条verify_t1工单从头到尾跑一遍六项全绿才敢交给团队用。希望帮到你。本文还有配套的精品资源点击获取