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 更安全。