Buildbot 4.3.0 配置参数详解

目标：逐项讲清 Buildbot 4.3.0 的 master.cfg 核心配置对象，每个参数都经 2026-10-20 实测：改动 → buildbot checkconfig 校验 → buildbot sighup 热加载 → Web API 回读验证。实验环境与部署过程见 《Buildbot 4.3.0 安装与部署指南》；命令行详见 《Buildbot 4.3.0 常用 CLI 命令详解》。

一、配置加载机制与验证方法

master.cfg 是纯 Python 程序，由 master 在启动与热加载时执行（源码 buildbot/config/master.py 中经 execfile 执行），最终必须产生名为 BuildmasterConfig 的字典。验证链条实测如下：

热更新闭环实测（2026-10-20）：把 c['title'] 从 Quzuo Buildbot 改为 Quzuo Buildbot CI（17 字符，未超限）→ checkconfig 通过 → sighup → 回读验证：

curl -s http://127.0.0.1:8150/config | python3 -c "import json,sys; d=json.load(sys.stdin); print('title:',d.get('title'))"

title: Quzuo Buildbot CI

首页 HTML 同步含 Quzuo Buildbot CI，证明 www 段改动经 sighup 即时生效、无需重启。

二、BuildmasterConfig 全局键逐项

以下全部键均在实测环境验证通过（标"实测"者为有正向验证动作的项）：

2.1 必设键

2.2 常用可选键（实测全部通过 checkconfig）

2.3 已删除键（实测报错原文）

追加以下两个 3.x 时代键后，checkconfig 实测报错：

Configuration Errors:
  Unknown BuildmasterConfig keys logMaxTailBytes, maxBuildReportsRunning

结论：4.3.0 对未知键是硬错误（非告警），从旧版升级必须清理。upgrade-master 迁移说明见 CLI 篇。

三、Worker 对象

from buildbot.plugins import worker
c['workers'] = [worker.Worker('bb-local-worker', 'w1w2e3r4')]

• 第一个参数是 worker 名，第二个是密码，必须与 worker 侧 buildbot-worker create-worker <dir> <master> <name> <passwd> 完全一致，实测不一致时 worker 连接被拒并提示 botname or password 错误。
• 实测连接成功链路：master 日志 worker 'bb-local-worker' attaching from IPv4Address(...) → bot attached → Worker bb-local-worker attached to demo-shell。
• 常用扩展参数：max_builds（最大并发构建设置）、properties（注入属性）、locks；弹性 worker 为独立类（worker.EC2LatentWorker、worker.DockerLatentWorker、worker.KubernetesLatentWorker 等，官方文档列出，未在本次实测范围）。

四、ChangeSource 变更源

实测启用的是 PB 变更源 + HTTP Webhook 两条入口：

from buildbot.plugins import changes
c['change_source'] = [changes.PBChangeSource()]

• PBChangeSource（实测）：开放 PB 端口上的 change 通道，buildbot sendchange -m 127.0.0.1:8149 ... 实测回显 change sent successfully，master 日志 added buildset 1 to database。
• change_hook（实测）：在 c['www']['change_hook_dialects'] 配置 {'base': True} 后，POST /change_hook/base 即接收 Webhook。实测回显 1 change found（HTTP 200），随后自动触发构建 #2。
• 其他官方变更源（官方文档列出，未逐一实测）：changes.GitPoller、changes.SVNPoller、changes.HgPoller、changes.GitHubPullrequestPoller 等，均为"轮询仓库转 Change"模型。

五、Scheduler 调度器

实测配置了两个调度器：

c['schedulers'] = [
    schedulers.AnyBranchScheduler(name='demo-any', treeStableTimer=5,
                                  builderNames=['demo-shell']),
    schedulers.ForceScheduler(name='force', builderNames=['demo-shell']),
]

调度器通用要点（实测验证）：改名重建即视为新调度器（热加载日志 adding 2 new schedulers, removing 0）；builderNames 必须指向已定义的 Builder，否则 checkconfig 报错。

六、Builder 与 BuildFactory/Step

factory = util.BuildFactory()
factory.addStep(steps.ShellCommand(
    name='shell-demo',
    description='running shell demo',
    command=['bash', '-c',
             'echo hello-from-buildbot; uname -sr; date +%F\\ %T; whoami'],
))
c['builders'] = [
    util.BuilderConfig(name='demo-shell',
                       workernames=['bb-local-worker'],
                       factory=factory),
]

实测验证点：

• BuilderConfig.name 是构建名，workernames 必须来自 c['workers'] 中的名字；实测 worker 挂载日志直接打印了这两者的绑定关系（Worker bb-local-worker attached to demo-shell）。
• steps.ShellCommand 的 command 支持列表形式；实测构建在 worker 的 worker/demo-shell/build 目录执行，stdout 逐行回传（hello-from-buildbot / Linux 6.8.0-138-generic / 2026-10-20 16:01:25 / root / program finished with exit code 0），完整实录见部署篇第六节。
• 同一 Builder 可配置多台 worker（workernames 列表多个成员）实现分摊；factory.addStep 顺序即执行顺序，Step 返回码决定成败与是否继续（官方文档 results 语义）。

七、www 段（端口/插件/Webhook/认证授权）

c['www'] = dict(
    port=8150,
    change_hook_dialects={'base': True},
    auth=util.UserPasswordAuth({'admin': 'q1w2e3r4'}),
    authz=util.Authz(
        allowRules=[
            util.StopBuildEndpointMatcher(role='admins'),
            util.ForceBuildEndpointMatcher(role='admins'),
            util.RebuildBuildEndpointMatcher(role='admins'),
        ],
        roleMatchers=[
            util.RolesFromUsername(roles=['admins'], usernames=['admin']),
        ],
    ),
    plugins={'waterfall_view': True, 'console_view': True, 'grid_view': True},
)

逐项实测结论：

八、常见配置错误对照表（实测报错原文速查）

九、参考

本系列篇目

• 《Buildbot 4.3.0 介绍与选型指南》
• 《Buildbot 4.3.0 安装与部署指南》
• 《Buildbot 4.3.0 常用 CLI 命令详解》

官方文档：配置手册 https://docs.buildbot.net/current/manual/configuration/index.html