Archery开源SQL审核平台Docker部署指南

1. Archery项目简介与部署概述

Archery是一款开源的SQL审核平台，由国内技术团队开发维护，主要用于企业级数据库管理、SQL审核和慢查询分析。作为一款基于Docker容器化部署的应用，它整合了MySQL、Redis、Inception等组件，为DBA和运维人员提供了便捷的数据库管理工具。

这次部署使用的是Archery 1.8.5版本，采用Docker Compose方式进行容器编排。相比传统部署方式，Docker化部署具有环境隔离、依赖管理简单、部署快速等优势，特别适合需要快速搭建测试环境或中小规模生产环境使用的场景。

提示：部署前请确保服务器已安装Docker 20.10.0+和Docker Compose 1.29.0+版本，并分配至少4GB内存。Archery对资源要求较高，尤其是MySQL容器需要足够的内存支持。

2. 环境准备与文件配置

2.1 下载和解压安装包

首先从Archery官网下载最新稳定版的安装包，这里我们使用1.8.5版本：

wget https://github.com/hhyo/Archery/releases/download/v1.8.5/Archery-1.8.5.tar.gz tar -zxf Archery-1.8.5.tar.gz cd Archery-1.8.5/src/docker-compose/

解压后进入docker-compose目录，这里包含了部署所需的所有配置文件。目录结构如下：

docker-compose/ ├── docker-compose.yml # 主编排文件 ├── mysql/ │ └── my.cnf # MySQL配置文件 ├── redis/ │ └── redis.conf # Redis配置文件 └── inception/ # Inception审核组件配置

2.2 MySQL关键配置调整

默认提供的my.cnf配置存在启动问题，需要进行调整。以下是经过验证可用的配置：

[mysqld_safe] socket = /var/run/mysqld/mysqld.sock nice = 0 [mysqld] pid-file = /var/run/mysqld/mysqld.pid socket = /var/run/mysqld/mysqld.sock port = 3306 basedir = /usr datadir = /var/lib/mysql tmpdir = /tmp lc-messages-dir = /usr/share/mysql skip-external-locking lower_case_table_names=1 # 表名大小写敏感设置 default-time_zone = '+8:00' # 设置中国时区 innodb_buffer_pool_size = 512M # 根据机器内存调整 server-id = 100 log_bin = /var/lib/mysql/mysql-bin.log expire_logs_days = 1 max_binlog_size = 500M max_allowed_packet = 1024M character-set-server = utf8mb4 # 完整UTF-8支持 collation-server = utf8mb4_general_ci slow_query_log_file = /var/lib/mysql/mysql-slow.log slow_query_log = 1 # 开启慢查询日志 long_query_time = 1 # 超过1秒视为慢查询 [client] default-character-set=utf8mb4 [mysqldump] quick quote-names max_allowed_packet = 1024M !includedir /etc/mysql/conf.d/

关键配置说明：

1. lower_case_table_names=1：强制表名小写，避免大小写敏感问题
2. default-time_zone = '+8:00'：设置中国时区，避免时间显示问题
3. innodb_buffer_pool_size：根据机器内存调整，建议为物理内存的50-70%
4. max_allowed_packet：增大包大小限制，避免大SQL执行失败

3. 容器启动与初始化

3.1 启动Docker服务

使用docker-compose命令启动所有服务：

docker compose -f docker-compose.yml up -d

这个命令会启动以下容器服务：

• archery：主应用服务
• mysql：MySQL数据库服务
• redis：缓存服务
• inception：SQL审核服务

可以通过以下命令检查容器状态：

docker compose ps

正常情况应该看到所有容器状态为"running"。

3.2 数据库初始化

进入archery容器执行初始化命令：

docker exec -ti archery /bin/bash cd /opt/archery source /opt/venv4archery/bin/activate # 激活虚拟环境

执行数据库迁移和初始化SQL：

python3 manage.py makemigrations sql python3 manage.py migrate python3 manage.py dbshell < sql/fixtures/auth_group.sql python3 manage.py dbshell < src/init_sql/mysql_slow_query_review.sql

这些命令完成了：

1. 创建数据库表结构
2. 导入初始权限组数据
3. 初始化慢查询分析表结构

3.3 创建管理员账户

最后创建超级管理员账户：

python3 manage.py createsuperuser

按提示输入用户名、邮箱和密码。建议密码复杂度：

• 至少12位字符
• 包含大小写字母、数字和特殊符号
• 避免使用常见单词或连续数字

4. 常见问题与解决方案

4.1 MySQL启动失败排查

问题现象：MySQL容器不断重启，查看日志显示启动失败。

解决方案：

1. 检查my.cnf文件格式是否正确，特别是方括号配对
2. 确认文件权限：chmod 644 mysql/my.cnf
3. 查看详细错误日志：docker logs mysql_container_name
4. 尝试增大容器内存限制，修改docker-compose.yml中mysql的mem_limit

4.2 数据库连接问题

问题现象：Archery应用无法连接MySQL数据库。

排查步骤：

1. 确认MySQL容器正常运行：docker exec -ti mysql mysql -uroot -p
2. 检查网络连通性：docker network inspect bridge
3. 验证数据库用户权限：

   CREATE USER 'archery'@'%' IDENTIFIED BY 'password'; GRANT ALL PRIVILEGES ON *.* TO 'archery'@'%'; FLUSH PRIVILEGES;

4.3 性能优化建议

1. MySQL配置优化：

   • 根据服务器内存调整innodb_buffer_pool_size
   • 增加max_connections（默认151可能不够）
   • 调整table_open_cache（默认2000）

2. Redis配置优化：

   • 增加maxmemory设置
   • 选择合适的淘汰策略（如volatile-lru）

3. 应用层优化：

   • 调整Django的CONN_MAX_AGE
   • 启用缓存框架
   • 配置合理的Celery worker数量

5. 生产环境部署建议

5.1 安全加固措施

1. 修改默认密码：

   • MySQL root密码
   • Redis密码
   • Archery管理员密码

2. 网络隔离：

   • 使用自定义bridge网络
   • 限制不必要的端口暴露
   • 配置防火墙规则

3. 数据备份：

   # MySQL备份 docker exec mysql sh -c 'exec mysqldump --all-databases -uroot -p"$MYSQL_ROOT_PASSWORD"' > all-databases.sql # Redis备份 docker exec redis redis-cli SAVE docker cp redis:/data/dump.rdp ./redis_backup.rdp

5.2 高可用方案

对于生产环境，建议采用以下高可用架构：

1. 数据库层：

   • MySQL主从复制
   • 使用HAProxy做负载均衡
   • 定期备份验证

2. 应用层：

   • 多实例部署Archery
   • 使用Nginx做反向代理和负载均衡
   • 配置会话共享（Redis）

3. 监控告警：

   • 容器资源监控（cAdvisor+Prometheus）
   • 应用性能监控（NewRelic/Datadog）
   • 日志集中收集（ELK）

5.3 版本升级策略

1. 备份所有数据和配置
2. 查看官方Release Notes和升级指南
3. 在测试环境验证升级过程
4. 生产环境采用蓝绿部署方式切换
5. 监控升级后系统运行状态

6. 日常维护与管理

6.1 容器管理命令参考

# 查看容器状态 docker compose ps # 查看日志 docker compose logs -f # 重启服务 docker compose restart archery # 更新镜像版本 docker compose pull docker compose up -d

6.2 数据备份与恢复

定期备份方案：

1. 创建备份脚本/opt/backup_archery.sh：

#!/bin/bash BACKUP_DIR="/data/backups/archery" DATE=$(date +%Y%m%d) # MySQL备份 docker exec mysql sh -c 'exec mysqldump -uroot -p"$MYSQL_ROOT_PASSWORD" --all-databases' | gzip > $BACKUP_DIR/mysql_$DATE.sql.gz # Redis备份 docker exec redis redis-cli SAVE docker cp redis:/data/dump.rdp $BACKUP_DIR/redis_$DATE.rdp # 配置文件备份 tar czf $BACKUP_DIR/config_$DATE.tar.gz /path/to/archery/config

2. 添加crontab定时任务：

0 2 * * * /opt/backup_archery.sh

6.3 性能监控指标

需要重点监控的指标包括：

指标类别	具体指标	正常范围	检查命令
MySQL	连接数	< max_connections*0.8	show status like 'Threads_connected'
QPS	根据业务而定	show global status like 'Questions'
Redis	内存使用率	< maxmemory*0.8	info memory
连接数	< 1000	info clients
系统	CPU使用率	< 70%	docker stats
内存使用率	< 80%	free -m

7. 进阶配置与功能扩展

7.1 邮件通知配置

在docker-compose.yml中配置邮件服务：

environment: EMAIL_HOST: 'smtp.example.com' EMAIL_PORT: 587 EMAIL_HOST_USER: '[e-mail]' EMAIL_HOST_PASSWORD: 'yourpassword' EMAIL_USE_TLS: 'True' DEFAULT_FROM_EMAIL: '[e-mail]'

7.2 LDAP集成

配置LDAP认证：

1. 修改docker-compose.yml：

environment: AUTH_LDAP: 'True' LDAP_SERVER: 'ldap://ldap.example.com' LDAP_PORT: '389' LDAP_BASE_DN: 'ou=users,dc=example,dc=com' LDAP_USER_DN_TEMPLATE: 'uid=%(user)s,ou=users,dc=example,dc=com'

2. 重启服务：

docker compose up -d

7.3 自定义审核规则

Archery支持通过Inception组件自定义SQL审核规则：

1. 进入inception容器：

docker exec -ti inception bash

2. 修改审核规则：

vi /etc/inception.cnf

3. 主要可配置规则包括：

• 禁止无WHERE条件的UPDATE/DELETE
• 表必须有主键
• 索引数量限制
• 表字段数量限制
• SQL最大长度限制

8. 使用技巧与最佳实践

8.1 慢查询分析优化

1. 配置合理的慢查询阈值（默认1秒）：

SET GLOBAL long_query_time = 0.5;

2. 定期分析慢查询日志：

SELECT * FROM mysql_slow_query_review ORDER BY query_time DESC LIMIT 100;

3. 常见优化手段：

• 添加合适索引
• 重写复杂SQL
• 拆分大事务
• 调整JOIN顺序

8.2 审核流程定制

1. 根据团队规模设置多级审核：

• 开发自审
• DBA审核
• 架构师终审

2. 配置自动化审核规则：

• 语法检查
• 执行计划分析
• 影响行数预估

3. 集成CI/CD流程：

• 代码提交触发SQL审核
• 审核通过才能合并代码
• 上线前二次确认

8.3 数据库变更管理

1. 线上变更必须通过工单系统
2. 变更前做好备份
3. 选择低峰期执行
4. 变更后验证影响
5. 记录变更结果和回滚方案

9. 故障排查手册

9.1 常见错误代码速查

错误代码	可能原因	解决方案
1045	认证失败	检查数据库用户权限
2003	连接拒绝	检查MySQL服务状态和网络
1213	死锁	重试事务或调整隔离级别
1205	锁等待超时	优化事务大小和持续时间

9.2 日志分析指南

1. MySQL错误日志：

   • 位置：/var/log/mysql/error.log
   • 关键信息：启动错误、崩溃信息、权限问题

2. Archery应用日志：

   • 位置：/opt/archery/logs/archery.log
   • 关键信息：请求处理错误、数据库操作异常

3. Inception审核日志：

   • 位置：/var/log/inception.log
   • 关键信息：SQL审核规则触发详情

9.3 性能问题诊断流程

1. 确认问题现象（慢查询、高CPU、连接堆积等）
2. 检查系统资源使用情况（CPU、内存、IO）
3. 分析数据库状态（连接数、锁等待、慢查询）
4. 检查应用日志（请求处理时间、错误信息）
5. 针对性优化（索引、SQL、配置参数）
6. 验证优化效果

10. 资源监控与告警配置

10.1 Prometheus监控方案

1. 配置exporter收集指标：

# docker-compose.yml添加 monitor: image: prom/mysqld-exporter environment: DATA_SOURCE_NAME: "exporter:password@(mysql:3306)/" ports: - "9104:9104"

2. Grafana仪表盘配置：

• MySQL Overview
• Redis Dashboard
• Docker容器监控

10.2 关键告警规则

1. MySQL告警：

   • 连接数 > 80% max_connections
   • 复制延迟 > 30秒
   • 磁盘空间 < 20%

2. Redis告警：

   • 内存使用 > 80%
   • 连接数 > 800
   • 持久化失败

3. 系统告警：

   • CPU使用 > 70%持续5分钟
   • 内存使用 > 80%
   • 磁盘IO延迟 > 50ms

10.3 日志监控方案

1. ELK架构部署：

   • Filebeat收集容器日志
   • Logstash解析处理
   • Elasticsearch存储
   • Kibana展示

2. 关键日志告警：

   • MySQL错误日志中的"ERROR"级别
   • Archery日志中的"Exception"关键词
   • 频繁认证失败记录

11. 安全加固措施详解

11.1 网络层安全

1. 容器网络隔离：

docker network create --driver bridge archery-net docker compose -f docker-compose.yml --project-name archery up -d

2. 防火墙规则：

# 只开放必要端口 ufw allow 80/tcp # HTTP ufw allow 443/tcp # HTTPS ufw enable

11.2 应用层安全

1. 密码策略：

   • 强制密码复杂度
   • 定期更换密码
   • 禁用默认账户

2. 访问控制：

   • 基于角色的权限管理
   • IP白名单限制
   • 操作审计日志

11.3 数据安全

1. 加密传输：

   • 启用TLS加密
   • 数据库SSL连接
   • 敏感信息加密存储

2. 备份策略：

   • 每日全量备份
   • 实时binlog备份
   • 异地备份存储

12. 版本升级与迁移指南

12.1 小版本升级步骤

1. 停止服务：

docker compose down

2. 备份数据和配置：

tar czf backup.tar.gz /path/to/archery/data /path/to/archery/config

3. 更新镜像：

docker compose pull

4. 启动新版本：

docker compose up -d

12.2 大版本迁移方案

1. 新环境部署新版本
2. 配置数据同步（主从复制/DTS）
3. 测试验证新版本功能
4. 切换DNS或负载均衡
5. 监控新版本稳定性
6. 旧环境保留一段时间

12.3 回滚方案

1. 停止当前服务
2. 恢复备份数据
3. 使用旧版本镜像启动
4. 验证数据一致性
5. 分析失败原因

13. 性能基准测试方法

13.1 测试工具选择

1. SQL性能测试：

   • sysbench
   • tpcc-mysql
   • 自定义业务SQL测试集

2. 应用层测试：

   • JMeter
   • Locust
   • wrk

13.2 测试指标收集

指标类型	收集工具	分析重点
数据库QPS/TPS	SHOW GLOBAL STATUS	吞吐量变化趋势
响应时间	慢查询日志	P95/P99延迟
资源使用率	docker stats	CPU/内存/IO瓶颈
应用吞吐量	JMeter聚合报告	并发处理能力

13.3 测试场景设计

1. 单业务场景测试：

   • 纯读场景
   • 纯写场���
   • 混合读写场景

2. 峰值压力测试：

   • 2倍日常峰值流量
   • 持续30分钟以上
   • 观察性能拐点

3. 稳定性测试：

   • 7*24小时运行
   • 监控内存泄漏
   • 检查错误率

14. 周边工具集成

14.1 与GitLab集成

1. Webhook配置：

   • SQL变更提交触发审核
   • 审核结果反馈到MR

2. CI/CD流水线：

stages: - test - sql-review sql-review: stage: sql-review script: - curl -X POST "http://archery/api/sql/review" -d @changes.sql rules: - changes: ["*.sql"]

14.2 与Jira集成

1. 工单对接：

   • 自动创建数据库变更工单
   • 工单状态同步

2. 审批流程：

   • Jira审批通过后执行SQL
   • 执行结果回写Jira

14.3 与监控系统集成

1. 告警对接：

   • Prometheus AlertManager
   • 企业微信/钉钉通知

2. 健康检查：

   • HTTP健康检查端点
   • 定时心跳检测

15. 架构演进建议

15.1 小型团队架构

客户端 → Nginx → Archery容器 → MySQL主从 ↘ Redis单节点

特点：

• 简单易维护
• 成本低
• 适合10人以下团队

15.2 中型团队架构

客户端 → LB → Archery集群 → MySQL集群(主从+Proxy) ↘ Redis集群 ↘ 监控告警系统

特点：

• 读写分离
• 应用高可用
• 适合50人以下团队

15.3 大型企业架构

全局LB → 区域代理 → Archery集群 → 分布式MySQL ↘ Redis集群 ↘ 审计日志系统 ↘ 多活数据同步

特点：

• 多地部署
• 多活容灾
• 完善监控体系
• 适合大规模企业

16. 成本优化方案

16.1 资源规划建议

团队规模	容器配置	MySQL配置	预估成本
小型(<10人)	2C4G	4C8G	低
中型(10-50人)	4C8G×2	8C16G+读副本	中
大型(50+人)	8C16G×N集群	16C32G集群	高

16.2 云服务选型

1. 自建方案：

   • 物理机/虚拟机
   • 自主运维
   • 适合有专业团队

2. 托管方案：

   • RDS for MySQL
   • ElastiCache for Redis
   • ECS部署应用

3. Serverless方案：

   • Aurora Serverless
   • 按需计费
   • 适合波动负载

16.3 许可证管理

1. 确认各组件许可证：

   • MySQL：GPL
   • Redis：BSD
   • Archery：Apache 2.0

2. 合规使用建议：

   • 遵循开源协议
   • 保留版权声明
   • 商业使用前审查

17. 技术栈深度解析

17.1 核心组件关系

Archery(Django) ├── MySQL(存储元数据和审核结果) ├── Redis(缓存和Celery消息队列) └── Inception(SQL审核引擎)

数据流向：

1. 用户请求 → Archery Web
2. SQL审核 → Inception
3. 执行结果 → MySQL
4. 异步任务 → Celery+Redis

17.2 关键实现原理

1. SQL审核流程：

   • 语法解析
   • 规则匹配
   • 执行计划分析
   • 风险评估

2. 慢查询分析：

   • 日志采集
   • 特征提取
   • 模式识别
   • 优化建议

3. 权限控制：

   • RBAC模型
   • 行级权限
   • 操作审计

17.3 性能关键点

1. 数据库设计：

   • 合理的索引策略
   • 规范化的表结构
   • 适度的反范式优化

2. 缓存策略：

   • 多级缓存
   • 合理的过期时间
   • 缓存击穿防护

3. 并发控制：

   • 连接池配置
   • 锁优化
   • 异步处理

18. 定制开发指南

18.1 开发环境搭建

1. 克隆代码：

git clone https://github.com/hhyo/Archery.git cd Archery

2. 启动开发环境：

docker compose -f docker-compose-dev.yml up -d

3. 安装依赖：

pip install -r requirements.txt

18.2 常见扩展点

1. 审核规则扩展：

   • 添加自定义审核规则类
   • 注册到审核流程中

2. 通知渠道扩展：

   • 实现新的通知后端
   • 支持企业微信/钉钉等

3. 认证方式扩展：

   • 集成OAuth2/OIDC
   • 支持多因素认证

18.3 贡献代码流程

1. Fork项目仓库
2. 创建特性分支
3. 提交代码变更
4. 编写测试用例
5. 发起Pull Request
6. 通过CI检查和代码审查

19. 替代方案对比

19.1 同类产品比较

产品	优势	劣势	适用场景
Archery	功能全面,中文友好	性能中等	中小团队,需要完整方案
Yearning	轻量简单	功能较少	小型团队,基础审核需求
SQLE	企业级功能	复杂度高	大型企业,专业DBA团队
自研方案	完全定制	开发成本高	特殊需求场景

19.2 技术选型建议

1. 评估维度：

   • 团队规模
   • 技术能力
   • 业务复杂度
   • 合规要求

2. 推荐路径：

   • 初创团队：Yearning
   • 成长团队：Archery
   • 企业用户：SQLE或定制开发

19.3 迁移方案

1. 数据迁移：

   • 导出原系统元数据
   • 转换为Archery格式
   • 验证数据一致性

2. 用户迁移：

   • 同步账户体系
   • 权限映射
   • 使用培训

3. 流程对接：

   • 集成现有审批流
   • 对接监控告警
   • 更新文档和规范

20. 未来演进方向

20.1 技术趋势跟踪

1. 云原生支持：

   • Kubernetes部署
   • Service Mesh集成
   • 弹性伸缩能力

2. AI增强：

   • 智能SQL优化建议
   • 异常检测
   • 自然语言查询

3. 多模支持：

   • 更多数据库类型
   • 混合云管理
   • 跨库查询

20.2 功能路线图

1. 近期规划：

   • 更完善的权限模型
   • 增强的审核规则
   • 性能优化

2. 中期规划：

   • 数据血缘分析
   • 影响评估系统
   • 智能索引推荐

3. 长期愿景：

   • 全链路数据库治理
   • 自治数据库管理
   • 深度业务洞察

20.3 社区生态建设

1. 贡献者计划：

   • 完善文档
   • 新手任务
   • 导师制度

2. 用户组活动：

   • 线上分享
   • 案例征集
   • 需求投票

3. 商业支持：

   • 专业服务
   • 培训认证
   • 托管方案