副本感知路由

副本感知路由 (也称为粘性会话、粘性路由或会话亲和性) 会将相关请求路由到同一个 ClickHouse 副本。当您需要让临时表或命名会话状态在多个查询间保持可用、希望相关查询复用同一副本的本地缓存，或需要在写入及后续读取之间实现写后读一致性时，请使用此功能。这是一种尽力而为的机制，并不保证隔离性。代理会将每个路由值映射到一个副本。只要副本数量不变，该映射便会保持稳定；服务扩缩容可能会使该值映射到其他副本。

需要 HTTP 接口副本感知路由在 HTTP/HTTPS 接口之上的代理层实施。ClickHouse Cloud 正在将副本感知路由从 session_id 迁移至 X-ClickHouse-Replica-Tag 请求头。下方选项卡介绍了滚动发布期间可用的两种方法。目前无法通过原生协议使用副本感知路由 (原生端口，例如默认使用原生模式的 clickhouse-go 驱动程序) 。原生协议客户端必须切换到 HTTP，并在每个请求中发送路由值。

前置条件

你的服务需要有 2 个或更多副本。如果服务只有单个副本，就没有可固定到的副本。
该功能在进入 GA 后，Enterprise 默认可用。
此功能适用于标准 ClickHouse Cloud 服务。BYOC 暂不支持。

配置副本感知路由

提交一个 support 工单，申请启用基于 HTTP 的粘性副本路由。请附上你的 service ID 以及需要启用它的原因 (临时表、会话状态、缓存复用或写后读一致性) 。迁移现有 service 前，请 Support 确认已为其启用基于请求头的路由。在收到确认之前，继续使用 session_id；在滚动发布覆盖到你的 service 之前，X-ClickHouse-Replica-Tag 不会提供粘性路由。无需重启。

基于 HTTP 的路由

X-ClickHouse-副本-标签（推荐）
session_id（legacy）

要将工作负载固定到某个副本，请在 HTTPS 接口中发送 X-ClickHouse-Replica-Tag 请求头。代理会根据请求头的值进行一致性哈希，因此只要副本数量不变，具有相同请求头值的请求就会被路由到同一副本。不同的值会独立进行哈希，可能会落到相同或不同的副本，但您无法指定某个值映射到哪个副本。使用现有服务的主机名即可，无需使用特殊的粘性主机名或更改 DNS。请求头的值可以是您选择的任意字符串，例如应用程序名称、用户 ID 或工作负载标签。不带该请求头的请求仍会使用常规负载均衡。在每个请求中设置 X-ClickHouse-Replica-Tag 请求头：

echo 'SELECT hostName()' | curl \
  -H 'X-ClickHouse-Replica-Tag: my-workload-1' \
  -H 'X-ClickHouse-User: default' \
  -H 'X-ClickHouse-Key: <password>' \
  'https://<host>:8443/' -d @-

对于 clickhouse-go (v2)，设置 Protocol: clickhouse.HTTP，并通过 HttpHeaders 连接选项传入请求头。

X-ClickHouse-Replica-Tag 无需创建 ClickHouse HTTP 会话即可实现副本亲和性。并发请求可复用同一标签，不会触发 SESSION_IS_LOCKED。

写后读一致性

在多副本服务中，在某个副本上写入的数据可能要等复制追赶完成后，其他副本才能看到。发送写入请求时添加 X-ClickHouse-Replica-Tag 请求头，然后在后续读取中复用相同的请求头值。代理会将两者路由到同一副本，因此即使其他副本仍未追赶上，您也能读到自己写入的数据。此模式适用于写入后立即读取相同数据的工作负载，例如交互式应用程序，或在继续执行前验证插入操作的 ETL 作业。如需在所有副本之间获得更强的一致性保证，还可以在 ClickHouse Cloud 上将 select_sequential_consistency 设置为 1。

检查命中了哪个副本

使用相同的 X-ClickHouse-Replica-Tag 值再次运行 SELECT hostName() 示例。只要副本数量不变，您应会获得相同的主机名。不同的请求头值可能会映射到不同的副本。

对于副本感知路由，X-ClickHouse-Replica-Tag 正在替代 session_id。在 Support 确认您的服务已启用基于请求头的路由之前，请继续使用 session_id。

并发请求因 SESSION_IS_LOCKED 失败

session_id 会创建 ClickHouse HTTP 会话，因此同一会话一次只能运行一个查询。
为您的服务启用基于请求头的路由后，仅需副本亲和性的工作负载可改用 X-ClickHouse-Replica-Tag。并发请求可以共享同一副本标签。
如果需要 ClickHouse HTTP 会话状态，请将共享同一 session_id 的请求串行执行。

要将工作负载固定到某个副本，请在 HTTPS 接口中发送 session_id 查询参数。代理会根据该参数值进行一致性哈希，因此只要副本数量不变，共享该值的请求就会被路由到同一副本。不同的值会独立进行哈希，可能被路由到相同或不同的副本，但您无法指定某个值映射到哪个副本。请使用现有的服务主机名。无需使用特殊的粘性主机名，也无需更改 DNS。session_id 可以是您指定的任意字符串，例如应用程序名称、用户 ID 或工作负载标签。未指定 session_id 的请求仍会采用常规负载均衡。在每个请求中设置 session_id 查询参数：

echo 'SELECT hostName()' | curl \
  -H 'X-ClickHouse-User: default' \
  -H 'X-ClickHouse-Key: <password>' \
  'https://<host>:8443/?session_id=my-workload-1' -d @-

对于 clickhouse-go (v2)，请设置 Protocol: clickhouse.HTTP，并将 session_id 作为设置传入。驱动程序会将其作为 URL 查询参数发送。

使用 `session_id` 实现写后读一致性

在多副本服务中，一个副本上的写入可能要等到复制完成后，其他副本才能看到。使用 session_id 发送写入请求，然后在后续读取中复用同一 session_id。代理会将两者路由到同一个副本，因此即使其他副本仍未同步，您也能读到自己写入的数据。此模式适用于写入后立即读取相同数据的工作负载，例如交互式应用程序，或在继续执行前验证插入操作的 ETL 作业。如需在所有副本之间获得更强的一致性保证，还可在 ClickHouse Cloud 上将 select_sequential_consistency 设置为 1。

使用 `session_id` 检查命中的副本

使用相同的 session_id 再次运行 SELECT hostName() 示例。只要副本数量不变，您应会获得相同的主机名。不同的 session_id 可能会映射到不同的副本。

旧版基于子域名的路由

新服务中不再启用基于子域名的路由。如果您已经在使用粘性子域名，请联系支持团队，迁移到 HTTP 请求头方法。

旧版基于子域名的路由工作原理

此前，启用副本感知路由后，可以在服务主机名下使用通配符子域名。对于主机名为 abcxyz123.us-west-2.aws.clickhouse.cloud 的服务，任何匹配 *.sticky.abcxyz123.us-west-2.aws.clickhouse.cloud 的主机名 (例如 aaa.sticky.abcxyz123.us-west-2.aws.clickhouse.cloud) 都会由 Envoy 通过哈希一致地路由到某个固定副本。原始主机名则继续使用 LEAST_CONNECTION 负载均衡，即默认的路由算法。