Buzz 如何用 buzz-backend-kubernetes provider 将托管 agent 部署到 Kubernetes 集群【免费下载链接】buzzA hive mind communication platform项目地址: https://gitcode.com/GitHub_Trending/buzz14/buzzBuzz Desktop 中的托管 agent 默认跑在本机。如果你希望这个 agent 跑在自己维护的 Kubernetes 集群上项目提供的第一款远端 substrate provider 就是buzz-backend-kubernetes它是一个独立的可执行文件运行在桌面上通过标准 kubeconfig 访问集群把一个裸 Pod运行sprig镜像中的buzz-acpharness部署到指定命名空间。完成后的结果是集群里出现一个名为buzz-agent-pubkey 前 12 位 hex的 Podagent 以你的 relay 上在线presence状态出现而桌面端之后对它的全部观察都走 relay不保留任何直连集群的管理通道。本文的操作依据是 docs/remote-agents.md 中「The Kubernetes Binding」一章、provider 实现 crates/buzz-backend-kubernetes/ 以及仓库自带的两个验证脚本。部署机制一个二进制 两个操作理解部署路径前先明确边界后面的步骤都建立在这几条之上桌面端按顺序扫描桌面可执行文件所在目录、PATH的每一段、~/.local/bin寻找名为buzz-backend-id的可执行文件id 需匹配[a-z0-9][a-z0-9_-]*同名取最先命中者。发现阶段不执行任何东西。每次操作启动一个进程请求 JSON 从 stdin 进入响应 JSON 写到 stdout 后退出。操作只有两个info10s 超时和deploy600s 超时。集群凭据不经过provider_config。provider 走标准 kubeconfig 解析$KUBECONFIG→~/.kube/config配置里只允许出现context和namespace这类非密字段见 client.rs。deploy不是「创建」而是收敛同名 Pod 已存在且已启动时严格 no-op只有当 harness 容器真正进入state.running才算成功Pod 处于Pending/ImagePullBackOff等状态不算。前置条件条件说明可达的 Kubernetes 集群本地必须有一份能认证通的目标集群 kubeconfigprovider_config.context可指定 context留空则用当前 context命名空间权限provider 会在命名空间不存在时尝试创建若被 RBAC 拒绝它不会回退到default而是返回一条需要你手工执行的kubectl create namespace name命令digest 固定的镜像镜像引用必须是namesha256:64 位 hex形式。只给 tag包括:latest会被拒绝——因为该 Pod 持有 agent 私钥平台v1 发布 macOS arm64/x64 与 Linux musl 二进制不发布 Windows 二进制本地构建可选路径Rust 工具链用于从工作区构建 provider第一步获取并放置 provider 二进制两种途径项目 release 产物spec 说明 v1 有独立的 release workflow产物macOS arm64/x64 Linux musl附在 release 上。本地构建仓库自带的 scripts/test-k8s-provider-release.sh 使用与桌面 release 相同的多包构建形态cargo build --release \ -p buzz-acp \ -p buzz-agent \ -p buzz-dev-mcp \ -p git-credential-nostr \ -p buzz-cli \ -p buzz-backend-kubernetes产物在target/release/buzz-backend-kubernetes。多包一起构建的原因在 main.rs 的注释里release 构建会把所有 sidecar 编进同一次 cargo 调用ring与aws-lc-rs特性被统一后 rustls 无法自动选择 crypto provider所以程序启动时显式安装 ring provider。如果你只构建-p buzz-backend-kubernetes单包也得到同一二进制但 release 形态与脚本保持一致可复现 CI 验证过的结果。把二进制放进桌面能发现到的位置最省事的是~/.local/binspec 指定的安装位置已在发现路径上。文件名必须精确为buzz-backend-kubernetes否则桌面发现不到它。macOS 上从 Finder 启动桌面意味着继承 launchd 的最小PATH如果 kubeconfig 用exec凭据插件认证如aws eks get-tokenprovider 会在构建客户端前自行把/opt/homebrew/bin、/usr/local/bin、~/.local/bin前置到PATH插件缺失时错误信息会直接点名缺失的插件二进制名。第二步用info探测协议不接触集群即可运行这是桌面渲染配置表单前调用的操作echo {op:info,request_id:req-1} | buzz-backend-kubernetes成功时响应为{ok: true, name: str, version: str, protocol_version: int, description: str, config_schema: JSON Schema}其中protocol_version是线协议版本桌面端会校验缺失或不兼容是错误而不是按 1 处理config_schema驱动 UI 表单的默认值预填与必填校验。注意namespace字段的default是每次info调用都新生成的随机名buzz-agents-rand6所以你每次打开表单看到的默认命名空间都不一样image的预填默认是 config.rs 中定义的 digest 固定引用ghcr.io/block/buzz-sprig:sha-6530b58sha256:17facfc7608d8ddb33bc056c9aaba1098f4ef6abe5655702fbfd7584d1f74d76tagdigest 形式tag 供人追溯 git SHAdigest 负责固定provider 内部会规范化为纯 digest 形式。第三步填写 provider_configv1 恰好开放 9 个字段上限 20默认值来自 config.rs字段必填默认值用途context否当前 contextkubeconfig context 名namespace是info每次生成的buzz-agents-rand6部署目标不存在则尝试创建image是见上一步的 digest 固定引用agent 容器镜像必须 digest 固定cpu_request否1CPU requestmemory_request否2Gi内存 requestcpu_limit否2CPU limitmemory_limit否4Gi内存 limitinactivity_seconds否7200无事件且无在途 turn 多少秒后 agent 自行退出service_account否无仅用于调度/RBAC 身份不会重新挂载 API token资源默认值偏大是刻意的——spec 说明「在 agent 工作区里跑cargo build使 500m/1Gi 的 request 不现实」。配置阶段的硬性拒绝都是 in-band 错误{ok:false,error:...}退出码 0image不含 digestprovider_config.image ... is not digest-pinned: a tag is a mutable pointer, and this object runs with the agents private key. Use namesha256:64 hex chars见 fixtures 中deploy-tag-image用例。inactivity_seconds: 0无限期生命周期在当前版本被拒绝它需要restartPolicy: OnFailure而该策略被 harness 退出码契约门禁卡住provider 拒绝组合而不是静默降级为Never。v1 实际只有restartPolicy: Never。agent 的provider解析为relay-mesh共享算力时直接拒绝deploy refused: this agent is configured for shared compute (relay-mesh), which runs on the relay rather than in a pod...因为该 transport 是桌面本地回环代理序列化进 Pod 后指向的是 Pod 自己的 localhost。第四步触发部署主路径桌面端把 agent 记录的 backend 设为该 provider按info返回的config_schema填写上面 9 个字段然后 Start。桌面端对任何非 Local agent 的 Start 都无条件下发deploy——它不跟踪 substrate 状态。等效的手工路径wire 协议直接向进程 stdin 写一个deploy请求。下面的示例取自 scripts/test-k8s-provider-release.sh 的真实请求形态把三处尖括号值替换为你自己的nsec1...换成该 agent 的私钥nsecwss://...换成 relay URL你的 context换成 kubeconfig context 名cat JSON | buzz-backend-kubernetes { op: deploy, agent: { relay_url: wss://relay-url, private_key_nsec: nsec1..., auth_tag: owner, launch: { command: goose, args: [], env: {}, policy_env: {} } }, provider_config: { context: 你的 context, namespace: buzz-agents-abc123, image: ghcr.io/block/buzz-sprig:sha-6530b58sha256:17facfc7608d8ddb33bc056c9aaba1098f4ef6abe5655702fbfd7584d1f74d76, inactivity_seconds: 7200 } } JSON桌面实际发出的 payload 还带有解析好的launch块分层 env、策略 env、owner_pubkey仓库中记录了真实桌面路径产出的完整样例 deploy-full-launch.request.json。成功响应形如{ok: true, agent_id: buzz-agent-12位hex}——agent_id就是 Pod 名桌面把它存为backend_agent_id作为「已部署」这一簿记轴。deploy内部做的事从 nsec 推导 pubkey先于任何集群访问→ 为本次尝试写一个唯一命名的不可变 Secretbuzz-agent-12位hex-gen承载身份环境变量与用户 env→ 创建引用该 Secret 的确定性命名 Pod → 等到 harness 容器state.running或 600s 操作截止。第五步验证部署结果wire 响应ok: true且agent_id已给出说明 harness 容器已确认启动不是 Pod 被 apiserver 接受。Pod 状态kubectl --context 你的 context get pod agent_id -n buzz-agents-abc123 kubectl --context 你的 context describe pod agent_id -n buzz-agents-abc123Pod 应带标签buzz.block.xyz/agent-pubkey前 32 位 hex、注解buzz.block.xyz/agent-pubkey-full完整 64 位以及管理标记app.kubernetes.io/managed-by: buzz-backend-kubernetes容器状态为 running 即对应 wire 层的成功判据。 3.relay presence这是桌面端唯一的存活信号kind 20001ephemeral。异常死亡到 presence 过期之间有 180s 的固定窗口relay 全局常量PRESENCE_TTL_SECS期间状态点可能短暂错误但必然收敛。presence 按 relay URL 的 community 作用域划分——用另一个 community 的 relay 观察会看到该 agent 离线而对其 deploy 会正确 no-op。仓库还有两个可复跑的验证脚本作为部署前的预检scripts/test-k8s-provider-release.sh构建 release 形态二进制后用指向http://127.0.0.1:9的假 kubeconfig 发一次deploy断言 provider 以退出码 0 返回单行 in-band的{ok: false, error: ...}不可达集群是错误不是 panic。不接触真实集群适合确认二进制本身工作正常。scripts/test-k8s-sprig-image-live.sh验证集群的 kubelet 确实能解析并启动你打算交给 provider 的那个 digest 固定镜像。需设置BUZZ_K8S_TEST_CONTEXT一个可丢弃/本地的 kubectl context和BUZZ_SPRIG_IMAGEnamesha256:64 hex格式不合法直接退出 2。副作用说明脚本会在该 context 创建一次性命名空间buzz-k8s-sprig-时间戳-随机和一个探针 Pod等待其以Succeeded结束并校验readlink /usr/local/bin/buzz-acp sprig后删除整个命名空间若命名空间的管理标记被改动或其中出现非本 provider 的 Pod清理会拒绝执行并保留现场。镜像存在于宿主 Docker daemon 不代表 kubelet 运行时能解析同一 namedigest这正是该脚本独立存在的原因。停止 agent 与残留回收Stop不是 provider 操作桌面在 relay 上发布指向该 agent 的!shutdownharness 校验发送者是 owner 后走优雅退出排空在途 turn、发布 presenceoffline、关闭 relay 连接。Pod 的terminationGracePeriodSeconds固定 60sentrypoint 必须以exec buzz-acp收尾保证信号直达 harnessPID 1 的 bash 收不到 SIGTERM 会导致 Pod 拖满宽限期被 SIGKILL、presence 残留 online。桌面端的本地 Stop 命令会拒绝远端 agent。无人值守回收inactivity_seconds默认 7200到期后 agent 自行走同一条优雅退出路径Pod 进入终态再次 Start 时 reconciler 会清理终态残留并重新创建。v1 没有undeploy操作。在桌面删除一个仍带backend_agent_id的 agent 需要显式force_remote_delete确认否则 substrate 对象被孤儿化。孤儿的成本有界Completed Pod 不会自行重启Pod 与其 Secret 会在下一次同 key 的 deploy的预检 GC 中被回收GC 只处理通过完整 pubkey 注解校验且带管理标记的对象也可以手工kubectl delete清掉。已知限制配置改动对运行中的 agent 不生效live 实例是严格 no-op零变更编辑只在下一次退出后的新代生效「stop 再 start」是 spec 明确指出的 v2 立即应用路径。600s 是同步等待预算镜像冷拉、scale-from-zero 调度都算在内。超时报告「startup not confirmed within the deadline」不触发清理或强制重建——下次 Start 的 reconciler 会接管观察到的状态已启动则 no-op 采纳仍可恢复则继续等待。Unschedulable不是致命状态scale-from-zero 集群在自动扩缩容器补容期间会短暂报告它provider 只观察不删除。工作区是emptyDircheckout 与临时文件随 Pod 消亡agent 的记忆走 relay 持久化NIP-AE不受影响。没有日志获取操作桌面不直连集群M1 约束终态 Pod 的日志是仅有的取证窗口且会被下次 GC 抹掉因此 spec 把集群原生的日志外送列为生产前提——provider 在 Pod 上携带的注解pubkey、generation token、镜像引用足够把外送日志归因到具体身份与代次。spec 的「Known Defects」一节列出的是28ae6cd21提交时点桌面/harness 侧的遗留问题如 deploy payload 尚未走 launch resolver、harness 退出码契约未固化其中直接约束本场景的是退出码契约未固化前restartPolicy: OnFailure不可用也就是inactivity_seconds: 0在本版本必然被拒绝。部署链路核对完毕后的下一步在 relay 上向该 agent 发一条消息确认它以自己的 NIP-OA 身份应答——这一步同时验证了 relay 认证、presence 与 agent 行为也是 M1 下你唯一可用的端到端确认手段。【免费下载链接】buzzA hive mind communication platform项目地址: https://gitcode.com/GitHub_Trending/buzz14/buzz创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考