沙箱生命周期 Webhook
CubeMaster 向运维配置的接收端 POST 生命周期通知。静态订阅作用于整个集群,默认关闭, 不是 SDK 管理的用户级订阅。Webhook 只观察既有业务结果,投递失败不改变这些结果。
开启通知
- 准备接收 JSON POST 的服务,处理重复请求,接纳下游工作后及时返回 2xx。
- 将此块合并到各 Master 配置,替换占位 URL。保留其它平台设置,包括业务 Redis。
- 使用一致配置重启所有 Master。运行中的订阅不热更新。执行真实沙箱操作, 检查接收端记录和 Master 指标。
webhooks:
enabled: true
ingress_capacity: 1024
workers: 4
request_timeout: 5s
max_attempts: 3
store:
max_records: 10000
subscriptions:
- id: lifecycle-receiver
enabled: true
url: https://receiver.example.com/cubesandbox/events
events:
- sandbox.lifecycle.created
- sandbox.lifecycle.resumed
- sandbox.lifecycle.paused
- sandbox.lifecycle.checkpointed
- sandbox.lifecycle.updated
- sandbox.lifecycle.killed全局和订阅 enabled 必须都为 true。过滤精确匹配完整事件名,不接受通配符和重复事件。 订阅 ID 必须非空且唯一,用于标识订阅,不是沙箱 ID。
webhooks 下的设置 | 默认值 | 接受范围 / 含义 |
|---|---|---|
enabled | false | 全局开关 |
ingress_capacity | 1024 | 每 Master 1–4096 个捕获事件 |
workers | 4 | 每 Master 1–32 个投递 worker |
request_timeout | 5s | 整次 HTTP 操作 1ms–1m |
max_attempts | 3 | 1–1000 次尝试,包含首次 |
store.max_records | 10000 | 每 Master 1–1000000 个 pending + inflight 目标任务 |
allow_http | false | 显式允许私网/本地 HTTP |
allowed_cidrs | 空 | 最多 64 个有效 CIDR,允许私网/回环目标 |
subscriptions | 空 | 最多 64 个订阅 |
subscriptions[].enabled | false | 订阅开关 |
subscriptions[].id, .url, .events | 未设置 | 必填;ID ≤1024 字节,URL ≤4096 字节,1–6 个不同的支持事件 |
这些数量限制不是进程 RSS 上限。全局开启但没有活动订阅时,不执行捕获或投递。 关闭时跳过通知准备;开启后仍消耗 CPU 和内存。
事件与成功边界
| 完整事件名 | CubeMaster 观察到成功的时点 |
|---|---|
sandbox.lifecycle.created | 公开创建获得既有成功结果并完成成功分支后处理。普通模板快速启动仍为 created。 |
sandbox.lifecycle.resumed | 公开创建从可信用户快照模板启动成功,或暂停恢复的最终代理 purge 成功。不能仅凭调用方 annotation/ID 前缀判为快照。 |
sandbox.lifecycle.paused | Cubelet 本地暂停和 Master pausesnap.Complete 成功。 |
sandbox.lifecycle.checkpointed | 实际执行的快照任务完成本地工作并持久化 READY,位于最终查询前。后续查询失败不撤回通知;只查询 READY 不重复发布。 |
sandbox.lifecycle.updated | 公开 SetTimeout/Refresh 返回可用有限截止时间,或既有节点网络更新成功。best-effort spec 写失败不撤销节点网络成功。 |
sandbox.lifecycle.killed | 既有同步销毁调用或异步 destroy handler 成功,包括原有容忍/warn-only 情况。任务入队成功不发布。 |
XFS 与 S3 的 pause/checkpoint 都表示本地成功,不表示 S3 上传完成、远端耐久性或 跨节点恢复能力。后续上传状态不撤回或重复事件。创建、暂停、READY 写入或最终 resume purge 失败,不发布其对应成功事件。内部创建回滚、暂停拆除和 resume timeout 刷新不 额外产生用户级 killed/updated。Mock 旁路不是真实生命周期通知入口。
创建取消遵循既有业务结果:取消先赢、操作返回失败时,后台随后成功和内部回收均不发布 created/resumed/killed。若业务成功先返回,之后请求在通知 hook 前取消,不抑制 created 或用户快照 resumed。投递仍为 best effort。
SetTimeout 接受正数秒数、0(立即截止)和 -1(永不超时),-1 不发 timeout-only 事件。Refresh 只接受正数秒数,拒绝 0 和负数。有限成功响应的 EndAt > 0 即可发布, provider 缺失或失败时也可能如此,因为截止时间可由既有 fallback 提供。 这不确认 Redis HSET 或 XADD 成功。 Resume 内部刷新不发布 updated。 重复成功操作可各自产生新事件。
Killed 遵循原业务对缺节点、nil/not-found 响应和 warn-only 清理的成功规则,不增加 物理销毁或 binding 删除完成的独立证明。业务重试仍执行原节点调用,通知不引入完成门控 或生产端去重。
接收与去重
| Header | 值 |
|---|---|
Content-Type | application/json |
e2b-webhook-id | 配置的订阅 ID |
e2b-delivery-id | 每次投递尝试的新 UUID |
Payload id 和原始正文在重试及多订阅 fanout 间不变。按 payload id 去重,必要时 加入订阅作用域。Delivery ID 标识一次尝试,不是幂等键。先保存必要下游工作再确认, 容忍并发、乱序和重复。接收成功但响应丢失也可能导致重试。
任意 2xx 表示成功。非 2xx(含 3xx/4xx/5xx)、网络错误和超时受有限预算约束。Claim 即消耗一次,因此取消、身份生成或地址校验可能在 HTTP Header 写出前消耗预算。 指数退避带抖动,最高 30s。预算耗尽后,接收端恢复也不会自动重放。
Payload 兼容性
本功能首版沿用现有 v2 payload,不宣称完整兼容 E2B 字段/操作。路径相对 JSON 根。
| 字段 | 来源及空值/省略规则 | 接收端影响 |
|---|---|---|
id | 成功时捕获的 UUID | 稳定的事件去重键 |
version | 固定 "v2" | 不是功能/签名版本 |
type | 六个完整名称之一 | 精确匹配 |
timestamp | 捕获时的 UTC RFC3339Nano 时间 | 不是 HTTP 发送时间或执行起点 |
sandbox_id | 真实响应/请求沙箱 ID | 不是 E2B execution ID |
sandbox_template_id | 可信创建解析结果或本来已读的 spec,否则 "" | Timeout/network/killed 不为补字段查询 |
sandbox_execution_id | "";无等价执行身份 | 严格 UUID/必填值解码器可能拒绝 |
sandbox_build_id | "";无可信构建身份 | 不用 job/snapshot ID 替代 |
sandbox_team_id | "";无等价 team | 严格 UUID/team 校验可能拒绝 |
event_category | "",保留键 | 不伪造旧分类 |
event_label | "",保留键 | 不伪造旧标签 |
events_ttl_days | 省略 | 无事件历史留存服务 |
event_data | 空时省略 | 不假定总是存在 |
event_data.sandbox_metadata | 可信当前公开创建输入,模板合并前取得;nil/未知省略,已知空 {} | 用户快照创建可携带当前输入;后续操作不继承 |
event_data.execution | 仅 paused/killed;至少 {"started_at":""} | 需容忍部分数据 |
event_data.execution.started_at | "";无可靠执行起点 | 空字符串不是有效 RFC3339 |
event_data.execution.execution_time | 省略;无可靠时长 | 不伪造零,不用于计费 |
event_data.execution.vcpu_count | 已有单容器 cubebox CPU 为精确正整数时填写,否则省略 | 1000m → 1;1500m 省略 |
event_data.execution.memory_mb | 已有单容器 cubebox 内存,先向上取整字节再取整数 MiB,否则省略 | 1Gi → 1024,512M → 488,1.5Mi → 1 |
event_data.set_timeout | 捕获的有限响应 EndAt,UTC RFC3339 秒精度 | 可来自 fallback;不确认持久化,不编码 -1 |
event_data.network_egress.allowed_cidrs | 请求 IPv4 IP/CIDR;IP → /32,CIDR 规范化;空 null | 不是完整策略 diff;保留显式 DNS IP |
event_data.network_egress.denied_cidrs | 请求 IPv4 deny;internet false 覆盖为 ["0.0.0.0/0"];空 null | Internet true/nil 使用本次请求 DenyOut |
event_data.network_egress.allowed_domains | AllowOut 域名/通配符,转小写去尾点;空 null | 无 L7 Rules/Inject/凭据或节点注入 DNS |
event_data.pause_mode | 当前已确认暂停路径为 "full" | 不是内部 snapshot_type |
event_data.resume_mode | 当前暂停/用户快照恢复路径为 "restore" | 不承诺未来所有路径 |
event_data.kill_reason | 保留显式原因;已知用户请求 "request",超时 "timeout",无来源 "unknown" | 不含内部错误文本,不额外通知清理 |
Metadata 排除精确的 host-mount、X-Caller 和 cube.master. 命名空间;普通用户键 含 token/secret/password 仍是用户数据,接收端日志应按此处理。创建捕获允许 64 个用户项、 key/value 共 16 KiB、key ≤256 字节、value ≤4096 字节。未知 metadata 不从合并标签、 缓存或私有存储字段补回。超限丢弃整条通知,不截断,不使业务失败。
资源字段与缺失时间独立。其它实例类型、多容器、非法/分数 CPU 和未知数量不猜测; 当前 killed 生产者无资源来源。网络投影不表达 IPv6 策略(当前节点拒绝)、全部 L7-only 变化或内部 DNS/私网规则,不补 E2B 默认 DNS。空分类是 null,包括空列表经 protobuf 往返后;要求 [] 的接收端需适配。
无 secret、自定义认证 Header、签名、e2b-signature、e2b-signature-version 或其它版本 Header。Header 和 ID 不能认证发送者。强制验签接收端不兼容,选择集成方式时 保留其安全要求。无动态订阅 CRUD、用户级订阅和公开测试事件 API。
编码示例
此例为既有 TestEncodeSixEvents 的 created fixture,输入来自 capture_test.go 的 captureInput,已对照当前编码器核对。ID/时间是测试数据,不是生产观测。Metadata 未知时省略 event_data;公开创建中已知空 metadata 则包含 sandbox_metadata: {}。
{
"id": "d12727fc-ab97-43d8-80cf-556cc1215017",
"version": "v2",
"type": "sandbox.lifecycle.created",
"timestamp": "2026-10-14T12:00:00Z",
"event_category": "",
"event_label": "",
"sandbox_id": "sb-1",
"sandbox_execution_id": "",
"sandbox_template_id": "tpl-1",
"sandbox_build_id": "",
"sandbox_team_id": ""
}容量、丢失与退出
每 Master 有两级上限,由该 Master 全部订阅共享:
- Ingress 按等待 writer 的捕获事件计数,满时丢弃事件。
store.max_records按目标任务计数,含 pending 重试和 inflight HTTP。一个事件匹配 三个订阅需三条记录。Fanout 可部分成功,任务满时丢该目标,不等空位。Retry 复用原记录, 成功/耗尽/取消释放容量。
每个目标任务的编码正文最多 256 KiB。目标副本和 worker/transport 也占用内存, 因此这些上限不限制进程 RSS。
通知状态由 DeliveryStore 后的进程内存保存。重启、崩溃或退出可丢失剩余工作。 各 Master 不共享通知积压、不互相接管。无磁盘/Redis 持久化、严格顺序、恰好一次、 零丢失、历史/查询或 replay API。Redis 持久化/HA 留待后续,业务 Redis 仍是平台依赖。 部分 webhook 联合集成测试有意经过业务 Redis→内存 Runtime→HTTP, 这不构成通知 Redis backend。
Webhook 先停止接收,在单一两秒总预算或 caller 更早截止时间内尽力 drain,然后 取消通知 HTTP/等待并丢弃剩余工作。不保证全部投完,也不限制整个 App/systemd 两秒退出。 SIGKILL 跳过 drain。
App 组装当前 memory + HTTP adapter。Go 调用者可通过公开 NewRuntime、通用 options 和静态订阅注入 DeliveryStore / DeliverySender;没有新增 backend YAML 键或 持久实现。Put/Claim/Retry/Complete 均有界(App 为 1s),清理共享剩余退出预算。 Complete 失败不能确认终态;Close 只统计实际丢弃,未来持久 backend 保留的工作不算 丢弃。实现必须遵守 context 取消,sender.Close 只做快速本地释放。
HTTP 与配置安全
公网目标要求 HTTPS,正常验证证书/主机名。私网/回环 HTTPS 还要求显式匹配的 allowed_cidrs。本地 HTTP 测试时将此例外合并到 webhooks,并将订阅 URL 改为 http://127.0.0.1:18096/events:
allow_http: true
allowed_cidrs: ["127.0.0.1/32"]HTTP 必须同时显式开启并匹配私网/回环 CIDR,公网 HTTP 仍被阻止。远端 Master 使用 接收端实际可达的精确网段。CIDR 不关闭 TLS,不放行 metadata、link-local、未指定、 组播或文档地址等被禁特殊地址。全部 DNS 结果均须符合策略,混合允许/禁止结果被拒绝。 新连接直接拨号到已检查 IP,已检查连接可复用。禁环境代理、重定向和自动 POST 重放。 拒绝 URL 用户凭据/fragment、未知键和错误类型。响应 body 读取 8 KiB、Header 16 KiB。
非法 webhook 配置只禁用通知,诊断脱敏 webhook 值。主 YAML 非法或其它模块仍沿用 原错误策略,不承诺独立修复通用配置日志。API 健康不代表 webhook 已开启。
敏感撤销前先停止全部旧投递实例,再应用新启动配置;混合配置期间仍可发给旧目标。 已开始请求无法撤回。重启丢弃旧内存积压,新订阅不接收历史事件。
排查与验证
| 指标 | 含义 |
|---|---|
cubemaster_webhook_operations_total{operation,result} | 本地 capture/ingress、映射/编码、put/claim/complete/retry、send/HTTP/status 和终结结果 |
cubemaster_webhook_claim_age_seconds | 领取时距目标任务创建的年龄直方图,含重试;不是执行时长 |
cubemaster_webhook_ingress_depth | Writer 观察的本地缓冲深度,可能落后于接收;不是目标任务积压 |
cubemaster_webhook_inflight | 本地活动 worker 任务,含发送前检查 |
常用计数对:capture/oversized、ingress/full、event/unmatched、put/capacity、 http/attempt、http/success、terminal/failed、terminal/cancelled、 task/shutdown_discarded、ingress/unprocessed_shutdown。HTTP attempt 计 Header 写出,不是 Claim 或接收端确认处理次数。有限诊断标签不是持久历史,无共享 Redis backlog 指标。
HTTP attempt/status/success 仅由 HTTP adapter 计数。send/timeout 表示单次截止或 传输超时,send/cancelled 表示显式取消。请求超时仍按有限预算重试,最终可为 terminal/failed。HTTP 2xx 与 Runtime 终态是不同层次,取消可在 Complete 前生效。 非 HTTP sender 根据 SendResult.Succeeded 成功,无需 HTTP 状态。
漏通知先查两级启动开关、精确过滤、真实业务成功点、capture/ingress 丢弃、mapping/put 结果,再查接收端 HTTP 状态、超时与地址/TLS 策略。确认是否重启或预算耗尽。 不要放宽 TLS 或改业务来获得通知,真实操作见沙箱生命周期。
仓库webhook 测试运行说明 提供有界本地 receiver、环境示例、组件检查和真实 SDK 六事件命令。 SDK 测试 README 说明现有 requirements 和平台 preflight。使用已有匹配工具链。Receiver/framework 自测和 collection 不证明部署中的 Master/Cubelet、XFS/S3、TLS 或故障场景通过。只运行已准备的 适用场景,保留初次失败,区分跳过、仅收集和未运行。文档检查不是生命周期验收。
迁移早期 PR 试用配置
删除 store.backend、store.redis、lease、旧 store 连接池键、operation_timeout 和 terminal_retention,通知 store 块只保留 store.max_records。废弃键通过严格校验 禁用通知,不静默选择内存或保留耐久性。无自动 Redis→memory backlog 迁移或重放。 核对两级开关、订阅和容量后重启所有 Master,平台业务 Redis 配置原样保留。