管理 Agent Sandbox 入口流量 - 容器计算服务 ACS

背景信息

自 ack-sandbox-manager 组件 v0.5.2 版本起，系统引入了 SandboxGateway 功能。

在默认配置下，Ingress 会将控制面（api.{domain}）与数据面（*.{domain}）的流量统一转发至 sandbox-manager 服务。由于控制面与数据面流量未实现物理分离，若控制面组件出现异常，可能会波及 Agent 的业务数据通信。

通过执行流量切换操作，数据面流量将改由 sandbox-gateway 负责转发。此方案实现了控制面与数据面的流量解耦，能够有效降低控制面故障对业务数据传输的影响，提升系统的稳定性。

适用范围

已在集群组件管理中升级 ack-sandbox-manager 组件至 v0.5.2 及以上版本。
已确认 sandbox-system 命名空间下 sandbox-gateway 工作负载的副本数大于等于 1 且 Pod 处于就绪状态。
已在控制面安全组中放行 TCP 7788 端口的入方向流量，允许 Ingress 转发到 sandbox-gateway。
如果已通过 TrafficPolicy 管理 Sandbox 网络策略，需在 Sandbox 侧的策略中放行来自 sandbox-gateway Service 的入方向流量。具体操作，请参见使用TrafficPolicy管理Agent网络访问。

工作原理

完成流量切换后，Ingress 将根据域名匹配规则分发流量：

控制面流量：通过 api.{domain} 访问，继续由 sandbox-manager 处理。
数据面流量：通过 *.{domain}访问，由 sandbox-gateway 负责。sandbox-gateway 会查询本地路由注册表，并根据配置路由规则将请求转发至目标 Sandbox Pod。

具体的流量转发路径如下表所示：

域名	路径	转发服务	说明
`api.{domain}`	`/*`	`sandbox-manager:8080`	控制面流量转发。
`*.{domain}`	`/*`	`sandbox-gateway:7788`	数据面流量转发。

准备工作

进行SandboxGateway的连通性验证。

评估业务流量，按需调整 SandboxGateway 实例配置以适应业务需求（参考使用限制）。
在目标集群详情页，选择工作负载 > 无状态，切换到 sandbox-system命名空间，单击sandbox-gateway工作负载名称进入详情页，确认副本数大于等于1且处于就绪状态。

获取 sandbox-gateway 服务的ClusterIP：

kubectl get svc -n sandbox-system sandbox-gateway -o jsonpath='{.spec.clusterIP}'

按以下模板发起请求，替换占位符后执行：
```
curl -v \
  --resolve "<PORT>-<NAMESPACE>--<NAME>.<DOMAIN>:7788:<SANDBOX-GATEWAY-SVC-IP>" \
  -H "e2b-sandbox-id: <NAMESPACE>--<NAME>" \
  -H "e2b-sandbox-port: <PORT>" \
  -H "X-Access-Token: <SANDBOX-TOKEN>" \
  http://<PORT>-<NAMESPACE>--<NAME>.<DOMAIN>:7788/health
```
预期输出：返回 HTTP/1.1 204 No Content，表示 sandbox-gateway 已将请求成功转发到 Sandbox Pod 内 envd 的健康检查端点。

占位符说明：
- <PORT>：Sandbox 提供服务的端口。未开启其他服务时，使用 envd 默认端口 49983。
- <NAMESPACE>：待验证 Sandbox 所在的命名空间。
- <NAME>：待验证 Sandbox 的名称。
- <DOMAIN>：指向网关的泛域名。
- <SANDBOX-TOKEN>：如开启入方向流量认证，需填写 Sandbox 的 envdAccessToken；未开启时可省略该请求头。

本验证仅覆盖 sandbox-gateway 到 Sandbox Pod 之间的连通性，Ingress 到 sandbox-gateway 流量需通过安全组放行。

流量切换

重要

数据面流量切换存在业务中断风险，建议在业务流量低峰期执行流量切换。执行前请评估业务流量影响，并按准备工作完成切换前验证，避免引发网络问题。

在控制台组件管理中，选择 ack-sandbox-manager 的配置，将 dataplaneService 切换为 sandbox-gateway。
（可选）如仅需通过 HTTP 协议访问 SandboxManager（无需配置 TLS 证书），在同一配置界面取消勾选 Whether to enable TLS for ingress。
在对应的负载均衡控制台验证转发路径已切换到 sandbox-gateway。
1. 通过Ingress资源查询关联的ALB实例名称：
  控制台
  
  在目标集群详情页，选择网络 > 路由，切换到 sandbox-system命名空间，查看sandbox-manager的端点（alb-xxx），前缀即为ALB实例名称。
  kubectl
```
kubectl get ingress -nsandbox-system sandbox-manager -o jsonpath='{.status.loadBalancer.ingress[0].hostname}' | sed -E 's/^(alb-[^.]+).*/\1/'
```
2. 进入ALB控制台，单击目标实例，依次进入监听 > ingress-auto-listener-443 > 转发规则，确认转发动作已修改为 sandbox-system-sandbox-gateway-7788。
在目标集群左侧导航栏，选择运维管理 > 日志中心菜单，切换到应用日志标签页。

在应用日志页面，日志库选择 ack-sandbox-gateway，查看访问日志及运行日志，检查是否存在response_code为非2xx、1xx的异常状态码。如需自行采集监控指标，可参考监控上报。

如需回滚，请参考如果切换后业务异常，如何进行回滚。

展开查看日志字段含义

字段	含义
`start_time`	Envoy 开始处理请求（收到请求行）的 UTC 时间戳，默认为带毫秒的 ISO-8601 格式。
`method`	请求的 HTTP 方法，如 `GET`、`POST`、`CONNECT`。
`path`	包含查询参数的完整请求路径。
`protocol`	下游协议，如 `HTTP/1.1`、`HTTP/2`。如果连接未进入 HTTP 解析阶段则为空。
`response_code`	返回给客户端的 HTTP 状态码。`0` 表示没有发送响应（如下游在响应头发送前已断开）。
`response_flags`	描述特殊响应情况的短码。常见值：`-`（无）、`UH`（无可用上游）、`UF`（上游连接失败）、`UT`（上游超时）、`DC`（下游断开）。
`bytes_received`	从下游客户端收到的请求体字节数（不包含请求头）。
`bytes_sent`	发给下游客户端的响应体字节数（不包含响应头）。
`duration_ms`	请求总耗时（毫秒），从下游收到第一个字节到上游返回最后一个字节（或本地应答）。
`upstream_host`	选定的上游端点地址 `IP:port`。对于 sandbox 流量即 filter 选中的 Sandbox Pod IP 与端口。`-` 表示未选定上游（如本地应答）。
`downstream_remote_address`	Envoy 视角看到的客户端套接字地址 `IP:port`。
`user_agent`	请求头 `User-Agent` 的值，缺失时为 `-`。
`request_id`	请求头 `x-request-id` 的值；客户端未提供时 Envoy 会自动生成，用于跨组件链路关联日志。
`authority`	HTTP/2 `:authority` 伪头（HTTP/1.1 对应 `Host`）。
`upstream_local_address`	Envoy 在上游连接上使用的本地套接字地址 `IP:port`，便于与 gateway 所在节点的 `conntrack`、Pod 网络工具关联。

使用限制

SandboxGateway 默认采用4 vCPU 8 GiB规格并部署 3 个副本。单个副本实例的出入向总带宽为 1.5 Gbit/s，约可支撑 90 MB/s 的业务流量（单个ACS实例支持的出入总带宽以ACS实例规格为准）。如需更高性能，请参考调整 SandboxGateway 规格。

单个4 vCPU 8 GiB实例的承载能力计算公式为：1.5 Gbit/s / 2 （出入双向） / 8（单位转换）≈ 93.75 MB/s。

以上数据为理论评估的上限，阿里云不作为业务指标承诺，请以实际业务场景为准。建议在运行过程中关注业务侧是否存在丢包现象，或通过网关日志监测是否出现502状态码，以评估实际承载性能。

进阶操作

配置路由规则

SandboxGateway 的路由匹配遵循 Header 优先及域名回退原则。系统在处理路由请求时，将优先执行基于 Header 的匹配逻辑；若 Header 未命中，则回退至基于域名的匹配策略。

基于 Header 的路由（优先匹配）

Header	默认名称	是否必填	说明
Sandbox ID 头	`e2b-sandbox-id`	是	沙箱ID。
Sandbox 端口头	`e2b-sandbox-port`	否	Sandbox Pod 内的目标端口，默认为 `49983`。

示例：

curl https://sandbox.domain/sandboxes \
  -H "e2b-sandbox-id: default--my-sandbox" \
  -H "e2b-sandbox-port: 49983"

基于域名的路由

当请求头中缺少 Sandbox ID 时，SandboxGateway 将按照 {port}-{namespace}--{name}.{domain} 的格式匹配 Host 或 authority 字段。

说明

受 DNS解析格式限制，域名最左侧标签 {port}-{namespace}--{name} 的总长度不能超过 63 个字符，否则基于域名的路由将无法正常解析。

字段	说明	示例
`{port}`	Sandbox Pod 上的目标端口。	`49983`
`{namespace}`	Sandbox 所在的 Kubernetes 命名空间。	`default`
`{name}`	Sandbox CR 的名称。	`my-app-v1`
`{domain}`	指向网关的泛域名。	`sandbox.example.com`

示例：

curl https://3000-default--my-sandbox.domain \
  -H "Host: 3000-default--my-sandbox.domain"

监控上报

sandbox-gateway 服务在9902端口配置了 metrics 端点，用于以 Prometheus 标准格式暴露监控指标，可通过 http://<pod_ip>:9902/metrics 地址进行采集（限集群内访问）。

优雅下线

SandboxGateway 支持实例优雅下线。实例下线时，preStop 钩子会调用 POST http://127.0.0.1:9901/drain_listeners?graceful，使在途请求尽可能完成后再结束容器，降低实例缩容或升级对业务的影响。

入方向流量认证

自 ack-sandbox-manager 组件 v0.6.6 版本起，sandbox-gateway 支持对入向请求进行访问令牌校验。sandbox-gateway 提供以下两种认证方式，可按业务凭据管理需要选用：

静态 Access Token 认证（v0.6.6 起）：校验请求头中的 X-Access-Token，Token 值为创建 Sandbox 时响应体返回的 envdAccessToken。适用于凭据静态、生命周期与 Sandbox 一致的场景。
基于 JWT 的动态令牌认证（v0.6.8 起）：校验请求头中的 E2B-Traffic-Access-Token，Token 值为 ack-agent-identity 组件签发的 JWT（JSON Web Token）。适用于需要防重放、多租户隔离，且可通过签发参数配置较短有效期实现凭据限时失效的场景。

展开查看认证方式详细对比

对比维度	静态 Access Token 认证	基于 JWT 的动态令牌认证
凭据定位	复用 Runtime 或 envd 的访问凭据。	数据面代理专用的访问凭据。
Token 格式	随机 UUID。	非对称签名的 Compact JWT。
请求头	`X-Access-Token`	`E2B-Traffic-Access-Token`
签发方	`sandbox-manager`	`ack-agent-identity` 组件
校验方式	对 Token 进行常量时间字符串比对。	本地验证 JWT 签名、标准 Claims 及 Sandbox ID 或 UID 绑定关系。
有效期	在 Sandbox 生命周期内静态不变。	由签发方参数控制，默认 100 年。失效后可重新签发。
泄露后可重放窗口	持续到 Sandbox 销毁。	限制在 JWT 有效期内。
持久化方式	写入 Sandbox CR 的 `agents.kruise.io/runtime-access-token` 注解。	不写入 Sandbox CR，仅在 Claim 返回对象中保留。
开启方式	控制台开启后对所有访问流量生效；与 JWT 校验同时勾选时的生效范围因 `ack-sandbox-manager` 版本而异，详见下方组件版本与勾选项的对应关系说明。	控制台开启后，客户端在创建 Sandbox 时通过 `metadata` 传入 `security.agents.kruise.io/enable-jwt-auth: "true"` 键值才对该 Sandbox 生效。
Token 获取字段	创建响应的 `envdAccessToken`。	创建响应的 `trafficAccessToken`。
SDK 使用方式	envd 端口由 E2B SDK 自动注入；非 envd 端口需手动设置请求头。	所有端口均需手动设置请求头，或按下文 Monkey Patch方案注入。
校验失败响应	HTTP `401`。	HTTP `403`。

静态 Access Token 认证

操作步骤

重要

开启入向流量认证后，未携带认证请求头的存量流量将被拒绝，返回 HTTP 401。请确认所有客户端已完成适配后再执行开启操作，并建议在业务流量低峰期变更。

在集群组件管理中，单击 ack-sandbox-manager 的配置，勾选是否开启入向流量认证，然后单击保存。

sandbox-gateway 需重启以应用变更。重启期间，已建立的长连接将断开，客户端重连后即可恢复，请评估变更影响。
通过 E2B SDK 创建 Sandbox，从 Sandbox 对象中获取 _envd_access_token。以 Python SDK 为例：

重要
_envd_access_token是访问 Agent Sandbox 数据面的关键安全凭证，泄露可能导致业务数据及沙箱环境面临安全风险。请妥善保管该 Token，建议进行加密存储，切勿明文写入代码或日志中。
```
from e2b_code_interpreter import Sandbox

sbx = Sandbox.create(template="code-interpreter")

# 从 Sandbox 实例的私有属性获取（Python SDK 未做脱敏）
access_token = sbx._envd_access_token
```
调用 sbx.run_code、sbx.commands.run、sbx.files.* 等 SDK 原生方法时，E2B SDK 会自动将 _envd_access_token 附加到 X-Access-Token 请求头，无需手动处理。仅当访问 Sandbox 内自建的 HTTP 服务（例如 3000 端口）时，才需要按步骤 3 手动携带该请求头。
访问 Sandbox 内自建的 HTTP 服务时，在请求头中携带 X-Access-Token，示例如下：
```
curl https://<YOUR-DOMAIN>/ \
  -H "X-Access-Token: <ENVD-ACCESS-TOKEN>" \
  -H "e2b-sandbox-id: <NAMESPACE>--<NAME>" \
  -H "e2b-sandbox-port: <PORT>"
```
请求头组合（基于 Header 的路由与基于域名的路由）遵循 SandboxGateway 的路由匹配规则，详见配置路由规则。

认证失败响应

当请求携带的令牌校验失败时，sandbox-gateway 返回 HTTP 401，响应体为：

unauthorized: invalid or missing access token

兼容性说明

入向流量认证默认关闭，升级组件后不影响存量流量，需手动开启。
若创建 Sandbox 时未生成 envdAccessToken，sandbox-gateway 会跳过该请求的令牌校验，直接转发。

基于 JWT 的动态令牌认证

适用范围

开启后，sandbox-gateway 会校验每个入向请求头中的 E2B-Traffic-Access-Token，Token 值取自创建 Sandbox 时响应体中的 trafficAccessToken 字段。

已升级 ack-sandbox-manager 组件至 v0.6.12 及以上版本。
已安装 ack-agent-identity 组件（0.4.1-rc.1 及以上版本）并已勾选启用token委托特性，用于签发和校验 JWT。

操作步骤

重要

开启入向流量认证后，未携带认证请求头的存量流量将被拒绝，返回 HTTP 403。建议在业务流量低峰期变更。

在集群组件管理中，单击 ack-sandbox-manager 的配置，按组件版本勾选以下配置项，然后单击保存。
- Whether to enable JWT (TrafficAccessToken) verification
- IdentityProvider plays a critical role in securing OpenKruise Agents through sandboxing
说明
组件版本与勾选项的对应关系及行为差异如下：
- v0.6.12 及以上版本：仅需勾选Whether to enable JWT (TrafficAccessToken) verification即可开启 JWT 认证。若同时勾选是否开启入向流量认证，对于未通过 metadata 开启 enable-jwt-auth 的 Sandbox，网关会回退到 X-Access-Token（静态 Access Token）认证。
- 低于 v0.6.12 的版本：需同时勾选是否开启入向流量认证和Whether to enable JWT (TrafficAccessToken) verification。对于未通过 metadata 开启 enable-jwt-auth 的 Sandbox，不会开启任何网关认证。
sandbox-gateway 需重启以应用变更。重启期间，已建立的长连接将断开，客户端重连后即可恢复，请评估变更影响。
创建 Sandbox 时通过 metadata 显式启用 JWT 认证，并从响应中获取 trafficAccessToken。以 E2B Python SDK 为例：

重要
E2B-Traffic-Access-Token 是访问 Agent Sandbox 数据面的关键安全凭证，泄露可能导致业务数据及沙箱环境面临安全风险。请妥善保管该 Token，建议进行加密存储，切勿明文写入代码或日志中。
```
from e2b_code_interpreter import Sandbox

sbx = Sandbox.create(
    template="code-interpreter",
    metadata={
        "security.agents.kruise.io/enable-jwt-auth": "true",
    },
)

# 从 Sandbox 对象获取 JWT（Python SDK 未做脱敏）
traffic_access_token = sbx.traffic_access_token
```
当前版本 JWT 有效期由 sandbox-manager 组件控制（通过向 ack-agent-identity 传入签发参数），默认有效期为 100 年，暂不支持自动刷新。若 JWT 失效，需重新创建 Sandbox 或调用签发接口获取新令牌。

访问 Sandbox 内的服务时，在请求头中携带 E2B-Traffic-Access-Token。以 curl 访问非 envd 端口的服务为例：

curl https://<YOUR-DOMAIN>/ \
  -H "E2B-Traffic-Access-Token: <TRAFFIC-ACCESS-TOKEN>" \
  -H "e2b-sandbox-id: <NAMESPACE>--<NAME>" \
  -H "e2b-sandbox-port: <PORT>"

说明

E2B 原生 SDK 尚未自动将 trafficAccessToken 注入 Sandbox 数据面请求。如需让 sbx.commands.run、sbx.files.* 等原生方法自动携带该请求头，可通过 Monkey Patch 方式将 Token 写入 SDK 的额外请求头配置。该方案依赖 E2B SDK 的内部实现和私有字段，请在使用前确认 SDK 版本兼容，并在创建任何 Sandbox 实例前应用此补丁。

展开查看 Monkey Patch 示例

以下代码通过包装 SandboxBase.__init__，在每次创建 Sandbox 后自动向 ConnectionConfig 注入 E2B-Traffic-Access-Token 请求头。

from functools import wraps

from e2b.sandbox.main import SandboxBase
from e2b_code_interpreter import Sandbox


def enable_traffic_access_token_header():
    """将 trafficAccessToken 注入所有 E2B Sandbox 数据面请求。"""
    current_init = SandboxBase.__init__

    # 避免重复包装。
    if getattr(current_init, "_traffic_token_header_patch", False):
        return

    @wraps(current_init)
    def patched_init(self, *args, **kwargs):
        current_init(self, *args, **kwargs)

        token = getattr(self, "traffic_access_token", None)
        if not token:
            return

        extra_headers = getattr(
            self.connection_config,
            "_ConnectionConfig__extra_sandbox_headers",
            None,
        )
        if not isinstance(extra_headers, dict):
            raise RuntimeError(
                "当前 E2B SDK 未暴露可变的 extra sandbox headers，请升级到支持的版本。"
            )

        extra_headers["E2B-Traffic-Access-Token"] = token

    patched_init._traffic_token_header_patch = True
    SandboxBase.__init__ = patched_init


# 使用示例
enable_traffic_access_token_header()

sbx = Sandbox.create(
    template="code-interpreter",
    metadata={
        "security.agents.kruise.io/enable-jwt-auth": "true",
    },
)

command = sbx.commands.run("echo hello-from-envd")
print(command.stdout)

sbx.files.write("/tmp/jwt-auth-ok.txt", "authenticated through gateway")
print(sbx.files.read("/tmp/jwt-auth-ok.txt"))
sbx.kill()

请求头组合（基于 Header 的路由与基于域名的路由）遵循 SandboxGateway 的路由匹配规则，详见配置路由规则。

基于 JWT 的动态令牌认证：认证失败响应

当 JWT 校验失败（例如令牌无效、过期或与目标 Sandbox 不匹配）时，sandbox-gateway 返回 HTTP 403。

当用户通过 metadata 创建了开启 JWT 动态令牌认证的 Sandbox，但网关侧尚未开启动态令牌认证功能时，sandbox-gateway 返回 HTTP 503。

常见问题

如果切换后业务异常，如何进行回滚？

在控制台组件管理中，单击 ack-sandbox-manager 的配置，将 dataplaneService 切换回sandbox-manager。
在网络 > 路由页面查看对应的网关（如 ALB）转发路径是否已切回 sandbox-manager。
在目标集群左侧导航栏，选择运维管理 > 日志中心菜单，切换到应用日志标签页。
在应用日志页面，日志库选择 ack-sandbox-manager-envoy，查看访问日志确认流量已回切，观察业务流量是否恢复正常。

如何调整 SandboxGateway 规格？

SandboxGateway 实例会受到底层网络资源的限制。作为代理组件，SandboxGateway 在处理流量转发时，涉及流入与流出两个方向，因此对底层网络带宽的吞吐能力有双倍需求（参考使用限制）。

完成容量评估后，可以通过以下方式调整规格：

增加 SandboxGateway 实例副本数。在 ack-sandbox-manager 组件的配置界面，调整 sandboxGateway.replicaCount。
调整实例规格以获取更大的底层带宽。

在 ack-sandbox-manager 组件的配置界面，调整 sandboxGateway.resources中的CPU和内存。

说明
调整 resources.cpu 时，需同步调整 envoy.concurrency 以获取最优性能。

背景信息

适用范围

工作原理

准备工作

流量切换

控制台

kubectl

使用限制

进阶操作

配置路由规则

基于 Header 的路由（优先匹配）

基于域名的路由

监控上报

优雅下线

入方向流量认证

静态 Access Token 认证

操作步骤

认证失败响应

兼容性说明

基于 JWT 的动态令牌认证

适用范围

操作步骤

基于 JWT 的动态令牌认证：认证失败响应

常见问题

如果切换后业务异常，如何进行回滚？

如何调整 SandboxGateway 规格？