部署
本页说明如何把 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 文件
Section titled “1. 准备 env 文件”cp env.example .envTelegram 网关的最小 .env：
BUB_MODEL=openrouter:openrouter/free
BUB_API_KEY=sk-or-...
BUB_TELEGRAM_TOKEN=123456:abcdef...
BUB_TELEGRAM_ALLOW_USERS=123456789docker compose 会自动加载 .env —— 见 docker-compose.yml 中的 env_file: 行。
2. 理解卷挂载
Section titled “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. 构建并启动
Section titled “3. 构建并启动”docker compose up -d --build
docker compose logs -f app首次构建需要几分钟 —— 镜像会安装系统工具（git、node、jq 等）并执行 uv sync --no-dev --no-editable。
4. entrypoint.sh 做了什么
Section titled “4. entrypoint.sh 做了什么”每次容器启动：
- 如果
/workspace/bub-reqs.txt存在，把其中列出的包装入镜像 venv。 - 无参运行
bub install—— 这会同步/data/bub-project/下的托管插件项目。pyproject.toml中新增的插件在这里被拉起。 - 如果
/workspace/startup.sh存在则 exec 它，否则 execbub gateway。
也就是说工作区可以通过提供自己的 startup.sh 覆盖入口 —— 用于在长期工作区上运行 bub chat，或自定义 gateway 参数：
# /workspace/startup.sh
exec /app/.venv/bin/bub gateway --enable-channel telegram5. 验证服务在运行
Section titled “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. 安全升级
Section titled “6. 安全升级”滚动升级会保留 /data（宿主机 BUB_HOME_HOST，默认 ~/.bub）下的插件项目：
git fetch --all --tags
git pull
docker compose build --pull
docker compose up -d
docker compose logs -f app容器内插件由 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 环境。