Docker部署archery项目常见问题及解决方案

1. 从零开始：为什么选择Docker部署Archery？

如果你是一名数据库管理员（DBA）或者经常和SQL打交道的开发者，肯定对“SQL审核”这个词不陌生。简单来说，它就是给SQL语句做“体检”，检查语法对不对、性能好不好、有没有安全隐患。手动做这事儿，费时费力还容易漏。Archery这个开源项目，就是来解决这个痛点的，它提供了一个Web界面，让你能一站式完成SQL审核、执行、备份、查询等一大堆数据库运维工作，可以说是DBA的“瑞士军刀”。

那为什么我们要用Docker来部署它呢？我刚开始接触Archery的时候，也尝试过传统的部署方式：在服务器上装Python、装一堆依赖、配数据库、配缓存……整个过程就像在玩“打地鼠”，解决一个报错，又冒出另一个。尤其是Python环境依赖和版本冲突，简直让人头大。后来转向Docker，感觉整个世界都清净了。Docker把Archery项目本身、它需要的Python环境、依赖包，甚至关联的MySQL、Redis等服务，全都打包成了一个个独立的“集装箱”（容器）。你只需要一条命令，就能把整个“码头”（运行环境）搭建起来，完全不用操心底层系统环境差异带来的各种“玄学”问题。

对于新手或者想快速搭建体验环境的朋友来说，Docker部署几乎是唯一推荐的选择。它极大地降低了部署门槛，让你能把精力集中在Archery功能本身，而不是和环境“斗智斗勇”。不过，就像任何工具一样，用Docker部署Archery也不是一路绿灯，中间总会遇到几个“收费站”需要你停下来处理一下。接下来，我就结合自己多次部署的经验，把那些常见的“坑”和解决办法，掰开揉碎了讲给你听。

2. 部署起步：镜像拉取与网络配置的“拦路虎”

万事开头难，部署Archery的第一步——拉取Docker镜像，就可能给你来个下马威。很多朋友执行docker-compose up -d后，看着终端卡在Pulling阶段，进度条半天不动，最后蹦出一个“超时”或“网络错误”，心态直接就崩了。这太正常了，因为Docker默认的镜像仓库在国外，国内访问速度慢不说，还经常不稳定。

我第一次部署时就栽在这里，等了大半个小时，最后以失败告终。解决方法其实很经典：给Docker换上一个国内的“镜像加速器”。网上教程很多，但并不是每个加速器地址都好用。有些大学的镜像源可能缺少某些偏门的镜像层，导致拉取不完整。我试了一圈，发现组合使用多个镜像源成功率最高。你需要修改Docker的守护进程配置文件。

# 编辑daemon.json文件，如果不存在就新建 sudo vim /etc/docker/daemon.json

在文件里加入以下内容（你可以挑选几个速度快的，不用全加）：

{ "registry-mirrors": [ "https://registry.docker-cn.com", "https://docker.mirrors.ustc.edu.cn", "https://hub-mirror.c.163.com", "https://mirror.baidubce.com" ] }

这里我主要推荐前四个，比较稳定。修改保存后，一定要重启Docker服务让配置生效：

# 重新加载配置并重启Docker sudo systemctl daemon-reload sudo systemctl restart docker

完成这步后，再回去重新拉取镜像，速度应该会有质的飞跃。如果还不行，可以尝试手动先拉取最大的那个基础镜像，比如python:3.8，看看网络是否真的通畅。

另一个新手容易忽略的点是Docker Compose的版本。Archery的docker-compose.yml文件语法可能依赖较新的Compose版本。如果你用docker-compose命令报一些奇怪的语法错误，比如“depends_on应该是一个数组”这类问题，很可能就是版本太低。现在推荐直接使用Docker Engine内置的docker compose插件（注意中间没有横杠），它是V2版本，兼容性更好。安装Docker时通常会自动安装，如果没有，可以参照官方文档安装。用docker compose version检查一下，确保不是太老的版本。

3. 核心陷阱：YAML配置文件与源码版本的对齐

镜像拉取成功后，你以为就能一帆风顺了？别急，第一个真正的“深坑”可能就在配置文件里等着你。这里我踩过一个记忆犹新的坑，差点让我放弃Docker部署。

事情是这样的：我最早部署时，是从Archery的GitHub仓库直接git clone了最新的主分支代码，然后找到里面的docker-compose.yml文件就开干。结果运行docker compose up时，直接报错，提示depends_on部分格式错误，应该是一个列表（数组）。我当时就懵了，把配置文件贴到在线YAML校验器里检查，又显示语法完全正确。

折腾了半天，我才意识到问题所在：我使用的docker-compose.yml文件版本，和当前Docker Compose工具期望的格式不匹配。Archery项目在快速迭代，主分支（main或master分支）的Docker配置可能是为最新的开发环境准备的，有时会使用一些新版本的语法或特性。而我们直接从Release页面下载的稳定版源码包，里面的配置才是经过测试、保证可用的。

所以，一个至关重要的建议：部署生产或稳定环境时，请务必使用GitHub Releases页面发布的源码包（Source code），而不是直接克隆开发分支。比如，你去 Archery的Releases页面，下载v1.10.0这样的标签对应的源码压缩包。解压后，你会发现目录结构里有一个src/docker-compose/文件夹，里面的docker-compose.yml才是“官配”。

我后来对比了两个文件，差异确实存在。开发版的配置可能更精简或实验性，而Release版的配置考虑了最大的兼容性。因此，请切换到正确的目录再执行命令：

# 假设你解压后目录是 archery-1.10.0 cd archery-1.10.0/src/docker-compose/ # 使用docker compose v2语法 docker compose -f docker-compose.yml up -d

这一步做对了，后面容器启动的成功率就高了90%。记住，在开源世界，跟着Release走，往往能避开很多开发中的“坑”。

4. 容器启动后：数据库初始化与管理员创建

当docker compose up -d命令执行成功，屏幕上刷刷刷地跑完日志，用docker ps看到四个容器（archery, mysql, redis, inception）都处于Up状态时，恭喜你，万里长征走完了一大半。但这时候访问http://你的服务器IP:9123，很可能还是打不开，或者无法登录。因为Archery这栋“大楼”虽然盖好了，里面的“房间”（数据库表）和“管理员”还没安排呢。

接下来需要进入Archery的容器内部，完成数据库迁移和初始化。这相当于运行它的安装脚本。很多新手会在这里卡住，不知道命令该在哪里执行。

# 1. 进入名为archery的容器内部（这个名称在docker-compose.yml里定义） docker exec -it archery /bin/bash # 2. 进入容器后，你会发现自己在/opt/archery目录下。需要激活Python虚拟环境 cd /opt/archery source /opt/venv4archery/bin/activate # 激活后，命令行提示符前可能会出现 (venv4archery) 字样 # 3. 生成并执行数据库迁移，创建所有数据表 python3 manage.py makemigrations sql python3 manage.py migrate # 4. 初始化一些必要的基础数据，比如权限组、初始SQL审核规则等 python3 manage.py dbshell < sql/fixtures/auth_group.sql python3 manage.py dbshell < src/init_sql/mysql_slow_query_review.sql # 5. 创建一个超级管理员账号，用于首次登录后台 python3 manage.py createsuperuser

执行createsuperuser命令时，它会交互式地提示你输入用户名、邮箱和密码。这里我建议邮箱可以填一个有效的（但非必须），用户名和密码一定要记住，这就是你登录Archery Web界面的“钥匙”。

全部执行完毕后，退出容器（输入exit），然后重启一下archery容器，让所有更改生效：

docker restart archery

现在，你再刷新浏览器，输入刚才创建的用户名和密码，应该就能成功登录Archery的管理后台了。如果还是不行，别急着关页面，查看容器日志是定位问题的好方法：

# 动态查看archery容器的最新10行日志 docker logs archery -f --tail=10

看看有没有明显的错误信息，比如数据库连接失败、某个模块导入错误等。常见的问题可能是MySQL容器还没完全启动好（需要等待几十秒），或者网络配置导致容器间无法通信（检查docker-compose网络设置）。

5. 功能配置：让SQL审核引擎真正跑起来

成功登录Archery后台，你会发现界面很漂亮，功能菜单很多。但当你兴冲冲地想去体验核心功能——SQL审核，上传一个SQL文件或MyBatis的Mapper XML文件时，可能会碰一鼻子灰。页面上报错，或者分析报告迟迟出不来。这是我遇到的第二个大坑：SQL审核依赖的外部引擎没有正确配置。

Archery的SQL审核功能本身不直接分析SQL，它更像一个“调度中心”，背后依赖了像SOAR、SQLAdvisor这样的开源SQL优化工具来做具体的分析工作。在Docker部署中，这些工具已经以可执行文件的形式，放在了容器内的特定路径。但Archery系统并不知道它们在哪，需要我们手动告诉它。

具体怎么配呢？登录Archery后台，在左侧菜单找到“系统管理”->“配置项管理”。在这里，你会看到很多系统参数。我们需要关注其中两个关键的路径配置：

1. SOAR_PATH: 这是小米开源的SQL优化和重写工具SOAR的可执行文件路径。
2. SQLADVISOR_PATH: 这是美团开源的SQL索引优化工具SQLAdvisor的可执行文件路径。

在Docker镜像中，这两个文件通常已经被预置了。它们的路径一般是：

• SOAR_PATH:/opt/archery/src/plugins/soar
• SQLADVISOR_PATH:/opt/archery/src/plugins/sqladvisor

你只需要在配置项管理页面，找到对应的配置项（可能需要翻页或搜索），将值修改为上面的路径并保存即可。修改后，通常不需要重启整个容器，Archery会读取新的配置。

配置完成后，你可以立刻在“SQL审核”页面找一个简单的SQL语句测试一下。选择正确的数据库类型（如MySQL），输入SELECT * FROM user;，点击“分析”。如果配置正确，几秒钟后你就能看到一份详细的审核报告，包括语法检查、索引建议、执行计划分析等等。

这一步的配置虽然简单，但却是Archery从“展示界面”变成“生产力工具”的关键。很多朋友部署完觉得没用，问题往往就出在这里。记得，开源软件“开箱即用”是理想，大部分时候都需要我们根据文档进行一些必要的配置。

6. 权限与定制：如何按需调整系统行为

Archery默认是一个需要登录认证的系统，所有操作都有权限控制。这对于团队内部使用来说很棒，很安全。但有时候，你可能想把它集成到自己的CI/CD流水线里，让自动化脚本直接调用它的SQL审核接口。这时候，每次调用都要传token或者处理登录态，就很麻烦。

这就需要我们做一些定制化的修改，比如绕过或简化某些接口的认证。请注意，这会影响系统安全性，请仅在受信任的内部网络环境或经过充分评估后操作。

修改通常涉及两部分：Django后端代码和前端页面。由于我们是用Docker部署，修改容器内的代码需要一点技巧。不建议直接进入容器用vim修改，因为容器重启后改动会丢失。正确的做法是使用“挂载卷”（Volume）的方式。

首先，在你宿主机上，创建一个目录用来存放需要修改的Archery源码。然后，将容器内的代码目录挂载到这个宿主机目录。但这需要修改docker-compose.yml文件，在archery服务下添加卷挂载配置，比较麻烦。对于初学者，一个更直接（但略粗糙）的方法是：

1. 在宿主机修改好代码文件。
2. 使用docker cp命令将文件复制到运行中的容器内。

例如，如果你想修改一个视图文件来跳过认证：

# 将宿主机当前目录下的 my_view.py 复制到 archery 容器的指定位置 docker cp ./my_view.py archery:/opt/archery/archery/views/ # 复制完成后，重启容器使修改生效 docker restart archery

具体要修改哪些文件呢？这取决于你的需求。常见的修改点包括：

• settings.py： 调整认证后端、中间件，比如注释掉SessionAuthenticationMiddleware。
• 特定视图（views）： 在你想放行的API视图函数上，加上@authentication_classes([])和@permission_classes([])装饰器（如果使用Django REST framework）。
• URL路由： 将某些API路径从需要登录的路由中移出。

这些修改涉及Python和Django框架知识，建议你先在本地开发环境测试通过，再应用到Docker环境。同时，务必做好原文件的备份。记住，修改开源代码意味着未来升级版本可能会遇到冲突，需要手动合并更改，这是一个需要权衡的代价。

7. 运维与排错：让Archery稳定运行

部署完成并能正常使用后，我们的工作还没结束。如何确保它长期稳定运行，出了问题如何快速定位？这里分享几个日常运维和排错的小技巧。

首先是日志查看，这是排查问题的第一利器。除了之前用过的docker logs，对于Archery这个Python应用，更详细的日志可能在它自身的日志文件里。你可以进入容器查看：

docker exec -it archery /bin/bash cd /opt/archery/logs/ tail -f archery.log # 查看实时日志

这里会记录每个Web请求、SQL审核任务、错误堆栈等信息，比Docker容器日志更详细。

其次是数据持久化。你有没有想过，如果MySQL容器崩溃重启，里面的审核记录、用户数据会不会丢？在默认的docker-compose.yml里，通常已经配置了MySQL的数据卷，将数据保存在名为mysql_data的Docker卷中。你可以用docker volume ls查看，用docker volume inspect检查具体位置。强烈建议定期备份这个卷，或者将其挂载到宿主机的某个具体目录（修改compose文件），方便备份。

# 在docker-compose.yml的mysql服务部分，类似这样的配置保证了数据持久化 services: mysql: ... volumes: - mysql_data:/var/lib/mysql volumes: mysql_data:

然后是性能监控。Archery本身资源消耗不大，但如果你审核的SQL文件很大很多，或者同时在线用户多，可能会占用较多CPU和内存。使用docker stats命令可以实时查看各个容器的资源使用情况。如果发现archery容器内存持续增长（可能是内存泄漏），可以设置一个重启策略，在docker-compose.yml中为服务添加restart: unless-stopped，让它异常退出时自动重启。

最后是升级。当Archery发布新版本时，如何安全升级？最稳妥的方法是：

1. 备份数据库（导出SQL或备份整个数据卷）。
2. 停止并删除现有容器：docker compose down。
3. 拉取新版本的源码包，替换旧的docker-compose.yml和必要的配置文件（注意对比差异，保留你的自定义配置）。
4. 重新拉取镜像并启动：docker compose up -d。
5. 进入新容器，执行数据库升级命令（如果有）：python3 manage.py migrate。

按照这个流程，就能在最大限度保证数据安全的前提下完成升级。部署Archery不是一劳永逸的事，把它当作一个需要轻微照料的服务，掌握这些基本的运维手段，就能让它在你手中稳定、高效地运行起来，真正成为团队数据库开发的得力助手。