企业级SQL审核平台Archery实战用Docker-compose一键部署完整指南含Soar配置对于任何一家技术驱动型公司而言数据库的稳定与高效是业务的生命线。然而随着业务复杂度的提升开发人员手写的SQL语句质量参差不齐性能问题、潜在风险往往在线上爆发时才被发现代价巨大。你是否也经历过深夜被慢查询告警惊醒或是面对一个因索引缺失而崩溃的线上服务传统的代码审查很难覆盖SQL的细节而手动分析又效率低下。这时一个集中化、自动化、具备深度分析能力的SQL审核平台就成了开发团队和DBA数据库管理员的“刚需”。Archery正是为解决这一痛点而生的开源利器。它不仅仅是一个SQL执行的Web界面更是一个集工单、审核、执行、查询、优化建议于一体的全流程管控平台。想象一下所有上线的SQL都需要经过平台的规则引擎和智能分析工具如Soar的“体检”将性能隐患和语法错误扼杀在摇篮里。这对于推行DevOps、追求研发规范与效率的团队来说价值不言而喻。本文将带你从零开始手把手完成Archery的生产级容器化部署。我们不会止步于简单的“跑起来”而是深入部署的每一个环节剖析最佳实践并重点攻克核心组件Soar的集成配置。无论你是团队的运维负责人还是希望提升数据库开发规范的架构师这份指南都将为你提供一条清晰、可落地的路径。1. 部署环境规划与准备在按下第一个Docker命令之前合理的规划是成功的一半。一个面向生产环境的部署需要考虑资源、网络、持久化以及后续的维护便利性。盲目开始往往会导致后期频繁的调整甚至重构。服务器资源建议对于中小型团队一台配置适中的云服务器或虚拟机即可胜任。建议最低配置为2核CPU、4GB内存、50GB SSD存储。内存是关键因为Archery服务本身及其依赖的数据库MySQL、缓存Redis都会占用一定资源。如果团队规模较大或审核任务繁重应考虑提升配置或将数据库等组件部署至独立的、更强大的实例上。网络与安全考量Archery默认使用9123端口对外提供服务。在云平台你需要在安全组或防火墙中明确放行该端口。绝对不要图省事直接开放所有端口或使用默认的测试密码。一个更安全的做法是将Archery部署在内网通过跳板机或VPN此处应避免提及具体翻墙工具可改为“通过内部网络通道”进行访问但这需要额外的网络架构支持本文以直接对外访问的简易场景为例。注意本文所有操作均基于Linux环境如CentOS 7/8, Ubuntu 20.04。Windows或macOS用户可通过虚拟机或WSL2获得类似的终端环境。1.1 基础依赖安装Docker与Docker Compose容器化部署的核心是Docker引擎及其编排工具Docker Compose。它们的安装虽然简单但选用合适的版本和配置国内镜像源是提升后续体验的关键。首先通过官方脚本安装Docker Engine。这条命令会自动化完成检测和安装。curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh安装完成后将当前用户加入docker用户组这样后续执行docker命令就无需每次都加sudo。sudo usermod -aG docker $USER # 执行此命令后需要退出当前终端并重新登录用户组变更才会生效。接下来安装Docker Compose。截至本文撰写时v2版本已成为主流且功能更强大推荐直接安装。你可以从GitHub Release页面查看最新稳定版本号进行替换。# 下载Docker Compose二进制文件到/usr/local/bin目录 sudo curl -L https://github.com/docker/compose/releases/download/v2.20.3/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose # 赋予可执行权限 sudo chmod x /usr/local/bin/docker-compose # 验证安装 docker-compose --version配置国内镜像加速器这是在国内环境部署必须做的一步能极大提升镜像拉取速度避免因网络超时导致的部署失败。编辑Docker守护进程配置文件sudo tee /etc/docker/daemon.json -EOF { registry-mirrors: [ https://registry.docker-cn.com, https://mirror.baidubce.com, https://hub-mirror.163.com ] } EOF然后重启Docker服务使配置生效sudo systemctl daemon-reload sudo systemctl restart docker至此基础环境已经就绪。你可以运行docker run hello-world来测试Docker是否正常工作。2. 获取与解析Archery部署资产许多人在部署开源项目时遇到的第一个坑就是应该使用哪个版本的代码是直接git clone主分支的最新代码还是使用官方发布的Release版本对于Archery答案非常明确务必使用官方GitHub仓库Release页面提供的源码包。主分支的代码处于持续开发状态可能包含未稳定的变更、依赖版本冲突或配置格式更新例如docker-compose.yml中depends_on的语法直接用于生产部署风险极高。Release版本是经过测试的稳定快照。操作步骤访问 Archery的GitHub Release页面。找到最新的稳定版本例如v1.10.0下载Source code (tar.gz)压缩包。将压缩包上传到你的服务器或者直接在服务器上使用wget命令下载。解压后进入项目目录。关键的部署文件位于src/docker-compose/路径下。让我们先审视一下这个核心的docker-compose.yml文件。它定义了一个完整的微服务栈服务名镜像端口映射核心作用archeryhhyo/archery:latest9123:9123Archery主应用提供Web界面和API。mysqlmysql:5.73306:3306存储Archery自身的元数据、用户、工单等信息。redisredis:56379:6379用作缓存和Celery任务队列的消息代理。goinceptionhhyo/goinception:latest4000:4000SQL审核和执行引擎支持MySQL语法审核、执行、备份等。这个编排文件已经为我们做好了服务依赖、网络联通和基础数据卷的配置。在部署前我们可能需要根据实际情况进行一些定制化修改例如修改默认密码在mysql和redis服务的环境变量中找到MYSQL_ROOT_PASSWORD和REDIS_PASSWORD将其改为强密码。数据持久化确保volumes配置指向了服务器上合适的持久化目录如/data/mysql防止容器重启后数据丢失。资源限制在生产环境可以考虑为每个服务添加deploy.resources.limits来限制CPU和内存使用避免单个服务耗尽主机资源。3. 一键启动与初始化配置检查无误后就可以启动整个服务栈了。进入src/docker-compose/目录执行以下命令docker-compose up -d-d参数代表在后台运行。此时Docker会依次拉取镜像如果本地没有、创建网络和卷、并启动四个容器。你可以通过docker-compose ps查看服务状态或使用docker-compose logs -f来实时跟踪启动日志。当所有容器状态显示为Up后Archery的应用容器已经运行但数据库尚未初始化。我们需要进入archery容器内部执行Django数据库迁移和初始化脚本。# 进入archery容器的bash环境 docker exec -it archery bash # 激活Python虚拟环境项目已内置 source /opt/venv4archery/bin/activate # 1. 生成数据库迁移文件 python3 manage.py makemigrations sql # 2. 执行迁移创建所有数据表 python3 manage.py migrate # 3. 初始化基础数据如权限组、初始配置 python3 manage.py dbshell /opt/archery/sql/fixtures/auth_group.sql python3 manage.py dbshell /opt/archery/src/init_sql/mysql_slow_query_review.sql # 4. 创建超级管理员账户按提示输入用户名、邮箱和密码 python3 manage.py createsuperuser完成以上步骤后退出容器输入exit并重启archery服务以使所有更改生效docker-compose restart archery现在打开浏览器访问http://你的服务器IP:9123应该能看到Archery的登录界面。使用上一步创建的超级管理员账号登录一个崭新的SQL审核平台就展现在你面前了。4. 核心功能配置Soar集成详解登录系统后你可能会迫不及待地尝试“SQL审核”功能上传一个SQL文件或MyBatis的Mapper XML文件进行分析。但很可能会遇到分析失败查看archery容器日志会发现类似SOAR_PATH is not set或NoneType object has no attribute ...的错误。这是因为Archery强大的SQL分析能力依赖于一个外部的智能优化工具——Soar。SoarSQL Optimizer And Rewriter是小米开源的基于Go语言编写的SQL优化器。它能够对输入的SQL进行索引建议、重写优化、风险评估等。Archery通过调用Soar的可执行文件来获得这些深度分析结果。4.1 获取与配置SoarSoar并未预装在Archery的Docker镜像中需要手动下载并放置到正确路径。以下是具体步骤下载Soar二进制文件进入Soar的GitHub Release页面选择与你的服务器架构通常是linux-amd64对应的最新版本压缩包下载并解压。你可以在服务器上直接操作# 进入一个临时目录例如/opt cd /opt # 下载请替换为最新的版本链接 wget https://github.com/XiaoMi/soar/releases/download/0.11.0/soar.linux-amd64 -O soar # 赋予可执行权限 chmod x soar将Soar复制到Archery容器内的插件目录Archery容器内预留了插件路径/opt/archery/src/plugins/。我们需要将本地的soar文件复制进去。# 从宿主机复制到正在运行的archery容器中 docker cp /opt/soar archery:/opt/archery/src/plugins/在Archery管理界面配置路径使用超级管理员账号登录Archery Web界面。点击顶部导航栏的“系统管理”选择“配置项管理”。在配置项列表中找到SOAR_PATH。点击其右侧的“编辑”按钮。在值一栏中填入Soar在容器内的绝对路径/opt/archery/src/plugins/soar。点击“提交”保存。同理如果你也需要集成另一个优化工具SQLAdvisor可以下载其二进制文件放置到/opt/archery/src/plugins/sqladvisor并配置SQLADVISOR_PATH。4.2 验证与使用SQL审核配置完成后无需重启容器Archery会读取新的配置。现在我们可以彻底测试一下核心功能。功能验证再次进入“SQL审核”页面尝试上传一个简单的SQL文件例如包含SELECT * FROM users WHERE id 1;的文件。点击“分析”。解读报告如果一切正常你将看到一份详细的分析报告。报告可能包含以下部分评分Soar给出的SQL质量综合评分。索引建议明确指出哪些列需要添加索引并给出创建索引的SQL语句。这是最具价值的部分。重写建议可能会建议你将SELECT *改为明确的字段列表或优化WHERE条件。风险评估提示潜在问题如全表扫描、使用OR条件可能导致索引失效等。为了让团队更好地利用这个功能你可以定义审核流程规定所有上线的SQL必须通过Archery工单系统提交并附带Soar的分析报告评分低于一定阈值如80分的SQL需要优化后才能执行。集成到CI/CD在代码提交或合并请求Merge Request阶段自动提取变更的SQL语句或Mapper文件调用Archery的API进行分析并将报告作为卡点评论实现左移的质量保障。5. 生产环境优化与进阶考量将平台“跑起来”只是第一步要让它稳定、高效地服务于生产还需要一些额外的优化工作。性能与高可用数据库分离考虑将mysql和redis服务从docker-compose中剥离部署到独立的、具备高可用架构如主从复制、集群模式的数据库实例上。这能提升整体稳定性和性能上限。只需修改archery服务中的数据库连接字符串即可。容器资源限制在docker-compose.yml中为每个服务设置资源限制和预留防止相互干扰。services: archery: # ... 其他配置 deploy: resources: limits: cpus: 1.0 memory: 2G reservations: cpus: 0.5 memory: 1G日志收集配置Docker的日志驱动将容器日志统一收集到ELKElasticsearch, Logstash, Kibana或Graylog等日志平台方便问题排查和审计。权限与流程精细化 Archery内置了基于RBAC角色基于访问控制的权限系统。你需要根据团队角色进行配置DBA拥有最高权限可以管理数据源、审核所有工单、执行SQL、查看慢查询等。开发组长可以审核本组提交的SQL工单。普通开发者可以提交工单、查询自己有权限的数据库。 通过“系统管理”-“权限管理”和“资源组管理”进行细致划分实现职责分离保障安全。备份与监控定期备份确保mysql容器的数据卷定期备份到异地。可以使用cron任务执行docker exec进行mysqldump。服务监控为Archery的9123端口以及各个容器状态设置健康检查告警。可以使用Prometheus监控Docker主机并结合Grafana进行仪表盘展示。部署和配置的过程可能会遇到各种小问题比如容器启动顺序导致的连接失败、时区不对、或者Soar版本兼容性问题。我的经验是多查看docker-compose logs输出的日志大部分错误信息都会指向明确的配置缺失或路径错误。这个平台一旦顺利运行起来对团队研发规范的提升和线上数据库风险的降低其回报将远超部署时所付出的努力。