Skip to content

沙箱生命周期 Webhook ​

English guide

CubeMaster 向运维配置的接收端 POST 生命周期通知。静态订阅作用于整个集群,默认关闭, 不是 SDK 管理的用户级订阅。Webhook 只观察既有业务结果,投递失败不改变这些结果。

开启通知 ​

  1. 准备接收 JSON POST 的服务,处理重复请求,接纳下游工作后及时返回 2xx。
  2. 将此块合并到各 Master 配置,替换占位 URL。保留其它平台设置,包括业务 Redis。
  3. 使用一致配置重启所有 Master。运行中的订阅不热更新。执行真实沙箱操作, 检查接收端记录和 Master 指标。
yaml
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 下的设置默认值接受范围 / 含义
enabledfalse全局开关
ingress_capacity1024每 Master 1–4096 个捕获事件
workers4每 Master 1–32 个投递 worker
request_timeout5s整次 HTTP 操作 1ms–1m
max_attempts31–1000 次尝试,包含首次
store.max_records10000每 Master 1–1000000 个 pending + inflight 目标任务
allow_httpfalse显式允许私网/本地 HTTP
allowed_cidrs空最多 64 个有效 CIDR,允许私网/回环目标
subscriptions空最多 64 个订阅
subscriptions[].enabledfalse订阅开关
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.pausedCubelet 本地暂停和 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-Typeapplication/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"];空 nullInternet true/nil 使用本次请求 DenyOut
event_data.network_egress.allowed_domainsAllowOut 域名/通配符,转小写去尾点;空 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: {}。

json
{
  "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:

yaml
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_depthWriter 观察的本地缓冲深度,可能落后于接收;不是目标任务积压
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 配置原样保留。