Agent Runtime 配置会话亲和

注意：说明：

注意：AffinityConfiguration 只能在创建弹性部署时提供。启用后，Mode 和 HeaderName 在弹性部署生命周期内不可修改，ModifyDeployment 不接受该配置。

一、能力概述

·AffinityConfiguration 是创建弹性部署时的可选配置，省略即表示不启用会话亲和。

·启用后，平台从配置的 Header 中读取 Affinity ID，并将同一 Affinity ID 的请求路由到对应沙箱实例。

·默认 HeaderName 为 X-Tencent-Agr-Affinity-Id。

·Affinity ID 是平台返回的不透明值，客户端应保存并原样回传，不要尝试解析出 InstanceId 等内部信息。

二、适用场景

·需要让同一会话的多次请求优先命中同一个沙箱实例。

·需要严格绑定到原沙箱实例，不希望平台自动改选。

·需要为单个用户独享 Workspace，避免不同 Affinity ID 共享沙箱实例。

三、工作方式

四、首次请求与 Header 回传

1. 首次请求不携带 Affinity ID。

2. 成功响应通过配置的 Header 返回完整的不透明 Affinity ID，客户端保存该值。

3. 后续请求使用同一 Header 回传已保存的 Affinity ID。

4. 每次成功响应都应以最新响应值覆盖本地保存值。

平台读取并处理该 Header，但不会将其转发到沙箱实例；即使沙箱实例返回同名 Header，也不能覆盖平台记录的值。

五、跨端口与跨弹性部署

有效的 Affinity ID 可在同一弹性部署的不同端口间继续选择同一沙箱实例，但不能用于其他弹性部署。

六、并发与无效 Affinity ID

·原沙箱实例并发已满时，BEST_EFFORT 可以改选；STRICT、EXCLUSIVE 不等待并返回 429。

·无效或已失效的 Affinity ID：

·BEST_EFFORT：按普通方式选择，仅在成功后返回新的 Affinity ID。

·STRICT、EXCLUSIVE：返回 409 affinity_conflict。

七、使用限制

·AffinityConfiguration 创建后不可修改：Mode 和 HeaderName 在弹性部署生命周期内保持不变，ModifyDeployment 不接受该配置。

·HeaderName 长度必须为 1～128 个 ASCII 字节，并符合 HTTP field-name 语法。

·HeaderName 不能使用 Authorization、Cookie、Host、X-Access-Token、逐跳 Header 等。

·Affinity ID 只在创建它的弹性部署内有效；可跨同一弹性部署的不同端口使用。

·平台不会将携带 Affinity ID 的 Header 转发到沙箱实例，沙箱实例返回的同名 Header 不能覆盖平台记录的值。

八、创建弹性部署并启用会话亲和

以下命令以 BEST_EFFORT 为例，创建弹性部署时通过 –affinity-configuration 指定 Mode 和 HeaderName：

agr deployment create \\ –region "${AGR_REGION}" \\ –deployment-name "${DEPLOYMENT_NAME}" \\ –tool-id "${TOOL_ID}" \\ –affinity-configuration '{ "Mode": "BEST_EFFORT", "HeaderName": "X-Tencent-Agr-Affinity-Id" }'

你可以根据场景将 Mode 替换为 STRICT 或 EXCLUSIVE。

九、客户端保存并回传 Affinity ID

# 首次请求：不携带 Affinity ID，从成功响应的 Header 中读取并保存 X-Tencent-Agr-Affinity-Id。curl -i \\ –header "X-Access-Token: ${DEPLOYMENT_TOKEN}" \\ "https://8080-${DEPLOYMENT_ID}.${AGR_REGION}.agents.tencentags.com/get"# 后续请求：使用已保存的 AFFINITY_ID 回传。curl -i \\ –header "X-Access-Token: ${DEPLOYMENT_TOKEN}" \\ –header "X-Tencent-Agr-Affinity-Id: ${AFFINITY_ID}" \\ "https://8080-${DEPLOYMENT_ID}.${AGR_REGION}.agents.tencentags.com/get"

十、生命周期交互