TiDB Starter txn-file Docker Compose 测试环境私有 NextGen 集群下的 SQL 提交与写冲突验证【免费下载链接】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本指南基于 TiDB 仓库中的 Starter txn-file Docker Compose 测试 README完整解析这套一次性私有 NextGen 集群测试 fixture 的拓扑设计、生命周期编排、运行方式与诊断机制。阅读本文后你将掌握如何从当前 TiDB checkout 构建镜像、拉起 PD / 三副本 TiKV / tikv-worker / MinIO / 生命周期容器组成的隔离网络并驱动两个 starter 模式 txn-file SQL 测试用例验证跨 Chunk 与 Region 的大事务提交和写冲突回滚行为同时理解其失败诊断与自动清理的工程细节。定位为什么需要一套 Docker Compose 测试环境该 fixture 位于 tests/realtikvtest/startertest/docker-compose/用于在开发者本机复现 NextGen 集群上的两个 starter 模式 txn-file SQL 测试。它的定位是替代性的本地入口README 明确说明它不替代基于二进制的 NextGen RealTiKV 工作流而是为这两类聚焦场景提供一条更轻量的启动路径。starter 模式TiDB 以 standby待命方式启动由外部激活流程将其拉入服务对应-standbytrue与激活接口的组合。txn-fileTiDB 侧通过 txn-file 机制处理大事务——当一个事务的变更量超过阈值后变更数据被切分为多个 chunk 写入外部存储此处为 S3 兼容的 MinIO提交时再经 tikv-worker 合并落盘。相关参数在 starter.toml 中可见txn-chunk-max-size 262144256 KiB、txn-file-min-mutation-size 10485761 MiB。NextGen 集群PD / TiKV 使用 API-v2 的 NextGen 镜像master-nextgen、cloud-engine-nextgen等 moving tagTiKV 侧开启api-version 2、DFS 外部存储等特性。整套环境通过 Docker Compose 编排全部服务共享一个私有网络且不发布任何宿主端口从根源上避免端口冲突与对外暴露。拓扑与生命周期十个有序阶段所有服务位于同一私有 Compose 网络每个阶段由运行脚本显式启动并逐一验证健康状态或完成状态。完整编排定义见 docker-compose.yml阶段推进逻辑见 run.sh。阶段服务验证方式1pdminiowait_healthyPD 通过/pd-ctl ... member探活MinIO 通过/minio/health/live探活2minio-initwait_completed创建并校验tidbcloud-local-dfs桶3tikv-1/tikv-2/tikv-3wait_healthyhttp://127.0.0.1:20180/status探活4本地tidb镜像compose build基于当前 checkout 构建一次5bootstrap-tidbwait_completed引导SYSTEMkeyspace 后正常退出6create-keyspacewait_completed创建并校验startertestkeyspace7tikv-workerwait_healthyhttp://127.0.0.1:19000/healthz探活8tidbstarterwait_healthy/status探活standby 模式就绪9activate-tidbwait_completed激活startertest后正常退出10test附加运行在网内执行两个选定用例关键的依赖链depends_onCompose 的depends_on条件与脚本的显式等待相互配合形成严格的启动顺序minio-init依赖minio的service_healthy见 docker-compose.yml。三个 TiKV 依赖pd、minio健康以及minio-init的service_completed_successfully——保证存储桶在 TiKV 启动前就已就绪。bootstrap-tidb依赖 PD 健康与三个 TiKV 健康。create-keyspace依赖pd健康与bootstrap-tidb的service_completed_successfully。tikv-worker依赖 PD、MinIO、minio-init以及create-keyspace完成。startertidb依赖pd健康与tikv-worker健康。activate-tidb依赖tidb健康test依赖tidb健康与activate-tidb完成。等待与完成判定机制run.sh 中的wait_healthy与wait_completed每次迭代都通过docker inspect读取真实容器状态、退出码与健康状态wait_healthy对exited/dead状态与unhealthy健康状态直接判失败wait_completed对一次性服务minio-init、bootstrap-tidb、create-keyspace、activate-tidb校验退出码是否为 0默认等待上限为300 次、每次 1 秒由COMPOSE_WAIT_ATTEMPTS控制脚本会对该变量做正整数校验run.sh开发机较慢时可调大常规运行不建议调低。前置条件README 列出的运行前提如下Docker Engine及操作 daemon 的权限Docker Compose v2 或更新版本必须通过docker compose插件调用。脚本启动时会执行docker compose version --short并解析主版本号小于 2 直接报错退出run.sh传统的docker-compose可执行文件不受支持私有仓库拉取权限PD 与 TiKV 镜像来自 PingCAP 私有 registryMinIO 服务器与客户端镜像另有来源运行前须完成认证资源容量PD、三个 TiKV、一个 worker、两个 TiDB 生命周期容器bootstrap 与 starter、MinIO、镜像编译及其卷建议至少4 CPU、12 GiB 内存、30 GiB 空闲 Docker 磁盘容量越大构建与引导越快。默认外部镜像清单以下为 docker-compose.yml 中的默认镜像组件镜像说明PDhub-zot.pingcap.net/mirrors/tidbx/tikv/pd/image:master-nextgenmoving tag未按 digest 固定TiKV / tikv-workerhub-zot.pingcap.net/mirrors/tidbx/tikv/tikv/image:cloud-engine-nextgenmoving tag未按 digest 固定MinIO 服务器hub.pingcap.net/test-infra/minio:latestsha256:d5c7b30d...按 digest 固定MinIO 客户端quay.io/minio/mc:latestsha256:a7fe349e...按 digest 固定Go 构建镜像golang:1.25.12sha256:fe5d57d3...按 digest 固定环境中的minioadmin凭据仅为本地 fixture 使用README 明确警告不得替换为真实凭据也不得对外发布该网络。值得注意docker-compose.yml 统一为各服务注入了空代理环境变量并将 Compose 服务名minio、pd、tikv-1…test加入NO_PROXY确保网内流量不经过宿主代理。运行方式基础运行从任意工作目录调用仓库路径下的 runner 即可从仓库根目录执行的确切命令为tests/realtikvtest/startertest/docker-compose/run.sh脚本会自行解析自身位置与仓库构建上下文script_dir定位脚本目录repo_root上溯到仓库根compose函数统一携带--project-name、--file与--project-directoryrun.sh。指定项目名便于人工 QA 关联未设置COMPOSE_PROJECT_NAME时脚本会生成tidb-txn-file-user-timestamp-random形式的唯一项目名用户名会做小写化与字符清洗。固定项目名便于将一次手工 QA 运行与日志关联COMPOSE_PROJECT_NAMEtidb-txn-file-e2e \ tests/realtikvtest/startertest/docker-compose/run.sh替换 TiKV/CSE 镜像需要为三个 TiKV 服务与 worker 统一指定兼容镜像时TIKV_COMPOSE_IMAGEcompatible-tikv-image \ tests/realtikvtest/startertest/docker-compose/run.sh该覆盖不影响 PD、MinIO 与本地构建的 TiDB 镜像。TiDB 与测试二进制始终来自当前 checkout——包括 Docker 构建上下文包含的已提交与未提交源码这正是该 fixture 用于本地回归验证的价值所在。镜像构建与源码元数据注入Dockerfile.test基于golang:1.25.12镜像先单独拷贝go.mod/go.sum与pkg/parser的模块文件执行go mod download以利用层缓存再拷贝整个仓库随后在构建参数校验通过后执行NEXT_GEN1 make server并go test -c -tagsintest,nextgen编译测试二进制到/opt/tidb/bin/见 Dockerfile.test。run.sh 在构建前采集SOURCE_COMMITgit rev-parse HEAD、SOURCE_BRANCH、SOURCE_RELEASE_VERSION通过NEXT_GEN1 ./build/compute-tidb-release-version.sh与git status --porcelainv1工作区状态作为--build-arg传入run_test.sh 通过伪造docker/git的测试验证了源码元数据必须在构建就绪后采集并完整传递这一约束FAKE_REQUIRE_METADATA_ORDER、FAKE_REQUIRE_SOURCE_METADATA两个场景。构建结果将 commit、工作区状态写入/opt/tidb/source-commit与/opt/tidb/source-status供后续诊断时核对所用源码。测试内容与预期证据测试容器只选择TestExternalStarterTxnFile*前缀用例启动参数见 docker-compose.yml/opt/tidb/bin/startertest.test -test.v -test.run ^TestExternalStarterTxnFile -test.count 1 -test.timeout 15m测试通过环境变量注入 DSN 与端点TIDB_STARTER_TEST_DSN/TIDB_STARTER_DSNroottcp(tidb:4000)/、TIDB_STARTER_STATUS_URLhttp://tidb:10080、TIDB_STARTER_PD_ENDPOINTpd:2379、TIDB_STARTER_TIKV_WORKER_URLtikv-worker:19000、TIDB_STARTER_KEYSPACE_NAMEstartertest等。用例一跨 Chunk 与 Region 的提交TestExternalStarterTxnFileCommitAcrossChunksAndRegions源码位于 txn_file_test.go其执行与断言链条为创建库表并SPLIT TABLE starter_txn_file.commit_case BY (1000), (2000)将表拆成三个 Region随后等待并断言3 个不同 Region测试日志打印representative_ids[1 1001 2001]。构造 24 行数据每行 value 为 48 KiBtxnFileValueSize 48 * 1024总计 payload 超过txnFileMutationLimit 1024 * 10241 MiB且按 256 KiB chunk 计算最少跨越4 个 chunkminimumChunks 4从而强制触发 txn-file 切分路径。在启用 txn-file 的会话中开启事务、插入 24 行并提交通过 status 接口读取 txn-file 计数器断言ok计数 1、err计数不变metric_delta ok1 err0。全表汇总断言count24、totalLengthpayload、exactRows24并抽查expected[0]、expected[8]、expected[16]三行 value 与内存期望完全一致。该用例证明大事务变更被切分为多个 chunk、跨三个 Region 仍能完整提交且不产生任何失败计数。用例二写冲突回滚TestExternalStarterTxnFileWriteConflictRollsBack源码位于 txn_file_conflict_test.go构建了一个乐观失败者 vs 悲观赢家的经典冲突场景先在禁用 txn-file 的会话中写入 23 行 baselinemakeTxnFileRows(d)。开启一个 txn-file 会话失败方 loser对 24 行执行 UPDATE但先不提交持有写锁与未提交的 txn-file 变更。另开一个悲观事务SET SESSION tidb_txn_modepessimistic赢家 winner对id1001写入并提交抢占该行。loser 提交时预期收到MySQL 错误 9007Write Conflicterrors.As到*mysql.MySQLError并断言Number 9007。断言 txn-file 计数器ok0 err1失败提交计入 err 增量。全表断言最终状态23 行 baseline 保持 赢家的 1 行更新 失败方写入的 24 行全部不存在losingRows 0随后执行悲观FOR UPDATE NOWAIT锁探测确认冲突后锁已被正确释放。该用例证明txn-file 事务在写冲突下整体回滚、不留半提交数据且锁资源在回滚后得到释放。输出保留策略测试客户端输出实时流式回传给调用方同时由 runner 持有的宿主临时文件mktemp -d创建的 run_tmp 下的test-output.log保留至 teardown因此即使测试容器被销毁或停止其结果也不会丢失。测试必须在 Compose 网络内运行——因为 PD 与 TiKV 对外通告的是 Compose 服务名如tikv-1:20160、pd:2379在宿主侧直接执行该测试二进制不被支持。诊断、退出状态与清理自动诊断输出任何启动、构建、激活、测试或信号失败runner 都会在 teardown 前打印带标题的诊断区块 Compose diagnostics 见 run.sh内容包括compose ps --all全量容器状态compose logs --no-color全部容器日志PD 文件日志/var/log/pd/pd.log、三个 TiKV 文件日志/var/log/tikv/tikv.log、worker 文件日志/var/log/tikv-worker/tikv-worker.logbootstrap-tidb输出与bootstrap-system.stdout.log/bootstrap-system.logstartertidb输出与/var/log/tidb/tidb.logactivate-tidb输出捕获的测试输出宿主临时文件与测试容器输出、/tmp/startertest.log。日志采集对运行中容器使用compose exec对已停止容器自动回退到docker cpprint_file_log中的两级策略。清理语义退出 trap 执行项目作用域的docker compose down -v --remove-orphans --rmi local即移除本项目容器的容器、卷、网络、孤儿资源与本地构建的 TiDB 镜像同时删除 runner 的宿主临时目录。状态优先级规则原始非零状态始终优先于清理失败清理失败仅在原本成功的前提下接管状态HUP/INT/TERM信号分别映射为退出码129 / 130 / 143走相同的诊断与清理路径清理严格限定在所选项目内绝不波及另一个 Compose 项目。常见故障速查症状检查或解决方案Compose v2 版本要求不通过安装或切换到现代docker compose插件确认docker compose version --short主版本为 2 及以上镜像拉取被拒认证 PingCAP 私有 registry并确认可访问按 digest 固定的 MinIO 镜像构建失败或使用了非预期源码检查 Docker 构建输出与保留调试镜像中的/opt/tidb/source-status正常运行的 runner 会在清理时移除本地镜像minio-init失败检查 MinIO 健康状态与桶初始化输出fixture 刻意禁用了 DFS fallbackDFS_ALLOW_FALLBACK_LOCAL: falseTiKV 或 worker 不健康查看自动诊断中的对应服务输出与文件日志确认 Docker 内存/磁盘容量与镜像兼容性SYSTEM 引导或 keyspace 创建失败检查bootstrap-tidb与create-keyspace输出SYSTEM与startertest都必须处于 ENABLED 状态且startertest必须为 keyspace 级 GC 管理starter TiDB 未激活检查tidb与activate-tidb输出确认 worker 就绪与startertestkeyspace 完全匹配测试无法连接通告的 TiKV 地址必须使用网内 runner不要添加宿主端口也不要在宿主上运行该测试二进制引导与激活的内部逻辑SYSTEM keyspace 引导bootstrap-system.shbootstrap-system.sh 以后台方式启动tidb-server参数包括-keyspace-name SYSTEM、-tidb-service-scope dxf_service、-store tikv -path pd:2379与-config /etc/tidb/starter.toml -config-strict。随后轮询http://127.0.0.1:10080/status上限 120 次一旦就绪即向 tidb-server 发送 TERM 并等待其优雅退出30 秒内未退出则升级为 KILL。元数据引导完成是create-keyspace服务的前提。Keyspace 创建与校验create-keyspace.shcreate-keyspace.sh 通过/pd-ctl完成三类校验等待 PD 就绪校验SYSTEMkeyspace 已存在且stateENABLED若startertest不存在则keyspace create startertest --config gc_management_typekeyspace_level随后校验其namestartertest、stateENABLED、gc_management_typekeyspace_level三者同时成立并重新校验 SYSTEM防止引导副作用。激活activate-tidbstartertidb以-standbytrue与-activation-timeout 120启动docker-compose.ymlactivate-tidb容器向其 status 接口发起激活请求curl -fsS --max-time 120 -X POST http://tidb:10080/tidb-pool/activate \ -H Content-Type: application/json \ -d {keyspace_name:startertest,export_id:starter-compose-export,max_idle_seconds:60,tidb_enable_ddl:true,run_auto_analyze:true}激活成功并退出后test容器才会启动。测试侧通过TIDB_STARTER_ACTIVATED_FROM_STANDBY1与TIDB_STARTER_ACTIVATE_EXPORT_IDstarter-compose-export感知由 standby 激活这一上下文。MinIO 初始化init-minio.sh 等待 MinIO 就绪后执行mc mb --ignore-existing local/tidbcloud-local-dfs创建桶再以mc stat校验桶可见。三个 TiKV 与 worker 通过DFS_*环境变量S3 端点、tidbcloud-local-dfs桶、cse前缀、http://tikv-worker:19000/compact远程压缩地址共享同一套 DFS 配置docker-compose.yml与 tikv-1.toml 中[dfs]与[kvengine]的配置一一对应。非目标Non-goalsREADME 对边界做了明确声明。该 fixture 只证明txn-file SQL 事务的成功提交确定的写冲突回滚与锁释放。它不证明也不应被用于作出以下保证DFS 孤儿数据清理orphan cleanup部分接受 chunk 的删除未决提交的恢复recovery of an undetermined commit依赖探测的共享锁 TTL 行为。这一边界声明与其定位一致它是聚焦的替代性本地入口验证面严格限定在提交成功与冲突回滚两条主路径上需要覆盖恢复与孤儿清理语义的场景应转向二进制版 NextGen RealTiKV 工作流。小结本文围绕 tests/realtikvtest/startertest/docker-compose/README.md 展开梳理了该 fixture 的完整运作方式从私有网络拓扑、十阶段生命周期编排、镜像与资源前置条件到运行入口与环境变量覆盖、两个测试用例的预期证据再到失败诊断、退出状态、自动清理与边界声明。结合 run.sh、docker-compose.yml 与两个测试用例源码 txn_file_test.go、txn_file_conflict_test.go你可以将这套环境作为本地验证 starter 模式 txn-file 提交与冲突回滚行为的可靠入口。【免费下载链接】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），仅供参考