TiDB Global Kill 功能端到端测试指南GlobalKillTest 工具的原理、部署与回归验证【免费下载链接】tidbTiDB is built for agentic workloads that grow unpredictably, with ACID guarantees and native support for transactions, analytics, and vector search. No data silos. No noisy neighbors. No infrastructure ceiling.项目地址: https://gitcode.com/GitHub_Trending/ti/tidbGlobalKillTest 是 TiDB 仓库中专门用于自动化验证 Global Kill全局 Kill特性的测试命令工具。本文以 tests/globalkilltest/README.md 为主体结合 Global Kill 设计文档、测试源码与核心实现完整讲解该工具的命令行参数、集群环境准备、七大测试场景、底层原理以及集成回归与手动单测两种用法帮助你理解并复跑这一套针对全局连接 ID 与KILL语句的测试体系。一、为什么需要 GlobalKillTestGlobal Kill 特性回顾在阅读测试工具之前有必要先理解它要验证的目标特性。传统 MySQL 协议中连接 IDconnID是 TiDB 实例本地的执行KILL x必须连到正确的实例上无法在集群层面安全地做负载均衡。为此TiDB 通过 docs/design/2020-06-01-global-kill.md 设计了全局 Kill方案核心包括三点全局连接 ID在所有 TiDB 实例间全局唯一KILL 重定向将KILL x转发到连接 x 所在的 TiDB 实例上执行32/64 位双模式 connID集群规模较小时TiDB 实例数小于 2048使用 32 位 connID 以兼容旧客户端大集群使用 64 位。connID 的 bit 0 作为标记位区分两者。32 位与 64 位 connID 的位布局来自设计文档如下32 bits: 31 21 20 1 0 -------------------------------- |serverID| local connID |markup| | (11b) | (20b) | 0 | -------------------------------- 64 bits: 63 62 41 40 1 0 ------------------------------------------------------------------- | | serverID | local connID |markup| |0| (22b) | (40b) | 1 | -------------------------------------------------------------------其中serverID由每个 TiDB 实例启动时从 PDetcd随机获取并由租约默认 12 小时保证唯一bit 63 恒为 0使 connID 落在非负 int64 范围内。在 pkg/util/globalconn/globalconn.go 中ParseConnIDglobalconn.go负责从 uint64 解析出 ServerID 与 LocalConnID 并检测 32 位截断MaxLocalConnID32 1LocalConnIDBits32 - 1、MaxLocalConnID64 1LocalConnIDBits64 - 1则定义了本地连接池容量约 2^20 与 2^40。注意设计文档中提到的KILL TIDB语法与compatible-kill-query配置项已废弃本测试工具只针对新的全局 Kill 语义。问题在于生产环境中的关键超时参数如 PD 断连判定、serverID 租约默认长达数小时不适合自动化测试。GlobalKillTest 正是为此而生——它通过编译期 ldflags 将这些变量压缩到秒级再在真实 PD TiKV 多 TiDB 节点集群上验证各种 Kill 与断连场景。二、工具总览与命令行参数GlobalKillTest 由 run-tests.sh 驱动其完整用法如下Usage: ./run-tests.sh [options] -h: Print this help message. -L info|warn|error: Log level of testing. Defaults to info. --server_log_level info|warn|error: Log level of TiDB server. Defaults to info. --tmp temporary path: Temporary files path. Defaults to /tmp/tidb_globalkilltest. -s tidb-server-path: Use tidb-server in tidb-server-path for testing. Defaults to bin/globalkilltest_tidb-server. --tidb_start_port port: First TiDB server listening port. port ~ port2 will be used. Defaults to 5000. --tidb_status_port port: First TiDB server status listening port. port ~ port2 will be used. Defaults to 8000. --pd pd-client-path: PD client path, ip:port list separated by comma. Defaults to 127.0.0.1:2379. --pd_proxy_port port: PD proxy port. PD proxy is used to simulate lost connection between TiDB and PD. Defaults to 3379. --conn_lost timeout in seconds: Lost connection to PD timeout, should be the same as TiDB ldflag ldflagLostConnectionToPDTimeout. See tidb/Makefile for detail. Defaults to 5. --conn_restored timeout in seconds: Time to check PD connection restored, should be the same as TiDB ldflag ldflagServerIDTimeToCheckPDConnectionRestored. See tidb/Makefile for detail. Defaults to 1.参数要点与源码对照这些 flag 与 global_kill_test.go 中的定义一一对应命令行参数测试内 flag默认值作用-L-Linfo测试自身日志级别--server_log_levelserver_log_levelinfo被拉起 TiDB server 的日志级别--tmptmp/tmp/tidb_globalkilltest临时文件路径日志、数据目录、mocktikv 路径等-ssbin/globalkilltest_tidb-server被测 TiDB server 二进制路径--tidb_start_porttidb_start_port5000首个 TiDB 监听端口占用 port ~ port2--tidb_status_porttidb_status_port8000首个 TiDB 状态端口占用 port ~ port2--pdpd127.0.0.1:2379PD 客户端地址逗号分隔的 ip:port 列表--conn_lostconn_lost5PD 断连超时秒须与 TiDB ldflagldflagLostConnectionToPDTimeout一致--conn_restoredconn_restored1PD 连接恢复检测周期秒须与 ldflagldflagServerIDTimeToCheckPDConnectionRestored一致关键点是后两个参数必须与编译进被测二进制中的 ldflag 取值严格一致——它们决定了断连多久后 TiDB 判定超时并杀掉连接/拒绝新连接以及恢复后多久重新接受连接测试用它精确控制时序。此外 global_kill_test.go 还定义了-ppd-server 路径默认 bin/pd-server、-ktikv-server 路径默认 bin/tikv-server两个二进制参数run-tests.sh的 help 中同样包含这两项。三、环境准备构建被测二进制与准备集群1. 构建带测试 hack 的 TiDB 二进制测试要求使用经过特殊编译的 TiDB server。执行cd tests/globalkilltest makeMakefile 通过 ldflags 注入一组覆盖默认值的变量这正是把数小时超时压缩到秒级的关键-X github.com/pingcap/tidb/pkg/domain.ldflagIsGlobalKillTest1 -X github.com/pingcap/tidb/pkg/domain.ldflagServerIDTTL10 -X github.com/pingcap/tidb/pkg/domain.ldflagServerIDTimeToKeepAlive1 -X github.com/pingcap/tidb/pkg/domain.ldflagServerIDTimeToCheckPDConnectionRestored1 -X github.com/pingcap/tidb/pkg/domain.ldflagLostConnectionToPDTimeout5 -X github.com/pingcap/tidb/pkg/store.ldflagGetEtcdAddrsFromConfig1 -X github.com/pingcap/tidb/pkg/util/globalconn.ldflagIsGlobalKillTest1 -X github.com/pingcap/tidb/pkg/util/globalconn.ldflagServerIDBits322 -X github.com/pingcap/tidb/pkg/util/globalconn.ldflagLocalConnIDBits324这些变量的生产默认值定义在 pkg/domain/domain.go如ldflagServerIDTTL 10、ldflagLostConnectionToPDTimeout 5单位为秒与 pkg/util/globalconn/globalconn.go如ldflagLocalConnIDBits32 20。测试版将其中的ldflagServerIDBits32压缩为 2 bit、ldflagLocalConnIDBits32压缩为 4 bit从而让 32 位连接池极小、极易触达上限方便在短时间内验证 32/64 位升级与降级逻辑。构建成功后输出Build TiDB Server (Global Kill Test) successfully! Setup a cluster with PD TiKV, then Run ./run-tests.sh --pdpd client path.2. 准备 PD 与 TiKV 二进制TiUP 方式测试需要一个真实集群PD TiKV可通过 TiUP 下载 nightly 二进制cd tests/globalkilltest mkdir -p bin tiup install pd:nightly tikv:nightly cp ~/.tiup/components/pd/$(ls ~/.tiup/components/pd | tail -1)/pd-server bin/ cp ~/.tiup/components/tikv/$(ls ~/.tiup/components/tikv | tail -1)/tikv-server bin/3. Docker 一键方式如果环境具备 Docker可直接运行 up.sh它会自动完成二进制下载与makecd tests/globalkilltest ./up.sh其内部逻辑为先tiup install pd:nightly tikv:nightly并拷贝到bin/然后基于 Dockerfile基于 rockylinux:9安装 Development Tools、procps-ng、mysql 客户端与 Go 1.21.13构建globalkilltest镜像最后挂载整个 TiDB 仓库到/tidb并在容器内执行make ./run-tests.sh。如需查看日志可额外挂载卷到/tmp例如-v $TIDB_PATH/tmp:/tmp。说明测试在启动 TiDB 时使用了 tikv.tomlreserve-space 1KB并分别通过 config.tomlenable-global-killtrue启用 32 位测试与 config-64.tomlenable-global-killtrue且enable-32bits-connection-idfalse强制 64 位驱动不同模式。enable-global-kill是 TiDB 的核心开关见 pkg/config/config.go默认即为trueconfig.go。四、七大测试场景GlobalKillTest 覆盖以下场景对应设计文档中 Scenario A–E 的自动化子集无 PD 的单 TiDB被 CtrlC 终止、被KILL终止带 PD 的单 TiDB被 CtrlC 终止、被KILL终止多 TiDB 节点分别通过{本地, 远程} × {Ctrl-C, KILL}组合终止连接断连 PD 后存量连接被终止长时间断连超时后断连 PD 后不再接受新连接断连 PD 后恢复新连接可被接受断连 PD 后恢复连接可被 Kill同场景 3。这些场景在 global_kill_test.go 中分别由TestWithoutPD、TestOneTiDB、TestMultipleTiDB、TestLostConnection内部覆盖场景 4–7实现每个测试又分为 32 位变体如TestWithoutPD32、TestLostConnection32与默认变体。五、工作原理SLEEP 载荷 秒级超时 hackREADME 明确了该工具的两个核心设计超时变量 hackTiDB 由 Makefile 编译时覆盖上述超时变量因为这些变量的默认值数小时对自动化测试而言太长SLEEP 探针以SELECT SLEEP(x)作为查询载荷并在 x 秒到期之前 Kill 该查询。若查询无错误且实际耗时小于 x则测试 PASSED。以场景 3 的远程 Kill 为例代码逻辑为在 tidb1 上取得连接 connID1随后在 tidb2 的连接上执行KILL QUERY connID1若远程查询在 2 秒内被终止则断言通过见 global_kill_test.go。这实际验证了从 connID 中提取 serverID → 通过CLUSTER_INFO定位目标实例 → 重定向 Kill 请求的整条链路。值得注意的是CtrlC 与 64 位 connID 的兼容性边界testKillByCtrlC通过向 mysql CLI 进程发送os.Interrupt模拟 CtrlC。在 32 位模式下断言 SLEEP 提前结束elapsed sleepTime而在 64 位模式下断言其不会提前结束global_kill_test.go因为 mysql 客户端会把 64 位 connID 截断为 32 位导致该 CtrlC 被 TiDB 忽略日志中会出现截断警告。这是设计文档64 位 connID 与旧 32 位客户端不兼容论断在测试中的直接体现。六、使用方式集成回归与手动单测集成测试回归提交后、合并前在 TiDB 仓库tests/globalkilltest目录下依次执行cd tests/globalkilltest make ./run-tests.shrun-tests.sh 会在测试前后调用clean_cluster()pkill -9清理 tidb-server / tikv-server / pd-server 残留进程然后通过go test -args $*运行全部用例保证测试环境的干净隔离。手动运行单个用例以TestMultipleTiDB为例cd tests/globalkilltest make go test -check.f TestMultipleTiDB -args --pdpd client path这里-check.f是 gocheck 框架的过滤器工具仍兼容 gocheck 风格用法也可用 Go 原生过滤如go test -test.run MultipleTiDB -args --pd127.0.0.1:2379。所有用例要求--pd指向一个已就绪的 PD 客户端地址否则会以connect PD err: ...失败并提示Establish a cluster with PD TiKV, and provide PD client path by --pdip:port[,ip:port]。七、更深一层测试基础设施与可扩展验证除了七大场景测试框架还提供了多组补充用例值得手工复跑ServerID 升级/降级TestServerIDUpgradeAndDowngrade通过 ldflags 将ldflagServerIDBits32压到 2 bit使 32 位 serverID 池容量极小。先启动 2 个 TiDB 验证 connID 为 32 位再扩容验证新实例自动升级到 64 位最后关闭部分实例验证回落到 32 位LocalConnID 升级/降级TestConnIDUpgradeAndDowngrade将ldflagLocalConnIDBits32压到 4 bit占满 32 位本地连接池后验证升级 64 位释放超过一半连接后再验证降级回 32 位对应设计文档 Scenario B/D空闲连接上的 KillTestKillQueryOnIdleConnection验证KILL QUERY只终止当前查询而连接保持存活KILL CONNECTION则彻底关闭连接。以上测试全部基于 main_test.go 的TestMain初始化并通过 util.go 中的checkPDHealth轮询/health、checkTiKVStatus轮询127.0.0.1:20180/status、checkTiDBStatus轮询statusPort/status做就绪探测超时分别设为 10s / 30s / 60s首次启动 TiDB 较慢。测试开始时还会通过 etcd client 连接 PD 获取当前成员并记录集群clusterID用于隔离数据目录。八、快速参考文件清单文件作用tests/globalkilltest/README.md工具说明本文主体tests/globalkilltest/Makefile以 ldflags 压缩超时/池大小变量的专用构建tests/globalkilltest/run-tests.sh一键回归入口自动清理残留进程tests/globalkilltest/up.shDocker 一键准备 构建 运行tests/globalkilltest/Dockerfile测试镜像rockylinux:9 Go 1.21.13 mysql 客户端tests/globalkilltest/global_kill_test.go全部测试用例与集群编排逻辑tests/globalkilltest/util.goPD / TiKV / TiDB 就绪探测tests/globalkilltest/config.toml32 位模式配置enable-global-killtruetests/globalkilltest/config-64.toml64 位模式配置额外enable-32bits-connection-idfalsedocs/design/2020-06-01-global-kill.mdGlobal Kill 特性设计文档pkg/util/globalconn/globalconn.goconnID 编解码与本地连接池实现pkg/domain/domain.goserverID 获取/租约/断连超时实现与 ldflag 默认值pkg/config/config.goenable-global-kill配置项定义九、结语GlobalKillTest 是一套小而完整的端到端测试体系它用编译期 ldflags 将不可测的长时间超时收敛到秒级以SELECT SLEEP(x)作为精确的时序探针在真实 PD TiKV 集群上覆盖了全局 Kill 的全部关键行为——本地/远程 Kill、32/64 位切换、PD 断连的容错与恢复。无论是作为 CI 集成回归、还是针对 Global Kill 行为的手动验证这套工具都能给出确定性的通过/失败结论是理解 TiDB 全局连接 ID 机制最直接的实验场。【免费下载链接】tidbTiDB is built for agentic workloads that grow unpredictably, with ACID guarantees and native support for transactions, analytics, and vector search. No data silos. No noisy neighbors. No infrastructure ceiling.项目地址: https://gitcode.com/GitHub_Trending/ti/tidb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考