Buildbot 4.3.0 常用 CLI 命令详解

Buildbot 4.3.0 两大命令族逐命令实测详解：buildbot（create-master/checkconfig/start/stop/restart/sighup/reconfig/sendchange/upgrade-master）与 buildbot-worker（create-worker/start/restart/stop），全部命令附实测回显，含 upgrade-master 4.3.0 缺陷与 sendchange 参数坑。

BuildbotBuildbotCI/CD2026/10/20

Buildbot 4.3.0 常用 CLI 命令详解

目标：逐命令实测 Buildbot 4.3.0 的 buildbot（master 侧）与 buildbot-worker（worker 侧）两大命令族。本文所有"输入"为实际执行命令、"回显"为 2026-10-20 实测输出逐行照抄；环境搭建见 《Buildbot 4.3.0 安装与部署指南》，配置对象见 《Buildbot 4.3.0 配置参数详解》。

一、命令族总览与版本确认

1.1 版本输出（实测）

buildbot --version && buildbot-worker --version

Buildbot version: 4.3.0
Twisted version: 26.4.0
worker version: 4.3.0
Twisted version: 26.4.0

1.2 buildbot 主命令族（--help 实测全文）

Usage:    buildbot <command> [command options]
Options:
      --help     Display this help and exit.
      --verbose
      --version
Commands:
    checkconfig         test the validity of a master.cfg config file
    cleanupdb           cleanup the database
    copy-db             copy the database
    create-master       Create and populate a directory for a new buildmaster
    dataspec            Output data api spec
    dev-proxy           Run a fake web server serving the local ui frontend and
                        a distant rest and websocket api.
    reconfig            SIGHUP a buildmaster to make it re-read the config file
    restart             Restart a buildmaster
    sendchange          Send a change to the buildmaster
    sighup              SIGHUP a buildmaster to make it re-read the config file
    start               Stop a buildmaster
    stop                Stop a buildmaster
    try                 Run a build with your local changes
    tryserver           buildmaster-side 'try' support function, not for users
    upgrade-master      Upgrade an existing buildmaster directory for the
                        current version
    user                Manage users in buildbot's database

注：以上为实测回显逐行照抄（help 文本中 start 的一行描述本身如此渲染）。

1.3 buildbot-worker 命令族（--help 实测全文）

Usage:    buildbot-worker <command> [command options]
Options:
      --help     Display this help and exit.
      --verbose
      --version
Commands:
    create-worker      Create and populate a directory for a new worker
    restart            Restart a worker
    start              Start a worker
    stop               Stop a worker

二、buildbot：master 生命周期命令

2.1 create-master —— 初始化 master 目录

cd /opt/data/buildbot-demo && buildbot create-master master

mkdir /opt/data/buildbot-demo/master
creating /opt/data/buildbot-demo/master/master.cfg.sample
creating database (sqlite:///state.sqlite)
buildmaster configured in /opt/data/buildbot-demo/master

关键选项（buildbot create-master --help 实测）：-c/--config（配置文件名，默认 master.cfg）、--db（数据库连接串，默认 sqlite:///state.sqlite）、-f/--force（复用已存在目录且不覆盖 master.cfg）、-r/--relocatable（生成可迁移的 buildbot.tac）、-n/--no-logrotate（关闭内置日志轮转，交给 logrotate）、-s/--log-size 与 -l/--log-count（轮转阈值与保留个数）。

2.2 checkconfig —— 静态校验配置

cd /opt/data/buildbot-demo/master && buildbot checkconfig

通过时回显：

Config file is good!

失败时给出完整 Python traceback + Configuration Errors。4.3.0 实测捕获的六类错误原文（逐条照抄，均实际复现）：

builtins.ImportError: cannot import name 'www' from 'buildbot.plugins'
builtins.TypeError: Authz.__init__() got an unexpected keyword argument 'usernamePassword'
builtins.AttributeError: Unknown component name: StopEndpoint
builtins.TypeError: RolesFromUsername.__init__() got an unexpected keyword argument 'admins'
Configuration Errors:
  Unknown BuildmasterConfig keys logMaxTailBytes, maxBuildReportsRunning
Configuration Errors:
  Unknown BuildmasterConfig key slaves

（逐条根因与正确写法见配置篇第八节对照表。）

2.3 start —— 启动 master

cd /opt/data/buildbot-demo/master && buildbot start

首次启动实测回显（初始化数据库较慢）：

Following twistd.log until startup finished..
The buildmaster took more than 10.0 seconds to start, so we were unable to
confirm that it started correctly. Please 'tail twistd.log' and look for a line
that says 'BuildMaster is running' to verify correct startup.

按提示确认日志：

2026-10-20 15:58:27+0800 [-] BuildMaster is running

2.4 stop —— 停止 master

buildbot stop

buildbot process 1380178 is dead

stop 通过 master 目录下的 twistd.pid 定位进程；若 pid 文件存在而进程已死，按提示清理即可。

2.5 restart —— 重启 master

buildbot restart

buildbot process 1384399 is dead
now restarting buildbot process..
Following twistd.log until startup finished..
The buildmaster appears to have (re)started correctly.

实测重启后 worker 自动重连，master 日志再次出现：

2026-10-20 16:08:38+0800 [-] bot attached
2026-10-20 16:08:38+0800 [Broker,1,127.0.0.1] Worker bb-local-worker attached to demo-shell

2.6 sighup / reconfig —— 热加载配置

两者行为一致（--help 描述相同：SIGHUP a buildmaster to make it re-read the config file），实测：

buildbot sighup     # 或 buildbot reconfig

sending SIGHUP to process 1384419

master 日志（tail twistd.log）：

2026-10-20 16:18:36+0800 [-] beginning configuration update
2026-10-20 16:18:36+0800 [-] Loading configuration from '/opt/data/buildbot-demo/master/master.cfg'
2026-10-20 16:18:36+0800 [-] initializing www plugin 'waterfall_view'
2026-10-20 16:18:36+0800 [-] initializing www plugin 'console_view'
2026-10-20 16:18:36+0800 [-] initializing www plugin 'grid_view'
2026-10-20 16:18:36+0800 [-] configuration update complete (took 0.006 seconds)

命令回显：

Reconfiguration appears to have completed successfully

热加载闭环（改 c['title'] → sighup → API 回读生效）实测过程见配置篇第一节。

2.7 upgrade-master —— 升级旧 master 目录

运行中执行会被拒绝（实测，master 未停止时）：

checking basedir
checking for running master
'/opt/data/buildbot-demo/master/twistd.pid' exists - is this master still running?

停止 master 后再执行，4.3.0 实测触发包内部缺陷（回显逐行照抄）：

problem while upgrading!:
Traceback (most recent call last):
  File "/opt/data/buildbot-demo/venv/lib/python3.10/site-packages/buildbot/scripts/upgrade_master.py", line 159, in _upgradeMaster
    yield upgradeDatabase(config, master_cfg)
  File "/opt/data/buildbot-demo/venv/lib/python3.10/site-packages/twisted/internet/defer.py", line 1838, in _inlineCallbacks
    result = context.run(
  File "/opt/data/buildbot-demo/venv/lib/python3.10/site-packages/buildbot/scripts/upgrade_master.py", line 123, in upgradeDatabase
    signal.signal(signum, handler)
  File "/usr/lib/python3.10/signal.py", line 56, in signal
    handler = _signal.signal(_enum_to_int(signalnum), _enum_to_int(handler))
TypeError: signal handler must be signal.SIG_IGN, signal.SIG_DFL, or a callable object

定位（读安装源码 buildbot/scripts/upgrade_master.py）：upgradeDatabase 在 finally 中恢复旧 signal handler 时，对值为 None 的历史 handler（由 C 层注册）调用 signal.signal()，Python 拒绝 None 导致 TypeError。对本例（4.3.0 全新创建的 master）无实际影响：库版本本就是最新，无需迁移；但从 3.x 升级到 4.3.0 的环境需注意此缺陷可能中断数据库结构迁移，升级前先备份 state.sqlite 并在验证 DB schema 后重试。

2.8 sendchange —— 向 master 投递变更（触发构建）

用法（buildbot sendchange --help 实测要点）：-m master:port 指向 PB 端口；-a/--auth 认证（默认 change:changepw）；-W 作者、-c 注释、-r revision、-P 项目、-b 分支；-p/--property 是属性参数（格式必须 name:value），不是 project——实测漏冒号直接解析崩溃：

buildbot sendchange -m 127.0.0.1:8149 -W quzuo-demo -c "demo" -r demo-0001 -p demo README.md

  File "/opt/data/buildbot-demo/venv/lib/python3.10/site-packages/buildbot/scripts/runner.py", line 302, in opt_property
    name, value = property.split(':', 1)
ValueError: not enough values to unpack (expected 2, got 1)

正确执行（-P demo 为项目，末尾 README.md 是变更文件列表）：

buildbot sendchange -m 127.0.0.1:8149 -W quzuo-demo -c "first real build via sendchange" -r demo-0001 -P demo README.md

change sent successfully

随后 master 自动调度构建（added buildset 1 to database → 构建 success，完整链路见部署篇第六节）。

三、buildbot-worker：worker 命令族

3.1 create-worker —— 初始化 worker 目录

cd /opt/data/buildbot-demo && buildbot-worker create-worker worker 127.0.0.1:8149 bb-local-worker w1w2e3r4

mkdir /opt/data/buildbot-demo/worker
mkdir /opt/data/buildbot-demo/worker/info
Creating info/admin, you need to edit it appropriately.
Creating info/host, you need to edit it appropriately.
Not creating info/access_uri - add it if you wish
Please edit the files in /opt/data/buildbot-demo/worker/info appropriately.
worker configured in /opt/data/buildbot-demo/worker

参数依次为 <basedir> <master> <name> <passwd>，name/passwd 必须与 master.cfg 的 worker.Worker(...) 一致。关键选项（--help 实测）：--connection-string（Twisted endpoint 字符串，可覆盖 master 参数）、-k/--keepalive（心跳间隔，默认 600 秒）、--maxdelay（重连间隔上限，默认 300 秒）、--maxretries、--umask、--use-tls（TLS 连接）、-r/--relocatable。

实测编辑 info 描述文件（管理员在 UI 中可见）：

printf 'quzuo.net MCP Service Account\n' > worker/info/admin
printf 'Ubuntu 22.04 x86_64 / Python 3.10.12 / demo worker for docs\n' > worker/info/host

3.2 start —— 启动 worker

buildbot-worker start worker

连接成功的 worker 侧日志（worker/twistd.log 实测）：

2026-10-20 15:59:19+0800 [Broker,client] Connected to buildmaster; worker is ready
2026-10-20 15:59:19+0800 [Broker,client] sending application-level keepalives every 600 seconds

3.3 restart —— 重启 worker

buildbot-worker restart worker

Following twistd.log until startup finished..
The buildbot-worker appears to have (re)started correctly.

3.4 stop —— 停止 worker

buildbot-worker stop worker

worker process 1384486 is dead

master 侧同步记录离线（master/twistd.log 实测）：

2026-10-20 16:08:49+0800 [Broker,2,127.0.0.1] Worker.detached(bb-local-worker)
2026-10-20 16:08:49+0800 [-] Worker bb-local-worker detached from demo-shell

四、本版未实测命令一览

以下命令在 buildbot --help 中列出、本次未执行（用途取自官方 help 文本）：cleanupdb（清理数据库）、copy-db（复制数据库）、dataspec（输出 Data API 规格）、dev-proxy（本地前端代理调试服务器）、try / tryserver（开发者本地 try 构建流程）、user（管理 buildbot 数据库中的用户）。

五、参考

本系列篇目

官方文档：CLI 手册 https://docs.buildbot.net/current/manual/command-line.html