企业官网建设流程全解析

TiDB 开源仓库 CI 流水线触发命令完全指南：从 PR 自动检查到手动集成测试

【免费下载链接】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 作为一个包含内核（pkg/）、备份恢复（br/）、数据导入（lightning/）与导出（dumpling/）等多个子系统的巨型 Go 仓库，其质量保障依赖一套分层明确的 CI（持续集成）流水线。本文以仓库根目录的 ci.md 为核心，系统梳理在 TiDB 开源贡献流程中如何触发各条 CI 流水线：哪些任务随 PR/推送自动执行，哪些高成本集成测试需要手动触发，以及/test ?命令的用法。读完本文，你将能够像维护者一样，通过 PR 评论区的一条命令，精准调度构建、代码检查、单元测试与各种基于真实 TiKV 的集成测试，为你的 PR 获得完整质量背书。

一、TiDB 的 CI 触发机制总览

在 TiDB 仓库中，CI 的执行入口是一个 Jenkins 流水线，其定义位于仓库根目录的 Jenkinsfile，内容极为精简：

#!groovy node { def TIDB_TEST_BRANCH = "master" def TIKV_BRANCH = "master" def PD_BRANCH = "master" fileLoader.withGit('git@github.com:pingcap/SRE.git', 'master', 'github-iamxy-ssh', '') { fileLoader.load('jenkins/ci/pingcap_tidb_branch.groovy').call(TIDB_TEST_BRANCH, TIKV_BRANCH, PD_BRANCH) } }

从源码结构看，TiDB 实际的 CI 任务定义（各 pipeline 对应的test/verify目录）保存在独立的运维仓库中，本仓库仅声明了被测代码分支与所依赖的 TiKV、PD 测试分支版本。理解这一点对贡献者很有用：CI 并非完全跑在本仓库代码内，还包括了外部tidb-test、tikv、pd等配套仓库的协作测试。

1.1 自动触发 vs 手动触发

在 PR 中直接输入/test ?，即可列出当前仓库支持的全部 CI 触发命令。整体上 CI 分为两类：

• Auto Trigger = Yes：当你提交一个 PR 或向已有 PR 推送新提交时，流水线会自动触发，无需任何操作；
• Auto Trigger = No：通常是比较耗时、需要完整分布式环境的集成测试，必须由维护者在 PR 评论区手动输入/test xxx才会运行，用于在合并前给 PR 质量加一道保险。

二、自动触发的质量门禁流水线

以下流水线在任何 PR/推送时自动执行，构成 TiDB 的第一道质量防线。

2.1/test build—— 编译产物验证

TiDB 仓库包含多个可执行组件，均通过根目录 Makefile 组织构建。本地对应的目标包括：

• make server—— 编译cmd/tidb-server得到bin/tidb-server，对应 cmd/tidb-server/main.go；
• make build_br—— 编译备份恢复工具，入口在 br/cmd/br；
• make build_lightning/make build_lightning-ctl—— 编译 TiDB Lightning 及其控制工具，入口在 lightning/cmd；
• make buildsucc—— 空目标，用于串联确认构建成功。

构建参数集中在 Makefile.common，例如通过BUILD_TAGS注入版本信息、通过LDFLAGS写入TiDBReleaseVersion、TiDBGitHash等。该流水线相当于在干净环境里对所有make目标做一次冒烟编译，防止合并的代码破坏任一组件的可构建性。

2.2/test check-dev—— 常用代码质量检查

check-dev对应本地make check/make dev所覆盖的常规静态检查，在 Makefile 中可以观察到其核心依赖链：

• lint：使用 revive 与 golangci-lint 对FILES_TIDB_TESTS（即除br/、cmd/、dumpling/之外的包）做风格与静态分析，并用tools/dashboard-linter校验pkg/metrics/grafana/下的监控面板 JSON；
• tidy：执行./tools/check/check-tidy.sh，确保go.mod与go.sum保持一致；
• check-parallel：强制 Go 测试串行执行，禁止出现t.Parallel()（见 Makefile）；
• testSuite、errdoc、license、check-bazel-prepare：分别校验TestSuite命名规范、errors.toml错误码文档、文件许可证头与 Bazel 构建文件是否同步更新。

2.3/test check-dev2—— 基于真实 TiKV 的全量测试

tests/realtikvtest是 TiDB 中需要真实 TiKV/PD 集群才能运行的测试套件集合。从目录结构看（见 tests/realtikvtest），它按功能域划分为众多子套件，例如：

• addindextest/～addindextest4/：ADD INDEX 回填相关；
• ddltest/、flashbacktest/、pessimistictest/、pipelineddmltest/；
• importintotest/～importintotest4/：IMPORT INTO 相关；
• pushdowntest/、sessiontest/、startertest/、statisticstest/、txntest/。

其启动与执行方式记录在 tests/realtikvtest/scripts/classic/README.md：脚本会拉起 3 个 PD 节点与 3 个 TiKV 服务器，占用 PD 端口2379/2380/2381/2383/2384与 TiKV 端口20160-20162/20180-20182，随后以：

./run-tests-with-gotest.sh <test_suite> [<timeout>] # 例如 ./run-tests-with-gotest.sh addindextest 60m ./run-tests.sh <make_test_task> # 例如 ./run-tests.sh bazel_addindextest

的方式执行单个套件。check-dev2本质上把上述所有 realtikv 套件一次性跑完，因此任何改动如果影响了真实 KV 存储上的事务、DDL、统计信息等路径，都会在此暴露问题。

2.4/test mysql-test与/test pull-mysql-client-test—— MySQL 兼容性测试

TiDB 的核心定位之一是高度兼容 MySQL 协议与语义。这两条流水线引用了外部测试仓库PingCAP-QE/tidb-test中的mysql_test用例集：mysql-test直接运行这些用例，而pull-mysql-client-test侧重各类 MySQL 客户端的连接行为验证。

2.5/test unit-test—— 全量单元测试

本地与 CI 单测对应的 Makefile 目标包括ut（Makefile）与gotest_in_verify_ci（Makefile）。CI 场景使用tools/bin/ut（源码见 tools/check/ut.go），它：

• 先启用 failpoint（./tools/check/failpoint-state.sh enable go）与注入测试专用LDFLAGS（如config.checkBeforeDropLDFlag=1，见 Makefile.common）；
• 支持--junitfile、--coverprofile生成 CI 报告；
• 支持--except/--only结合unstable.txt把不稳定用例单独分组，避免偶发失败阻塞主干。

从 Makefile.common 可以看出，单测默认携带deadlock,intest构建标签，意味着部分测试代码仅在测试构建中存在（intest），并在启用 deadlock 检测的条件下运行。

2.6/test pull-integration-ddl-test—— 外部 DDL 回归集

DDL 是 TiDB 正确性与稳定性要求最高的子系统之一（本仓库的 DDL 实现位于 pkg/ddl，包含 online DDL、backfill、dist reorg 等大量逻辑）。除仓库内部 pkg/ddl 与 tests/realtikvtest/ddltest 的测试外，该流水线还拉取外部tidb-test仓库的ddl_test用例，对 ALTER TABLE、索引构建等历史回归场景做交叉验证。

三、手动触发的深度集成测试流水线

以下流水线默认不自动运行，需要维护者在 PR 评论区显式输入命令，通常作为合并前的最终把关。

3.1/test pull-br-integration-test与/test pull-lightning-integration-test—— 备份恢复与数据导入

BR（Backup & Restore）与 TiDB Lightning 的集成测试分别位于 br/tests（BR 用例）与 lightning/tests（Lightning 用例）。注意 ci.md 中 Lightning 一行标注的测试目录同样是br/tests，这是仓库演进过程中 Lightning 一度内嵌于 br 目录（参见br/pkg/与 lightning/pkg 结构）留下的组织痕迹。两套测试都依赖make build_br/make build_lightning先产出二进制，再通过make br_integration_test、make lightning_integration_test等目标（见 Makefile）拉起真实集群执行端到端备份/导入/恢复验证。

3.2/test pull-common-test与/test pull-integration-common-test—— ORM 生态兼容

这两条流水线验证各类 ORM（对象关系映射框架）在 TiDB 上的兼容性，区别在于底层存储引擎：

• pull-common-test走 unistore（纯 Go 实现的嵌入式 KV，无外部依赖，运行快）；
• pull-integration-common-test走真实 TiKV，覆盖真实事务/锁语义下的行为。

当你的改动涉及事务隔离级别、连接会话行为或 DML 路径时，这两条流水线能有效发现仅在真实引擎下复现的 ORM 兼容问题。

3.3/test pull-e2e-test—— 进程级端到端测试

E2E 测试关注的是多进程/多节点场景下的行为，典型代表是 tests/globalkilltest（“Global Kill” 全局 Kill 功能验证）与tests/graceshutdown（优雅停机）。

以 tests/globalkilltest/README.md 为例，它通过重新编译 TiDB 二进制并注入更短的超时参数（--conn_lost、--conn_restored），将原本需要数小时的“PD 失联后 Kill 连接”场景压缩到可自动验证的窗口内，覆盖 Ctrl+C / KILL 语句、多 TiDB 节点、PD 断连恢复后连接可再被 Kill 等 7 类场景。运行方式：

cd tests/globalkilltest && make && ./run-tests.sh # 或单独跑某个用例： go test -check.f TestMultipleTiDB -args --pd=127.0.0.1:2379

3.4/test pull-integration-copr-test—— Coprocessor 一致性测试

TiDB 会将下推算子（如聚合、表达式计算）发送到 TiKV 的 Coprocessor 执行。为了验证“下推结果与 TiDB 本地计算结果一致”，该流水线引用 TiKV 配套的 copr-test 用例集做结果比对，是保障下推正确性的关键防线。

3.5 客户端生态流水线：pull-integration-nodejs-test/pull-integration-jdbc-test/pull-integration-mysql-test

这三条流水线专门验证驱动程序与协议栈兼容性：pull-integration-jdbc-test覆盖 Java JDBC（对数据类型、元数据、预处理语句的兼容性最敏感），pull-integration-nodejs-test覆盖 Node.js 生态，pull-integration-mysql-test则把 2.4 节的mysql_test换到真实 TiKV 上再跑一遍，用于排查仅在真实引擎下出现的协议/行为差异。

3.6/test pull-sqllogic-test—— 逻辑一致性回归

SQL logic 测试是业界经典的“用海量随机/确定性 SQL 语句比对多个数据库执行结果”的回归手段。本仓库内的对应测试框架位于 tests/integrationtest（通过make integrationtest以.test+.result文件驱动的 SQL 执行结果比对，见 Makefile），而pull-sqllogic-test则引入外部更大规模的 sqllogic 用例集，用于发现优化器改写、表达式求值等层面的语义偏差。

3.7/test pull-tiflash-test—— TiFlash 列存协同测试

当改动涉及 TiFlash 相关的 MPP 执行、列存读取或tiflash副本调度时（TiDB 侧对 TiFlash 副本的管理可参考 pkg/ddl/ddl_tiflash_api.go），需要通过该流水线启动 docker 化的 TiFlash 集群做完整协同验证。

四、全量流水线速查表

为便于日常对照，以下汇总 ci.md 中全部 19 条流水线，可直接复制使用：

五、贡献者实操建议

结合以上触发机制，给 TiDB 贡献者三条实用建议：

1. 善用自动门禁快速迭代：提交后重点观察build、check-dev、unit-test、mysql-test与check-dev2五条自动流水线。其中check-dev（lint/tidy）失败通常意味着需要本地先跑make check或make fmt；check-dev2失败则意味着改动影响了真实 TiKV 上的行为，可参照 tests/realtikvtest/scripts/classic/README.md 在本地拉起集群复现。

2. 按改动范围主动申请手动流水线：手动流水线并非每 PR 必跑，而是“按需”。如果你的改动涉及备份/恢复工具链，请维护者执行/test pull-br-integration-test；涉及导入则执行/test pull-lightning-integration-test；改动事务/会话语义时可请求/test pull-integration-common-test、/test pull-e2e-test与pull-integration-jdbc-test；改动下推逻辑则请求/test pull-integration-copr-test；涉及 SQL 语义则可请求/test pull-sqllogic-test。

3. 不确定时先查后问：所有可用命令以/test ?输出的实时列表为准——它由仓库当前配置动态生成，比任何静态文档都更权威；同时留意 Jenkinsfile 中声明的测试分支（TIDB_TEST_BRANCH、TIKV_BRANCH、PD_BRANCH），部分外部用例集与 TiDB master 存在版本耦合，属正常现象。

小结：TiDB 的 CI 体系呈“自动门禁 + 手动深测”双层结构——自动层覆盖构建、静态检查、单元测试、MySQL 兼容与真实 TiKV 基础测试，保证主干不被低级问题污染；手动层则按改动领域精准调度 BR/Lightning、ORM、Coprocessor、E2E、sqllogic、TiFlash 等高成本集成测试，为合并质量提供最终保障。对贡献者而言，掌握/test <pipeline>命令与各流水线的适用范围，是让 PR 快速通过评审、进入合并队列的必备技能。

【免费下载链接】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