客户端版本检查

客户端版本检查是一项系统功能，旨在确保用户使用最新的稳定客户端版本连接到 Claude Code Hub。通过分析请求中的 User-Agent 标头，系统可以识别客户端类型和版本，然后根据配置的 GA（正式发布）版本策略决定是否拦截来自过时客户端的请求。

概述

为什么客户端版本管理很重要

在现代 AI Agent 服务架构中，客户端版本管理是一个关键但经常被忽视的方面。随着 Claude Code 和 Codex CLI 等工具的快速迭代，用户可能会同时使用多个不同的客户端版本，从而导致：

• 兼容性问题：不同版本可能有不同的 API 实现
• 功能不一致：较旧的版本可能无法使用新功能
• 潜在安全风险：旧版本可能包含已知的漏洞

客户端版本检查功能旨在解决这些问题。

核心能力

客户端版本检查提供以下能力：

• 自动版本检测：根据活跃用户数据自动识别最新的 GA 版本，无需手动维护版本列表
• 多客户端支持：独立管理 VSCode 扩展、纯 CLI、SDK 等不同类型的客户端，每种客户端都有自己的版本演进路径
• 平滑升级引导：为使用旧版本的用户提供清晰的升级提示，而不是简单地拒绝服务
• 运行控制：管理员可以通过管理界面动态启用或禁用版本检查，根据运营需求调整策略

在请求管道中的位置

客户端版本检查位于代理请求处理管道的 version 阶段。完整的管道顺序如下：

1. auth — 身份验证
2. sensitive — 敏感词检查
3. client — 客户端类型检查
4. model — 模型验证
5. version — 版本检查（当前阶段）
6. probe — 探测请求处理
7. session — 会话管理
8. warmup — 预热请求处理
9. requestFilter — 请求过滤
10. rateLimit — 限流
11. provider — 供应商选择
12. providerRequestFilter — 供应商请求过滤
13. messageContext — 消息上下文

这种定位是有意为之的：

• 在身份验证之后执行，确保只有合法用户才会进行版本检查
• 在客户端检查之后执行，避免为已被拒绝的客户端进行不必要的版本计算
• 在会话管理之前执行，防止为过时客户端创建不必要的会话记录
• 在限流之前执行，确保过时客户端不会消耗限流配额

版本检查同时适用于聊天请求和 Token 计数请求（/v1/messages 和 /v1/count_tokens 端点）。

工作原理

User-Agent 解析

版本检查系统的基础是 User-Agent 解析器，它从 HTTP 请求中提取客户端类型和版本信息。由于不同的 Claude 客户端使用不同的 UA 格式，解析器处理了多种变体。

支持的客户端类型

系统识别以下客户端类型：

User-Agent 格式示例

解析器使用正则表达式提取客户端名称和版本号。对于 claude-cli 类型的客户端，它通过检查括号内的标记进一步区分 VSCode 扩展和纯 CLI。

GA 版本检测

GA（正式发布）版本被定义为至少有一定数量用户使用的最新稳定版本。系统通过以下过程确定 GA 版本：

1. 统计收集：统计过去 7 天内活跃用户的版本分布
2. 阈值过滤：将用户数 >= GA_THRESHOLD 的版本视为候选 GA 版本
3. 最新选择：从候选 GA 版本中选择版本号最高的版本

GA 阈值配置

GA 阈值通过环境变量 CLIENT_VERSION_GA_THRESHOLD 配置：

CLIENT_VERSION_GA_THRESHOLD=2

• 默认值：2
• 有效范围：1-10
• 低于阈值的版本会被强制设为 1；高于阈值的版本会被强制设为 10

较低的阈值意味着新版本会更快地成为 GA，从而推动用户更快升级。较高的阈值提供了更多的容忍度，允许更多用户同时使用旧版本。

缓存策略

为了减少数据库查询压力，系统使用 Redis 进行缓存：

GA 版本使用较短的 TTL（5 分钟），原因如下：

• 发布后需要快速检测到新版本
• 用户升级需要及时体现
• 5 分钟的延迟是可以接受的
• 显著减轻数据库查询压力

版本比较

系统使用语义化版本控制 (SemVer) 进行版本比较：

• 支持标准 SemVer 格式：主版本号.次版本号.修订号 (例如 1.2.3)
• 支持预发布标识符：(例如 1.2.3-beta.1)
• 忽略构建元数据：(+ 之后的内容)
• 处理 v 前缀：(例如 v1.2.3)

比较规则遵循 SemVer 规范：

• 稳定版本比预发布版本新：1.2.3 > 1.2.3-beta
• 数字标识符按数值比较：alpha.2 < alpha.10
• 数字标识符的优先级低于字符串标识符：alpha.1 < alpha.beta

故障开启 (Fail Open) 设计

版本检查采用“故障开启”设计原则：

• 任何错误都允许请求通过，不影响服务可用性
• 当功能被禁用时，跳过所有检查
• 当 UA 解析失败时，保持向后兼容
• 当数据库查询失败时，返回空结果
• 当版本字符串无法解析时，将它们视为相等（允许请求通过）

这种设计确保了版本检查功能不会成为系统的单点故障。

此外，用户版本跟踪是在每个请求上异步执行的。系统在 Redis 中更新用户的当前版本，而不会阻塞主请求流程。如果此更新失败，它会被静默记录，且不会影响用户的请求。

启用客户端版本检查

前提条件

在启用客户端版本检查之前，建议：

1. 观察版本分布：查看版本分布统计信息，了解您的用户目前正在使用的版本
2. 等待新版本稳定：确保已有多个用户升级到了新版本
3. 设置适当的阈值：选择适合您用户规模的 GA 阈值

通过管理界面启用

1. 以管理员身份登录管理界面
2. 导航至 设置 > 客户端版本
3. 切换 启用客户端版本检查 开关
4. 配置立即生效，无需重启服务

查看版本分布

版本分布页面显示以下信息：

统计卡片：

• 客户端类型数量
• 用户总数
• 拥有 GA 版本的客户端类型数量
• GA 覆盖率

详细表格（按客户端类型分组）：

• 用户名
• 当前版本
• 最后活跃时间
• 状态（最新/需升级/未知）

状态标签使用颜色进行区分：

• 最新（绿色）：用户的版本与当前的 GA 版本完全匹配
• 需升级（红色）：用户的版本比 GA 版本旧
• 未知（灰色）：没有可供比较的 GA 版本

用户体验

使用最新版本时

如果您使用的是最新的 GA 版本，请求将正常进行，完全感觉不到版本检查的存在。

使用过时版本时

如果您使用的是过时版本，系统将返回 HTTP 400 错误：

{
  "error": {
    "type": "client_upgrade_required",
    "message": "您的 Claude CLI (v2.0.20) 已过时。请升级到 v2.0.35 或更高版本以继续使用此服务。",
    "current_version": "2.0.20",
    "required_version": "2.0.35",
    "client_type": "claude-cli",
    "client_display_name": "Claude CLI"
  }
}

错误响应包含以下信息：

• type: 错误类型标识符，客户端可以据此提供特定的处理逻辑
• message: 包含当前版本和所需版本的人类可读错误消息
• current_version: 您的当前版本
• required_version: 最低要求的版本
• client_type: 客户端类型标识符
• client_display_name: 客户端显示名称（参见下表）

客户端显示名称映射：

升级客户端

收到升级提示后，您需要将客户端升级到最新版本：

对于 VSCode 扩展：

1. 打开 VSCode
2. 转到扩展视图
3. 找到 "Claude"
4. 点击“更新”按钮（如果可用）

对于 CLI：

# 使用 npm
npm install -g @anthropic-ai/claude-code

# 或使用安装脚本
curl -sSL https://claude.ai/install | bash

配置参考

环境变量

数据库配置

系统设置表包含以下字段：

运行时配置

通过管理界面进行的配置更改会实时生效，无需重启服务。配置缓存 TTL 为 60 秒。

最佳实践

初始部署建议

1. 先观察，后启用：部署后，先观察版本分布数据 1-2 周
2. 逐步调整阈值：从较高的阈值（如 3-5）开始，逐渐降低
3. 监控用户反馈：关注用户对升级提示的反馈

日常运营建议

1. 定期检查版本分布：每周在管理界面查看版本统计信息
2. 监控新版本发布：官方发布新版本时，监控用户的升级进度
3. 及时调整策略：根据运营情况随时启用或禁用版本检查

配合客户端发布

1. 灰度发布期间：禁用版本检查，允许新旧版本共存
2. 正式发布后：观察 1-2 天，确认稳定后启用版本检查
3. 紧急修复场景：如果需要强制升级，将 GA 阈值降低到 1

故障排除

用户报告无法访问

排查步骤：

1. 检查用户收到的错误消息：

   • 如果是 "client_upgrade_required" → 正常拦截，用户需要升级
   • 如果是其他错误 → 检查系统日志

2. 检查版本检查是否已启用：

   SELECT enable_client_version_check FROM system_settings;
   

3. 在管理界面检查用户的客户端版本和当前的 GA 版本

GA 版本检测异常

问题现象：新版本已发布但 GA 版本未更新

排查步骤：

1. 检查 Redis 缓存：

   redis-cli GET ga_version:claude-vscode
   

2. 检查活跃用户数据：

   SELECT user_agent, COUNT(DISTINCT user_id) as user_count
   FROM message_request
   WHERE created_at >= NOW() - INTERVAL '7 days'
   GROUP BY user_agent;
   

3. 检查 GA 阈值配置：

   echo $CLIENT_VERSION_GA_THRESHOLD
   

性能问题

问题现象：请求延迟增加

排查步骤：

1. 检查 Redis 连接状态
2. 检查数据库查询性能
3. 考虑调整缓存 TTL 或 GA 阈值

与其他功能的关系

与客户端守护 (Client Guard) 的区别

与会话管理的关系

版本检查在会话管理之前执行，确保：

• 过时客户端在建立会话之前被拦截
• 不会为过时客户端创建不必要的会话记录

与限流的关系

版本检查在限流之前执行，确保：

• 过时客户端不会消耗限流配额
• 限流统计仅包含合规的客户端

总结

客户端版本检查是 Claude Code Hub 的一项重要运营功能。通过自动检测并拦截过时的客户端，它帮助管理员确保用户使用的是经过验证的稳定版本。关键特性包括：

1. 智能化：根据真实用户数据自动识别 GA 版本，无需手动维护版本列表
2. 多客户端支持：独立管理 VSCode 扩展、CLI、SDK 等不同客户端，各具版本演进路径
3. 故障开启：任何异常都不影响服务可用性，确保版本检查不会成为单点故障
4. 可配置：通过管理界面动态启用或禁用，根据运营情况调整策略
5. 可观察：提供详细的版本分布统计信息，帮助管理员了解用户的版本使用情况

此功能特别适用于需要统一管理大量用户客户端版本的场景。它可以有效推动用户及时升级，减少由过时版本引起的问题。通过合理的 GA 阈值配置和逐步启用的策略，您可以在确保系统平稳运行的同时，引导用户保持客户端的更新。