OpenSandbox Ingress通配符主机路由实战一个域名服务所有沙箱【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox 使用OpenSandbox Ingress的通配符主机路由Wildcard Host Routing你只需配置一个域名如*.sandbox.example.com就能让成百上千个沙箱实例各自拥有独立、稳定的访问地址——无需为每个沙箱单独分配端口或域名。本文是一份面向新手的实战指南带你快速掌握这套路由机制的原理、配置与排错方法。为什么需要通配符主机路由在 AI Agent 场景下沙箱是动态创建、随生随灭的Agent 今天跑 10 个沙箱明天可能跑 1000 个。传统做法——为每个服务开一个公网端口——显然无法扩展。OpenSandbox Ingress 是一个 HTTP/WebSocket 反向代理组件源码位于 components/ingress/它解决的核心问题是让所有沙箱共享同一个 Ingress 入口和同一个通配符域名通过主机名Host自动把流量分发到正确的沙箱和端口。路由原理一个域名如何区分上千个沙箱主机名解析规则通配符模式的核心在于主机名的结构化命名。当请求到达 Ingress 时它会解析Host头中最左侧的 DNS 标签沙箱ID-端口.sandbox.example.com解析逻辑非常直观见 components/ingress/pkg/proxy/host_route_parse.go片段含义示例最后一个-之后目标端口号8080最后一个-之前沙箱 ID可含多个连字符my-sandbox-01后面的父域名仅用于路由不参与鉴权sandbox.example.com也就是说my-sandbox-01-8080.sandbox.example.com会被解析为「沙箱my-sandbox-01的 8080 端口」然后 Ingress 查询该沙箱的后端端点Kubernetes CR 或 FastPath把请求透明转发过去。原始请求路径完整保留沙箱里的应用完全感知不到自己被代理了。三种路由模式对比OpenSandbox Ingress 提供三种路由模式通配符模式是最适合对外暴露服务的模式路由信息位置典型 URL 形态适用场景wildcard通配符Host头https://id-8080.sandbox.example.com/api对外暴露、可分享链接 ✅header请求头OpenSandbox-Ingress-To头任意域名 自定义请求头客户端可编程修改头部uri路径URL 路径https://gw.example.com/id/8080/api无法改 Host 或请求头时三种模式的解析入口统一在 components/ingress/pkg/proxy/host.go 中通配符和 header 模式共用同一套主机名解析逻辑。一步到位通配符网关配置教程第 1 步准备通配符域名为你的服务申请一个支持泛解析的域名例如*.sandbox.example.com并将 DNS 的泛解析记录指向 Ingress 服务的入口 IP。第 2 步配置 OpenSandbox Server在服务器配置文件如~/.sandbox.toml中启用网关模式关键有三处完整示例见 docs/guides/secure-access.md[ingress] mode gateway [ingress.gateway] address *.sandbox.example.com # 必须是通配符域名 [ingress.gateway.route] mode wildcard # 通配符路由模式⚠️常见坑配置校验器会强制检查——wildcard模式的address必须是通配符域名如*.example.com反过来header/uri模式则不允许地址含通配符校验逻辑见 server/opensandbox_server/config.py。如果使用 Helm 部署同样的配置通过opensandbox-server图表的server.gateway项暴露见 kubernetes/charts/opensandbox-server/。第 3 步创建沙箱并获取访问地址创建沙箱后调用 GetEndpoint 接口即可拿到该沙箱某端口的公网 URLcurl -s http://localhost:8080/v1/sandboxes/${SANDBOX_ID}/endpoints/8080 # → https://sandbox-id-8080.sandbox.example.com/你也可以用 CLI 查看当前所有沙箱从中拿到sandbox-id见 cli/README.md进阶实战签名短时效 URL安全地分享沙箱通配符域名意味着任何拿到主机名的人都能尝试访问——如果沙箱开启了安全访问secureAccess: trueIngress 会要求调用方先证明自己有权访问。这时签名短时效 URL就派上用场了EXPIRES$(( $(date %s) 3600 )) # 有效期 1 小时 curl -s http://localhost:8080/v1/sandboxes/${SANDBOX_ID}/endpoints/8080?expires${EXPIRES} # → https://{sandbox_id}-8080-{expires_b36}-{signature}.sandbox.example.com/生成的 URL 形如my-sandbox-8080-x2qxvk-aabbccddk.sandbox.example.com这个四段式标签由{沙箱ID}-{端口}-{过期时间(base36)}-{签名}组成Ingress 会逐段校验签名和过期时间。URL 到期即失效非常适合把沙箱临时分享给用户或第三方系统无需暴露长期有效的访问令牌。这套机制的完整设计规范见 oseps/0011-secure-access-endpoint.md实现细节可查阅 components/ingress/pkg/signature/。实战场景通过通配符域名访问 VS Code 开发环境以远程开发场景为例沙箱内运行 Code ServerVS Code Web你只需把 GetEndpoint 返回的地址贴进浏览器同样地Jupyter Notebook、Web UI、WebSocket 终端等所有服务都能以相同方式暴露——一个域名服务所有沙箱的所有端口。排错指南404、503、401 分别意味着什么遇到访问失败时先按错误码对号入座行为定义见 docs/components/ingress.md状态码含义常见原因与排查400路由格式错误主机名不合法、端口不是数字签名 URL 的expires参数格式错误401鉴权失败签名 URL 已过期、签名不匹配、安全访问开启但未携带凭据404沙箱不存在沙箱 ID 打错、沙箱已被删除、或不属于 Ingress 可访问的命名空间503沙箱未就绪副本数不足、后端端点缺失稍后重试Retry-After头会提示等待时长502上游错误Kubernetes API 异常等需检查集群状态健康检查访问 Ingress 的/status.ok端点可确认其存活状态/status.ok/network-readiness则提供上游网络质量的影子评估。WebSocket 排错小贴士如果你的前端是 HAProxy 等支持 HTTP/2 的 L7 代理且浏览器报WebSocket close 1006请确认 Ingress 侧的握手走的是 HTTP/1.1Ingress 只接受 RFC 6455 的Upgrade握手。验证方法与完整策略表见 docs/components/ingress.md 的 L7 Frontend 章节。小结 通过OpenSandbox Ingress 通配符主机路由你获得了一个域名承载无限沙箱id-port.domain结构化命名自动分流端口级隔离同一沙箱的多个服务端口各得其所安全分享签名短时效 URL到期自动失效WebSocket 全支持终端、Jupyter、浏览器自动化等场景开箱即用延伸阅读Ingress 组件文档docs/components/ingress.md安全访问指南docs/guides/secure-access.md路由解析源码components/ingress/pkg/proxy/host_route_parse.go开发指南components/ingress/DEVELOPMENT.md【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考