CodeProof 使用指南 —— Docker / TUI 快速上手#

Engula CodeProof 是一套 Docker 可运行的验证工具，用于在本地测试机上运行 Engula 的兼容性、客户端、性能、稳定性、迁移、平台与高可用验证，并生成可审计的 HTML 报告。

这篇官网指南只介绍 Docker 镜像 + 交互式 TUI 的使用方式。源码构建、裸机安装、命令行参数、自动化集成和远程服务器模式会放在开源项目文档中维护。

安全提示：只有当你在 TUI 中选择 client 或 platform 这类需要再次启动 Docker 容器的测试时，才需要把宿主机 Docker socket 挂入 CodeProof 容器。这样容器可以调用宿主机 Docker daemon，请只在受控测试机中使用。

目录#

1. CodeProof 是什么
2. 运行前准备
3. 拉取 Docker 镜像
4. 启动 TUI
5. TUI 界面与操作
6. 选择哪些测试
7. 查看结果与报告
8. 常见问题

1. CodeProof 是什么#

CodeProof 是 Engula 的完整验证套件。它把 Redis 官方测试集、社区客户端测试、性能基准和运维场景组织成多个 suite，每次运行都会把日志与报告写到 results/ 目录。

2. 运行前准备#

官网版使用 Docker 镜像运行，不需要在主机上安装 Go、Redis 源码、memtier_benchmark、JDK、Node.js 或 Python 依赖。镜像内已经打包了主要运行组件：

你只需要准备：

如果选择 client 或 platform，测试过程会再拉取社区镜像或平台镜像。国内主机可能因为镜像下载速度慢而等待较久。

3. 拉取 Docker 镜像#

预构建镜像使用 latest tag 发布，Docker 会根据运行主机的平台自动拉取匹配镜像，不需要手动区分 x86、Arm 或不同操作系统：

1docker pull registry.ap-southeast-1.aliyuncs.com/montplex/engula-code-proof:latest

4. 启动 TUI#

在任意工作目录执行：

1mkdir -p results
2
3docker run --rm -it \
4  -v "$(pwd)/results:/work/results" \
5  registry.ap-southeast-1.aliyuncs.com/montplex/engula-code-proof:latest \
6  proof tui

这条命令会进入交互式终端界面。运行结束后，报告会写入主机当前目录的 results/。

如果你准备在 TUI 中运行 client 或 platform，请用下面的启动方式，让 CodeProof 容器能够访问宿主机 Docker：

1mkdir -p results
2
3docker run --rm -it --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-code-proof:latest \
8  proof tui

--net host 用于让 CodeProof 容器和它启动的子容器网络互通；/var/run/docker.sock 用于让 CodeProof 容器调用宿主机 Docker daemon；/tmp:/tmp 让 client 子项（如 2.4 node-redis sentinel 测试）写入的 sentinel.conf 等临时文件能被宿主机 Docker daemon 看到。只跑 compat、perf、stability、migration、ha 时，通常不需要这三个选项。

5. TUI 界面与操作#

5.1 套件与子项选择#

启动后首先进入选择界面：

1engula-code-proof
2
3 Suite                         Sub-item
4 ┌──────────────────────┐      ┌──────────────────────────────┐
5 │▶ #1 compat      [16] │      │  All sub-items in #1 compat  │
6 │  #2 client       [4] │      │  1.1  runtest                │
7 │  #3 ha           [6] │      │  1.2  coverage               │
8 │  #4 migration    [6] │      │  1.3  protocol               │
9 │  #5 perf         [8] │      │  1.4  lua                    │
10 │  #6 platform     [4] │      │  ...                         │
11 │  #7 stability   [10] │      └──────────────────────────────┘
12 │  ★ All suites   [54] │
13 └──────────────────────┘
14
15 engula-bin: ~/.proof/bin/engula-server   results: /work/results
16 ↑↓ move  →  pick suite  ←  back  Enter  run  q  quit

常用操作：

如果停在某个 suite 上直接按 Enter，会运行该 suite 的全部子项。如果切到右侧并选中某个子项，再按 Enter，只会运行这个子项。

5.2 运行看板#

按 Enter 后进入运行看板：

1Running: #1 compat — All sub-items   elapsed 03:42
2
3 Queue (3/16)                     Current: 1.4 lua
4 ✓ 1.1 runtest        02:18 PASS
5 ✓ 1.2 coverage       00:06 PASS    █████████░░░░░░░░░░░░░░
6 ▶ 1.3 protocol       00:11 …
7   1.4 lua                         Live metrics
8   1.5 transaction                   ops/sec   —
9   ...                               vcore%    —
10                                     used_mem  —
11
12 Output
13 [10:30:01] === Compat E2E started ===
14 [10:30:02] Binary: /root/.proof/bin/engula-server
15 [10:30:08] PASS protocol_resp2_inline
16
17 c  cancel batch   l  full log   q  quit

看板分为三块：

运行期间可以按 l 查看完整日志，按 Esc 返回看板；需要取消本轮运行时按 c。

5.3 完成页#

全部子项完成后会进入完成页：

1#1 compat — DONE in 05:23
2
3 ✓  15 / 16 PASS
4
5 Press Enter to open /work/results/unknown/20260520T103000/index.html in $BROWSER.
6
7 Output
8 [10:35:00] === Summary ===
9 [10:35:00] Total: 16  Passed: 15  Failed: 1
10
11 Enter open in browser   o  re-open   b  back   q  quit

容器里通常没有配置图形浏览器，所以 Enter 不一定能直接打开页面。你可以在主机上打开 results/ 下生成的 HTML 文件。

6. 选择哪些测试#

第一次使用建议从小范围开始：

不建议第一次直接选择 All suites。完整运行耗时更长，也更依赖机器资源和网络环境。

7. 查看结果与报告#

运行结束后，主机当前目录会出现 results/：

1results/
2├── compat-1.2-coverage-logs/
3│   └── 20260520T103000/
4│       ├── main.log
5│       └── report.html
6└── unknown/
7    └── 20260520T103500/
8        ├── report.json
9        └── index.html

常用文件：

浏览器直接打开 report.html 或 index.html 即可查看结果。报告是静态 HTML，不依赖服务端。

8. 常见问题#

TUI 一启动就退出，提示需要 TTY#

请确认 docker run 中包含 -it。TUI 需要真实终端，不能在普通管道或无交互终端中运行。

运行 client 或 platform 时报 Docker daemon 连接失败#

这类测试会在 CodeProof 容器内部再启动其它容器。请使用带 Docker socket 的启动方式：

1docker run --rm -it --net host \
2  -v /var/run/docker.sock:/var/run/docker.sock \
3  -v /tmp:/tmp \
4  -v "$(pwd)/results:/work/results" \
5  registry.ap-southeast-1.aliyuncs.com/montplex/engula-code-proof:latest \
6  proof tui

client 或 platform 等待时间很长#

这些测试可能需要从 docker.io 拉取社区镜像或平台镜像。国内主机上如果镜像下载速度慢，首次运行会等待更久。建议先从 compat、perf 或 ha 这类不额外拉镜像的 suite 开始。

报告没有出现在主机目录#

确认启动时挂载了结果目录：

1-v "$(pwd)/results:/work/results"

TUI 默认结果目录是 /work/results。如果没有挂载这个目录，报告会留在容器内部，容器退出后不会保留。