Buildbot 4.3.0 安装与部署指南

Buildbot 4.3.0 pip/venv 形态全流程实测部署指南：venv 安装 master 与 worker、create-master/checkconfig/start、master.cfg 最小可跑配置、create-worker 连接、sendchange 与 change_hook 触发真实 shell 构建并取回 stdout，含 4.x 五处配置变更排错实录。

BuildbotBuildbotCI/CD2026/10/20

Buildbot 4.3.0 安装与部署指南

目标：在 Linux 服务器上以官方主线形态（Python venv + pip 安装 master 与 worker）完整部署 Buildbot 4.3.0，并跑通第一个真实构建。本文全部命令与回显均为 2026-10-20 在实测服务器逐条执行的真实记录（输入=实际执行命令，输出=实测回显逐行照抄）；组件背景与选型见 《Buildbot 4.3.0 介绍与选型指南》。

一、实测环境

项目值
操作系统Ubuntu 22.04（内核 6.8.0-138-generic）
系统PythonPython 3.10.12（python3 --version）
部署形态venv + pip（官方文档主线，非 Docker）
Buildbot 版本buildbot / buildbot-worker 均 4.3.0，Twisted 26.4.0
实验目录/opt/data/buildbot-demo（master 与 worker 均在此下）
端口master PB 端口 8149（worker 连接用）、Web UI 8150（从空闲段取得，ss -ltn 确认未被占用；PB 默认 9989、Web 默认 8010，可按需修改）
示例账号Web UI 管理员 admin / q1w2e3r4；worker 账号 bb-local-worker / w1w2e3r4

二、创建 venv 并安装 Buildbot

2.1 创建虚拟环境

本机 Python 3.10.12 缺少 ensurepip（未安装 python3.10-venv 系统包），标准 python3 -m venv 失败。实测采用 --without-pip 创建目录后用官方 get-pip.py 引导安装，全程无需 root 之外的系统包：

python3 -m venv --without-pip /opt/data/buildbot-demo/venv
curl -sS https://bootstrap.pypa.io/get-pip.py -o /opt/data/buildbot-demo/get-pip.py
/opt/data/buildbot-demo/venv/bin/python /opt/data/buildbot-demo/get-pip.py -q
/opt/data/buildbot-demo/venv/bin/pip --version

实测回显：

pip 26.2.1 from /opt/data/buildbot-demo/venv/lib/python3.10/site-packages/pip (python 3.10)

若系统已装 python3-venv，直接 python3 -m venv /opt/data/buildbot-demo/venv 即可，无此引导步骤。

2.2 安装 master 与 worker 包

/opt/data/buildbot-demo/venv/bin/pip install buildbot buildbot-worker

安装完成后验证版本：

/opt/data/buildbot-demo/venv/bin/buildbot --version
/opt/data/buildbot-demo/venv/bin/buildbot-worker --version

实测回显：

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

2.3 补装 Web UI 包（4.x 必做，漏装启动必失败）

Buildbot 4.x 把 Web 前端与各视图拆成了独立 pip 包，pip install buildbot 只装核心。实测启动时报错并逐个补装：

/opt/data/buildbot-demo/venv/bin/pip install buildbot-www buildbot-waterfall-view buildbot-console-view buildbot-grid-view

装完后 pip list 中的 buildbot 全家桶（实测回显）：

buildbot                4.3.0
buildbot-console-view   4.3.0
buildbot-grid-view      4.3.0
buildbot-waterfall-view 4.3.0
buildbot-worker         4.3.0
buildbot-www            4.3.0

不装这些包的症状见第八节排错表：master 启动即报 could not find buildbot-www; is it installed? 或 could not find plugin waterfall_view; is it installed?。

三、创建并配置 master

3.1 create-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.tac（启动入口）、master.cfg.sample（配置样例）、state.sqlite（默认数据库）。

3.2 最小可跑 master.cfg

复制样例后覆写为最小可跑配置。以下为实测通过 checkconfig 的最终版本全文（关键点：worker 账号密码、PB 端口、调度器、Builder、Web 认证）：

# -*- python -*-
# Buildbot 4.3.0 最小可跑配置
from buildbot.plugins import changes, schedulers, steps, util, worker

c = BuildmasterConfig = {}

# 关闭匿名使用数据上报（内网环境必改项，否则启动时告警）
c['buildbotNetUsageData'] = None

# ---- 工作节点 ----
c['workers'] = [worker.Worker('bb-local-worker', 'w1w2e3r4')]

# PB 协议端口（worker 经此端口连接 master）
c['protocols'] = {'pb': {'port': 8149}}

# ---- 变更源 ----
c['change_source'] = [changes.PBChangeSource()]

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

# ---- Builder 与工厂 ----
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),
]

# ---- Web 界面 ----
c['title'] = 'Quzuo Buildbot'
c['titleURL'] = 'https://www.quzuo.net'
c['buildbotURL'] = 'http://127.0.0.1:8150/'
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},
)

# ---- 项目级杂项 ----
c['db_url'] = 'sqlite:///state.sqlite'
c['logCompressionLimit'] = 16384
c['logCompressionMethod'] = 'gz'
c['logMaxSize'] = 4 * 1024 * 1024

3.3 checkconfig 校验

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

实测回显：

Config file is good!

校验过程并非一次通过——4.x 的五处写法变更（实测均踩到，报错原文见第八节排错表）：plugins.www 已移除、Authz 不再接受 usernamePassword、StopEndpoint 更名为 StopBuildEndpointMatcher、RolesFromUsername 改为 roles=/usernames= 两个位置参数、c['slaves'] 等旧键已删除。逐项修正细节见 《Buildbot 4.3.0 配置参数详解》。

四、启动 master

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

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

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

确认端口监听（实测回显）：

ss -ltn | grep -E '8149|8150'

LISTEN 0      50                0.0.0.0:8149       0.0.0.0:*
LISTEN 0      50                0.0.0.0:8150       0.0.0.0:*

验证 Web UI（实测回显）：

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8150/
curl -s http://127.0.0.1:8150/ | grep -oE "<title>[^<]*</title>"

200
<title>Buildbot</title>

五、创建并连接 worker

5.1 create-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

名称 bb-local-worker 与密码 w1w2e3r4 必须与 master.cfg 中 worker.Worker('bb-local-worker', 'w1w2e3r4') 一致，否则连不上。

5.2 填写 worker 描述信息并启动

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
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

master 侧日志（实测回显，master/twistd.log）：

2026-10-20 15:59:19+0800 [Broker,0,127.0.0.1] worker 'bb-local-worker' attaching from IPv4Address(type='TCP', host='127.0.0.1', port=52552)
2026-10-20 15:59:19+0800 [-] bot attached
2026-10-20 15:59:19+0800 [Broker,0,127.0.0.1] Worker bb-local-worker attached to demo-shell

第三行 Worker bb-local-worker attached to demo-shell 表示 worker 已挂载到 demo-shell Builder，可接构建。

六、跑通第一个真实构建

6.1 用 sendchange 触发（PBChangeSource + AnyBranchScheduler）

cd /opt/data/buildbot-demo && 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 日志显示调度与执行全过程（实测回显，节选）：

2026-10-20 16:01:25+0800 [-] added buildset 1 to database
2026-10-20 16:01:25+0800 [-] starting build <Build demo-shell number:1 results:success> using worker <WorkerForBuilder builder='demo-shell' worker='bb-local-worker' state=AVAILABLE>
2026-10-20 16:01:25+0800 [-] starting build <Build demo-shell number:1 results:success>.. pinging the worker <WorkerForBuilder builder='demo-shell' worker='bb-local-worker' state=BUILDING>
2026-10-20 16:01:25+0800 [-] command '['bash', '-c', 'echo hello-from-buildbot; uname -sr; date +%F\\ %T; whoami']' in dir 'build'
2026-10-20 16:01:25+0800 [-]  step 'shell-demo' complete: success (None)
2026-10-20 16:01:25+0800 [-]  <Build demo-shell number:1 results:success>: build finished

6.2 构建步骤的真实 stdout

通过 REST API 取回 shell-demo 步骤 stdio 日志（实测回显，逐行照抄）：

bash -c 'echo hello-from-buildbot; uname -sr; date +%F\ %T; whoami'
 in dir /opt/data/buildbot-demo/worker/demo-shell/build (timeout 1200 secs)
 using PTY: False
hello-from-buildbot
Linux 6.8.0-138-generic
2026-10-20 16:01:25
root
program finished with exit code 0
elapsedTime=0.010496

构建 #1 结果：success（results=0）。worker 在 /opt/data/buildbot-demo/worker/demo-shell/build 目录下真实执行了 shell 命令并回传输出。

6.3 用 change_hook 再触发一次（HTTP Webhook 入口）

master.cfg 中 change_hook_dialects={'base': True} 开启了 Webhook 端点，实测：

curl -s -X POST -H "Content-Type: application/json" \
  -d '{"comments":"change-hook test","repository":"demo","project":"demo"}' \
  http://127.0.0.1:8150/change_hook/base

实测回显：

1 change found

约 5 秒后（treeStableTimer=5）触发构建 #2。用 REST API 查询全部构建（实测回显）：

curl -s "http://127.0.0.1:8150/api/v2/builds" | python3 -c "import json,sys; [print('build',b['number'],'results:',b['results']) for b in json.load(sys.stdin)['builds']]"

build 1 results: 0
build 2 results: 0

两次构建均 success，master + worker 链路完整跑通。

七、日常启停

master 与 worker 的启停、重启、热重载命令的逐参数实测（buildbot stop/restart/sighup/reconfig、buildbot-worker stop/restart 等）见 《Buildbot 4.3.0 常用 CLI 命令详解》。实测要点：

  • buildbot stop：向 twistd.pid 记录的进程发信号，回显 buildbot process 1384399 is dead；
  • buildbot restart：先停后启，回显 The buildmaster appears to have (re)started correctly.，重启后 worker 会自动重连（master 日志再次出现 bot attached）；
  • buildbot sighup / reconfig：热加载 master.cfg，回显 Reconfiguration appears to have completed successfully，日志中 configuration update complete (took 0.008 seconds)，无需停机。

八、实测排错表（4.x 五处坑，报错原文逐行照抄）

实测中按顺序踩到并修复的报错，全部真实发生，可供同类环境直接对号入座：

#触发点实测报错原文原因与修复
1checkconfigbuiltins.ImportError: cannot import name 'www' from 'buildbot.plugins'4.x 移除了 plugins.www 命名空间，认证类改从 buildbot.plugins.util 导入；from buildbot.plugins import changes, schedulers, steps, util, worker
2checkconfigbuiltins.TypeError: Authz.__init__() got an unexpected keyword argument 'usernamePassword'4.x 的 util.Authz 只接受 allowRules/roleMatchers/stringsMatcher，旧版 usernamePassword 参数已删
3checkconfigbuiltins.AttributeError: Unknown component name: StopEndpoint4.x allowRules 用 util.StopBuildEndpointMatcher / ForceBuildEndpointMatcher / RebuildBuildEndpointMatcher，旧 *Endpoint 名称已不存在
4checkconfigbuiltins.TypeError: RolesFromUsername.__init__() got an unexpected keyword argument 'admins'4.x 签名为 RolesFromUsername(roles, usernames)：写 util.RolesFromUsername(roles=['admins'], usernames=['admin'])
5checkconfigConfiguration Errors: Unknown BuildmasterConfig keys logMaxTailBytes, maxBuildReportsRunning这两个键在 4.x 已删除；另实测确认旧键 c['slaves'] 报 Unknown BuildmasterConfig key slaves，必须写 c['workers']

另有两处非致命告警/报错：

  • Title 长度告警：WARNING: Title is too long to be displayed. "Buildbot" will be used instead.——实测 c['title'] 超过 18 字符即触发（源码 max_title_len = 18），改短即可，不影响运行；
  • 缺 UI 包启动失败：启动报 builtins.RuntimeError: could not find buildbot-www; is it installed?，补装 buildbot-www 后再报 could not find plugin waterfall_view; is it installed?，需把三个视图包一并装齐（见 2.3 节）。

九、参考

本系列篇目

官方文档：安装手册 https://docs.buildbot.net/current/manual/installation/index.html