企业官网建设流程全解析

简介：本资源是一份面向数据库管理员、后端开发及运维工程师的《Archery使用手册》实战指南，聚焦SQL审核、性能优化与MySQL实例精细化管理三大核心场景。手册系统覆盖SQL语法与规范审核（含高危语句自动驳回、钉钉通知）、慢SQL分析与优化建议、binlog清理、会话/事务/锁监控、账号权限配置，以及PTArchiver、Binlog2SQL、SchemaSync等关键插件的可视化操作流程，特别适配开发测试环境SQL工单闭环管理与线上故障快速排查需求。资源为1个1.2MB的Word文档（.doc），内容结构清晰，含功能详解、审核流程图解、SQL优化前后对比示例、锁等待模拟排障步骤及工具配置实操截图，便于按需查阅与落地执行。目前已有1474人学习下载，是掌握Archery平台从部署到高阶运维的实用型入门到进阶参考材料。

1. Archery 是什么：一个能让你的 DBA 从“救火队员”变成“审核守门员”的 SQL 审核平台

Archery 不是又一个数据库 GUI 工具，也不是简单的 SQL 执行器。它是一个面向企业级 MySQL（也支持 PostgreSQL、Oracle、SQL Server 等）的开源 SQL 审核与执行平台，核心价值在于把「人肉 Review」变成可配置、可审计、可回溯、带风险分级的自动化流程。我见过太多团队：开发提 PR 时随手写个UPDATE user SET status=1 WHERE id IN (SELECT id FROM order WHERE create_time < '2023-01-01')，DBA 深夜被电话叫醒 kill 连接、查 undo log、手写 binlog 回滚脚本——这种“血泪经验”不是玄学，是没上审核卡点的必然结果。Archery 就是那个卡在 SQL 上线前的“守门员”：它能静态分析语法、识别高危操作（如无 WHERE 的 UPDATE/DELETE）、检测缺失索引、估算影响行数、拦截全表扫描、甚至结合 pt-archiver 或 binlog2sql 做变更预演。适合中小团队 DBA、SRE、以及对数据安全有强诉求的 DevOps 团队——尤其当你开始用 kubesphere 部署 MySQL、或在 centos9 上跑 zabbix 7.0 + MySQL 8.0 这类生产环境时，Archery 不是锦上添花，而是防翻车的后悔药。

2. 本地快速部署 Archery：用 Docker Compose 跑通最小可用环境（含 MySQL 8.0 兼容配置）

Archery 官方推荐 Docker 部署，但直接docker-compose up很容易踩坑——尤其是 MySQL 8.0 默认启用 caching_sha2_password 插件，而 Archery 的 Python 后端（基于 Django + PyMySQL）默认不兼容该认证方式。下面这套配置是我在线上灰度验证过的最小可行组合，已适配 MySQL 8.0.33+ 和最新 Archery v1.10.x（2024 年主流稳定版）。

2.1 准备 docker-compose.yml：显式声明 MySQL 认证插件与字符集

# docker-compose.yml version: '3.8' services: mysql: image: mysql:8.0.33 container_name: archery-mysql restart: unless-stopped environment: MYSQL_ROOT_PASSWORD: "archery_root_2024" MYSQL_DATABASE: "archery" MYSQL_USER: "archery" MYSQL_PASSWORD: "archery_pass_2024" # 关键：强制使用 mysql_native_password 插件，避免 PyMySQL 连接失败 MYSQL_DEFAULT_AUTHENTICATION_PLUGIN: "mysql_native_password" command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci --default-authentication-plugin=mysql_native_password volumes: - ./mysql-data:/var/lib/mysql - ./my.cnf:/etc/mysql/conf.d/my.cnf:ro ports: - "3307:3306" healthcheck: test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-parchery_root_2024"] timeout: 20s retries: 10 archery: image: hhyo/Archery:latest container_name: archery-web restart: unless-stopped depends_on: - mysql environment: # 数据库连接字符串：注意 host 必须用 service 名（mysql），不是 localhost DATABASE_URL: "mysql://archery:archery_pass_2024@mysql:3306/archery?charset=utf8mb4" # 开启 SQL 审核核心功能 ENABLE_SQLAUDIT: "true" # 指定默认审核规则集（后面会细调） AUDIT_RULE_SET: "default" # 日志级别，调试阶段建议 DEBUG LOG_LEVEL: "INFO" ports: - "9123:9123" volumes: - ./archery-data:/opt/archery/upload - ./archery-logs:/opt/archery/logs

提示：DATABASE_URL中的host必须填mysql（Docker 内部服务名），填localhost或127.0.0.1会导致容器内无法解析，这是新手最常翻车的点。PyMySQL 在容器网络中访问宿主机 localhost 会失败，必须走 Docker 内网 DNS。

2.2 补充 my.cnf：解决 MySQL 8.0 默认 strict mode 导致的建表失败

Archery 初始化时会执行大量 DDL（如创建sql_workflow、workflowauditlog等表），MySQL 8.0 默认开启STRICT_TRANS_TABLES，而部分 Archery 的建表语句未显式声明NOT NULL或默认值，会导致初始化失败。新建my.cnf：

# my.cnf [mysqld] sql_mode = "ONLY_FULL_GROUP_BY,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION" # 关键：关闭 STRICT_TRANS_TABLES，否则 Archery 初始化报错 # 注意：生产环境请勿长期关闭，此处仅为部署通过 sql_mode = "ONLY_FULL_GROUP_BY,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION"

2.3 启动并验证基础服务连通性

# 1. 创建目录结构 mkdir -p ./mysql-data ./archery-data ./archery-logs # 2. 启动服务（首次启动会自动初始化数据库） docker-compose up -d # 3. 等待 MySQL 健康就绪（约 30 秒） docker-compose logs -f mysql | grep "ready for connections" # 4. 查看 Archery 初始化日志（关键看是否成功 migrate） docker-compose logs archery | grep -i "migrate\|success\|running" # 5. 检查 Archery 是否监听 9123 端口 curl -I http://localhost:9123 # 应返回 HTTP/1.1 302 Found（重定向到 /login）

逻辑说明：

• docker-compose up -d启动后，MySQL 容器先就绪，Archery 容器启动时会读取DATABASE_URL，自动执行 Django 的migrate命令建表。
• 若看到django.db.utils.InternalError: (1071, 'Specified key was too long...')，说明utf8mb4索引长度超限，需确认my.cnf中innodb_large_prefix=ON（MySQL 5.7+ 默认开启，8.0 已移除该参数，故无需额外配置）。
• 若 Archery 日志卡在Starting development server但无后续，大概率是数据库连接失败，请docker exec -it archery-web bash进入容器，手动执行python manage.py dbshell测试连接。

3. 配置第一个 MySQL 实例：添加线上库、设置审核规则、触发一次真实 SQL 审核

Archery 本身不管理业务数据库，它只作为“审核代理”连接你已有的 MySQL 实例。这一步是落地核心——让 Archery 真正开始工作，而不是停留在登录页。

3.1 通过 Web UI 添加 MySQL 实例（以本地 3307 端口为例）

1. 浏览器打开http://localhost:9123，初始账号密码均为admin/admin（首次登录强制修改）

2. 进入【实例管理】→【实例列表】→【新增实例】

3. 填写关键字段：

   • 实例名称：prod-mysql-8033（建议含版本和用途）
   • IP 地址：host.docker.internal（Mac/Windows）或172.17.0.1（Linux，即 Docker0 网桥地址）

     为什么不用 localhost？容器内localhost指向自身，而 Archery 需要连宿主机上的 MySQL（我们映射了 3307 端口）。host.docker.internal是 Docker 提供的宿主机别名，Mac/Win 原生支持；Linux 需在docker-compose.yml的 archery service 下加extra_hosts: - "host.docker.internal:host-gateway"。

   • 端口：3307
   • 用户名/密码：archery/archery_pass_2024（即前面 docker-compose 中定义的非 root 用户）
   • 数据库：留空（Archery 会自动探测所有库）
   • 字符集：utf8mb4
   • 环境类型：生产（影响审核严格度）

4. 点击【测试连接】→ 成功后【保存】

3.2 配置审核规则集：针对 MySQL 8.0 的 3 个必调参数

Archery 的审核能力高度依赖规则集。默认default规则集较宽松，需根据 MySQL 8.0 特性强化。进入【审核配置】→【规则集管理】→ 编辑default规则集：

注意：若开启full_table_scan后审核失败报Access denied; you need (at least one of) the PROCESS privilege(s)，需给 Archery 连接用户授权：

GRANT PROCESS ON *.* TO 'archery'@'%'; FLUSH PRIVILEGES;

3.3 提交第一条审核工单：用真实 SQL 触发审核链路

1. 进入【SQL 审核】→【提交审核】
2. 选择实例：prod-mysql-8033
3. 输入 SQL（故意写一个高危语句）：

   -- 危险示例：无 WHERE 的 UPDATE（Archery 会拦截） UPDATE user SET status = 0; -- 安全示例：带 WHERE 和 LIMIT（应通过） UPDATE user SET last_login_time = NOW() WHERE id BETWEEN 1000 AND 1010 LIMIT 10;

4. 【提交】→ 系统自动生成工单号（如WF20240515001）
5. 进入【审核列表】，查看该工单状态：
   • 若为自动驳回，说明no_where规则生效；
   • 若为自动通过，检查limit_rows是否生效（LIMIT 10≤1000）；
   • 点击工单详情，可看到每条 SQL 的审核报告：影响行数预估、索引建议、执行计划（EXPLAIN）、风险标签。

逻辑说明：

• Archery 对 SQL 的解析不是正则匹配，而是调用sqlparse库做语法树解析，再结合 MySQL 的EXPLAIN FORMAT=JSON获取执行计划，因此能准确识别WHERE子句是否存在、LIMIT是否合规、是否触发全表扫描。
• 审核报告中的“影响行数预估”来自EXPLAIN的rows字段，非真实执行，但足够用于风险判断。
• 所有审核记录、操作日志、回滚语句均落库持久化，满足等保 2.0 对数据库操作审计的要求。

4. 集成 Binlog2SQL 与 PT-Archiver：让 Archery 具备“变更回滚”与“历史归档”双能力

Archery 的价值不止于“拦”，更在于“救”。当高危 SQL 意外执行后，能否秒级生成回滚语句？当大表需要按时间归档时，能否一键生成pt-archiver命令？这两项能力需手动集成外部工具，但配置一次，受益长久。

4.1 集成 Binlog2SQL：为 Archery 注入“后悔药”能力

Binlog2SQL 是网易开源的 binlog 解析工具，能将 MySQL binlog 转为可逆 SQL（INSERT → DELETE，UPDATE → 反向 UPDATE）。Archery 通过调用其 API 实现回滚语句生成。

步骤 1：在宿主机安装 Binlog2SQL（Archery 容器内不装，避免权限问题）

# Ubuntu/Debian sudo apt update && sudo apt install python3-pip -y sudo pip3 install binlog2sql # CentOS/RHEL sudo yum install python3-pip -y sudo pip3 install binlog2sql

步骤 2：配置 Archery 调用 Binlog2SQL 的路径与参数

编辑 Archery 配置文件（需进入容器修改）：

docker exec -it archery-web bash # 修改 /opt/archery/settings.py vi /opt/archery/settings.py

找到BINLOG2SQL_CMD配置项（若无则新增），修改为：

# settings.py 中追加 BINLOG2SQL_CMD = '/usr/local/bin/python3 /usr/local/bin/binlog2sql' # 指向宿主机上 binlog2sql 的绝对路径（pip3 install 后的位置） # 注意：Archery 容器需挂载宿主机的 binlog2sql 可执行文件或 Python 环境

关键避坑：Archery 容器默认无 Python3 环境，且binlog2sql依赖PyMySQL版本需与 Archery 一致（>=1.0.2）。推荐方案：不挂载宿主机二进制，而是在 Archery 容器内安装（修改 Dockerfile 或用 exec 安装）：

docker exec -it archery-web bash -c "pip install binlog2sql==1.4.6"

版本1.4.6兼容 MySQL 8.0 binlog 格式，且与 Archery 的 PyMySQL 无冲突。

步骤 3：在工单详情页触发回滚语句生成

1. 找到一条已执行的UPDATE工单（需确保该 SQL 真实执行过，且 binlog 未过期）
2. 点击【生成回滚语句】按钮
3. Archery 自动调用binlog2sql，解析对应 binlog position，输出反向 SQL：

   -- 原 SQL: UPDATE user SET status=1 WHERE id=1001; -- 回滚 SQL: UPDATE user SET status=0 WHERE id=1001;

   原理：Archery 通过SHOW MASTER STATUS获取当前 binlog 文件及 position，结合工单提交时间戳，定位到对应 binlog 区间，再交由binlog2sql解析。

4.2 集成 PT-Archiver：一键生成大表归档命令

pt-archiver是 Percona Toolkit 中最成熟的大表归档工具，支持按条件归档、删除、分批处理。Archery 本身不执行归档，但可生成标准化命令供 DBA 复制执行。

配置 Archery 的 PT-Archiver 模板

进入【审核配置】→【审核模板】→ 新建模板：

• 模板名称：pt-archiver-delete-by-date
• 模板内容（关键参数可变量化）：

  pt-archiver \ --source h=INSTANCE_HOST,D=DATABASE,t=TABLE,u=USER,p=PASSWORD \ --where "create_time < 'DATE'" \ --limit 1000 \ --txn-size 1000 \ --sleep 0.1 \ --progress 1000 \ --statistics \ --no-check-charset \ --bulk-delete \ --purge

• 变量说明：
  INSTANCE_HOST→ Archery 实例 IP
  DATABASE→ 目标库名
  TABLE→ 目标表名
  DATE→ 归档截止日期（格式2024-01-01）
  USER/PASSWORD→ 实例连接凭据

提交后，在 SQL 审核页面选择该模板，输入DATE=2023-01-01，即可生成完整命令。DBA 复制到终端执行，避免手写错误。

为什么不用 Archery 直接执行？
pt-archiver是重量级工具，需在数据库服务器本地运行（减少网络 IO），且涉及DELETE操作，Archery 作为 Web 平台不承担执行风险，只做“命令生成器”更安全、更符合职责分离原则。

5. 避坑指南：Archery 生产部署中 4 个高频翻车点与血泪解决方案

Archery 功能强大，但部署和配置环节存在多个“静默陷阱”，稍不注意就会导致审核失效、连接中断、甚至数据泄露。以下是我在 3 个不同规模团队中踩过的真坑，按现象→原因→解法结构整理，拒绝模糊描述。

5.1 现象：审核通过后执行 SQL 报错ERROR 1045 (28000): Access denied for user 'archery'@'%'

原因：Archery 执行 SQL 时，使用的是“审核通过时指定的数据库用户”，而非实例配置里的用户。若该用户在目标库无权限，执行必然失败。常见于 DBA 为安全起见，只给archery用户SELECT权限，但审核通过的UPDATE需要UPDATE权限。
解决：

• 进入【实例管理】→ 编辑对应实例 → 勾选【执行用户】→ 输入一个具备SELECT,INSERT,UPDATE,DELETE,ALTER,CREATE,INDEX权限的专用账号（如archery_executor）；
• 该账号权限需严格限定在业务库，禁止GRANT OPTION和SUPER；
• 权限授予语句示例：

  CREATE USER 'archery_executor'@'%' IDENTIFIED BY 'strong_pass_2024'; GRANT SELECT,INSERT,UPDATE,DELETE,ALTER,CREATE,INDEX ON `business_db`.* TO 'archery_executor'@'%'; FLUSH PRIVILEGES;

5.2 现象：full_table_scan规则始终不生效，审核报告里无“全表扫描”警告

原因：MySQL 8.0 默认关闭performance_schema的events_statements_summary_by_digest表，而 Archery 的EXPLAIN分析依赖此表获取执行计划。即使开了PROCESS权限，若该表为空，也无法解析。
解决：

• 登录 MySQL，执行：

  UPDATE performance_schema.setup_consumers SET ENABLED = 'YES' WHERE NAME = 'events_statements_summary_by_digest'; UPDATE performance_schema.setup_instruments SET ENABLED = 'YES' WHERE NAME = 'statement/sql/explain';

• 重启 MySQL 或执行FLUSH STATUS;刷新；
• 验证：SELECT * FROM performance_schema.events_statements_summary_by_digest LIMIT 1;应有返回。

5.3 现象：Docker 容器启动后 Archery Web 页面空白，F12 查看 Network 显示GET /static/js/app.js net::ERR_ABORTED 404

原因：Archery 的静态资源（JS/CSS）默认由 Nginx 服务提供，但官方镜像中 Nginx 配置未正确挂载/static路径，或collectstatic命令未执行。Docker 镜像构建时若未预编译静态文件，会导致前端资源 404。
解决：

• 进入 Archery 容器：docker exec -it archery-web bash；
• 执行静态文件收集：cd /opt/archery && python manage.py collectstatic --noinput；
• 重启容器：docker restart archery-web；
• 验证：ls -l /opt/archery/static/js/应有app.js等文件。

5.4 现象：审核通过的 SQL 执行后，Archery 工单状态卡在执行中，无后续更新

原因：Archery 执行 SQL 是异步任务，依赖 Celery + Redis。若docker-compose.yml中未配置 Redis 服务，或 Celery worker 未启动，任务将堆积在队列中永不执行。
解决：

• 在docker-compose.yml中添加 Redis 服务：

  redis: image: redis:7-alpine container_name: archery-redis restart: unless-stopped ports: - "6379:6379"

• 修改 Archery 环境变量，指向 Redis：

  environment: CELERY_BROKER_URL: "redis://redis:6379/1" CELERY_RESULT_BACKEND: "redis://redis:6379/2"

• 重启全部服务：docker-compose down && docker-compose up -d；
• 查看 Celery 日志：docker-compose logs archery | grep celery，确认celery@archery-web ready。

6. 进阶技巧：用 Archery 的 API 自动化接入 CI/CD 流水线（Jenkins/GitLab CI 实战）

Archery 提供完整的 RESTful API，这意味着你可以把它嵌入到 Jenkins Pipeline 或 GitLab CI 中，实现“代码提交 → SQL 自动审核 → 通过后自动上线”的闭环。这不是噱头，而是我们团队已在生产环境跑了一年的方案，日均拦截高危 SQL 12+ 条。

6.1 获取 API Token：安全访问的前提

Archery 的 API 需 Token 认证，且 Token 与用户绑定、可设置有效期。

1. 登录 Archery Web → 右上角头像 → 【个人设置】→ 【API Token】→ 【生成 Token】；
2. 设置 Token 名称（如jenkins-cd-token）、有效期（建议 90 天）、权限（勾选sqlworkflow和instance）；
3. 复制生成的 Token（形如a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6），立即存入 Jenkins Credentials 或 GitLab CI Variables，切勿硬编码。

6.2 Jenkins Pipeline 调用 Archery API 的完整脚本

以下是一个精简但可直接复用的 Jenkins Pipeline 示例，假设你的 SQL 文件存放在./sql/目录下：

pipeline { agent any environment { ARCHERY_URL = 'http://your-archery-host:9123' ARCHERY_TOKEN = credentials('archery-api-token') // Jenkins Credentials ID INSTANCE_NAME = 'prod-mysql-8033' } stages { stage('SQL Audit') { steps { script { // 1. 读取 SQL 文件内容 def sqlContent = readFile('./sql/deploy_v2.1.sql') // 2. 构造 API 请求体 def payload = [ "workflow_name": "CI-${BUILD_NUMBER}-deploy", "demand_url": "https://gitlab.example.com/project/merge_requests/${env.CHANGE_ID}", "group_name": "DBA", "engineer": "jenkins", "instance_name": "${INSTANCE_NAME}", "db_name": "business_db", "sql_content": sqlContent, "is_backup": "true" ] // 3. 调用 Archery API 提交审核 def response = sh( script: """curl -s -X POST '${ARCHERY_URL}/api/v1/sqlworkflow/submit/' \ -H "Authorization: Token ${ARCHERY_TOKEN}" \ -H "Content-Type: application/json" \ -d '${JsonOutput.toJson(payload)}'""", returnStdout: true ).trim() // 4. 解析响应，提取 workflow_id def json = readJSON text: response if (json.status == 0) { env.WORKFLOW_ID = json.data.workflow_id echo "SQL 审核已提交，工单ID: ${env.WORKFLOW_ID}" } else { error "Archery 审核提交失败: ${json.msg}" } } } } stage('Wait for Audit Result') { steps { script { // 轮询 Archery API 获取审核状态（最多等 5 分钟） def maxRetry = 30 def interval = 10 for (int i = 0; i < maxRetry; i++) { def statusResp = sh( script: """curl -s -X GET '${ARCHERY_URL}/api/v1/sqlworkflow/detail/?workflow_id=${env.WORKFLOW_ID}' \ -H "Authorization: Token ${ARCHERY_TOKEN}" """, returnStdout: true ).trim() def statusJson = readJSON text: statusResp if (statusJson.status == 0 && statusJson.data.status == 'workflow_reviewed') { if (statusJson.data.audit_status == '0') { echo "审核通过，准备执行" break } else { error "审核未通过: ${statusJson.data.audit_result}" } } sleep(interval) } if (i >= maxRetry) { error "等待审核超时，请登录 Archery 查看工单 ${env.WORKFLOW_ID}" } } } } stage('Execute SQL') { steps { script { // 调用执行接口（仅当审核通过后） def execResp = sh( script: """curl -s -X POST '${ARCHERY_URL}/api/v1/sqlworkflow/executesql/' \ -H "Authorization: Token ${ARCHERY_TOKEN}" \ -H "Content-Type: application/json" \ -d '{"workflow_id": "${env.WORKFLOW_ID}"}'""", returnStdout: true ).trim() def execJson = readJSON text: execResp if (execJson.status != 0) { error "SQL 执行失败: ${execJson.msg}" } echo "SQL 执行成功" } } } } }

逻辑说明：

• submit接口提交 SQL，返回workflow_id；
• detail接口轮询状态，直到status == 'workflow_reviewed'；
• audit_status == '0'表示通过（1=驳回，2=等待人工审核）；
• 最终调用executesql执行，Archery 自动调用 MySQL 执行并记录结果。

安全提醒：Jenkins 中credentials('archery-api-token')必须使用 Secret Text 类型 Credential，禁止明文写 Token。GitLab CI 同理，将 Token 存入Settings → CI/CD → Variables，Key 设为ARCHERY_TOKEN，勾选Mask variable。

6.3 一个真实收益：把 MySQL 主从复制异常排查时间从 2 小时压缩到 8 分钟

我们曾遇到一次线上事故：主库某张大表order_history的UPDATE语句在从库延迟 3 小时。传统排查需SHOW SLAVE STATUS、pt-heartbeat对比、mysqlbinlog解析，平均耗时 120 分钟。接入 Archery 后，我们做了两件事：

1. 在 Archery 中为该表配置专属规则：alter_table强制要求ALGORITHM=INSTANT（MySQL 8.0 支持），并禁用LOCK=SHARED；
2. 所有 DDL 变更必须走 Archery 审核，工单详情页自动关联pt-table-checksum校验结果。

当再次出现延迟时，DBA 直接打开 Archery → 【审核列表】→ 筛选order_history+ 时间范围 → 找到最近一条ALTER TABLE工单 → 点击【执行详情】→ 查看pt-table-checksum输出：

TS ERRORS DIFFS ROWS CHUNKS SKIPPED TIME TABLE 05-15T10:23:41 0 1 12456789 12 0 12.345 order_history

DIFFS=1表示主从数据不一致，且定位到具体 chunk。8 分钟内完成定位与修复。

这就是 Archery 的真实价值：它不替代 DBA 的专业能力，而是把重复劳动自动化，把经验沉淀为规则，把救火变成预防。我坚持每天花 10 分钟 review Archery 的审核拦截日志，就像医生看体检报告——不是为了找问题，而是为了确认防线还在。希望帮到你。

本文还有配套的精品资源，点击获取