系统设置
客户端升级提醒
客户端版本管理功能帮助团队管理员确保用户使用最新的稳定版客户端。启用后，系统会自动检测过旧的客户端版本并阻止其请求，引导用户升级到最新版本。
访问客户端版本页面
- 登录管理后台
- 在左侧导航栏选择「设置」
- 点击「客户端升级提醒」子菜单
功能概览
客户端版本管理页面包含两个主要部分：
- 升级提醒设置：控制是否启用版本检查和阻断功能
- 客户端版本分布：展示过去 7 天内活跃用户的客户端版本统计信息
升级提醒设置
启用开关
通过开关控制是否启用客户端版本检查功能。
启用后的影响
启用版本检查后，使用旧版本客户端的用户将收到 HTTP 400 错误，无法继续使用服务。请确保在启用前观察版本分布情况，确认新版本稳定后再开启。
检测机制说明
启用版本检查后，系统将按以下规则运行：
1. 自动检测 GA 版本
系统会自动检测每种客户端的最新稳定版本（GA 版本）。GA 版本的判定规则为：
当某个版本被 2 个或以上用户使用时，视为 GA（Generally Available）版本
可通过环境变量 CLIENT_VERSION_GA_THRESHOLD 调整阈值（范围 1-10，默认为 2）。
2. 活跃窗口
版本统计仅考虑过去 7 天内有请求的活跃用户。超过 7 天未活跃的用户版本记录将自动过期。
3. 独立客户端类型
不同客户端类型独立管理版本，互不影响：
| 客户端类型 | 说明 | 示例 |
|---|---|---|
claude-vscode | VSCode 插件 | Claude Code VSCode Extension |
claude-cli | 命令行工具 | Claude CLI |
claude-cli-unknown | 无法识别的旧版本 CLI | 早期版本 |
anthropic-sdk-typescript | TypeScript SDK | Node.js SDK |
4. 阻断行为
当检测到用户使用的版本低于当前 GA 版本时：
- 返回 HTTP 400 错误
- 错误信息中包含用户当前版本号和需要升级到的目标版本号
- 用户需升级客户端后方可继续使用服务
客户端版本分布
版本分布统计区域展示过去 7 天内所有活跃用户的客户端使用情况，按客户端类型分组显示。
统计信息
每个客户端类型卡片显示以下信息：
- 客户端名称：友好的显示名称（如 Claude Code VSCode Extension）
- 内部类型：系统识别的客户端类型标识
- 当前 GA 版本：该类型客户端的最新稳定版本，无则显示「无」
- 用户数量：使用该类型客户端的活跃用户总数
用户版本列表
每个客户端类型下方展示用户详情表格：
| 列名 | 说明 |
|---|---|
| 用户 | 用户名称 |
| 当前版本 | 用户使用的客户端版本号 |
| 最后活跃时间 | 用户最近一次请求的时间（相对时间） |
| 状态 | 版本状态标识 |
状态标识
用户版本状态分为三种：
| 状态 | 样式 | 含义 |
|---|---|---|
| 最新 | 绿色徽章 | 用户版本与当前 GA 版本一致 |
| 需升级 | 红色徽章 | 用户版本低于 GA 版本，启用检查后将被阻断 |
| 未知 | 灰色徽章 | 无法确定版本状态（通常因为暂无 GA 版本） |
配置建议
首次启用前
- 先观察版本分布统计，了解团队成员的客户端版本情况
- 确认至少有 2 位以上用户使用了较新版本（产生 GA 版本）
- 通知需要升级的用户提前更新客户端
- 选择低峰期启用功能
运营期间
- 定期查看版本分布，了解团队升级进度
- 关注「需升级」状态的用户，必要时主动通知
- 新版本发布后，给予团队适当的升级缓冲期
阈值调整
如果团队规模较小（少于 2 人），可通过环境变量调整 GA 判定阈值：
# 设置 GA 阈值为 1（单用户即可成为 GA 版本）
CLIENT_VERSION_GA_THRESHOLD=1
技术实现
数据存储
- GA 版本缓存：存储在 Redis，TTL 为 5 分钟
- 用户版本记录：存储在 Redis，TTL 为 7 天（与活跃窗口一致）
- 版本统计查询：基于请求日志中的 User-Agent 解析
Fail-Open 策略
版本检查采用 Fail-Open 策略：
- Redis 不可用时，跳过版本检查，放行请求
- 版本解析失败时，不阻断请求
- 确保服务可用性优先于版本限制
版本比较逻辑
版本号按语义化版本（Semantic Versioning）规则比较：
- 主版本号 > 次版本号 > 修订号
- 例如：
2.0.35>2.0.33>1.9.0
常见问题
为什么显示「暂无客户端数据」？
可能的原因：
- 过去 7 天内没有用户发起请求
- 所有请求的 User-Agent 无法被识别为已知客户端类型
为什么某个客户端类型没有 GA 版本？
GA 版本需要满足阈值条件（默认 2 个用户使用同一版本）。如果所有用户使用的版本都不同，则无法产生 GA 版本。
启用后用户立即被阻断怎么办？
- 通知用户升级客户端
- 如需紧急恢复，可临时关闭版本检查开关
- 考虑调低 GA 阈值或等待更多用户升级后再启用
版本数据多久更新一次？
- 用户版本：每次请求时实时更新
- GA 版本缓存：5 分钟刷新一次
- 版本分布统计：页面加载时实时查询
