ZeroClaw Gateway 进程提取架构解析:从进程内 Crate 到可选独立进程的 ADR-007 演进之路
ZeroClaw Gateway 进程提取架构解析:从进程内 Crate 到可选独立进程的 ADR-007 演进之路
导读
本文围绕 ZeroClaw 仓库中的架构决策记录 ADR-007:将 Gateway 提取为独立的可选进程,系统讲解为什么 ZeroClaw 要把承载 HTTP、WebSocket、Webhook 与 Web Dashboard 的 zeroclaw-gateway crate 从「进程内 feature 门控的中间接缝」演进为「可独立运行、可选安装的 zeroclaw-gw 进程」,以及这条演进路径上必须满足的 IPC 契约、鉴权、版本协商、进程生命周期等硬性条件。读完本文,你将理解 ZeroClaw 微内核式架构中「运行时(agent authority)」与「网关(外部网络边界)」的职责切分,掌握本 ADR 尚未落地前的当前代码形态,并能在自己的部署中判断何时可以省略 Web 表面、如何为网关故障设计隔离策略。
一、决策背景:为什么进程内 Crate 不等于进程隔离
1.1 现状:zeroclaw-gateway 已是一个独立 Crate,但仍「寄生」在主进程里
ZeroClaw 的 HTTP、WebSocket、webhook 与 dashboard 表面早已有专门的 crate:crates/zeroclaw-gateway(描述为 "HTTP/WebSocket gateway for ZeroClaw — REST API, web dashboard, webhooks")。但正如 ADR-007 的 Context 明确指出:主应用仍然在 gateway feature 门控下,链接并在进程内启动该 crate。
从工作区配置可以看到这一点:根 Cargo.toml 将 zeroclaw-gateway = { path = "crates/zeroclaw-gateway", version = "0.8.5" } 声明为 workspace 依赖,并在根 crate 中以 zeroclaw-gateway = { workspace = true, optional = true } 形式按需启用;src/main.rs 中 #[cfg(feature = "gateway")] mod gateway; 让 CLI 暴露 zeroclaw gateway start / restart / get-paircode 等子命令。
这意味着 crate 边界虽然改善了代码归属(code ownership),但并未提供:
- 进程隔离:网关崩溃会连带影响同进程内的 agent 执行;
- 独立运维:无法独立重启、升级网关;
- 按需省略:无法在构建或部署时完全不携带 Web 表面。
1.2 已有的接缝:运行时 JSON-RPC 表面仍不是完整的外部契约
ADR 同时指出,zeroclaw-runtime 虽然已有 JSON-RPC 表面,但「完整稳定的本地契约、传输层、鉴权模型、兼容性策略、进程监督」尚未作为一条受支持的边界整体交付。因此当前现状被定性为:crate 与 RPC 接缝是「有用的迁移步骤」,而非进程提取完成的证明。
二、核心决策:zeroclaw-gw 独立可选进程与职责边界
2.1 决策内容
ADR-007 的 Decision 明确:
我们将把网关做成独立的、可选的
zeroclaw-gw进程。
两条硬性职责边界:
| 主体 | 职责范围 |
|---|---|
Agent 运行时(zeroclaw-runtime) |
agent 执行、会话、记忆、配置、工具、安全策略及其他领域状态的唯一权威(authority) |
zeroclaw-gw 进程 |
外部 HTTP 与流式协议、dashboard 交付、配对(pairing)与传输面关切、通用 webhook 入口 |
关键约束是:网关必须通过受支持的 IPC 契约请求运行时操作,而不是直接伸手进入进程本地的运行时状态。
2.2 IPC 边界的四项硬性要求
ADR 对 runtime ↔ gateway 的 IPC 边界给出明确要求:
- 必须鉴权(authenticated);
- 必须版本化(versioned);
- 必须有文档(documented);
- 默认连接必须保持本地,且不得在公共接口上静默暴露运行时控制面。
此外,传输选择可以随平台而异(例如 Unix socket、Windows named pipe、loopback 端口),但「本地默认」是不可妥协的底线。
2.3 中间接缝的定位
当前 feature 门控的进程内 zeroclaw-gateway crate 被明确定位为中间接缝(intermediate seam):
在 IPC 对等能力和进程生命周期支持建设期间,它可以继续存在;但新架构不应把「直接访问运行时内部」变成网关的永久性需求。
2.4 运维底线
- 操作者必须能在没有
zeroclaw-gw的情况下运行 agent; - 网关故障或重启不得终止本应健康的 agent 执行。
这两条是进程提取的验收红线,也是 headless/边缘部署(如 Raspberry Pi)场景的价值来源。
三、当前源码中的「迁移接缝」证据
3.1 网关 Crate 的进程内形态:run_gateway 的注入式依赖
从 crates/zeroclaw-gateway/src/lib.rs 的 run_gateway 签名可以看出当前「进程内启动」的耦合形态:函数接收 host、port、Config,以及一长串由 daemon 持有的运行时服务:
external_event_bus(daemon 的事件总线);reload_controls(daemon 的重载控制);tui_registry、canvas_store;- 共享的
sop_engine/sop_audit/sop_driver_handles; daemon_authority(inbound 鉴权状态:pairing guard、accepted policy、live config)。
run_gateway_with_authority 则围绕 daemon 代的 LiveConfigAuthority 运行。这些参数全部是进程内直接注入的句柄——正是 ADR-007 所说的「直接访问运行时内部」的形态,是未来要逐步替换掉的接缝。
3.2 网关表面一览:REST / WS / SSE / webhook
网关 crate 的模块清单(lib.rs)覆盖了 ADR 提到的全部外部表面:
- REST API:
api.rs、api_config.rs、api_logs.rs、api_oidc.rs、api_pairing.rs、api_skills.rs、api_sop.rs、api_upload.rs等; - 实时/流式:
ws.rs(WebSocket)、sse.rs(SSE 事件流)、session_queue.rs(会话串行化队列); - webhook 入口:
webhook_ingress.rs、api_webhook.rs,以及按 feature 门控的 WhatsApp / Linq / Nextcloud Talk / Gmail 推送通道; - 安全与治理:
principal_gate.rs(inbound 鉴权)、auth_rate_limit.rs、security_headers.rs、tls.rs; - 配对:
api_pairing.rs(PairingGuard、GATEWAY_ADMIN_TOKEN_HEADER、gateway_admin_token_path来自zeroclaw_runtime::security::pairing); - 静态交付:
static_files.rs(dashboard 由resolve_web_dashboard_availability解析,支持embedded-webfeature 嵌入或gateway.web_dist_dir指向文件系统目录两种模式)。
3.3 网关自身的防御性设计(进程内已有,提取后仍需保留)
即使进程边界尚未落地,网关 crate 已经实现了独立的限流、幂等与超时治理,这些在独立进程形态下依然是必需能力:
- 请求体上限:
MAX_BODY_SIZE = 65_536(64 KiB),防止内存耗尽(lib.rs); - 请求超时:默认
REQUEST_TIMEOUT_SECS = 30(慢速攻击防护),长运行 cron 触发端点豁免为LONG_RUNNING_REQUEST_TIMEOUT_SECS = 600,两者均从GatewayConfig.request_timeout_secs/long_running_request_timeout_secs读取; - 滑动窗口限流:
SlidingWindowRateLimiter以 60 秒窗口、默认 10_000 个客户端键、5 分钟清扫间隔实现pair与webhook两条独立的速率限制; - 幂等存储:
IdempotencyStore以 TTL + 键上限防止 webhook 重复投递,并支持plugins-wasm下的预留-提交/回滚语义。
四、IPC 契约的现状:运行时 RPC 层已具备的构件
ADR-007 要求 IPC 边界「authenticated, versioned, documented」。当前仓库中 crates/zeroclaw-runtime/src/rpc 已实现大部分底层构件,可作为未来 zeroclaw-gw 连接的支撑。
4.1 传输层:本地与远程两条平面
rpc/transport.rs 定义 TransportKind:
- Local:Unix socket / Windows named pipe,同主机,受文件系统权限 / pipe ACL 约束;
- Wss:远程 WebSocket TLS 监听器。
文档注释明确区分鉴权规则:本地 IPC 保留兼容路径,远程 WSS 必须显式凭证。这与 ADR「默认连接必须保持本地,不得在公共接口暴露控制面」的要求一一对应。
4.2 本地监听器的资源边界
rpc/local.rs 定义 LocalListenerLimits(全部来自 config.rpc.max_local_connections 等配置):
max_connections:并发连接上限(钳制在 tokioSemaphore::MAX_PERMITS内,防止配置异常拖垮监听器);write_timeout(30s)、initialize_timeout(30s)、frame_read_timeout(30s);- 帧上限
MAX_FRAME_BYTES = 8 MiB; - 关闭时对拒绝连接的客户端提供限量的拒因通知(
MAX_PENDING_REFUSALS = 16)。
4.3 鉴权:initialize 握手 + 凭证路由
rpc/auth.rs 是 daemon 侧的入站鉴权束,由 initialize 握手与逐方法授权门消费:
- 握手携带
auth_token时,按auth_provider显式选择凭证提供方(默认nativepairing token),选择固定且最终,绝不在提供方之间扫描回退; - 无 token 时使用内核提供的对端凭证(Unix peercred);
- 两者皆无时,仅允许本地连接且无
[users]名单的兼容路径; - 连接鉴权状态只保留非秘密证据(如
native_token_hash的 SHA-256 摘要、OIDC 策略代号),bearer 绝不存活于握手之后,授权代(generation)变更时重新解析授权。
rpc/types.rs 的 InitializeParams 展示了版本协商的关键字段:
protocol_version: u64(默认 1);tui_id(可选的断线重连身份);auth_token与auth_provider(显式凭证选择);InitializeResult回传协商后的protocol_version。
这正是 ADR 要求的「版本化、鉴权化」契约的落点:未来的 zeroclaw-gw 连接同样会经过 initialize 完成版本与身份协商。
4.4 订阅:有界、可重放的流式事件源
rpc/subscription.rs 实现 SubscriptionHub:每个 Source(Logs——logs/subscribe;Events——events/subscribe,仅 observer 帧)持有有界环形缓冲,全部环形共享一个进程级字节预算(默认 16 MiB),游标落后时返回 Read::Lagged 并给出首个缺失序号与可恢复位置,绝不静默丢帧;hub 携带随机 epoch,daemon 重启/重载后客户端以新 epoch 从 1 重新计数。这对仪表盘/事件流的跨进程交付是直接可复用的机制。
4.5 共享的协议类型
crates/zeroclaw-api/src/jsonrpc.rs 提供 ACP server 与运行时 RPC 层共享的 JSON-RPC 2.0 类型:JSONRPC_VERSION = "2.0"、出站 ID 前缀 zc-out-、字段名常量(jsonrpc/method/params/id/result/error),以及保留方向语义的帧错误类型——确保畸形信封也能安全处理。
五、目标架构:微内核视角下的最终形态
5.1 从「单二进制内嵌」到「运行时 + 可选网关」
FND-001:Intentional Architecture 用操作系统微内核类比给出了目标图景:
当前(错误形态):
zeroclaw 二进制
└── gateway
├── Web UI server(React app)
├── REST/WS/SSE API
├── WhatsApp/Linq/Nextcloud/Gmail webhook 处理器
└── 直接访问进程内运行时状态
目标(正确形态):
zeroclaw-kernel
└── 本地 IPC API(Unix socket / 127.x HTTP)
zeroclaw-gw(独立二进制,可选)
├── 连接 kernel 的 IPC API
├── Web UI server
├── REST/WS/SSE API
└── 通用 webhook 代理 → 路由到 channel 插件
5.2 独立进程的价值场景
FND-001 明确点出该形态的关键收益,也是 ADR-007 的核心动机:
当网关是独立进程时,它可以崩溃、重启或缺席而不影响 agent,kernel 持续运行。
典型场景是边缘硬件:Raspberry Pi 上运行 kernel,Web UI 由 VPS 上的网关进程提供,kernel 通过 channel 插件出站连接,因此无需任何入站防火墙规则——入站暴露面被压缩到最小,与 ADR-007「默认连接保持本地、不在公共接口暴露控制面」的安全底线完全一致。
5.3 发行形态与稳定性分级
FND-001 进一步给出了 zeroclaw-gw 的发行规划:
zeroclaw-gw网关二进制与 kernel 使用同一平台矩阵(x86_64-unknown-linux-musl、aarch64-unknown-linux-gnu、armv7-unknown-linux-gnueabihf、macOS/Windows 目标),发布时与 kernel 并列,用户单独安装;- 稳定性分级中,
zeroclaw-gw处于 Beta(v0.9.0 → v1.0.0):功能可用、已测试,MINOR 版本允许破坏性变更但需在 changelog 中公告升级说明; - 桌面形态由 Tauri 应用 apps/tauri 承载:
externalBin将运行时作为 sidecar 打包,架构图将zeroclaw-desktop描述为「bundles zeroclaw-gw as a sidecar」。
5.4 版本化与兼容策略
统一版本模型(workspace 单版本)下,FND-001 定义了 IPC 契约变更的升级语义:
- MAJOR:kernel IPC API 不兼容变更(网关或外部客户端破坏)、配置 schema 迁移、CLI 命令移除;
- MINOR:新能力、新稳定 API、稳定性分级晋升;
- PATCH:bug 修复与安全补丁。
这正是 ADR-007「兼容性策略在运行时与网关版本可不同时必须存在」的治理机制:一旦 runtime 与 gateway 可以独立升级,IPC 契约的版本号与不兼容变更门槛就同时约束了两侧的发布节奏。
六、后果分析:收益与代价
ADR-007 明确列举了进程提取的双向后果,这是决策记录中最具操作参考价值的部分。
6.1 正面后果
- 无头/受限部署可完全省略 Web 表面:不链接、不启动网关即可运行;
- 网关崩溃、重启、升级与 agent 执行隔离:故障半径被限制在传输面;
- IPC 契约为桌面应用及其他可信本地客户端提供明确的集成边界:Tauri 桌面端、CLI 工具可共用同一条受支持契约;
- 跨边界访问显式化后,运行时与网关的职责归属更易测试与推理。
6.2 负面后果
- 多进程的安装、启动、鉴权、日志与诊断比进程内函数调用复杂;
- 流式数据与大型 payload 必须穿越序列化边界(JSON-RPC 帧,8 MiB 帧上限即是该代价的体现);
- 运行时与网关版本可不同时,必须存在兼容性策略(见 5.4 的版本升级语义);
- 对等能力完成前,维护者须同时支撑「进程内接缝」与「目标进程边界」两条路径——这是中间接缝模式的典型过渡成本。
七、验收条件:本 ADR 从 proposed 转正的四个前提
ADR-007 目前状态为 proposed。它明确给出四条验收条件,全部满足前不视为完成:
- 受支持的
zeroclaw-gw二进制通过文档化的本地 IPC 契约与运行时通信; - IPC 边界在不直接访问进程本地状态的前提下,覆盖受支持的 dashboard 与 API 体验所需的全部网关能力;
- 鉴权、版本协商、重连、健康检查、启动与关闭行为均已实现并文档化;
- 受支持的运行时发行版可以在不链接或启动网关服务器的情况下运行。
对照当前仓库:第 4 条已具备清晰的验证路径(根 Cargo.toml 中 gateway 为 optional feature、src/main.rs 按 feature 编译网关模块、FND-001 规划了 lean kernel 二进制 + plugin install 的形态);第 1~3 条所需的底层构件(本地传输、initialize 握手、协议版本、订阅重放、连接活动跟踪与优雅排空)在 zeroclaw-runtime/src/rpc 中已就位,但完整的 zeroclaw-gw 独立二进制与端到端 IPC 对等仍未在仓库中出现——这与 ADR 的 proposed 状态完全一致。读者在阅读或部署时,应将当前 zeroclaw-gateway crate 视为「迁移中的中间接缝」,而非最终进程形态。
八、结论
ADR-007 是 ZeroClaw 从「架构上独立、进程上耦合」走向「真正的进程隔离」的关键路线图。它回答了一个具体的工程问题:当 Web 表面拥有自己的 crate 却仍与 agent 运行时共享进程生命周期时,如何在不牺牲安全性与可运维性的前提下把它彻底拆出去。 其答案——独立的可选 zeroclaw-gw 进程、必须鉴权/版本化/文档化的本地 IPC 契约、以及「无网关可运行」的运维底线——与仓库中已存在的运行时 RPC 层(本地传输、initialize 握手、有界订阅、优雅排空)构成了完整的实现拼图。理解这条决策链,是深入 ZeroClaw 微内核架构、评估边缘部署形态、或为桌面端集成设计边界的第一站。
延伸阅读
- ADR-002:Trait 驱动的扩展性:网关能力所依赖的
Channel、Tool、Memory等契约来源; - ADR-006:运行时 Channel 插件:与 ADR-007 同期提出的可选通道插件化方向,网关只保留通用 webhook 入口;
- FND-001:Intentional Architecture:目标架构图、发行矩阵与稳定性分级;
- 架构 Crate 地图、Channel 运行时生命周期;
- Gateway API:网关外部 API 与 channel-plugin webhook 入口的当前行为;
- 源码锚点:
crates/zeroclaw-gateway、crates/zeroclaw-runtime/src/rpc、crates/zeroclaw-api/src/jsonrpc.rs。