Archery部署实战：基于Docker Compose搭建SQL审核平台并接入三种数据库-平芜编程栈

做数据库运维的同学应该都有这种体会：公司里一旦过了几十个开发、几百张表，数据库变更就开始失控了。开发提了一条SQL过来，到底是好是坏、有没有索引失效、会不会锁表，全靠DBA肉眼去“人肉审计”。更麻烦的是，执行完没留痕、想回溯找不到记录、账号权限也分不清楚谁动了哪张表。Archery就是来解决这个问题的，它是一个开源的SQL审核查询平台，把“提交SQL、规则校验、DBA审核、在线执行、结果回滚、日志审计”整条链路全部Web化，支持MySQL、PostgreSQL、ClickHouse等多种数据库，而且全部操作留痕。这篇教程我想把从零开始，用Docker Compose把它完整部署起来、再把三种数据库实例接入的过程，一步步讲清楚。整个实操下来，你会发现这东西部署起来并没有想象中复杂，反而是实例接入和权限配置更值得花心思。

1. Archery核心价值与方案选型思路

1.1 Archery到底解决了什么问题

先说一个真实场景。早些年我在一家电商公司做DBA，每周最头疼的事情就是收开发发来的SQL变更申请，通常是Excel或者聊天消息，写得乱七八糟。“给xx表加个索引”“某条UPDATE忘写WHERE了，能帮我回滚吗”这种消息天天有。人工审核有两个致命问题：

第一，不可追溯。SQL到底是谁提交的、什么时候执行的、执行前有没有人审过，全靠邮件和聊天记录，出事只能靠猜。

第二，规则不一致。同一个DBA今天心情好，放过了一条没走索引的SQL，明天另一个DBA审核时直接打回。开发完全不知道标准是什么，流程形同虚设。

Archery的定位就是把这件事标准化。它不是一个GUI工具，而是一个“平台”，核心功能包括：

SQL审核：内置规则引擎，对提交的SQL做语法解析、索引分析、规范校验，比如检测到全表DELETE、无WHERE条件的UPDATE、大表DDL等高风险操作会直接拦截或告警。
工单流转：开发提交SQL后生成工单，DBA在Web界面审核，通过后可以手动执行、定时执行，执行过程自动记录。
查询能力：开发可以在线查询，但管理员可以控制查询权限、限制返回行数、敏感字段脱敏。
审计日志：谁在什么时间执行了什么SQL，一律留痕。
多数据库支持：当前主流的MySQL、PostgreSQL、ClickHouse都能接入，这也是这篇教程选这三种数据库的原因。

拿它和其他开源方案横向比一比：

平台	SQL审核	工单流程	多数据库支持	查询/脱敏	社区活跃度
Archery	强	完整	MySQL/PostgreSQL/ClickHouse等	支持	高
Yearning	中	完整	主要MySQL	部分	中
CloudBeaver	弱	无	多种	支持但不克制	中
Kebinet	中	部分	主要MySQL	不支持	低

Archery的优势在于“审核+流程+查询+审计”是一条完整的闭环，而不是只做了其中某一个点。这也是我当年最终选它的核心理由。

1.2 为什么选择Docker Compose部署

Archery自身是基于Django开发的Web应用，依赖的东西不算少：Python运行时、系统库、MySQL（它自己的元数据库）、Redis（缓存和异步队列）、Django Q（异步任务调度），再加上各类数据库驱动和工具包。如果用裸机部署，光是把这些依赖在干净环境里装一遍，就能消耗掉大半天时间。更崩溃的是，不同版本的Python和MySQL之间还有兼容性问题，换个机器就是一场新的灾难。

用Docker Compose部署的好处非常直接：

环境隔离：所有依赖都封装在镜像里，宿主机上装了什么乱七八糟的Python、库都不影响。
一条命令拉起：docker compose up -d搞定，不再需要手写初始化脚本。
升级回滚方便：镜像版本切来切去，配合数据卷挂载，数据还在。
三个角色一个镜像：Archery容器可以按启动参数分成web、task、scheduler不同角色，实际部署时可以用一个镜像跑多个容器。

当前这套部署方案的整体架构大致是这样的：

web容器：Django应用本体，提供Web界面和API，端口默认8080。
task容器：异步任务执行器，处理SQL执行、工单状态变更等后台任务。
scheduler容器：定时任务调度，负责周期性的清理、巡检、统计等任务。
MySQL容器：Archery的系统元数据库，存放用户、实例、工单、规则等数据。
Redis容器：缓存与异步队列。

搞清楚这个架构，后面看docker-compose配置文件就不会一头雾水了。

2. 环境准备与前置条件

2.1 Docker与Docker Compose的安装检查

工欲善其事，必先利其器。不管你是Linux服务器还是Windows/macOS笔记本，先把Docker环境跑起来。

Linux（CentOS/Ubuntu/Debian）

我建议直接用官方脚本安装，简洁省事：

curl -fsSL https://get.docker.com | bash systemctl enable --now docker docker --version

装完Docker之后，确认一下Compose插件：

docker compose version

现在新版Docker都自带Compose V2插件，不需要单独装docker-compose这个独立二进制了。如果执行报错，说明版本太老，建议把Docker升级到20.10以上。

Windows / macOS

Windows上首推Docker Desktop。但很多人在安装后启动时遇到过一个问题：提示virtualization support not detected或者虚拟化支持没有检测到，容器根本跑不起来。这个问题一般不是Docker的锅，而是宿主机的虚拟化开关没开，排查路径按这个顺序来：

打开任务管理器 -> 性能 -> CPU，确认“虚拟化”这一项是不是“已启用”。
如果显示“已禁用”，需要进BIOS开启Intel VT-x或AMD-V。这一步网上各种教程写得很多，我不展开。
确认Windows功能里“适用于Linux的Windows子系统”和“虚拟机平台”两个选项都勾上了，然后重启。
如果依然报错，打开PowerShell（管理员），执行wsl --version确认WSL2内核是否完整。

Windows下如果Docker Desktop实在启动不了，还有一个保底方案：用WSL2里装Docker Engine。但那是另一个话题，本节的目标是先确认Docker和Docker Compose两条命令能正常输出版本号。

验证环境是否就绪：

docker info docker compose version

两个命令不报错，就可以继续了。

2.2 资源规划与端口规划

Docker部署虽然省事，但资源需求不能忽视。Archery本身是Java都不用的轻量级应用，但它要同时跑MySQL和Redis，还要执行一些SQL审核任务，所以资源底线不能太低。

我的建议是：

节点角色	最低配置	推荐配置
单机部署（本教程）	4核8GB内存	8核16GB内存
磁盘	50GB	100GB以上

为什么内存要求不低？因为MySQL系统库本身就要吃内存，加上Django进程、Redis缓存，以及执行审核任务时的临时开销，8GB以下会明显感觉卡顿，工单提交多了还可能OOM。

端口规划也比较重要。Archery的Web端口默认是8080，系统库MySQL默认3306，Redis默认6379。这几条端口在部署前就要想清楚：

服务	默认端口	用途	注意点
Archery Web	8080	浏览器访问平台	宿主机端口可映射为自定义端口
系统MySQL	3306	存储Archery元数据	如果宿主机已有MySQL，建议改映射端口
Redis	6379	缓存与异步队列	内网使用，不建议暴露公网

本机如果已经有服务占用这些端口，docker compose启动时会报port is already allocated。我的习惯是，如果宿主机3306已经被MySQL占用，就把容器里的MySQL映射到13306:3306，完全不影响Archery内部通信，因为容器之间走的是Docker网络，不依赖宿主机端口映射。

部署前最好先规划一个干净的工作目录，把配置、数据、日志都放在一个地方，后面对比排查会省很多事。

mkdir -p ~/archery cd ~/archery

在这个目录下，我们会创建docker-compose.yml，同时会有两个数据卷目录：mysql-data和redis-data，分别挂载系统库的MySQL数据和Redis持久化数据。这样即使容器删了重建，数据也不会丢。

我的工作目录结构大概是这样的：

~/archery ├── docker-compose.yml ├── mysql-data/ └── redis-data/

Docker的细节很多人容易忽略：一定要把数据卷挂载出来。不挂载的话，容器删了数据就没了，Archery里面的用户、工单、实例配置全部归零，那种感觉比环境没装好还要崩溃。

3. 从零部署：编写并启动docker-compose

3.1 获取Archery部署文件与镜像版本选择

部署Archery之前，先到它的GitHub Releases页面拿到最新的release包。二进制包里除了Docker配置文件，还包括初始化SQL脚本、Dockerfile、示例配置等。我习惯把整个release包解压到刚才的~/archery目录里，官方推荐的做法是保留它自带的docker-compose.yml再按需修改。

镜像的话，官方Docker Hub有构建好的镜像，仓库名一般是hhyo/archery。我建议直接使用官方镜像，不要自己从头构建。自己构建要拉Python、编译依赖、装MySQL客户端、装ClickHouse驱动，一套下来耗时很久，而且配置容易出错。直接用官方镜像，省去这些繁琐步骤。

拉镜像的命令：

docker pull hhyo/archery:latest

如果网络拉取比较慢，可以考虑配置国内镜像加速器，这个按自己的网络环境处理即可。

3.2 编写docker-compose.yml：核心配置逐行解读

这里我给出一个经过我实际验证可用的docker-compose.yml，这个文件同时也适合多数中小型团队直接抄作业：

version: "3.8" services: archery: image: hhyo/archery:latest container_name: archery-web restart: unless-stopped ports: - "8080:8080" environment: MYSQL_HOST: mysql MYSQL_PORT: 3306 MYSQL_USER: archery MYSQL_PASSWORD: ArcheryPass2024 MYSQL_DATABASE: archery REDIS_HOST: redis REDIS_PORT: 6379 TZ: Asia/Shanghai volumes: - ./data:/app/data depends_on: - mysql - redis mysql: image: mysql:8.0 container_name: archery-mysql restart: unless-stopped ports: - "13306:3306" environment: MYSQL_ROOT_PASSWORD: RootPass2024 MYSQL_DATABASE: archery MYSQL_USER: archery MYSQL_PASSWORD: ArcheryPass2024 TZ: Asia/Shanghai command: - --character-set-server=utf8mb4 - --collation-server=utf8mb4_unicode_ci volumes: - ./mysql-data:/var/lib/mysql redis: image: redis:7 container_name: archery-redis restart: unless-stopped ports: - "16379:6379" volumes: - ./redis-data:/data

各个配置的作用我逐条解释一下：

archery 服务：核心应用容器。端口8080映射到宿主机，浏览器访问http://localhost:8080就是Archery的登录页。
MYSQL_环境变量*：告诉Archery去连哪台MySQL。这里的mysql是compose网络内的服务名，Docker内部的DNS会自动解析到这个MySQL容器，不需要写IP。
REDIS_环境变量*：同理，指定Redis服务地址。
depends_on：保证MySQL和Redis先于Archery启动。但这里有个坑，MySQL容器起来不等于数据库初始化完成，所以后面首次启动后需要等几秒钟再初始化Archery。
mysql 服务：Archery的系统库。ports映射我用的是13306:3306，避免和宿主机已有的MySQL冲突。同时指定了utf8mb4字符集，避免中文乱码。
redis 服务：缓存和消息队列。

3.3 首次启动与初始化：从拉取镜像到创建管理员

配置完成后，第一次启动不要急着直接初始化，按这个顺序操作：

第一步，启动容器：

cd ~/archery docker compose up -d

这个命令会依次拉取镜像并启动三个容器。第一次拉取可能需要一段时间，取决于网络。启动后用docker compose ps查看状态：

docker compose ps

看到三个容器状态都是Up，说明容器层面没问题了。

第二步，等MySQL初始化完成：

MySQL容器首次启动时，需要初始化数据目录和系统表，这个过程通常需要10到30秒。直接执行下面的命令，确认MySQL能正常连上：

docker exec -it archery-mysql mysql -uarchery -pArcheryPass2024 -e "select 1;"

如果能返回1，说明数据库已经可用。如果报连接失败，等一下再试。

第三步，初始化Archery系统表并加载数据：

Archery的release包中自带初始化脚本，通常位于sql/目录下。把release包里的init.sql文件复制到容器中执行，或者直接用docker exec进入容器执行迁移：

docker exec -it archery-web python3 manage.py migrate

这一步会创建Archery运行所需的全部数据表。如果执行时报错说连不上MySQL，大概率是MySQL还没准备好，重新执行一次即可。

随后加载初始化数据：

docker exec -it archery-web python3 manage.py dbshell < sql/init.sql

初始化数据会写入内置规则、默认资源组、管理员账号等基础数据。

第四步，创建超级管理员：

docker exec -it archery-web python3 manage.py createsuperuser

按提示输入用户名、邮箱、密码，建议用户名直接用admin，密码设置复杂一点。这一步创建的账号是超级管理员，可以登录平台做所有配置。

第五步，访问平台：

浏览器打开http://localhost:8080，用刚创建的超级管理员账号登录。看到登录页，说明整套系统已经跑起来了。

到这里，Archery的部署已经完成。很多教程会在这里收尾，但实战中真正花时间的往往是后面的实例接入和权限配置，这也是接下来我要重点展开的部分。

4. 系统配置与三种数据库实例接入

4.1 登录后台后的基础配置

用超级管理员登录Archery之后，第一件事不是急着加数据库实例，而是把系统的整体配置过一遍。

进入“系统管理”->“系统配置”，建议优先调整以下几项：

平台名称：改成自己公司的名称，开发人员登录后知道进的是哪个平台。
工单超时时间：设置一个合理的审核超时限制，避免工单被DBA遗忘。
邮箱SMTP配置：如果希望工单提交、审核时有邮件通知，这里必须配置。没有邮件服务可以先跳过，不影响核心流程。
LDAP/LDAP对接：公司有统一认证的话可以对接，小团队可以暂时忽略。

基础配置完成后，接下来就是重头戏：把三种数据库实例接入进来。

Archery的实例管理入口在“实例管理”->“新增实例”。接入的过程虽然界面相似，但每种数据库在权限和连接参数上有些细微差异，逐个来说。

4.2 接入MySQL实例：最顺手也最需要细心

MySQL是Archery支持得最完善的数据库类型，也是绝大多数团队的第一选择。新增实例时，关键参数这样填：

数据库类型：选MySQL
实例名称：建议用“环境+业务+角色”的命名方式，比如生产-订单库-主库
主机地址与端口：填MySQL实例所在的IP和端口。这里必须是Archery容器能访问到的地址，不能填localhost，否则Archery连的是它自己的容器网络，连不到你的MySQL。这是新手最容易踩的坑。
数据库账号与密码：Archery连接MySQL执行审核和执行操作，需要一个专用的账号，不要直接用root。建议按下面的SQL创建一个账号：

CREATE USER 'archery'@'%' IDENTIFIED BY 'YourPass2024'; GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, INDEX, CREATE VIEW, SHOW VIEW, PROCESS, SUPER ON *.* TO 'archery'@'%'; FLUSH PRIVILEGES;

这里为什么需要PROCESS和SUPER权限？因为Archery做SQL审核时需要获取当前数据库的线程列表和会话信息，以便判断当前是否存在长事务、锁等待等高危场景。没有这两个权限，功能会部分失效。

测试连接：填完参数后，点击“测试连接”，Archery会尝试连接目标库并校验账号权限。如果提示连接失败，优先检查网络连通性和账号权限。

MySQL接入完成后，建议提交一条最简单的SELECT查询工单验证一遍完整流程：开发提交查询申请，DBA审核通过，执行并返回结果。流程走通，说明这个实例真正可用了。

4.3 接入PostgreSQL实例：注意schema与权限

PostgreSQL在复杂查询、地理信息等场景下非常受欢迎，Archery对它的支持也比较成熟。新增实例时，类型选PostgreSQL，主机端口默认填5432。

接入PostgreSQL时有三个细节需要特别留意：

第一，账号权限模型和MySQL完全不同。PostgreSQL使用“角色”体系，建议为Archery单独创建专用角色：

CREATE USER archery WITH PASSWORD 'YourPass2024'; GRANT CONNECT ON DATABASE yourdb TO archery; GRANT USAGE ON SCHEMA public TO archery; GRANT SELECT ON ALL TABLES IN SCHEMA public TO archery; GRANT SELECT ON ALL SEQUENCES IN SCHEMA public TO archery;

如果还要执行DDL，需要额外授予相应的权限。很多人在这里图省事直接给了超级用户权限，我不推荐，一是审计留痕会混淆操作者，二是一旦账号被滥用，影响范围太大。

第二，schema的选择。PostgreSQL默认是public，但很多业务会自建schema。在Archery实例配置中指定正确的schema，否则会出现“表不存在”的问题。

第三，驱动兼容性。Archery通过psycopg2连接PostgreSQL，如果实例是PostgreSQL 12以上版本，驱动一般没问题。如果是老版本，建议升级Archery镜像到最新版本，避免驱动兼容性报错。

4.4 接入ClickHouse实例：分析场景的另类玩法

ClickHouse接入Archery的场景通常是大数据部门做OLAP分析，开发需要跑一些查询，但这些查询可能很重，会对ClickHouse集群造成压力。这时候用Archery做审核和限流就非常有价值。

新增ClickHouse实例时，关键配置和MySQL/PostgreSQL略有不同：

数据库类型：选ClickHouse
端口：ClickHouse有HTTP端口（默认8123）和Native端口（默认9000），Archery通常走HTTP端口。填8123即可，不需要填9000。
账号权限：ClickHouse的权限控制比较特殊，可以为Archery单独建一个账号，只授予只读权限，并根据需要限制查询的内存和超时。

CREATE USER archery IDENTIFIED WITH plaintext_password = 'YourPass2024'; GRANT SELECT ON *.* TO archery;

如果ClickHouse开启了readonly=1，Archery执行查询不会有问题，但执行DDL或INSERT类工单会被拒。这是正常的，ClickHouse的生产环境通常也是这种安全模式。

ClickHouse接入有一个特别值得注意的点：Archery的审核规则是基于MySQL语法规则设计的，ClickHouse的SQL语法和一些函数跟MySQL有差异。所以ClickHouse实例的“审核”能力会比MySQL弱一些，更多是流程管理和查询权限控制。这一点在团队内推广的时候要提前说明，避免开发误以为CRC（代码审查）层面的规则也能完全覆盖ClickHouse。

4.5 资源组与用户权限：让合适的人做合适的事

实例接入完成后，还差最后一步：把实例和用户绑定到资源组。Archery的权限模型是“用户 -> 资源组 -> 实例”，只有把用户加入某个资源组，用户才能在该资源组下的实例上提交工单或发起查询。

进入“资源组”页面，新增一个资源组，比如“订单业务组”，然后把刚才接入的三个实例都加入这个资源组，再把开发人员和DBA账号加入进来。注意用户权限分两种：

DBA角色：可以审核和执行工单，权限较大，严格控制人数。
开发角色：只能提交工单和发起查询，不能审核自己的工单。

我见过很多团队部署完Archery，所有账号都给超级管理员权限，结果审计日志完全失去意义。规范的做法是：超级管理员只留1到2个人，其余人都按角色分配，DBA负责审核，开发负责提交。

5. 常见问题与排查技巧实录

5.1 高频问题速查表

把这几年用Archery过程中遇到的典型问题整理成一张速查表，部署时遇到问题可以直接对照：

问题现象	可能原因	解决方法
Docker Desktop启动失败，提示virtualization support not detected	宿主机虚拟化没开启，或WSL2未正确安装	进BIOS开启VT-x/AMD-V，开启“虚拟机平台”和WSL2功能
`docker compose up`报端口已占用	宿主机端口被已有服务占用	修改docker-compose.yml中的端口映射
Archery容器启动后立刻退出	环境变量配置错误，或MySQL还没就绪	`docker logs archery-web`查看日志，确认MYSQL_HOST、MYSQL_PASSWORD正确
`python3 manage.py migrate`报连接MySQL失败	MySQL尚未完成初始化，或者MYSQL_HOST配置错误	等待MySQL就绪后重试，确认容器间使用服务名通信
新增实例测试连接失败	网络不通、账号权限不足、端口填错	从Archery容器内ping目标实例，检查账号权限和端口
连接MySQL 8.0时报认证协议错误	目标库的认证插件是caching_sha2_password，Archery驱动不支持	创建账号时指定`IDENTIFIED WITH mysql_native_password BY '密码'`
工单提交后一直处于等待执行状态	task容器没起来或Redis没连上	检查task容器状态，确认Redis环境变量配置正确
ClickHouse实例能查但执行DDL失败	账号只读权限或ClickHouse只读模式	按需调整账号权限，或在ClickHouse配置中关闭readonly
页面中文乱码	系统库字符集不是utf8mb4	在MySQL容器启动命令中增加`--character-set-server=utf8mb4`

5.2 实操中踩过的几个大坑

坑一：容器名和实例地址混为一谈

新增MySQL实例的时候，如果你填的是localhost:3306，从Archery容器内部访问到的不是宿主机的MySQL，而是容器自己。宿主机上的数据库要从容器内访问，需要填宿主机的内网IP，或者把端口映射出来用宿主机IP访问。这个细节是新手最常见的失误，菜鸟教程里几乎没人提。

坑二：MySQL 8.0的认证插件兼容问题

MySQL 8.0默认的认证插件是caching_sha2_password，但Archery内置的MySQL驱动在某些版本下对它有兼容问题，表现为“测试连接失败”或者“认证插件不支持”。解决方案是创建专用账号时显式指定：

CREATE USER 'archery'@'%' IDENTIFIED WITH mysql_native_password BY 'YourPass2024';

这个坑我在第一次部署时折腾了将近一个下午，最后查驱动源码才定位到。现在每个环境接入MySQL我都直接用这个写法，省事很多。

坑三：容器启动顺序导致初始化失败

docker-compose的depends_on只保证服务启动顺序，不保证MySQL“可用”。如果MySQL容器还在初始化数据目录，Archery就已经开始连数据库，必然报错。init时不要急，先用docker logs archery-mysql查看MySQL日志，看到类似ready for connections的日志再执行Archery的迁移命令。

坑四：忘挂载数据卷

有同事把Archery部署在测试环境，用了一个月，后来为了升级镜像删掉容器，结果所有配置、工单、审计记录灰飞烟灭。Archery的元数据全在系统MySQL里，如果MySQL容器没有把数据目录挂载到宿主机，删容器=删数据。所以我强烈建议在部署开始时就把数据卷挂载做好，这比任何高级配置都重要。

5.3 日常维护与备份建议

Archery上线之后，日常维护主要围绕三件事：

第一，定期备份系统库。Archery的元数据库是整个平台的“大脑”，所有用户、实例、工单、审计记录都在里面。我的习惯是每天凌晨用mysqldump做一次全量备份，保留7天。命令行可以直接写在宿主机cron里：

docker exec archery-mysql mysqldump -uarchery -pArcheryPass2024 archery > /backup/archery_$(date +%F).sql

第二，观察容器状态。上线初期最容易出现task容器内存飙升的情况，尤其是大量工单同时执行时。用docker stats看一眼实时资源，如果内存持续偏高，考虑给task容器加上内存限制。

第三，升级前先看变更记录。Archery迭代速度还算快，但每次升级数据库表结构可能都有变化。升级前一定先备份，然后用新镜像启动一个测试容器，验证没问题再替换生产环境。直接在生产环境硬升级，万一数据迁移脚本有问题，工单和审计记录很可能出问题。

结尾：一个老DBA的心里话

最后再分享一点个人经验。Archery这套系统部署起来不难，难的是让它真正在团队里落地。我第一次部署的时候，流程跑通了，但开发根本不乐意用，觉得在Web上提SQL比直接连数据库麻烦多了。后来我们做了两件事扭转了局面：一是把审核规则和开发团队公开对齐，让规则透明；二是让DBA在工单里写清楚驳回原因，不搞一言堂。工具是死的，流程是活的。Archery能把“数据库变更”这件高风险的事变得有章可循，但真正让它发挥价值，还是靠团队一起把规范立起来。希望这篇教程能帮你少走一些弯路，少踩几个坑。