Archery SQL审核平台部署与运维全流程指南

1. 为什么DBA群体需要一套完整的SQL审核流程

1.1 从一次凌晨变更事故说起

做运维和数据库管理这些年，我最怕的不是服务器半夜宕机，而是业务方过来说一句：“我就改个字段类型，你帮我执行一下。”看似简单的需求，背后往往是几万行核心表，一旦字段类型变更引发隐式转换，索引失效，慢查询瞬间堆满数据库，整个业务链路直接雪崩。更让人后怕的是，很多执行的SQL没有任何评审记录，不知道是谁提的、为什么要改、有没有备份方案，出了事情连回滚都无从下手。

Archery SQL审核平台就是冲着这个痛点来的。它把“SQL从哪里来、谁审核、如何执行、执行后能不能回滚”这条链条完整地治理起来，核心不是替DBA执行一条语句，而是把变更流程规范化、可视化。在我落地过的几个团队里，引入这套平台之前，每周都有两三次因为线上直接执行SQL引发的小故障；引入之后，类似的变更事故基本绝迹了。这篇文章就是我基于实际部署经验整理的一份运维部署手册，从架构认知、环境准备、安装步骤到日常维护都会讲到，适合正在做DB运维规范化、或者准备在公司内部搭建SQL审核流程的DBA和运维工程师参考。

1.2 Archery的定位：审核、上线与查询的闭环

很多人第一次接触Archery，容易把它理解成“一个能在网页上执行SQL的工具”。这个理解就偏差了。Archery本质上是一个基于Django框架开发的工单系统，它把数据库变更按照“提交—审核—执行—追踪”的流程去管理。开发同学提交SQL上线工单，指定负责审核的人，审核通过后DBA点击执行，整个过程在平台里留痕，可追溯。

它和gh-ost、pt-online-schema-change这类在线DDL工具不是替代关系，而是协作关系。Archery负责流程治理和权限控制，真正执行大表结构变更时，底层可以对接到这些变更工具，做到不锁表、可回滚。平台对库表结构、慢日志、查询记录都有统一的管理入口，避免了开发人员拿着生产库账号直接连客户端执行SQL这种高危操作。我现在所在的团队，所有生产环境变更都必须走平台，没有工单编号的SQL语句不允许在正式环境出现。

1.3 核心组件解析：不是一个进程就能跑完的

Archery部署起来看起来简单，但里面其实包含了三个核心进程，我见过不少人在部署时只启动了Django Web服务，结果工单点了上线按钮却没反应，或者定时任务完全不触发，就是这个原因。

理解了这张表，部署思路就清晰了：Web负责“界面”，Worker负责“干活”，Beat负责“定时”，MySQL和Redis负责“存储和通信”。后面所有配置和排障，都是围绕这几个角色的关系展开的。

2. 部署前的软硬件规划：版本、端口与目录布局

2.1 版本选型：别在起点就埋雷

Archery对运行环境有一定要求，我建议在一开始就确定一套经过验证的版本组合，而不是什么都装最新版。操作系统层面，CentOS 7/8、Ubuntu 18.04/20.04这些常见发行版都没问题；Python版本建议选择3.6到3.8之间，我实际用的是3.8，跑得很稳定，太新的Python版本反而可能遇到部分依赖包没来得及适配的情况。

元数据库MySQL建议5.7以上，8.0也可以，但要注意一点：如果使用MySQL 8.0，需要额外确保Python连接库的兼容性，因为8.0默认的caching_sha2_password认证插件会让部分旧版本的pymysql报认证失败。解决的办法是安装新版本的cryptography库，或者在部署时直接用5.7版本省心一些。Redis建议5.0以上，基本没什么特殊限制。

还有一点比较关键：Archery平台自己的元数据库一定不要和业务数据库混用。我见过有人图省事，直接拿一个业务实例的MySQL来装Archery的元数据，结果平台本身的备份策略和业务备份策略互相干扰，出了问题两边都受影响。单独准备一个小规格的MySQL实例给平台用，数据量不大，但隔离性很重要。

2.2 操作系统基础依赖：先补齐编译环境

在用pip安装Archery的Python依赖时，很多包需要通过源码编译，比如MySQL连接驱动、加密相关库。如果操作系统缺少编译工具链，pip会在安装过程中报错，报错信息通常是“Failed building wheel”或者缺少某个头文件。提前把系统依赖装好，能省掉后面一大半麻烦。

CentOS/RHEL系统执行：

yum install -y gcc python3-devel openssl-devel zlib-devel libffi-devel

Ubuntu/Debian系统执行：

apt-get update apt-get install -y build-essential python3-dev libssl-dev zlib1g-dev libffi-dev

这些包分别对应什么作用，我简单解释一下：gcc是编译C扩展的编译器，python3-devel提供Python头文件，openssl-devel是为了让pip能正常编译带SSL支持的扩展，libffi-devel则和cffi库相关，Python连接MySQL驱动时经常用到。没有它们，pip安装阶段就会卡住，而且报错信息对新手很不友好，容易让人误判成网络问题。

另外建议把pip源替换成国内镜像源，比如清华源或阿里源。Archery的依赖项里包含不少体积较大的包，直接用官方PyPI源在部分网络环境下会非常慢，甚至超时。在虚拟环境里执行：

pip install pip -U pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

之后再安装依赖，速度差别是体感级别的。

2.3 目录、端口与日志规划

部署目录我习惯统一放在/opt/archery下，代码放/opt/archery/Archery，虚拟环境放/opt/archery/venv，日志统一放/opt/archery/logs。这样备份、迁移、权限控制都很清晰。

端口规划上，Archery Web服务默认监听8000端口，Celery的Worker和Beat不需要对外暴露端口，Redis监听6379，MySQL监听3306。如果全部部署在同一台机器上，要提前确认这些端口没有被占用，尤其是Redis和MySQL，很多机器会预装或者历史遗留进程占用端口，启动后看起来正常但连不上，排查起来很费劲。

日志规划容易被忽略。Archery运行时的日志主要有两类：一类是Django的请求日志和Celery的任务日志，可以通过nohup重定向输出到文件；另一类是平台内部的错误日志，默认会写入代码目录下的logs目录。我在部署时会统一做一个logrotate切割配置，避免日志文件无限增长把磁盘撑爆。这个细节后面在运维章节里会详细展开。

3. 从源码到可用：核心服务安装步骤

3.1 拉取代码与创建Python虚拟环境

先把代码克隆到本地。Archery项目的源码托管在GitHub上，仓库地址是github.com/hhyo/Archery，直接clone最新稳定版本即可。

mkdir -p /opt/archery cd /opt/archery git clone https://github.com/hhyo/Archery.git cd Archery

这里有一个很重要的建议：始终使用虚拟环境，不要让依赖包装到系统Python里。用虚拟环境的好处是，如果后面升级或者重装，只需删掉venv目录重新创建，不会污染系统环境，也不会和系统自带的Python包冲突。

cd /opt/archery python3 -m venv venv source venv/bin/activate cd Archery pip install -r requirements.txt

requirements.txt文件在Archery源码的根目录下，里面包含了Django、Celery、MySQL驱动、Redis客户端等所有运行依赖。安装完成后，可以用pip list快速检查关键包是否就位。这一步如果前面的系统依赖装好了，基本是几分钟的事，不会卡住。

3.2 修改核心配置：数据库连接与Redis

Archery的配置文件是archery/settings.py，在开始初始化之前，必须把数据库和Redis的连接信息改成自己的环境。这里需要注意，Archery本身依赖的配置项很多，但核心就那几项，不需要所有配置都看懂才能部署。

# archery/settings.py 关键配置片段，路径以实际代码为准 ALLOWED_HOSTS = ['*'] DATABASES = { 'default': { 'ENGINE': 'django.db.backends.mysql', 'NAME': 'archery', 'USER': 'archery_user', 'PASSWORD': '在这里填强密码', 'HOST': '127.0.0.1', 'PORT': '3306', 'OPTIONS': { 'charset': 'utf8mb4', }, } } REDIS = { 'host': '127.0.0.1', 'port': '6379', 'password': '', 'db': 0, } CELERY_BROKER_URL = 'redis://127.0.0.1:6379/0' CELERY_RESULT_BACKEND = 'redis://127.0.0.1:6379/0'

ALLOWED_HOSTS默认是空列表，如果不改成包含实际访问域名或直接使用通配符，Django会拒绝非本机host的请求，页面直接返回400。初期内网部署可以直接写['*']，但如果暴露到公网环境，务必改成具体的域名。

Redis如果设置了密码，上面的URL也要带上密码，格式是redis://:密码@127.0.0.1:6379/0。我遇到过新手部署时，Redis明明有密码，但配置文件里没写，结果页面能打开，工单一提交就卡住不动，日志里全是连接Redis认证失败的报错。

3.3 初始化平台数据库

配置改好之后，需要创建元数据库并执行数据迁移。首先在MySQL里建库和建账号，UTF8MB4字符集是必须的，不然存中文的工单描述、SQL文本会出现乱码，后续排查问题会非常痛苦。

mysql -uroot -p CREATE DATABASE archery DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_bin; CREATE USER 'archery_user'@'%' IDENTIFIED BY '强密码'; GRANT ALL PRIVILEGES ON archery.* TO 'archery_user'@'%'; FLUSH PRIVILEGES;

然后执行迁移：

cd /opt/archery/Archery source /opt/archery/venv/bin/activate python manage.py makemigrations python manage.py migrate

migrate执行成功之后，平台的表结构就建好了。Archery在初始化时会自动创建管理员账号，默认的管理员账号通常是admin，初始密码取决于具体版本，官方README里会注明。我第一次部署时是按默认密码登录的，但强烈建议登录成功后立即修改管理员密码，并且不要把这个账号共享给多人。

3.4 启动Web、Worker与Beat三个进程

初始化完成，就可以试启动。一定要先在前台启动验证一次，不要直接一把nohup丢后台，否则日志会掩盖启动错误。

python manage.py runserver 0.0.0.0:8000

浏览器访问 http://服务器IP:8000，能出现登录页面说明Web服务正常。确认没问题后，按Ctrl+C停止，再把三个进程全部用后台方式拉起：

cd /opt/archery/Archery source /opt/archery/venv/bin/activate nohup python manage.py runserver 0.0.0.0:8000 >> /opt/archery/logs/archery_web.log 2>&1 & nohup celery -A sql_web worker -l info >> /opt/archery/logs/celery_worker.log 2>&1 & nohup celery -A sql_web beat -l info >> /opt/archery/logs/celery_beat.log 2>&1 &

注意，Celery的-A参数指定的是sql_web，这是Archery项目里定义的Celery应用模块名，不是所有项目都叫这个名字，排障时看到日志里的sql_web不要觉得奇怪。启动后建议用tail -f检查日志，看到类似“ready”的关键字基本就是起来了。三个进程缺一不可，尤其是Worker，如果没启动，工单点了执行永远不会有反应。

4. 接入Nginx并让平台真正可用

4.1 用gunicorn替代runserver，更符合生产要求

Django自带的runserver开发服务器，性能一般，而且官方明确说不建议用于生产环境。部署Archery到正式使用阶段，我会把Web服务切换到gunicorn，配合多worker运行，并发能力会好很多。

pip install gunicorn

启动方式：

cd /opt/archery/Archery source /opt/archery/venv/bin/activate nohup gunicorn -w 4 -b 127.0.0.1:8000 sql_web.wsgi:application >> /opt/archery/logs/gunicorn.log 2>&1 &

注意这里gunicorn绑定的地址是127.0.0.1，不是0.0.0.0。原因很简单，生产环境我们会在前面架一层Nginx，让Nginx监听对外端口（比如80或443）然后把请求转发到后端的gunicorn，这样Archery本身不直接对外暴露，减少攻击面。如果直接在8000端口对外提供服务，安全性和灵活度都会差很多。

4.2 Nginx反向代理配置要点

Nginx配置本身不复杂，但有两个容易踩坑的点：一个是请求体大小限制，一个是长连接超时时间。

SQL审核工单在提交时，SQL文本可能很大，尤其是一次提交几十条批量上线语句。Nginx默认的client_max_body_size只有1m，提交稍微大一点的工单就会报413错误。还有查询工单执行时间可能比较长，Nginx默认的proxy_read_timeout是60秒，超时就会返回504，而SQL查询或者大表结构变更执行几分钟都很正常，必须把超时时间调长。

server { listen 80; server_name your_domain_or_ip; client_max_body_size 50m; location / { proxy_pass http://127.0.0.1:8000; 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_read_timeout 300s; proxy_connect_timeout 300s; } access_log /opt/archery/logs/nginx_access.log; error_log /opt/archery/logs/nginx_error.log; }

50m的client_max_body_size对于绝大多数SQL工单场景足够用了，如果你们团队日常提交的SQL脚本特别大，可以再往上调，但最好同时在平台层面限制单次提交的SQL条数，防止有人把整个数据库的初始化脚本一次性贴进来。

配置完后，nginx -t检查语法，reload生效。到这一步，浏览器的访问路径就从8000端口平滑变成了80端口，用户体验好很多。

4.3 首次登录后的基础设置

能打开登录页面，说明部署成功了一大半。用默认管理员账号登录进去之后，除了改密码，我还建议按以下顺序把平台基础设置做一遍：

• 修改平台名称和logo，避免默认的Archery品牌直接暴露给公司内部用户，也显得更正式。
• 配置管理员邮箱地址，后续平台发送邮件通知时会用到。
• 检查时区设置，确保工单显示的提交时间和执行时间和服务器本地时间一致，避免因为时区偏差导致定时执行工单提前或延后触发。
• 开启用户注册审核。默认情况下，平台允许注册用户，但如果开了注册，我建议在系统设置里开启注册审核，管理员审批后才能登录，防止外部人员随意注册获取系统权限。

这些设置都集中在平台的后台管理页面里，边走边看就能找到。核心逻辑是：平台上线前把基础信息维护好，再开始拉真实用户进来，不要一登录就急着接实例。

5. 把平台用起来：实例、资源组、审核规则与通知配置

5.1 接入数据库实例：最小权限账号原则

Archery部署好之后，下一步是把需要管理的数据库实例接入平台。在“实例管理”里点新增实例，需要填写的信息包括实例类型、实例环境（测试/生产）、主机地址、端口、数据库账号密码等。

这里我要强调一个建议：为Archery创建专用的数据库账号，不要直接用root或者业务账号。因为这个账号会被平台用来获取库表结构、采集慢日志、执行上线SQL，如果权限给太大，一旦平台账号泄露或者被误用，影响范围会非常大。最小权限的MySQL账号示例：

CREATE USER 'archery_conn'@'%' IDENTIFIED BY '强密码'; GRANT SELECT, INSERT, UPDATE, DELETE ON *.* TO 'archery_conn'@'%'; GRANT SHOW DATABASES, PROCESS, SUPER ON *.* TO 'archery_conn'@'%';

具体权限组合要根据你们要使用的功能来确定，比如要在大表执行DDL时使用pt-osc，就需要额外的权限；要做数据订正，就需要INSERT/UPDATE/DELETE权限。核心原则就一条：每个功能对应最小权限，宁可后续缺权限再加，也不要一开始就放开所有权限。

5.2 资源组：Archery权限模型的核心

Archery里的权限控制核心是“资源组”，不是简单的“管理员/普通用户”两级权限。一个典型的配置是：创建“业务系统A”这个资源组，把业务系统A的数据库实例、负责该系统的研发账号、审核角色全部放进去，然后这个资源组里的用户在工单流转时，只能看到该系统相关的实例和工单，做到了逻辑隔离。

我强烈建议在正式推广前，先按照公司的业务线把资源组架构规划好。这个规划做得好，后续权限维护会非常省事；如果等用户量大了再调整资源组，每个工单的归属都要重新梳理，很麻烦。一个业务线一个资源组，里面放对应的实例和人员，这是目前我见过最清晰的模式。

5.3 审核规则：从“错误”级别开始，逐步放宽

Archery内置了几百条SQL审核规则，包括常见的“禁用SELECT *”“UPDATE/DELETE语句必须带WHERE条件”“禁止使用子查询”“限制影响行数”“建议使用索引”等等。每条规则可以设置级别，通常是“警告”和“错误”两档。

我的建议是：刚开始部署时，先把规则调到偏严，尤其是“错误”级别，让所有不符合规范的SQL直接被拦截。团队会有一些不适，但磨合一两周，开发同学就会习惯规范写法。之后再根据实际反馈，把个别太严的规则（比如某些公司确实需要SELECT *的场景）降为“警告”，而不是彻底关掉。

有一个经验值得分享：审核规则要跟着业务的SQL风格迭代，不是一成不变的。初期按默认规则跑，看平台积累的审核驳回记录，每季度审视一次规则清单，把高频误伤的规则调准，这样平台才不会变成“开发同学绕道走的摆设”。

5.4 消息通知：让工单流转不依赖盯页面

Archery支持对接钉钉、企业微信、飞书等IM的机器人Webhook。配置好之后，工单提交、审核通过、执行完成、执行失败等关键节点，都会自动推送通知到对应的群或负责人。这一步非常提升使用体验。不然每个工单审核都要人等页面刷新，推广阻力会很大。

在系统配置里填入Webhook地址，再勾选需要通知的事件类型即可。要注意的是，Webhook如果填错地址，平台本身不会报错，只会默默推送失败，所以在配置完以后，最好真实走一遍提交工单的流程，验证通知能不能正常收到，别等上线了才发现消息一直没发出去。

6. 日常运维：日志、备份、升级与常见故障排查

6.1 进程管理：用systemd取代裸nohup

部署初期用nohup拉起服务没毛病，但长期运维建议改用systemd管理，这样服务崩了能自动重启，开机也能自动拉起。我通常会为三个进程各写一个Unit文件，下面以Worker为例：

[Unit] Description=Archery Celery Worker After=network.target redis.service mysql.service [Service] User=archery Group=archery WorkingDirectory=/opt/archery/Archery ExecStart=/opt/archery/venv/bin/celery -A sql_web worker -l info Restart=always RestartSec=5 [Install] WantedBy=multi-user.target

Web服务和Beat进程同理。切换到systemd之后，systemctl status随时能查状态，日志统一交给journald管理，比翻nohup日志文件方便得多。这里顺带提醒一下：如果代码目录、虚拟环境、日志目录的属主不是运行用户，启动会报权限错误，创建目录时就要用chown把权限理顺。

6.2 数据备份与恢复：备份元数据库就够了

Archery平台自身的业务数据都存在MySQL元数据库里，包括用户信息、资源组配置、工单记录、审核日志。备份策略很简单，就是定时mysqldump这个库：

mysqldump -uarchery_user -p archery --single-transaction --quick > /backup/archery_$(date +%Y%m%d).sql

配合crontab每天凌晨执行一次，保留最近30天的备份文件。恢复时更简单：

mysql -uarchery_user -p archery < /backup/archery_20250101.sql

除了数据库，系统的settings.py配置文件、nginx配置、systemd配置这些文件虽然小，但丢了会非常麻烦，建议一起纳入备份范围。恢复时如果不小心弄丢了，光靠重新配置可能要花一小时，而备份只需要一秒钟。

6.3 升级注意事项：先备份、看变更、再操作

Archery的版本迭代还是挺积极的，新版本会修复漏洞、增加审核规则、优化界面。升级前有三件事必须做：

• 完整备份元数据库，这是所有操作的前提；
• 阅读官方Changelog，确认目标版本的配置变更、依赖变更，有些大版本升级需要额外执行数据脚本；
• 在测试环境先升一遍，确认功能正常后再动生产。

升级时通常只需要拉取新代码、安装新的依赖包、执行数据库迁移，然后重启三个服务。这里最忌讳的是跨多个大版本一次性升级，中间的数据结构和逻辑变化可能直接让migrate报错。我习惯的做法是小版本跟随，大版本跳跃时先找官方文档确认升级路径，必要时中间版本过渡一轮。

6.4 常见故障排查：一张表解决80%的问题

运维Archery半年到一年，常见的坑基本就那几个。我把它们整理成一张表，遇到问题先对号入座：

这套排查思路的核心是：先从进程是否存活入手，再看日志，最后看配置。我遇到过很多人卡在“页面能打开”这一步，就以为部署成功了，实际上Worker和Beat都没起来，导致平台只能看不能用。验证平台真正可用的标准是：完整走一遍“提交工单—审核—执行—收到通知”的流程。

6.5 我的几点落地经验

最后分享几个我在实际运维过程中沉淀下来的习惯，不一定所有人都认同，但对团队落地很有帮助。

第一，先试点再推广。不要第一天就把所有生产库实例接进来，而是选一个非核心业务系统作为试点，跑通全流程，把审核规则调好，团队熟悉了操作方式，再逐步扩大覆盖范围。上来就全面覆盖，最容易引发业务团队反弹。

第二，管理员账号只用来做系统管理，日常工单审核和执行，要给DBA分配独立账号。这样每个操作都能定位到具体责任人，也方便审计。

第三，定期查看平台的慢日志和审核驳回记录。Archery的价值不只是上线前把关，更重要的是积累SQL质量数据。每月看一次驳回记录，能清晰看到各团队SQL质量的变化趋势，这些数据用来推动研发规范落地，比口头强调有力得多。

第四，不要迷信平台的自动化执行，高危操作（如DROP TABLE、批量UPDATE影响行数过大）建议开启人工复核，或者直接由平台管理员二次确认后再执行。审核平台是辅助手段，最终对生产环境负责的还是人。

第五，配置文件和备份脚本要纳入版本管理或者至少放在独立目录。服务器本身有可能出问题，但只要备份齐全、配置有记录，重新部署一台机器做到半小时内恢复是完全可行的。

Archery本身不复杂，按这套流程走一遍，基本上一个下午就能跑起来。真正需要投入精力的，是把审核规则、资源组、权限模型这些东西结合自己团队的业务形态打磨好。工具只是骨架，流程和规范才是让平台真正发挥价值的关键。