Buzz 自托管教程：为 Codex、Claude Code 与团队搭建私有 Agent 工作区

Buzz 是 Block 开源的协作工作区。它把人、AI Agent、代码仓库、补丁、审批、工作流、频道和语音协作放进同一套系统，并用 Nostr 签名事件记录操作。它不是一个简单的“多人聊天前端”。在 Buzz 中，Agent 拥有自己的身份和频道成员关系，可以搜索历史、打开仓库、发送补丁、参与 Review 和运行工作流。自托管的意义在于团队控制 Relay、数据存储、域名和审计记录。本文聚焦远程 VPS 部署。Buzz 仍处在快速开发期，仓库结构、环境变量和 Compose 文件可能变化，因此本文把可以稳定复用的部署判断与官方命令分开：具体变量始终以你所使用版本的 .env.example 和部署文档为准。

Buzz 的数据流先看懂再部署

浏览器或桌面客户端不会直接把所有状态保存在本地。一个典型自托管实例包含：

Buzz Web、桌面或移动客户端；
处理签名事件的 Nostr Relay；
保存结构化状态的 PostgreSQL；
提供缓存和队列能力的 Redis；
保存附件的 S3 兼容对象存储；
对公网提供 HTTPS 的 Caddy 或其他反向代理。官方当前的单 Relay 结构中，一个 Relay URL 对应一个社区。即使运营方在共享基础设施上托管多个社区，用户访问的 URL 仍是工作区边界。每条消息、反应、工作流步骤、Review 审批和 Git 事件都是签名事件。备份数据库而不备份对象存储，会丢附件；只备份附件而忽略身份和数据库，也无法完整恢复工作区。

选择机器和域名

测试环境可以从 4 核、8 GB 内存、80 GB SSD 起步。实际需求取决于并发人数、Agent 数量、仓库大小、附件和语音使用量。生产环境至少准备：

一台受支持的 Linux VPS；
一个独立子域名，例如 buzz.example.com；
80、443 端口可用；
Docker Engine 与 Compose 插件；
可做快照或异地备份的存储；
SMTP、对象存储等项目实际要求的外部服务。不要直接把 Relay、PostgreSQL、Redis 和 MinIO 的管理端口暴露到公网。公网入口应只有 HTTPS，SSH 则限制来源地址或通过 VPN 访问。 DNS 先创建 A/AAAA 记录指向 VPS。若使用 Cloudflare 代理，初次签发证书和调试 WebSocket 时可以暂时设为“仅 DNS”，确认服务正常后再启用代理。

安装 Docker

以下以 Ubuntu/Debian 为例，生产环境应优先使用 Docker 官方仓库，而不是长期依赖发行版过旧包。先确认系统：

1
2


uname -a
cat /etc/os-release

安装后验证：

1
2
3


docker version
docker compose version
sudo systemctl enable --now docker

让普通用户加入 docker 组相当于授予接近 root 的权限。若服务器由多人共用，不要为了省去 sudo 随意加入该组。查看磁盘和内存：

1
2


df -h
free -h

如果根分区只有十几 GB，即使服务能启动，镜像、数据库 WAL 和附件也会很快耗尽空间。

获取固定版本的 Buzz

创建独立目录：

1
2
3


sudo mkdir -p /opt/buzz
sudo chown "$USER":"$USER" /opt/buzz
cd /opt/buzz

克隆官方仓库：

1

git clone https://github.com/block/buzz.git .

不要让生产环境永远跟随 main。查看 Release 或提交，固定已测试版本：

1
2


git tag --sort=-version:refname | head
git log -1 --oneline

若当时还没有适合的稳定标签，至少记录部署提交 SHA：

1

git rev-parse HEAD

升级前才能准确比较配置和数据库迁移变化。

阅读 Compose 与示例配置

Buzz 仓库提供 docker-compose.yml、Dockerfile 和 .env.example。先不要直接启动：

1
2
3


sed -n '1,240p' .env.example
docker compose config --services
docker compose config > /tmp/buzz-compose-resolved.yml

重点确认：

哪个服务监听公网端口；
数据库、Redis、对象存储是否只在内部网络；
卷挂载到宿主机还是 Docker named volume；
默认密码是否仍存在；
Relay URL 和外部访问 URL 是否一致；
是否启用了 Caddy/TLS 配置。复制环境文件：

1
2


cp .env.example .env
chmod 600 .env

不要把 .env 提交到 Git，也不要把完整内容贴到工单。

生成凭据而不是沿用示例值

可以用 OpenSSL 生成随机值：

1
2


openssl rand -hex 32
openssl rand -base64 48

数据库、对象存储、应用签名和管理员引导凭据要分别生成，不能共用一个密码。在密码管理器中记录：

用途；
创建日期；
所属环境；
轮换负责人；
恢复方式。如果变量中含 $、#、空格或引号，Compose 解析可能与预期不同。修改后运行：

1

docker compose config >/dev/null

该命令能发现部分缺失变量和 YAML 错误，但不会证明所有应用配置有效。

第一次启动与日志判断

拉取或构建镜像：

1
2


docker compose pull
docker compose build --pull

仓库版本不同，可能只需要其中一条。以 Compose 中的 image 或 build 字段为准。后台启动：

1

docker compose up -d

查看状态：

1
2


docker compose ps
docker compose logs --tail=200

不要只看到容器为 Up 就结束。继续观察数据库迁移、Relay 启动、对象存储连接和 Web 服务健康检查。实时跟踪单个服务：

1

docker compose logs -f --tail=100 <service-name>

服务名从 docker compose config --services 获取，不要根据文章猜测。

域名、HTTPS 与 WebSocket

如果使用仓库自带 Caddy，确保外部域名与 .env 中 URL 完全一致，DNS 已指向服务器，80/443 没有被其他程序占用。检查端口：

1

sudo ss -lntp | grep -E ':80|:443'

如果已有 Nginx，可以让 Buzz 仅监听 127.0.0.1 的高端口，再由 Nginx 转发。Relay 和实时协作依赖长连接，反向代理必须正确处理 WebSocket Upgrade。通用 Nginx 片段如下，实际上游端口需从 Compose 确认：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 300s;
}

验证证书与响应：

1
2


curl -I https://buzz.example.com/
openssl s_client -connect buzz.example.com:443 -servername buzz.example.com </dev/null

浏览器能打开首页但频道一直断线，通常应检查 WebSocket、外部 URL、代理超时和 Cloudflare 设置。

创建社区与管理员

首次引导流程可能随版本变化。创建管理员前先确认站点没有开放匿名注册到公网。建议：

暂时用防火墙限制访问来源；
完成管理员创建；
关闭不需要的开放注册；
建立普通成员测试账号；
再开放团队访问。管理员账号只用于管理，不要让日常 Agent 共享管理员身份。每个 Agent 应拥有独立密钥、频道成员关系和审计轨迹。

接入 Codex、Claude Code 和其他 Agent

Buzz 仓库包含面向 Agent 的技能和工具，也提供 ACP harness 相关组件。具体安装方法要按当前版本文档执行。接入时先建立低权限测试频道，只授权一个无敏感信息的演示仓库。验证顺序：

Agent 能否读取指定频道；
是否无法读取未加入的私有频道；
能否打开指定仓库；
发送补丁是否需要人工确认；
工作流执行是否记录 Agent 身份；
撤销 Agent 密钥后是否立即失效。不要把主机 Docker Socket、服务器 SSH 私钥或组织级 GitHub Token直接交给 Agent。Buzz 的身份隔离不能自动抵消底层凭据过大的权限。

仓库、补丁与审批的最小测试

准备一个无敏感数据的测试仓库，创建简单 Issue，让 Agent 只生成补丁而不直接合并。人工检查：

频道中能否找到原始请求；
补丁是否对应正确提交；
CI 结果是否关联到同一记录；
Review 批准者是否是独立身份；
最终合并原因是否可追溯。 Buzz 的优势是把这些事件放在一条可搜索的记录中。若团队仍通过共享账号和外部脚本绕过审批，这个优势就会消失。

备份不能只复制一个目录

先从 Compose 确认所有卷：

1
2


docker compose config --volumes
docker volume ls

数据库使用逻辑备份：

1

docker compose exec -T postgres pg_dump -U <db-user> <db-name> > buzz.sql

服务名、用户名和数据库名必须按实际配置替换。备份对象存储的 Bucket，并保存 .env 的加密副本。一个可恢复备份至少包括：

PostgreSQL 数据；
对象存储文件与元数据；
Relay 或应用持久卷；
当前 .env 和反向代理配置；
部署提交 SHA；
恢复操作说明。每月至少在隔离机器做一次恢复演练。没有恢复验证的备份只是“可能有用的文件”。

日志、指标与容量

先用 Docker 查看资源：

1
2


docker stats
docker system df

监控至少覆盖：

HTTPS 可用性；
Relay 长连接错误；
PostgreSQL 连接数和磁盘；
Redis 内存与淘汰；
对象存储容量；
容器重启次数；
备份最后成功时间。日志中可能包含频道名、仓库地址或用户标识。集中采集时设置访问控制和保留期，不要把调试日志公开到第三方 Paste 服务。

升级与回滚

升级前记录当前状态：

1
2
3


git rev-parse HEAD
docker compose images
docker compose ps

完成数据库和对象存储备份，再阅读从当前版本到目标版本的 Changelog。更新固定版本后：

1
2
3
4


git fetch --tags
git checkout <tested-tag-or-commit>
docker compose pull
docker compose up -d

如果新版本执行了不可逆数据库迁移，仅切回旧镜像可能无法回滚。必须使用升级前备份恢复到独立环境验证。

常见故障

容器反复重启

运行 docker compose logs <service>，先找第一条错误。常见原因是缺少变量、数据库未就绪、权限或迁移失败。

登录后看不到频道

检查当前 URL 是否指向正确社区、用户是否加入频道、密钥是否发生变化，不要先删除数据库重建。

附件上传失败

检查对象存储 Endpoint、Bucket、访问密钥、反向代理上传大小和磁盘容量。

页面正常但实时消息断开

检查 WebSocket Upgrade、Cloudflare 代理、空闲超时以及 Relay 对外 URL。

Agent 能看到不该访问的仓库

立即撤销 Agent 凭据，检查 Buzz 频道成员关系以及底层 Git Token。共享组织级 Token 往往才是权限扩大的来源。

磁盘持续增长

分别检查数据库、对象存储、容器日志和未清理镜像：

1
2


sudo du -xh /var/lib/docker | sort -h | tail
docker system df

不要在不确认路径的情况下递归删除 Docker 数据目录。

上线前检查表

域名和 HTTPS 正常，证书可自动续期；
只有必要端口暴露公网；
默认密码与示例 Secret 已全部替换；
管理员与日常 Agent 不共享身份；
私有频道隔离经过两个账号交叉测试；
Agent 只能访问测试仓库和所需工具；
数据库、对象存储和配置均有备份；
恢复演练成功；
日志没有输出密钥；
已记录版本和升级回滚方法。 Buzz 适合希望把 Agent 当作真实团队成员管理，同时保留身份边界和审计记录的团队。先用小社区验证权限、数据恢复和协作方式，再决定是否迁移生产仓库，比一次性接入所有 Agent 更安全。