在 Knative 中使用 Agent Sandbox 工作负载

创建 Sandbox Service

1. 将以下配置应用到集群，启用 Sandbox 工作负载类型和会话保持。

   请将镜像地址中的registry-cn-wulanchabu-vpc替换为实际地域，如registry-cn-hangzhou-vpc。

   apiVersion: serving.knative.dev/v1
   kind: Service
   metadata:
     name: ai-agent-delete
   spec:
     template:
       metadata:
         annotations:
           # 启用 Sandbox 工作负载类型
           serving.knative.dev/workload-type: "sandbox"
           # 启用会话保持，确保每个用户请求路由到固定实例
           serving.knative.dev/session-affinity: "true"
           # 30 分钟无请求后释放实例
           serving.knative.dev/session-timeout: "30m"
           # Cookie 名称，用于标识用户会话
           serving.knative.dev/session-affinity-cookie: "app"
           # 按活跃会话数扩缩容
           autoscaling.knative.dev/metric: "session"
           # 每个实例严格绑定 1 个会话
           autoscaling.knative.dev/target: "1"
       spec:
         containers:
         - image: registry-cn-wulanchabu-vpc.ack.aliyuncs.com/acs/knative-samples-helloworld-go-session:v1.0-bfdce98

2. 等待ai-agent-delete部署完成后，在服务管理页面，获取访问网关地址和服务的默认域名。

3. 结果验证。

   1. 首次请求携带Cookie: app=11，同一 Cookie 再次访问应路由到同一 Pod。

      curl -i -H "Host: ai-agent-delete.default.example.com" http://<GATEWAY_IP> \
        -H "Cookie: app=11"

      预期输出：

      HTTP/1.1 200 OK
      Date: Fri, 05 Jun 2026 08:00:53 GMT
      Content-Type: text/plain; charset=utf-8
      Content-Length: 75
      Connection: keep-alive
      
      Hello World!
      
      Cookies:
        Name:  app
        Value: 11
      
      Raw Cookie Header: app=11

   2. 再次请求携带Cookie: app=22，该请求将会访问另一个Pod。

      curl -i -H "Host: ai-agent-delete.default.example.com" http://<GATEWAY_IP> \
        -H "Cookie: app=22"

      预期输出：

      HTTP/1.1 200 OK
      Date: Fri, 05 Jun 2026 08:02:49 GMT
      Content-Type: text/plain; charset=utf-8
      Content-Length: 75
      Connection: keep-alive
      
      Hello World!
      
      Cookies:
        Name:  app
        Value: 22
      
      Raw Cookie Header: app=22

请求路由逻辑

配置生效后，用户请求的处理流程如下：

1. 首个用户请求到达：无可用实例，自动扩容创建 Sandbox-1，会话绑定到 Sandbox-1。

2. 第二个用户请求到达：Sandbox-1 已被 session-1 独占（target=1），请求等待，APA 自动扩容 Sandbox-2，会话绑定到 Sandbox-2。

3. 用户 30 分钟未访问：会话超时，实例删除，资源释放。

4. 所有用户均无活跃：缩容到 0，零资源占用。

创建 Pause 模式 Sandbox Service

1. 相比 Delete 模式，需增加 serving.knative.dev/sandbox-idle-policy: "pause"注解。

   请将镜像地址中的registry-cn-wulanchabu-vpc替换为实际地域，如registry-cn-hangzhou-vpc。

   apiVersion: serving.knative.dev/v1
   kind: Service
   metadata:
     name: ai-agent-pause
   spec:
     template:
       metadata:
         annotations:
           serving.knative.dev/workload-type: "sandbox"
           serving.knative.dev/sandbox-idle-policy: "pause"
           serving.knative.dev/session-affinity: "true"
           # 指定暖池大小（预热的 Sandbox 实例数量）
           serving.knative.dev/warm-pool: "3"
           serving.knative.dev/session-timeout: "30m"
           serving.knative.dev/session-expiry: "2h"
           serving.knative.dev/session-affinity-cookie: "test"
           autoscaling.knative.dev/metric: "session"
           autoscaling.knative.dev/target: "1"
       spec:
         containers:
         - image: registry-cn-wulanchabu-vpc.ack.aliyuncs.com/acs/knative-samples-helloworld-go-session:v1.0-bfdce98

2. 等待ai-agent-pause部署完成后，在服务管理页面，获取访问网关地址和服务的默认域名。

3. 结果验证。

   curl -i -H "Host: ai-agent-pause.default.example.com" http://<GATEWAY_IP> \
     -H "Cookie: app=11"

   预期输出：

   HTTP/1.1 200 OK
   Date: Fri, 05 Jun 2026 08:33:06 GMT
   Content-Type: text/plain; charset=utf-8
   Content-Length: 75
   Connection: keep-alive
   
   Hello World!
   
   Cookies:
     Name:  app
     Value: 11
   
   Raw Cookie Header: app=11

状态保留范围

Pause 后，以下状态完整保留，唤醒后无需重新初始化。

配置预热池

预热池（Warm Pool）是 Pause 模式的高级配置，预先创建并冻结指定数量的 Sandbox 实例，使新用户到来时能直接唤醒已有实例，而无需等待冷启动。

通过以下Annotation指定预热池大小。

annotations:
  # 指定预热池大小（预热的 Sandbox 实例数量）
  serving.knative.dev/warm-pool: "3"

Pause 模式和 Delete 模式如何选择？

取决于是否需要保留运行状态：

• Pause 模式：需要保留容器状态（文件、进程）。

• Delete 模式：无需保留状态，追求空闲时零资源占用。

多个用户的请求会路由到同一个 Sandbox 吗？

设置 target=1 时不会。每个 Sandbox 实例严格绑定一个会话，新用户到来时会等待新实例就绪或唤醒预热池中的冻结实例。

Activator 重启后会话会丢失吗？

取决于会话存储模式：

• 内存模式：单实例且有限恢复会话数据。

• Redis 模式：从 Redis 完整恢复，零数据丢失。

因此，生产环境建议使用 Redis 模式以确保 Activator 重启后会话完整恢复。