Ubuntu 22.04 安装 Apache Burr 指南

Ubuntu 22.04 从零安装 Apache Burr 0.42.0 实测指南：apt 工具链、虚拟环境 pip 安装、start 扩展、demo 验证及 Web UI 服务与 API 检查，全程真实回显。

Apache BurrBurr2026/10/14

Ubuntu 22.04 安装 Apache Burr 指南

目标：在 Ubuntu 22.04 服务器上从零安装 Apache Burr 0.42.0（Apache Incubating 项目，Python 轻量工作流/状态机框架），覆盖 apt 安装 Python 3 工具链、虚拟环境创建、pip 安装 burr 与 start 扩展、状态机 demo 运行验证，以及 Web UI 服务启动与 HTTP API 端点检查。以下命令与回显均在真实环境逐步实测。

一、环境信息

Apache Burr 由 Apache Software Foundation 孵化，定位为"用简单 Python 积木构建会做决策的应用"（聊天机器人、智能体、仿真等）的轻量状态机框架。本文实测服务器环境如下：

  • 操作系统：Ubuntu 22.04.5 LTS（x86_64）
  • Python：3.10.12（二进制版本），apt 元包 python3 版本 3.10.6-1~22.04.1
  • pip：22.0.2（python3-pip 版本 22.0.2+dfsg-1ubuntu0.7）
  • curl：7.81.0
  • 软件版本：burr 0.42.0（PyPI 迁移壳包，实际安装主体为 apache-burr 0.42.0）
  • 网络环境：PyPI 拉包使用内网代理 http://192.168.1.62:7897 加速

环境基线实测回显：

cat /etc/os-release | head -2
PRETTY_NAME="Ubuntu 22.04.5 LTS"
NAME="Ubuntu"

python3 --version
Python 3.10.12

验证结果：操作系统与 Python 基线版本确认无误。

二、安装 Python 3 工具链

Ubuntu 22.04 自带 Python 3.10，但默认未安装 venv 与 pip，需通过 apt 补齐工具链。

apt-get update
apt-get install -y python3 python3-venv python3-pip curl

安装实测回显（重跑安装，关键行，apt 输出行尾的进度省略点按规范省略）：

Reading package lists
Building dependency tree
Reading state information
curl is already the newest version (7.81.0-1ubuntu1.29).
python3 is already the newest version (3.10.6-1~22.04.1).
python3-pip is already the newest version (22.0.2+dfsg-1ubuntu0.7).
python3-venv is already the newest version (3.10.6-1~22.04.1).
0 upgraded, 0 newly installed, 0 to remove and 1 not upgraded.

验证结果：python3、venv、pip、curl 均已就绪。

三、创建虚拟环境并安装 burr

为隔离系统 Python 环境，使用 venv 创建独立虚拟环境；PyPI 直连下载缓慢，统一走内网代理。

python3 -m venv /opt/burr-demo/.venv
. /opt/burr-demo/.venv/bin/activate
pip install --proxy http://192.168.1.62:7897 burr

安装过程实测回显：

Collecting burr
  Downloading burr-0.42.0-py3-none-any.whl (2.3 kB)
Collecting apache-burr==0.42.0
  Downloading apache_burr-0.42.0-py3-none-any.whl (4.7 MB)
Installing collected packages: apache-burr, burr
Successfully installed apache-burr-0.42.0 burr-0.42.0

补充说明：burr 是迁移壳包，仅 2.3 kB，指向实际主体 apache-burr 0.42.0（约 4.7 MB），其元数据声明 Requires-Python>=3.9。

版本验证回显：

pip show apache-burr | grep -E "Name|Version"
Name: apache-burr
Version: 0.42.0

验证结果：apache-burr 0.42.0 安装成功。

四、补装 start 扩展并验证 CLI

仅安装 burr 主体时 CLI 不可用，执行 burr --help 会报 Missing plugin start! 错误，因为 CLI 依赖的 click、FastAPI、Uvicorn 等由 start 扩展提供。另建纯净虚拟环境复现该报错，实测回显（报错尾部）：

  File "/tmp/venv-plain/lib/python3.10/site-packages/burr/cli/__main__.py", line 44, in <module>
    require_plugin(
  File "/tmp/venv-plain/lib/python3.10/site-packages/burr/integrations/base.py", line 20, in require_plugin
    raise ImportError(
ImportError: Missing plugin start! To use the start plugin, you must install the 'extras' target [start] with burr[start] (replace with your package manager of choice). Note that, if you're using poetry, you cannot install burr with burr[start], so you'll have to install the components individually. See https://burr.apache.org/getting_started/install/ for more details.

补装 start 扩展：

pip install --proxy http://192.168.1.62:7897 "burr[start]"

安装过程实测回显（结尾关键行）：

Successfully installed apache-burr-0.42.0 burr-0.42.0 fastapi-0.143.0 uvicorn-0.54.0 openai-3.29.0

CLI 验证回显：

burr --help
Usage: burr [OPTIONS]

Options:
  --port INTEGER        Port to run the server on
  --dev-mode            Run the server in development mode
  --no-open             Run the server without opening it
  --no-copy-demo_data   Don't copy demo data over.
  --host TEXT           Host to run the server on -- use 0.0.0.0 if you want
                        to expose it to the network
  --backend [local|s3]  Backend to use for the server.
  --help                Show this message and exit.

验证结果：补装 start 扩展后 burr CLI 正常输出帮助信息。

五、状态机 demo 运行验证

编写一个"计数器累加到 3 后转入汇总"的两动作状态机应用，验证框架核心能力。程序示例 app.py：

from burr.core import action, State, ApplicationBuilder, expr, default

@action(reads=[], writes=["count"])
def counter(state: State) -> State:
    return state.update(count=state["count"] + 1)

@action(reads=["count"], writes=["result"])
def summarize(state: State) -> State:
    return state.update(result=f"count reached {state['count']}")

app = (
    ApplicationBuilder()
    .with_actions(counter=counter, summarize=summarize)
    .with_transitions(
        ("counter", "counter", expr("count < 3")),
        ("counter", "summarize", default),
    )
    .with_state(count=0, result="")
    .with_entrypoint("counter")
    .with_tracker(project="burr-quickstart")
    .build()
)

last_action, result, state = app.run(halt_after=["summarize"])
print("stopped after action:", last_action.name)
print("result:", result)
print("final state:", state)

运行命令：

python3 app.py

实测回显：

stopped after action: summarize
result: {}
final state: {'count': 3, 'result': 'count reached 3', '__SEQUENCE_ID': 3, '__PRIOR_STEP': 'summarize'}

执行轨迹落盘结构实测回显：

ls ~/.burr/burr-quickstart/
1b853a06-13d9-44e2-83a0-55897f602302
20ba004b-ee9c-43df-b958-a7b078e9d34c

ls ~/.burr/burr-quickstart/1b853a06-13d9-44e2-83a0-55897f602302/
graph.json
log.jsonl
metadata.json

验证结果：状态机执行链路正确，tracker 将每次运行的图结构、元数据与执行日志分别落盘。

六、Web UI 服务验证

burr 主命令即 Web UI 服务入口，后台启动并指定端口与监听地址：

burr --no-open --port 7241 --host 0.0.0.0

启动日志实测回显（关键行）：

2026-10-13 16:18:20.794 | INFO     | burr.cli.__main__:_run_server:170 - Starting server on port 7241
2026-10-13 16:18:20.794 | INFO     | burr.cli.__main__:_run_server:178 - Copying demo data over to /root/.burr
2026-10-13 16:18:20.795 | INFO     | burr.cli.__main__:_command:59 - Running command: /opt/burr-demo/.venv/bin/python3 -m uvicorn burr.tracking.server.run:app --port 7241 --host 0.0.0.0
INFO:     Started server process [196]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:7241 (Press CTRL+C to quit)

HTTP 端点实测回显：

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:7241/ready
200

curl -s http://127.0.0.1:7241/api/v0/version
{"version":"0.42.0"}

首页 GET / 返回 200，页面大小为 678 字节，为 React 单页应用（含 Burr 页面标题）。项目列表接口返回 5 个项目：demo_counter、demo_chatbot、demo_conversational-rag、demo_chatbot_with_traces，以及本次 demo 产生的 burr-quickstart，实测回显（仅展示第一个条目的完整 JSON）：

[{"name":"demo_counter","id":"demo_counter","last_written":"2026-10-13T15:48:22.019192Z","created":"2026-10-13T15:52:37.170526Z","num_apps":5,"uri":"https://github.com/apache/burr/tree/main/examples/hello-world-counter"}

验证结果：Web UI 服务正常，就绪检查、版本接口、项目列表接口均返回预期数据。

七、参考链接