帮你快速理解、总结文档立即下载
文档中心>Agent Runtime>操作指南>弹性部署(beta)>配置会话亲和

配置会话亲和

最近更新时间：2026-09-10 10:03:30
我的收藏

本页目录：

本文介绍如何为弹性部署（Deployment）配置会话亲和（AffinityConfiguration）。通过该配置，平台可以根据请求中的 Affinity ID 将同一会话的请求稳定路由到对应的沙箱实例。您可以在创建弹性部署时启用该能力，由客户端保存平台返回的 Affinity ID，并通过配置的 Header 原样回传，以完成会话绑定。
说明：
AffinityConfiguration 只能在创建弹性部署时提供。启用后，Mode 和 HeaderName 在弹性部署生命周期内不可修改，ModifyDeployment 不接受该配置。

能力概述

AffinityConfiguration 是创建弹性部署时的可选配置，省略即表示不启用会话亲和。
启用后，平台从配置的 Header 中读取 Affinity ID，并将同一 Affinity ID 的请求路由到对应沙箱实例。
默认 HeaderName 为 X-Tencent-Agr-Affinity-Id。
Affinity ID 是平台返回的不透明值，客户端应保存并原样回传，不要尝试解析出 InstanceId 等内部信息。

适用场景

需要让同一会话的多次请求优先命中同一个沙箱实例。
需要严格绑定到原沙箱实例，不希望平台自动改选。
需要为单个用户独享 Workspace，避免不同 Affinity ID 共享沙箱实例。

工作方式

配置
路由行为
不同 Affinity ID 是否共享沙箱实例
适用场景
不配置
不启用会话亲和。
-
请求无需绑定到特定沙箱实例
BEST_EFFORT
同一 Affinity ID 优先路由到原沙箱实例；原沙箱实例不可用、拒绝新流量或无法恢复时，可改选并返回新的 Affinity ID。
可共享
优先保持会话，同时允许弹性恢复
STRICT
只路由到原沙箱实例；不可用时失败，不改选。
可共享
必须使用原沙箱实例
EXCLUSIVE
一个 Affinity ID 独占一个沙箱实例，不同 Affinity ID 不共享且不能迁移。
不共享
用户独享 Workspace

首次请求与 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"

生命周期交互

生命周期动作
行为
PAUSE
BEST_EFFORT 优先恢复原沙箱实例，必要时改选；STRICT、EXCLUSIVE 只能恢复原沙箱实例。EXCLUSIVE 与 PAUSE 配合可表达独占且可恢复的 Workspace。
STOP
永久放弃亲和目标，旧 Affinity ID 不能重建或改绑。
中国站