URI哈希调度必须在HTTP模式下使用，TCP模式无法解析URI而失效；需配置mode http、hash-type consistent以避免缓存雪崩，并禁用cookie会话保持确保哈希逻辑生效。
URI哈希调度必须用http模式，tcp模式下无效
HAProxy 的 uri 调度算法只在七层 http 模式下可用，四层 tcp 模式无法解析 URI，强行配置会静默忽略 balance uri 或直接报错（如 invalid argument）。确认当前 backend 或 listen 块中已明确设置 mode http，且前端监听未被误设为 mode tcp。
常见错误现象：
- 配置了
balance uri但请求仍轮询或随机分发 - stats 页面显示后端连接数分布均匀，无明显倾斜
- 日志中出现
backend uses static LB algorithm提示（说明实际生效的是 fallback 算法）
hash-type 必须设为 consistent，否则节点增减会雪崩式打乱缓存命中
默认的 hash-type map-based（取模法）是静态哈希：当后端服务器数量或权重变化时，几乎所有 URI 的哈希结果都会重映射，导致缓存大规模失效、后端压力陡增。对缓存场景这是灾难性的。
正确做法是显式指定：
balance uri hash-type consistent
这样即使下线一台缓存节点，只有约 1/n 的 URI 会重定向，其余缓存仍可复用。
注意：consistent 仅对 uri、url_param、hdr 等哈希类算法有效，roundrobin 或 leastconn 不受此影响。
URI提取逻辑默认不含 query string，需加 uri 参数控制
HAProxy 默认对 balance uri 使用的是完整请求路径（req.uri），但不包含查询参数（?key=value）。这意味着 /api/user?id=1 和 /api/user?id=2 会被哈希到同一后端——对缓存友好，但若业务要求按完整 URL 区分（比如 CDN 缓存策略依赖 query），就得改用 balance url_param 或自定义 ACL。
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
如果确实需要包含 query string，可配合 http-request set-var 提取完整 URL：
http-request set-var(req.full_uri) str(%[capture.req.uri,query]) balance uri # 然后用 var(req.full_uri) 做 hash（需 HAProxy ≥ 2.0）
更稳妥的做法是评估业务是否真需要 query 参与哈希；多数静态资源缓存（如 /static/js/app.js?v=1.2.3）靠路径本身已足够区分。
后端服务器必须启用健康检查，且避免 cookie 会话保持干扰哈希结果
uri 调度和 cookie 会话保持是互斥的：一旦配置了 cookie（如 cookie WEBSERV insert），HAProxy 会优先按 Cookie 值路由，完全跳过 URI 哈希逻辑。这对缓存节点是严重干扰。
确保以下几点：
- backend 中未配置任何
cookie相关指令（insert、rewrite、prefix） - 没有全局或 frontend 级别的
stick规则覆盖 URI 调度 - 后端服务器自身不返回
Set-Cookie头（或用rspdel清除） - 健康检查使用
option httpchk，而非tcp-check，以保证 HTTP 模式全程生效
缓存节点通常无状态，不需要会话粘性；强行开启 cookie 会破坏哈希一致性，让缓存彻底失效。
URI 哈希真正起效的前提，是整个链路都走 HTTP 模式、禁用所有会话干扰项、并用 consistent 哈希抗抖动——这三个点漏掉任何一个，缓存节点的“精准调度”就只是配置文件里的一行幻觉。
