部署

本页说明如何把 Bub 作为容器部署：构建镜像、挂载持久化状态、以及在不丢失插件项目的前提下升级。

仓库提供三份关键文件：Dockerfile、docker-compose.yml 与 entrypoint.sh。

开始之前

已安装 Docker（或兼容运行时）与 docker compose。
.env 中至少包含 BUB_MODEL 以及 BUB_API_KEY 或某个提供商专用 key —— 参见配置。
Telegram 部署还需要 .env 中包含 BUB_TELEGRAM_TOKEN 与一份白名单 —— 参见 Telegram。

1. 准备 env 文件

cp env.example .env

Telegram 网关的最小 .env：

BUB_MODEL=openrouter:openrouter/free
BUB_API_KEY=sk-or-...
BUB_TELEGRAM_TOKEN=123456:abcdef...
BUB_TELEGRAM_ALLOW_USERS=123456789

docker compose 会自动加载 .env —— 见 docker-compose.yml 中的 env_file: 行。

2. 理解卷挂载

volumes:
  - ${BUB_WORKSPACE_PATH:-.}:/workspace
  - ${BUB_HOME_HOST:-${HOME}/.bub}:/data
  - ${BUB_AGENT_HOME:-${HOME}/.agents}:/root/.agents

挂载	用途
`/workspace`	Bub 视为工作仓库的目录。默认是你执行 `docker compose` 时的目录。
`/data`	Bub home 目录的宿主机绑定（history、tapes、插件项目）。
`/root/.agents`	共享 skill 目录（沿用 `agents.md` 约定）。

Compose 文件会在容器内设置 BUB_HOME=/data。如果要把宿主机侧源路径放到 ~/.bub 以外的位置，请设置 BUB_HOME_HOST。此部署的运行时设置应放在 .env 中；BUB_HOME 不会移动 Bub 默认的 config.yml 路径。

3. 拉取并启动

docker-compose.yml 使用预构建镜像 ghcr.io/bubbuild/bub，每次发布 release 时都会推送到 GHCR：

docker compose pull
docker compose up -d
docker compose logs -f app

镜像 tag 与发布版本一致（如 0.6.0a2）；正式版还会额外打 <major>.<minor> tag，latest 指向最新的正式版。如需锁定版本，在 .env 中设置 BUB_IMAGE，例如 BUB_IMAGE=ghcr.io/bubbuild/bub:0.6.0a2。

如果要从本地源码构建，加上 --build。本地构建的镜像会以 BUB_IMAGE 为 tag，在下一次 docker compose pull 之前替代拉取的镜像：

docker compose up -d --build

本地构建需要几分钟 —— 镜像会安装系统工具（git、node、jq 等）并执行 uv sync --no-dev --no-editable。

不使用 Compose 运行

也可以直接用 docker run 运行镜像。挂载同样的卷，并显式传入 .env：

docker run -d --name bub --restart unless-stopped \
  --env-file .env \
  -e BUB_HOME=/data \
  -v "$PWD":/workspace \
  -v ~/.bub:/data \
  -v ~/.agents:/root/.agents \
  ghcr.io/bubbuild/bub:latest
docker logs -f bub

升级时先 docker pull 新 tag，再 docker rm -f bub 并重新执行上面的命令。

4. `entrypoint.sh` 做了什么

每次容器启动：

如果 /workspace/bub-reqs.txt 存在，把其中列出的包装入镜像 venv。
无参运行 bub install —— 这会同步 /data/bub-project/ 下的托管插件项目。pyproject.toml 中新增的插件在这里被拉起。
如果 /workspace/startup.sh 存在则 exec 它，否则 exec bub gateway。

也就是说工作区可以通过提供自己的 startup.sh 覆盖入口 —— 用于在长期工作区上运行 bub chat，或自定义 gateway 参数：

# /workspace/startup.sh
exec /app/.venv/bin/bub gateway --enable-channel telegram

5. 验证服务在运行

docker compose ps
docker compose logs -f app | rg "telegram.start polling"

健康的 Telegram 部署会输出一次 telegram.start polling。如果完全没有 channel 相关日志，检查 BUB_TELEGRAM_TOKEN 是否进入了容器（docker compose exec app env | rg BUB_TELEGRAM）。

6. 安全升级

滚动升级会保留 /data（宿主机 BUB_HOME_HOST，默认 ~/.bub）下的插件项目：

docker compose pull
docker compose up -d
docker compose logs -f app

如果使用本地构建，用 git pull && docker compose build --pull 代替 docker compose pull。

容器内插件由 bub install 与 bub update 管理：

docker compose exec app bub install                       # 同步项目
docker compose exec app bub install owner/repo@v1.2.0     # 新增或锁定插件
docker compose exec app bub update                        # 全量升级
docker compose exec app bub update specific-plugin        # 升级指定插件

二者都作用于 BUB_PROJECT 指定的托管项目（默认 bub.home / "bub-project"，在此 compose 部署中为 /data/bub-project），不会触碰系统 Python 环境。

后续阅读

配置 —— 环境变量优先级与提供商设置。
Telegram —— bot token 与白名单行为。
CLI 参考 —— bub gateway、bub install、bub update 的参数。