配对的热点文已经把 block/buzz 的定位讲透了：人机共享 workspace，agent 是 member 不是 bot，底层是 Nostr relay，每条消息、反应、工作流、git event 都是签名事件。但看完定位，真正想自己搭一个的人会卡在下一步——仓库是 Rust monorepo，依赖 Postgres/Redis/MinIO 一整套，README 给了三条路径，到底走哪条？
更关键的是，buzz 的 relay 不是聊天服务的一个组件，而是「单一事实来源」--所有读写都过它，事件、搜索、审计、工作流全在一条 log 上。自托管 relay 等于把团队整条人机协作的事件流攥在自己手里，这是 SaaS workspace 给不了的数据主权。
这篇 SOP 接住「定位之后怎么落地」。把 buzz 的自托管部署拆成三条路径（桌面试用 / 本地开发 / 生产单节点），配齐 relay 签名密钥、community 绑定、agent keypair，最后给踩坑和 FAQ。所有命令来自 block/buzz 仓库 README、deploy/compose/README.md 与 .env.example，不编造。
一、部署准备：三条路径，先选对
README 把「上手 buzz」分成三条路径，选错会白费力气：
| 路径 | 适合谁 | 代价 |
|---|---|---|
| 桌面试用 | 只想体验 app，不关心 relay | 下载打包构建，零配置，但连的是别人的 relay |
| Railway 一键托管 | 想要自己的 relay 但不想管服务器 | 点一下部署，月付托管费 |
| 源码构建（本 SOP 重点） | 想完全自托管、要接 agent | 要装 Rust/Docker，自己跑 Postgres/Redis/MinIO |
桌面构建从 releases 页下载：macOS（aarch64/x64 dmg）、Linux（AppImage/deb）、Windows（x64 exe，未签名，SmartScreen 拦截就点 More info → Run anyway）。默认连 ws://localhost:3000，没有 relay 就得自己起。
源码路径的环境依赖（README 原文）：Docker + Hermit，或自行备齐 Rust 1.88+、Node 24+、pnpm 10+、just。Hermit 是 buzz 的 pinned toolchain 脚本，激活后工具首次用时自动下载，省去手动对版本。Windows 用户额外装 Git for Windows（提供 Git Bash），或用 BUZZ_SHELL 指向别的 bash 兼容 shell。
为什么需要 Postgres/Redis/MinIO 三件套？这得从架构说起。buzz 的 relay 是 Axum 写的 Rust 服务，也是整个系统的单一事实来源：Postgres 存事件加全文搜索（FTS），Redis 管 pub/sub、presence、typing，MinIO/S3 走 Blossom 协议存媒体。每条动作--消息、reaction、workflow step、git event--都是一条按 kind 整数分发的签名 Nostr 事件。三件套不是凑数，是这条事件流的物理承载。
二、本地开发部署：clone + just dev
这是 README 的 Quick start，开发者与自托管入门路径，起一个本地 relay 加桌面 app。
一次性准备：
git clone https://github.com/block/buzz.git && cd buzz
. ./bin/activate-hermit # 激活 pinned toolchain，工具首次用自动下载
just setup && just buildjust setup 会自动跑 just bootstrap：把 .env.example 复制成 .env、用 Hermit 下齐工具、起 Docker 服务并跑 migration。你不用手动配 Postgres/Redis，Docker 全拉起来。
日常启动：
. ./bin/activate-hermit
just dev # relay + 桌面 app 一起起relay 落在 ws://localhost:3000，桌面 app 弹出来就能进。想看 relay 日志和 Vite 输出分开，就两个终端：一个 just relay，一个 just desktop-dev。常用 just 命令速查：
just setup # Docker、migration、桌面端依赖
just relay # 只起 relay
just dev # relay + 桌面端
just build # 编译 Rust workspace
just check # fmt + clippy + 桌面端检查
just test-unit # 单测，不需要基础设施
just reset # ⚠️ 清数据重建，别在生产敲三、生产单节点部署：deploy/compose
本地 just dev 是开发栈，不能直接上生产。buzz 在 deploy/compose/ 里放了独立的单节点/VPS bundle，和根目录的 docker-compose.yml（仅限本地开发）有意分开。栈是真依赖：Postgres、Redis、MinIO、可选 Caddy/TLS。
cd deploy/compose
cp .env.example .env
$EDITOR .env # 把每个 CHANGE_ME 替换掉
./run.sh start公网 VPS 要自动 Let's Encrypt 证书：
cd deploy/compose
BUZZ_COMPOSE_TLS=true ./run.sh start要求 Docker Compose v2.24.4+；TLS 模式用 Compose 的 !reset 把 relay 直连端口摘掉，由 Caddy 终结 HTTPS。镜像默认跟 ghcr.io/block/buzz:main（早期测试用），生产要 pin 到 ghcr.io/block/buzz:sha-<7> 或 semver tag。几个密钥必须跨重启保持稳定，换了就断：BUZZ_RELAY_PRIVATE_KEY、BUZZ_GIT_HOOK_HMAC_SECRET、数据库/Redis、S3 凭据。
新库要先迁移：设 BUZZ_AUTO_MIGRATE=true，或起 relay 前跑 buzz-admin migrate（镜像得带嵌入式 SQLx migration）。上线前自检（deploy/compose/README.md 给的验证流程）：
./run.sh config
./run.sh start
curl -fsS "http://127.0.0.1:$(grep -E '^BUZZ_HTTP_PORT=' .env | cut -d= -f2-)/_liveness"
./run.sh status/_liveness 通了、status 正常，再对外开。
四、配置：relay 签名密钥、community 与 owner pubkey
buzz 的配置全在 .env，本地开发默认值开箱即用，生产才需改。关键字段（来自 .env.example）：
| 变量 | 作用 | 备注 |
|---|---|---|
BUZZ_BIND_ADDR | relay 监听地址 | 默认 0.0.0.0:3000 |
RELAY_URL | 对外 WebSocket URL | 参与 NIP-42 认证挑战，生产改成真实域名 |
DATABASE_URL | Postgres 17 连接串 | 事件 + FTS 全文搜索都存这 |
REDIS_URL | Redis 7 连接串 | pub/sub、presence、typing |
BUZZ_S3_* | S3/MinIO 媒体存储 | Blossom 协议，本地 MinIO 默认 path 风格 |
BUZZ_RELAY_PRIVATE_KEY | relay 签名密钥（32 字节 hex） | 跨重启必须稳定，换了 REST 创建的帖子里作者对不上 |
community 是 buzz 的租户边界。ARCHITECTURE.md 讲清了：自托管默认一机一 relay 一隐式 community；多 community 部署时，req.community = resolve_host(connection.host) 在 AUTH 之前就定好，未知 host 直接拒绝，不会 fallback 到默认租户。一句话：URL 即工作区，host 决定 community。即便后端共享同一套 Postgres/Redis/S3，每个 community 的租户可见行、缓存键、搜索文档、工作流状态都按 host 隔离--共享基础设施是实现细节，不是用户可见的全局工作区。
要开「闭门 relay」（只许 owner 信任的人进），设 RELAY_OWNER_PUBKEY 为 64 位 hex Nostr 公钥——注意它没 BUZZ_ 前缀，别跟 relay 签名密钥搞混。人机分桶限流也在配置里：BUZZ_RATE_LIMIT_HUMAN_* 和 BUZZ_RATE_LIMIT_AGENT_* 是两套桶，agent 的标准/提升/平台档消息上限比人高，因为 agent 本就该干得更多。
五、加入 Agent：keypair + buzz-cli + buzz-acp
部署完 relay，下一步是把 agent 当 member 加进来。buzz 的 agent 不走 bot token，走自己的 Nostr keypair。README 列了 agent 进 room 后能干的事：open repos、send patches、review code、run workflows、edit canvases、orchestrate other agents、voice huddles、create channels--和人一样的操作面，只是换一副 keypair。
- 装 agent 侧 CLI：
cargo install --path crates/buzz-clibuzz-cli 是 agent-first 的，JSON 进 JSON 出，专门给 LLM tool call 用。
- 给 agent 配身份和 relay 地址：
export BUZZ_PRIVATE_KEY="nsec1..." # agent 的 Nostr 私钥，hex 或 bech32
export BUZZ_RELAY_URL="https://relay.example.com"
buzz channels list # 验证连通BUZZ_PRIVATE_KEY 做 NIP-98 Schnorr 签名，标识 agent 在 relay 上的身份。这就是「agent 是 member 不是 bot」的落地：它有自己的 key，不是挂在人账号下的 token。
- 把 agent 加进 channel，当 teammate 用：
buzz channels create --name "release-plan" --type stream --visibility open
buzz channels join --channel <uuid>
buzz messages send --channel <uuid> --content "我来跑首轮 review"
buzz messages search --query "性能 patch" # 带 receipts 的检索buzz-cli 覆盖面和人类队友一样：messages、channels、canvas、workflows、dms、repos（NIP-34 git，patches/repo announcements/status）、mem（NIP-AE agent 记忆，可 set/get/patch）。git 事件走 NIP-34，所以 patch、CI 结果、review、merge 能全落在一个 channel 里，代码和讨论不分两处。agent 发的事件过的是和人同一条管线--认证、验签、成员校验、入库、fan-out、索引、审计、触发工作流--痕迹自然落在同一条 log。
- 想让 AI 模型自动响应 @mention，用 buzz-acp harness，桥接 relay 事件到 Goose/Codex/Claude Code：
BUZZ_PRIVATE_KEY=<hex> BUZZ_RELAY_URL=ws://localhost:3000 buzz-acpACP 配置（.env.example 的 ACP 段）：BUZZ_ACP_AGENT_COMMAND（goose / codex-acp / claude-code）、BUZZ_ACP_AGENT_ARGS、BUZZ_ACP_AGENTS（并行子进程数 1–32）、BUZZ_ACP_MODEL、BUZZ_ACP_TURN_TIMEOUT（默认 320 秒）。长跑 agent 建议 BUZZ_ACP_HEARTBEAT_INTERVAL=60 防 session 超时。密钥生成走 buzz-admin（operator CLI，管 relay 成员 + 生成 keypair）。
六、踩坑记录
坑一：拿根目录 docker-compose.yml 上生产。 那个是本地开发栈。生产必须用 deploy/compose/，两者分开是有意的。
坑二：换 relay 私钥导致作者错乱。 BUZZ_RELAY_PRIVATE_KEY 跨重启必须稳定。换了，REST 创建的 forum 帖会对不上原作者。密钥和 DB/Redis/S3 凭据一起进 secrets 管理，别提交到 git。
坑三：新库不跑 migration。 全新数据库要么 BUZZ_AUTO_MIGRATE=true，要么手动 buzz-admin migrate，否则 relay 起不来。镜像得带嵌入式 SQLx migration。
坑四：RELAY_OWNER_PUBKEY 填错格式。 闭门模式要 64 位 hex Nostr 公钥，且没 BUZZ_ 前缀。填成 nsec 或加了前缀，closed relay 模式不开。
坑五：Windows 没 bash。 agent 的 shell 工具在 bash 下跑。Windows 不装 Git for Windows，agent 执行命令直接挂；要换 shell 就设 BUZZ_SHELL 指向 bash.exe 路径。
坑六：MinIO 地址风格错。 Compose 栈把 relay 的 S3 endpoint 固定成 http://minio:9000 加 path 风格，Docker DNS 解析 minio、不解析 <bucket>.minio。换外部 S3（如 virtual 风格的 bucket 子域）要改 Helm 或自定义 Compose，.env 改不动。
FAQ
Q1：不会 Rust 能部署 buzz 吗？
A：能。生产用 deploy/compose/ 的 Docker 镜像（ghcr.io/block/buzz:*），不需要自己 cargo build。只有想从源码跑本地开发栈或改代码，才需要 Rust 1.88+。最省事是 Railway 一键托管 relay，桌面端下打包构建连上即可。
Q2：buzz 的 relay 必须配 Postgres/Redis/MinIO 三件套吗？
A：本地 just dev 用 Docker 全拉起来，你不用单独装。生产栈也依赖这三样，因为它们是 buzz 当前的真实依赖——事件存 Postgres、pub/sub 走 Redis、媒体走 MinIO/S3。README 提到未来 Minimal 模式会简化，今天还没有。
Q3：agent 怎么认证？和 bot token 有什么不同？
A：agent 用自己的 Nostr keypair，通过 BUZZ_PRIVATE_KEY 做 NIP-98 Schnorr 签名。它不是挂在人账号下的 bot token，是 relay 上的独立 member，有自己的 channel membership 和 audit trail。这就是「agent 是 teammate」的落地。
Q4：一个 relay 能服务多个团队吗？
A：能。多 community 模式下，community 由请求 host 决定（resolve_host），在 AUTH 之前绑定。每个 community 保持独立的租户边界，即使后端共享 Postgres/Redis/S3。自托管默认一机一 community，要多团队就按域名或子域分。
Q5：闭门 relay 怎么开，只让 owner 信任的人进？
A：设 RELAY_OWNER_PUBKEY 为 64 位 hex Nostr 公钥（无 BUZZ_ 前缀），启用 closed relay 模式，未知 pubkey 进不来。agent 的 keypair 也要 owner 加进成员才能用，buzz-admin 管 relay 成员和 key 生成。
看法
buzz 的部署门槛比一般「AI 工具」高，但高的部分是诚实的：它不是套个聊天壳，而是把工作区拢成一条可审计的 Nostr 事件流，Postgres/Redis/MinIO 是这条流的物理承载。deploy/compose/ 把生产栈封成一条 ./run.sh start，比手搓三件套省心；真嫌重，Railway 一键托管 relay 加桌面端连上，是最快尝鲜路径。
自托管 buzz 的真正价值不在「我也有个 relay」，在于 agent 有了独立 keypair 和 audit trail 后，它能干 teammate 该干的事——开 repo、发 patch、跑 workflow、改 canvas——痕迹全和人在同一条 log 里。这是 Slack bot 模式给不了的。如果你团队已经在人机协作上撞到「bot 永远是二等公民」的墙，搭一个自己的 buzz relay 值得。
参考来源
- block/buzz 仓库：https://github.com/block/buzz （star 据 GitHub API 2026-08-06 核实 23,490）
- README「Quick start」与「Getting started」章节（部署命令来源）
- deploy/compose/README.md（生产单节点部署与验证流程来源）
- .env.example（relay/ACP 配置字段来源）
- crates/buzz-cli/README.md（agent CLI 命令来源）
- ARCHITECTURE.md（community 绑定与事件管线来源）
- Block 工程博客「Run your own Buzz relay」：https://engineering.block.xyz/blog/run-your-own-buzz-relay