AgentENV反向代理设计详解HTTP、SSE与WebSocket如何路由进沙箱【免费下载链接】AgentENVAgentENV (AENV) is a distributed platform for running agent environments at scale.项目地址: https://gitcode.com/gh_mirrors/age/AgentENVAgentENVAENV是运行大规模 AI Agent 环境的分布式平台其内置反向代理是访问沙箱内服务的唯一数据面入口一个 HTTP 反向代理端点就能把普通请求、SSE 流和 WebSocket 长连接无缝路由进 Firecracker microVM 沙箱内部。本文带你快速看懂它的路由方式、流式转发机制与自动恢复行为。为什么需要反向代理沙箱本质上是隔离的 microVM宿主机外部无法直接访问其内部网络。AgentENV 在每个节点上都运行一个反向代理客户端请求先到 API 服务器代理解析出去哪个沙箱、哪个端口再转发到沙箱交互网络上的目标服务。在多节点部署中链路是Gateway → Scheduler → 节点代理网关从请求头或 Host 域名中解析出沙箱路由向调度器查询归属节点再把数据面请求转发到该节点。网关只做路由不做沙箱鉴权——鉴权由拥有沙箱的运行时统一执行详见 架构文档。四种把流量送进沙箱的写法 AgentENV 提供了四种入口覆盖不同客户端习惯源码src/api/proxy.rs入口形式转发行为/proxyANY /proxy转到沙箱内的//proxy/{path}任意路径前缀剥掉/proxy前缀后转发路由头兜底其他未匹配路径 沙箱路由头原样转发请求路径Host 域名{port}-{sandboxID}.{domain}原样转发无需任何路由头其中路由头兜底是关键设计客户端可以把API_URL直接当作沙箱数据面地址使用无需手动拼/proxy这与 E2B 的用法完全兼容。Host 域名方式则让http://8080-sandbox-uuid.example.com/status这样像真实域名的 URL 直接可用网关侧解析逻辑见 host_route.go。请求的两个要素沙箱 ID 目标端口无论哪种入口代理最终都要求两个字段路由头如下请求头说明E2B 兼容别名x-agentenv-sandbox-id目标沙箱 UUIDe2b-sandbox-idx-agentenv-target-port沙箱内服务端口e2b-sandbox-port校验规则很明确沙箱 ID 必须是合法 UUID端口必须是大于 0 的u16解析实现。请求转发前这些路由头会被剥离不会泄露给沙箱内应用同时会注入x-forwarded-host、x-forwarded-proto等标准转发头。 鉴权小知识X-API-Key只是控制面凭证永远不是数据面凭证。公开沙箱直接放行私有入口allowPublicTraffic: false需要e2b-traffic-access-token安全模式 envd 端口需要X-Access-Token。HTTP 与 SSE流式直通不是缓冲搬运很多代理会把响应体缓存完再吐出而 AgentENV 的 HTTP 请求体和响应体都是流式代理——SSE 事件流、大文件上传下载都能原样穿透HTTP 转发语义查询字符串原样转发百分号编码与连续斜杠都保留请求体上传阶段按每收到一个数据帧就重置空闲计时器的方式计时长上传不会误触发 30 秒超时请求与响应的 hop-by-hop 头Connection、Upgrade等在双向路径上都会被清理。一个典型的访问示例curl http://127.0.0.1:8000/proxy/health?fulltrue \ -H x-agentenv-sandbox-id: sandbox-uuid \ -H x-agentenv-target-port: 8080WebSocket同一个入口双向帧桥接WebSocket 升级请求走的是同一组/proxy端点不需要单独地址。流程是桥接实现校验客户端的升级请求并转发上游完成握手握手成功后建立客户端 ↔ 沙箱之间的双向帧桥接上游选定的子协议subprotocol会传播回客户端应用层头也保留给客户端可见。握手失败时的行为也很克制上游以 HTTP 状态拒绝如401/403/404就原样透传状态与响应体连接失败返回502握手超时返回504。自动恢复请求打到了暂停中的沙箱暂停Paused的沙箱并非不能访问。代理的路由查找会返回一个状态枚举ProxyLookupResult代理据此决策Ready正常转发Paused 允许自动恢复代理会替用户尝试一次恢复恢复超时上限 60 秒沙箱超时保底 5 分钟成功后请求照常转发Paused 不允许恢复返回410 Gone恢复失败 / 路由缺失502 Bad Gateway恢复超时504 Gateway Timeout。路由表本身是一张内存哈希表ProxyRouteTable只有Running状态的沙箱会发布路由热路径读取几乎无锁这也是暂停→恢复→转发能做到毫秒级状态判断的基础。错误码速查表 状态码触发场景400 Bad Request路由头缺失/非法、端口非法、Host 路由格式错误404 Not Found沙箱不存在410 Gone沙箱已暂停且不允许自动恢复502 Bad Gateway上游连接失败、运行中沙箱路由缺失、自动恢复失败504 Gateway Timeout自动恢复超时、上游响应头超时、WebSocket 握手超时继续深入阅读清单设计文档proxy-design.md —— 路由契约、生命周期竞态加固全在这里用户文档sandbox proxy节点代理实现src/api/proxy.rs运行时路由表src/orchestrator/proxy.rs网关侧 Host 路由services/gateway/internal/host_route.go端到端代理测试scripts/tests/e2e/suites/06_proxy.sh一句话总结AgentENV 反向代理用一个入口 路由头/域名两种寻址方式配合流式直通、WebSocket 桥接和暂停自动恢复把沙箱内服务的访问体验做到了与直连几乎无差——这正是 Agent 平台即开即用体验背后最不起眼、却最关键的一环。✨【免费下载链接】AgentENVAgentENV (AENV) is a distributed platform for running agent environments at scale.项目地址: https://gitcode.com/gh_mirrors/age/AgentENV创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考