Engula ClientCompat（客户端兼容性测试工具）#

Engula ClientCompat 是一个 Docker 可运行的客户端兼容性验证工具。它把主流 Redis 社区客户端的官方测试集打包到镜像中，用同一套测试分别验证 Redis 7.2 基线和 Engula，并生成 HTML 报告。

这篇官网指南只介绍 Docker 镜像 + 常用运行方式 + 报告解读。源码构建、客户端源码切换、长期趋势入库和 CI 深度集成等高级用法，会放在开源项目文档中维护。

安全提示：只有运行 jedis、redis-py、node-redis 这类需要再次启动辅助容器的测试时，才需要把宿主机 Docker socket 挂入测试容器。这样容器可以调用宿主机 Docker daemon，请只在受控测试机中使用。

1. 这个工具验证什么#

客户端兼容性测试回答的问题是：现有 Redis 客户端 SDK 使用 Engula 作为服务端时，连接、命令、事务、Pipeline、Pub/Sub、Stream、TLS 等常见行为是否与 Redis 7.2 基线保持一致。

当前镜像聚焦 4 个社区客户端：

如果你只想快速确认 Redis 命令与数据结构兼容性，优先使用 Engula KernelCompat。如果你要做完整交付验收，使用 Engula CodeProof。ClientCompat 位于两者之间，专门验证真实客户端生态。

2. 验证原理#

每个客户端测试都会按同一套流程运行：

1. 在容器内启动 Redis 7.2 作为基线服务。
2. 使用客户端官方测试集运行一遍，记录 Redis 基线通过情况。
3. 在相同测试环境中启动 Engula。
4. 使用同一份客户端源码和同一版本测试集再运行一遍。
5. 解析 JUnit、pytest、Ginkgo 或 Mocha 结果，按测试用例统计 Pass / Fail / Skip。
6. 生成 report.html，展示 Engula 与 Redis 基线的通过率、差异用例和日志位置。

默认判断方式是通过率对齐 Redis 基线。报告会同时列出 Redis 基线结果和 Engula 结果，方便判断差异来自 Engula 行为、客户端测试假设，还是上游测试环境。

3. 运行前准备#

官网版使用预构建 Docker 镜像运行，不需要在主机上安装 Java、Maven、Python、Go、Node.js 或客户端源码。你只需要准备：

go-redis 测试不需要挂载 Docker socket，适合作为第一次快速跑通验证。jedis、redis-py、node-redis 会启动辅助容器，因此需要额外挂载 Docker socket。

4. 拉取镜像#

1docker pull registry.ap-southeast-1.aliyuncs.com/montplex/engula-client-compat:latest

:latest 是多架构镜像，amd64 与 arm64 主机会自动拉取匹配架构。

5. 快速开始：先跑 go-redis#

go-redis 不需要额外挂载 Docker socket，命令最简单：

1mkdir -p results
2
3docker run --rm \
4  -v "$(pwd)/results:/work/results" \
5  registry.ap-southeast-1.aliyuncs.com/montplex/engula-client-compat:latest \
6  proof test client --sub 2.3 \
7    --results-dir /work/results \
8    --version engula-latest

这里的 --sub 2.3 对应 go-redis，用作最小化示例。完整客户端验证可以直接运行下一节的命令。

运行结束后，在主机当前目录的 results/ 下查看报告：

1results/
2└── client-2.3-go-redis-logs/
3    └── 20260519T100000/
4        ├── main.log
5        ├── report.json
6        └── report.html

浏览器打开 report.html 即可查看本次测试的通过率、失败用例和日志索引。

6. 运行完整客户端验证#

如果要一次运行 4 个客户端，请使用带 Docker socket 的启动方式：

1mkdir -p results
2
3docker run --rm --net host \
4  -v /var/run/docker.sock:/var/run/docker.sock \
5  -v /tmp:/tmp \
6  -v "$(pwd)/results:/work/results" \
7  registry.ap-southeast-1.aliyuncs.com/montplex/engula-client-compat:latest \
8  proof test client \
9    --results-dir /work/results \
10    --version engula-latest

这条命令会按镜像内置顺序运行 Jedis、redis-py、go-redis 和 node-redis。

作为参考，在 M2 机器上完整运行一次约 38 分钟；实际耗时会受网络、辅助镜像缓存和 Docker 资源限制影响。

参数说明：

如果你只运行 go-redis 示例，不需要 --net host、Docker socket 和 /tmp 绑定。

7. 查看结果#

完整运行后，结果目录类似：

1results/
2├── client-2.1-jedis-logs/20260519T100000/
3│   ├── main.log
4│   ├── report.json
5│   └── report.html
6├── client-2.2-redis-py-logs/20260519T100500/
7│   ├── main.log
8│   ├── report.json
9│   └── report.html
10├── client-2.3-go-redis-logs/20260519T101200/
11│   ├── main.log
12│   ├── report.json
13│   └── report.html
14├── client-2.4-node-redis-logs/20260519T102000/
15│   ├── main.log
16│   ├── report.json
17│   └── report.html
18└── engula-latest/
19    └── 20260519T103000/
20        ├── client.json
21        ├── report.json
22        └── index.html

常用文件：

报告是静态 HTML，不依赖服务端。可以直接在浏览器打开，也可以作为 PoC 或验收材料归档。

8. 如何解读报告#

每个客户端报告会展示这些核心字段：

建议重点看三类信息：

• Redis 基线是否也有失败。如果 Redis 基线失败，优先排查客户端测试环境。
• Engula 独有失败用例。它们更可能代表协议、命令语义或测试假设差异。
• 失败用例是否来自测试框架的内部假设，例如进程路径、临时目录或辅助容器启动方式。

9. 常见问题#

是否需要先手动启动 Redis 或 Engula？#

不需要。工具会自动启动并管理 Redis 与 Engula 进程，测试结束后自动清理。

为什么有些客户端需要 Docker socket？#

部分客户端官方测试集会在测试过程中启动辅助容器，例如测试集群、代理、Sentinel 或 TLS 场景。测试容器需要通过宿主机 Docker daemon 启动这些辅助容器，因此要挂载 /var/run/docker.sock。

为什么要挂载 /tmp:/tmp？#

部分测试会在 /tmp 下生成临时配置，再把这些配置挂给辅助容器。挂载 /tmp:/tmp 可以保证测试容器和宿主机 Docker daemon 看到同一条临时路径。

第一次运行很慢怎么办？#

首次运行可能需要拉取辅助测试镜像。建议先确认宿主机 Docker 可以正常拉取镜像，再运行完整客户端验证。只想快速确认工具链是否可用时，可以先跑 go-redis 示例。

这个工具和 CodeProof 是什么关系？#

Engula CodeProof 是完整验证套件，覆盖兼容性、客户端、性能、稳定性、迁移、平台与高可用。ClientCompat 只保留其中的客户端验证能力，镜像和文档都更聚焦，适合单独验证客户端生态。