基于Docker部署Yearning SQL审核平台：从配置到落地的完整实践

1. 为什么你的团队需要一个SQL审核平台

先聊点实际的。你肯定遇到过这种情况：凌晨两点被电话叫醒，说线上订单表被一条UPDATE语句误刷了全表；或者代码评审的时候看了一个小时的SQL，眼睛都花了也没看出那个索引失效的问题；再或者运营提了个需求，开发直接在生产库执行了一条没走索引的大查询，把库打满了。

这些问题的根源其实不在某一个人，而是缺少一个流程控制点：SQL从编写到上生产，中间缺了一道自动化的评审关卡。人工review当然有用，但人的注意力和业务压力会导致很多细节被跳过去，特别是当一周要发布几十个变更的时候。

Yearning就是解决这个问题的。它是开源的MySQL SQL审核平台，核心能力包括：SQL语法检查、索引建议、工单审批流、执行回滚、操作审计。开发写完SQL提交工单，DBA在平台上审核，审核通过后由平台执行，整个过程留痕。相当于把原来"口头沟通+执行一把梭"的模式，变成了规范的、可追溯的流程。

这个项目我用了快两年，从2.3版本一路用过来，期间踩了不少坑，也沉淀了一些实际使用经验。这篇博文就以Docker方式部署Yearning为主线，把整个流程、配置细节、使用逻辑、常见坑都梳理一遍。不管你是在公司搭一套给团队用，还是自己学习研究，照着走都能跑起来。

需要先说清楚，Yearning目前对MySQL的支持是最成熟的。它本身也需要一个MySQL实例来存元数据，这个库和你要审核的业务库是分开的。后面讲配置文件的时候会详细说。

2. 部署前要搞清楚的几个关键点

很多人拿到一个项目就直接docker run，跑起来发现问题一堆，原因就是没搞清楚项目本身的架构和依赖。Yearning虽然启动很简单，但有几个前置概念必须先明白。

2.1 Yearning的工作模式与组件关系

Yearning本质上是一个Web应用，前端是Vue写的，后端是Go写的，编译后就是一个二进制文件加一个静态目录。它把页面、API服务、定时任务全整合在一个进程里，所以Docker部署非常轻量。

但它的运行依赖一个MySQL实例，这个实例用来存储工单、用户、权限、审计日志这些平台自身的元数据。注意，Yearning不负责存储你的业务数据，它只是通过JDBC方式连接你的业务库，在审核通过后执行SQL或者拉取表结构。

所以整个架构是这样的：

• Yearning容器：跑Web服务和定时任务
• MySQL元数据库：存平台自身数据（可以复用已有实例，也可以单独起一个）
• 业务MySQL实例：要被审核和执行的目标库

这个三层的结构决定了你在规划的时候，要先想好元数据库放哪里。如果你的公司已经有了一套MySQL运维体系，直接在已有的实例上建一个独立的database就行，没必要为Yearning单独起一个数据库容器。当然，如果是测试环境自己玩，用Docker Compose把Yearning和MySQL一起起也是可以的。

2.2 Docker镜像的选择与版本陷阱

Yearning在Docker Hub上有官方镜像，直接搜yearning就能找到。但这里有个很关键的细节：不同大版本的配置文件格式是完全不同的。

2.x版本用的是.toml配置文件，而3.x版本，配置文件改成了config.toml，但很多字段的层级和命名有变化。网上很多教程是拿旧版本写的，你照着抄在新版本上可能直接报错。

我自己现在用的是3.x版本，镜像tag用latest其实不太推荐，建议指定具体版本号，比如3.1.0。为啥？因为Yearning迭代挺快的，latest某次更新后配置格式变了，你脚本里写的映射字段可能就失效了。用固定版本，至少出了问题能在GitHub上找到对应版本的文档。

拉镜像的方式很简单：

bash复制docker pull yearning/yearning:3.1.0

如果镜像拉取慢，可以配置一下Docker的镜像加速器。不同云厂商都有提供加速地址，在/etc/docker/daemon.json里加一行registry-mirrors配置然后重启Docker服务就行。

2.3 版本升级与数据兼容性

这个必须单独说。Yearning的版本升级不是简单替换镜像就完事的，特别是跨越大的版本，比如2.x升到3.x，数据库结构有很多变更，官方提供了升级脚本，但操作顺序有点讲究。

假设你原来是用Docker方式部署的2.3.0版本，升级到3.x的时候，正确的做法是先把原容器停掉，备份元数据库，然后用新版本镜像启动容器，启动时它会自动检测数据库版本并执行迁移脚本。这个过程我建议先在测试库上跑一遍，确认数据迁移没问题再上生产，别直接在线上搞，一旦失败回滚很麻烦。

我遇到过一次比较尴尬的情况：2.3.4升3.0.0的时候，由于源数据库字符集不是utf8mb4，导致迁移过程中中文乱码，后来查了官方issue才知道，需要先把库表字符集改成utf8mb4再升级。这个坑网上很少人提，先记在这。

3. 用Docker部署Yearning的完整流程

3.1 准备MySQL元数据库

不管你用已有的MySQL还是单独起一个容器，元数据库需要提前建好。Yearning在启动时会自动建表，所以只需要给它一个空的数据库实例和账号权限就够了。

这里给出一个创建账号的SQL示例：

sql复制CREATE DATABASE yearning CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'yearning'@'%' IDENTIFIED BY 'yourpassword';
GRANT ALL PRIVILEGES ON yearning.* TO 'yearning'@'%';
FLUSH PRIVILEGES;

有一点要注意，Yearning元数据库的字符集必须用utf8mb4，不然工单里如果有中文或者特殊字符，后期查询会出问题。

3.2 准备配置文件config.toml

这是整个部署过程的核心。3.x版本的配置文件长这样：

toml复制[mysql]
host = "127.0.0.1"
port = 3306
user = "yearning"
password = "yourpassword"
db = "yearning"

[host]
port = 8000

[ldap]
enable = false
host = ""
port = 389
user = ""
password = ""
base_dn = ""
ssl = false

[message]
enable = false
type = "wechat"
key = ""
secret = ""
url = ""

[base]
secret_key = "you-can-change-this"

简单解读一下核心字段：

• [mysql]段：连接元数据库的连接串信息，这里填的是你第3.1步准备的那个库。
• [host]段：Yearning服务对外的监听端口，默认8000。
• [ldap]段：如果你公司有LDAP认证体系，可以开启；没有就用默认false。
• [message]段：消息通知，支持企业微信、钉钉、邮件等方式，工单状态变化时推送消息。先用默认关闭，后面再配。
• [base]段的secret_key：用于加密敏感数据的密钥，比如保存的业务库密码。这个一定要改，用默认值的话等于把密码的加密密钥裸奔。

配置文件准备好后，放到一个本地目录下，比如/opt/yearning/config.toml。

3.3 启动容器

先用最简单的docker run方式启动，适合快速验证：

bash复制docker run -d \
  --name yearning \
  -p 8000:8000 \
  -v /opt/yearning/config.toml:/app/config.toml \
  -v /opt/yearning/volume:/app/volume \
  yearning/yearning:3.1.0

这里做了两个目录映射：

• config.toml映射：宿主机配置文件直接挂载进容器，这样改配置不用进容器操作。
• volume目录映射：Yearning会把一些附件、备份文件、导出文件放到这个目录，映射到宿主机方便管理。

启动之后，用docker logs yearning看一下日志。正常情况下会看到服务启动成功的提示，然后浏览器访问http://服务器IP:8000就能打开登录页面。

首次访问会进入初始化界面，需要你设置管理员账号和密码。有两种初始化模式：

1. 首次安装：直接设置管理员账号密码，默认管理员的用户名是admin。
2. 对接已有LDAP：如果开启了LDAP，可以用LDAP账号登录。

初始化完成后，Yearning会有一个默认的顶级分组，你需要在这个分组下进入后台管理页面，配置各种权限参数和功能开关。

3.4 用Docker Compose管理更省心

如果是要长期使用，我建议直接用Docker Compose来管理，特别是本地测试环境，可以把元数据库也一起编排进去。下面是我常用的compose文件：

yaml复制version: '3'

services:
  mysql:
    image: mysql:8.0
    container_name: yearning-mysql
    environment:
      MYSQL_ROOT_PASSWORD: rootpass
      MYSQL_DATABASE: yearning
      MYSQL_USER: yearning
      MYSQL_PASSWORD: yearningpass
    volumes:
      - mysql-data:/var/lib/mysql
    restart: always

  yearning:
    image: yearning/yearning:3.1.0
    container_name: yearning
    depends_on:
      - mysql
    ports:
      - "8000:8000"
    volumes:
      - ./config.toml:/app/config.toml
      - yearning-volume:/app/volume
    restart: always

volumes:
  mysql-data:
  yearning-volume:

用Compose的好处是：

• 一条docker compose up -d全部搞定，测试环境反复重建很方便。
• 配置都在一个文件里，方便版本管理。
• 容器重启策略可以统一设置，挂掉后自动拉起。

测试环境玩腻了，准备正式用的时候，建议把元数据库从容器中剥离出去，用公司现有的MySQL实例，运维上会省心很多。容器化MySQL虽然方便，但数据持久化和备份还是要依赖外部机制，不用白不用。

4. 核心配置与初始化，别让平台裸奔

4.1 表结构自动创建与账号初始化

第一次启动时Yearning会在元数据库中自动建库建表，并将默认的表数据初始化进去。如果你启完容器发现数据库里只有几个空库没有表，那大概率是账号权限不够，没权限建表。检查一下你给Yearning的MySQL用户是否拥有DDL权限。

账户初始化完毕、Web页面能打开后，第一件事就是进后台管理页面，把以下几项配好：

• Token管理：用于API调用，如果你有自动化发工单的需求，这里会用到。
• 消息通知：配置企业微信机器人或者钉钉机器人，工单有更新的时候能推送到群里。
• 用户管理：建立开发、DBA等不同角色，分配对应权限。
• 分组管理：把数据库实例按业务线分组，不同组执行隔离。

这里要重点强调权限模型的逻辑。Yearning的权限体系是"分组-用户-权限"三者的关系：一个组对应一组数据库实例，用户按角色加入组，角色决定能做什么。比如开发角色能发起工单、查看自己的工单；DBA角色能审核、执行、回滚。这个模型和公司组织架构匹配起来，后续使用会很顺畅。

4.2 低权限账号的规范化配置

这是很多刚上手的人容易忽略的问题。Yearning要连接你的业务数据库执行SQL，那它就需要业务库的账号密码。但很多人图省事直接用了业务库的root账号，安全隐患非常大。

强烈建议给Yearning单独建数据库账号，权限按需分配：

sql复制-- 如果Yearning主要做DML审核执行
GRANT SELECT, INSERT, UPDATE, DELETE ON business_db.* TO 'yearning_app'@'%';
-- 如果需要做DDL变更
GRANT ALTER, CREATE, DROP, INDEX ON business_db.* TO 'yearning_app'@'%';
-- 如果需要在平台上查看表结构
GRANT SHOW VIEW, PROCESS ON *.* TO 'yearning_app'@'%';

权限范围宁小勿大，特别是生产库。Yearning平台上有多少人在用，就等于有多少人间接获得了这些凭据的操作能力，账号权限管控得严一点，出事的时候能少很多麻烦。

另外，如果业务库开启了慢查询日志和审计日志，建议把Yearning使用的账号IP段加白，这样日志审计时可以把平台执行的操作和人工操作区分开，定位问题的时候就清晰多了。

4.3 数据库实例的接入方式

在Yearning后台添加数据库实例的时候，它会要求填这些信息：

• 实例名称，组内唯一
• 数据库地址和端口
• 用于审核/执行的账号密码
• 实例类型（MySQL版本）
• 高级选项：是否允许执行DDL、是否开启查询审计等

有一个细节，Yearning连接MySQL的时候，如果MySQL版本是8.0以上，需要在数据库实例的dsn参数里加上charset=utf8mb4&parseTime=True&loc=Local，不然中文注释显示乱码、时间字段格式还会对不上。这个在实例配置的"高级选项"里可以设置。

5. 从SQL审核到上线执行的完整使用链路

部署好了，配置完了，接下来是日常使用的流程。很多人第一次用Yearning会不知道从哪里下手，我按实际使用的顺序拆解一遍。

5.1 开发提交SQL工单

开发登录Yearning后，进入工单页面发起一个"SQL上线"工单。操作流程是：

1. 选择目标实例和所属分组。
2. 填写工单标题和描述，写清楚变更目的。
3. 粘贴SQL语句。Yearning支持多条SQL一起提交，它会逐条进行语法检查和规范检查。

这里说一个实际使用的经验：建议在提交前先把SQL在测试库跑一遍，确认没有语法错误。虽然Yearning会做语法检查，但如果逻辑有问题它检查不出来，执行的时候报错，再走一遍回滚流程会浪费时间。

Yearning的检查项包括：

• 语法是否正确
• 是否命中表结构变更规范（比如无索引的ALTER TABLE）
• 是否包含高危操作（比如不带WHERE的DELETE）
• 是否可回滚（根据SQL类型生成回滚语句）

检查结果会直接展示在工单详情里，有警告、有错误，一目了然。这些都是在Yearning的SQL分析器和审核规则配置里控制的，审核规则可以根据团队规范自定义。

5.2 DBA审核与执行

工单提交后，DBA登录平台会在待审核列表中看到。审核的时候可以逐条SQL点开看：

• 执行计划预览
• 影响行数预估
• 索引建议
• 是否涉及大表

确认没问题就点击通过并执行。执行过程Yearning是逐条事务执行的，执行完会展示每条SQL的成功或失败状态。有失败的SQL可以在工单里直接查看失败原因，不会影响其他成功的SQL。

执行完成之后，工单会进入"已上线"状态，所有操作记录在审计日志里，谁在什么时间提交了什么SQL，谁审核的，谁执行的，执行结果如何，全部可查。上线的工单还支持一键回滚，Yearning会在执行前生成逆向SQL文件，存在volume目录里，出了问题可以用它来恢复。

5.3 查询工单的作用

除了SQL上线，Yearning还有一个很实用的功能：查询工单。开发想要查生产数据，不用直接连生产库，而是发起一个查询工单，指定要查询的实例和SQL，DBA审批通过后，在Yearning的查询页面执行。

这个功能的好处是：

• 查询操作留痕，方便审计。
• 可以限制返回行数，防止一次性捞几百万行。
• 可以限制是否允许SELECT *等高风险查询方式。
• 不需要把生产库连接信息分发给每一个人。

权限上还可以配合MySQL端的账号限制，比如只给SELECT权限，从源头上杜绝误操作。

5.4 自动化与API集成

如果你的团队有比较成熟的上线流水线，Yearning还提供了一套API接口，可以把SQL审核集成到CI/CD流程里。大概的流程是：

1. 构建流水线中收集SQL变更文件。
2. 调用Yearning的API创建工单，并附带SQL内容。
3. 审核通过后调用API执行工单。
4. 流水线根据执行结果决定是否继续部署。

具体的接口文档在Yearning官方GitHub仓库的Wiki里有示例，支持工单创建、状态查询、执行等接口。这部分做成自动化的门槛不高，但对流程规范化帮助很大，值得投入时间去搞。

6. 容器部署常见问题排查思路

这部分算是经验之谈，把我在Docker部署和使用Yearning过程中遇到的高频问题整理一下，按问题现象分类，给出定位思路和解决办法，你在排查的时候可以直接对照着看。

6.1 容器起了但页面打不开

先确认容器进程状态：

bash复制docker ps

如果容器状态是Exited，看日志：

bash复制docker logs years --tail 100

常见原因有这么几种：

• 端口映射冲突，宿主机的8000端口被别的进程占用了。改一下映射的宿主机端口，比如-p 8001:8000。
• 配置文件里的MySQL连接信息不对，比如host名、密码错。注意如果你是Compose方式部署并且用了容器名连接MySQL，连接信息要用mysql而不是127.0.0.1。
• 元数据库的账号权限不够，建不了表。

6.2 首页能打开但登录报错

这种情况一般是初始化没完成，或者数据库表结构有问题。排查思路：

1. 看docker logs有没有SQL执行错误的日志。
2. 检查元数据库中是否真的把表建好了：USE yearning; SHOW TABLES;。
3. 确认config.toml里的secret_key是否和初始化时一致。如果你改了secret_key，会导致已有用户密码无法解密，表现为登录时密码正确也提示错误。

6.3 SQL审核提示"连接数据库失败"

Yearning在工单提交的时候会去连接业务数据库做检查，如果提示连接失败，从这三个方向排查：

• 业务数据库的防火墙或安全组是否放行了Yearning容器所在主机的IP。
• MySQL用户是否有远程登录权限，MySQL8.0默认是只允许localhost登录的，要单独创建远程账号。
• Yearning容器访问业务库的网络是否通畅。用docker exec -it yearning mysql -h业务库IP -P3306 -u用户名 -p进去试一下，能连上说明网络没问题，连不上就检查网络和防火墙。

6.4 SQL执行后回滚失败

回滚依赖的是执行前生成的回滚SQL，但有一种情况：如果工单里既有INSERT又有UPDATE，执行过程中前一条语句成功了、后面报错了，生成的回滚文件可能就不完整。还有如果执行完成后有别的SQL又改动同一行数据，回滚时会因为数据状态变化而失败。

所以我的建议是：

• 一个工单尽量只包含同一种类型的SQL操作，不要塞一堆混合语句。
• 执行前确认回滚文件的内容是否合理，不要盲目点"执行"。
• 上线前先看影响行数，如果影响的行数超过预期，暂停执行先确认问题。

6.5 消息通知不生效

在后台配置了企业微信或者钉钉机器人，但收不到消息。最常见的原因是Webhook地址配置错了，或者机器人的关键词没设置对。企业微信机器人要求消息内容里包含特定关键词，如果Yearning推送的消息里没有设置的关键词，消息会被微信侧拦截。

解决办法是在企业微信群机器人配置里加一个固定关键词，比如"工单"，Yearning推送的内容里包含这个词就能正常收到。

7. 安全加固与数据备份，这是长期使用的底气

7.1 用Nginx反代加HTTPS

Yearning本身是HTTP服务，如果在公网或者办公网使用，建议在前面加一层Nginx做反向代理，同时启用HTTPS。这样既保证了数据传输加密，也能把Yearning的访问收敛到一个域名下，后续做统一认证也方便。

一个简单的Nginx配置示例：

nginx复制server {
    listen 443 ssl;
    server_name yearning.example.com;

    ssl_certificate     /etc/nginx/ssl/yearning.pem;
    ssl_certificate_key /etc/nginx/ssl/yearning.key;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

7.2 定期备份元数据库

元数据库里存了所有工单、审计日志、权限配置，这个库挂了等于整个平台的历史记录都没了。建议至少每天备份一次元数据库，并设置合理的保留周期。

备份命令很简单，用mysqldump：

bash复制mysqldump -h127.0.0.1 -uyearning -pyourpassword yearning > /backup/yearning_$(date +%F).sql

再配个crontab让它每天凌晨跑一次，保留最近7天的备份就够。

7.3 定期关注官方安全更新

Yearning作为一款开源的内部平台，它的安全问题不只是功能上的Bug，也可能涉及权限绕过、数据泄露这一类风险。官方GitHub仓库的Release页面和issue区可以看到版本更新和安全通告，遇到涉及安全修复的版本，建议及时评估升级。2023年前后官方修复过几起与权限校验和接口鉴权相关的问题，用户量大的平台影响面不小。

升级的时候按前面说的方法：备份元数据，拉新镜像，替换容器，观察日志，确认没有问题再切正式流量。

8. 我踩过的一些跟Docker部署相关的坑

最后分享几个实际踩过的坑，这些细节官方文档基本不会说。

8.1 容器时区问题

Yearning默认使用UTC时区，你看到的工单时间可能比本地时间慢8小时。虽然界面上的时间显示可以手动调整，但审计日志和导出的文件时间还是按照系统时间来的，排查问题的时候很别扭。解决办法是启动容器时挂载时区：

bash复制-v /etc/localtime:/etc/localtime:ro

或者在compose文件里添加：

yaml复制environment:
  - TZ=Asia/Shanghai

8.2 内存占用问题

Go写的程序按理说内存占用不高，但如果同时有大量工单并发执行或者查询任务，内存会明显上涨。我遇到过容器因为内存不足被OOM killer杀掉的情况。建议在Docker启动参数里加内存限制：

bash复制--memory=2g

同时确保宿主机有足够的swap空间。如果团队规模大、并发高，可以考虑把Yearning的容器调度到专门的机器上，别和一堆重型中间件挤在一起。

8.3 不要随便升级latest镜像

我第二次部署的时候图省事直接用了latest tag，过了一段时间镜像更新了，配置文件格式变了，容器起不来。排查了半天才发现是新版本改了配置字段。后来学乖了，所有部署都指定精确版本号，升级动作走正式的登记和验证流程。

8.4 执行大SQL导致的连接超时

在Yearning里执行一个几百万行的批量UPDATE，MySQL执行本身可能很快，但由于Yearning默认的数据库连接超时时间比较短，连接空闲超时会断掉，导致工单状态还停在"执行中"。解决办法是在Yearning的配置里调大连接超时参数，同时把业务库的wait_timeout和max_allowed_packet适当调大。具体数值根据自己的环境情况来。

9. 从部署到落地的最后一步：让团队真正用起来

平台搭好了只是第一步，真正让团队接受并且形成习惯，还需要一些软性的推动。

我的经验是，刚开始不要追求一步到位把所有功能都打开。先是只开通工单提交和审核功能，让开发和DBA先跑通流程，尝到甜头后再逐步打开查询工单、API集成这些高级功能。步子迈大了，团队成员容易抵触，反而推行不下去。

还有一个比较有效的方式是在团队内部做一次简短的培训演示，就讲两件事：第一，以后生产库变更怎么提交；第二，查询数据怎么走平台。当场操作一遍，把整个过程录屏发到团队群里，基本就没人找借口说不会用了。

Yearning这个平台本身已经在很多互联网公司内部验证过，它解决的是研发流程规范化的最后一公里问题。用Docker部署只是手段，真正值钱的是它带来的流程变化和数据沉淀。希望这篇内容能帮你少走一些弯路，省下的时间多看看业务代码。