部署

Bub 既能在本地终端交互使用（见终端交互），也可以部署到服务器常驻运行：

常驻网关（Gateway）：7×24 小时监听 Telegram、飞书等渠道并响应消息。
云端隔离沙箱（Remote Workspace）：在独立容器内提供完整的开发工具链，并通过终端接入 bub chat 交互，保障宿主机安全。

两种主流部署方式：

方式	场景	优势
Docker Compose（推荐）	云服务器、VPS、NAS、本地容器	开箱即用，自带 Node/pnpm/Python/Git 等工具链；环境隔离，易于备份与升级
Daemon 模式	已有 Python 环境的 Linux / Windows 宿主机	资源占用低，通过 `bub gateway --install` 一键注册为系统后台服务

开始之前

部署前需完成以下准备：

模型配置：在 .env 中指定 BUB_MODEL 和 BUB_API_KEY，详见配置。
渠道凭据与白名单：接入 Telegram 等渠道时，务必配置白名单（如 BUB_TELEGRAM_ALLOW_USERS），防止未授权访问消耗 Token。
数据持久化：会话状态（Tape）、历史记录与插件保存在数据目录（宿主机 ~/.bub，容器内 /data），部署时需确保持久化存储。

Docker Compose

官方镜像（ghcr.io/bubbuild/bub）内置 Python 3.12、uv、Git、Node.js、pnpm 及常用命令行工具，宿主机只需提供配置文件与存储卷。

1. 配置环境

在部署目录中获取 docker-compose.yml 与 env.example：

mkdir -p bub-deploy && cd bub-deploy
curl -O https://raw.githubusercontent.com/bubbuild/bub/main/docker-compose.yml
curl -O https://raw.githubusercontent.com/bubbuild/bub/main/env.example
cp env.example .env

在 .env 中填入核心参数：

# 模型
BUB_MODEL=openrouter:openrouter/free
BUB_API_KEY=sk-or-...

# 渠道（以 Telegram 为例）
BUB_TELEGRAM_TOKEN=123456789:your-telegram-bot-token
BUB_TELEGRAM_ALLOW_USERS=123456789,your_telegram_username

# 宿主机数据目录与工作区（可选）
# BUB_HOME_HOST=~/.bub
# BUB_WORKSPACE_PATH=.

docker compose 会自动读取当前目录的 .env。切勿将包含 Token 的 .env 提交到公开仓库。

2. 挂载目录

默认 docker-compose.yml 包含三个卷挂载：

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

容器路径	宿主机对应路径	说明
`/workspace`	`BUB_WORKSPACE_PATH`（默认当前目录）	工作区：Agent 执行命令与读写文件的目录
`/data`	`BUB_HOME_HOST`（默认 `~/.bub`）	数据目录：保存 Tape、历史记录和托管插件（`/data/bub-project`）
`/root/.agents`	`BUB_AGENT_HOME`（默认 `~/.agents`）	全局技能：跨项目复用的 Agent 技能目录

容器内设置了 BUB_HOME=/data，容器销毁重建不会丢失会话数据与插件。

3. 启动

拉取镜像并在后台启动：

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

生产环境建议在 .env 中固定具体 Tag（如 BUB_IMAGE=ghcr.io/bubbuild/bub:0.6.0）。

从源码构建并启动：

docker compose up -d --build

不依赖 Compose 时的等价命令：

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

docker logs -f bub

4. 验证

检查容器状态与网关日志：

docker compose ps
docker compose logs -f app

Telegram 网关启动正常时会输出：

telegram.start allow_users_count=1 allow_chats_count=0 proxy_enabled=False
telegram.start polling

检查环境变量是否注入（不输出明文）：

docker compose exec app sh -c 'test -n "$BUB_TELEGRAM_TOKEN" && echo token-present'

5. 交互式 Chat

Compose 默认开启了 stdin_open 与 tty。即使容器在后台运行网关，你也可以随时进入容器开启交互式对话：

docker compose exec -it app bub chat

这让你能在云端完全隔离的沙箱环境中，直接调用预装的工具链与 Agent 结对编程。

6. 定制启动与依赖

容器启动时，entrypoint.sh 依次执行：

安装 Python 依赖：若 /workspace/bub-reqs.txt 存在，自动通过 uv pip install 安装。
同步插件：激活虚拟环境并执行 bub install，同步 /data/bub-project 中的托管插件。
执行入口：若 /workspace/startup.sh 存在，用 bash 执行它；否则执行 bub gateway。

覆盖启动命令示例

在工作区创建 startup.sh 并赋予可执行权限：

#!/bin/bash
# /workspace/startup.sh
set -euo pipefail

# 必须使用 exec 替换进程，确保系统信号正常传递给网关
exec /app/.venv/bin/bub gateway --enable-channel telegram

7. 插件管理

托管插件存放在持久卷 /data/bub-project 中，直接在容器内安装无需重建镜像：

# 安装插件
docker compose exec app bub install https://github.com/owner/repo.git@v1.2.0

# 更新插件
docker compose exec app bub update

# 重启使新插件生效
docker compose restart app

8. 备份与升级

Tape 是追加写入的 JSONL 文件。升级前建议先暂停写入并备份：

# 1. 停止写入并备份
docker compose stop app
tar -czf "bub-data-$(date +%Y%m%d-%H%M%S).tar.gz" "$HOME/.bub"
cp .env ".env.bak-$(date +%Y%m%d-%H%M%S)"

# 2. 拉取新镜像并启动
docker compose pull
docker compose up -d

若需回滚，只需在 .env 中换回旧 Tag（如 BUB_IMAGE=ghcr.io/bubbuild/bub:0.6.0）并重新启动。

Daemon 模式

在已有 Python 环境的主机上，可使用 bub gateway 内置的 --install 命令直接注册为系统后台服务：

Linux：注册为 systemd 用户级服务 ~/.config/systemd/user/bub-gateway.service。
Windows：注册为当前用户的计划任务（登录自启，失败自动重启）。
macOS：暂不支持 --install，建议使用 launchd、tmux 或上述 Docker 方案。

1. 安装服务

在包含 .env 的工作区目录下执行：

# 创建环境并安装应用
uv venv && source .venv/bin/activate
uv pip install 'bub[app]'

# 一键安装并启动后台服务
bub gateway --install

安装程序会自动记录当前 Python 解释器路径、工作区目录与环境变量。

2. 保活与管理

Linux 用户注销 SSH 后，默认会挂起用户级服务。如需保持 7×24 小时运行，需启用 linger：

loginctl enable-linger $USER

常用管理命令：

# 查看状态
systemctl --user status bub-gateway

# 实时查看日志
journalctl --user -u bub-gateway -f

# 重启与停止
systemctl --user restart bub-gateway
systemctl --user stop bub-gateway

3. 卸载服务

如需移除后台服务：

bub gateway --uninstall

安全建议

严格白名单：配置 BUB_TELEGRAM_ALLOW_USERS 或 BUB_TELEGRAM_ALLOW_CHATS，未通过验证的消息将被拒绝或静默丢弃。
最小化工作区：工作区仅挂载所需项目目录，不要让 Agent 访问包含主机密钥或系统关键路径的目录。
轮数上限：通过 BUB_MAX_STEPS 限制单次任务的最大模型步数，防范死循环与 API 额度消耗。该值默认不设上限（sys.maxsize），生产部署应显式设置，例如 50。
凭据安全：通过 .env 或环境变量注入密钥，不要将 Token 提交至版本管理。
定期备份：定期归档备份 ~/.bub（或容器 /data）目录中的 Tape 文件。