Dashboard 功能
用户管理
用户管理是 Claude Code Hub 的核心功能之一，允许管理员创建和管理团队成员，为每个用户配置独立的限额和权限。本文将详细介绍用户管理页面的各项功能。
页面概览
用户管理页面采用主从布局设计：
- 左侧：用户列表，显示所有用户及其基本信息
- 右侧：选中用户的 API Key 列表及详细信息
普通用户登录后只能看到自己的 API Key 列表，不会显示用户列表。只有管理员才能看到完整的主从布局。
用户列表
搜索与筛选
页面顶部提供了三个筛选工具：
- 搜索框：根据用户名或标签进行模糊搜索
- 分组筛选：按供应商分组筛选用户（显示所有已配置的分组）
- 标签筛选：按用户标签筛选（显示所有已使用的标签）
用户卡片
每个用户卡片显示以下信息：
| 元素 | 说明 |
|---|---|
| 用户名 | 用户的显示名称 |
| 备注 | 用户的描述信息（如有） |
| Key 数量 | 该用户拥有的 API Key 总数 |
| 启用 Key 数 | 当前处于启用状态的 Key 数量 |
点击用户卡片可在右侧查看该用户的详细信息和 API Key 列表。
创建用户
管理员可以通过点击用户列表右上角的「添加用户」按钮创建新用户。
基础配置
| 字段 | 必填 | 说明 |
|---|---|---|
| 用户名 | 是 | 用户的唯一标识名称，最大 64 字符 |
| 备注 | 否 | 用户的描述信息，最大 200 字符 |
| 用户标签 | 否 | 为用户添加分类标签，每个标签最大 32 字符，最多 20 个 |
| 供应商分组 | 否 | 限制用户只能使用特定分组的供应商 |
| RPM | 是 | 每分钟请求数限制，默认 60 |
| 每日额度 | 是 | 每日消费上限（美元），默认 100 |
高级限额配置
管理员可以为用户配置更细粒度的消费限制：
| 字段 | 说明 |
|---|---|
| 5 小时限额 | 5 小时内的消费上限（美元） |
| 周限额 | 每周消费上限（美元） |
| 月限额 | 每月消费上限（美元） |
| 总消费上限 | 历史累计消费上限（美元），超过后拒绝所有请求 |
| 并发 Session 限制 | 同时活跃的会话数量上限 |
留空的限额字段表示不限制。建议根据团队成员的实际需求合理配置限额，避免意外超支。
用户状态与过期时间
管理员可以控制用户的启用状态和设置过期时间：
| 字段 | 说明 |
|---|---|
| 启用状态 | 控制用户是否可以使用系统，禁用后所有 API 请求都将被拒绝 |
| 过期时间 | 用户账户的有效期截止日期，过期后用户将被自动禁用 |
过期时间验证规则
设置用户过期时间时，系统会进行以下验证：
- 不能是过去时间：创建或续期用户时，过期时间必须是未来的时间点
- 最大续期 10 年：过期时间不能超过当前时间 10 年后
- 时间精度：系统会将选择的日期转换为当天结束时间（23:59:59），确保用户在选定日期当天仍可正常使用
仅管理员可以设置和修改用户的过期时间。普通用户无法在编辑页面看到此选项。
懒过期检查机制
系统采用「懒过期检查」机制来处理用户过期：
- 请求时检测：用户发起 API 请求时，系统会检查
expiresAt字段 - 自动标记禁用：如果检测到用户已过期，系统会异步将该用户标记为禁用状态
- 立即拒绝：过期用户的当前请求会被立即拒绝，返回认证失败错误
这种机制的优势是无需后台定时任务，过期处理在请求时自动完成，同时不会阻塞正常请求的处理流程。
续期用户
对于已过期或即将过期的用户，管理员可以通过编辑用户来延长有效期：
- 在用户列表中点击编辑按钮
- 修改「过期时间」字段为新的截止日期
- 如果用户已被禁用，可同时开启「启用状态」开关
- 保存更改
如果用户因过期被自动禁用，仅修改过期时间不会自动重新启用用户。需要同时将「启用状态」设置为开启。
快速续期功能
v0.3.36 新增
快速续期功能允许管理员通过预设选项一键延长用户或密钥的有效期。
在用户或密钥列表中，点击续期图标（日历图标）可打开快速续期对话框。
预设续期选项：
| 选项 | 说明 |
|---|---|
| 7 天 | 延长 7 天有效期 |
| 30 天 | 延长 30 天有效期 |
| 90 天 | 延长 90 天有效期 |
| 1 年 | 延长 1 年有效期 |
| 自定义 | 选择具体的截止日期 |
续期计算逻辑：
系统采用「基于较晚日期」的续期逻辑：
新过期时间 = max(当前时间, 原过期时间) + 选择的时长
这意味着：
- 未过期用户：从原过期时间往后延长
- 已过期用户：从当前时间往后延长
示例：
| 原过期时间 | 当前时间 | 选择 30 天 | 新过期时间 |
|---|---|---|---|
| 2025-02-15 | 2025-01-20 | +30 天 | 2025-03-17 |
| 2025-01-10 | 2025-01-20 | +30 天 | 2025-02-19 |
同时启用功能：
快速续期对话框提供「同时启用」选项，勾选后：
- 如果用户/密钥处于禁用状态，会在续期时自动启用
- 无需额外进入编辑页面手动启用
编辑用户
点击用户名右侧的编辑图标（铅笔图标）可以修改用户信息。编辑表单与创建表单字段相同，所有配置项均可修改。
删除用户
点击用户名右侧的删除图标（垃圾桶图标）可以删除用户。
删除用户是软删除操作，会同时删除该用户的所有 API Key。历史日志数据会保留以供审计，但用户将无法继续使用系统。
删除确认对话框会显示：
- 即将删除的用户名
- 该用户拥有的 Key 数量
批量编辑
批量编辑功能允许管理员同时修改多个用户或密钥的配置，大幅提升管理效率。此功能在 v0.3.33 版本中引入。
启用批量编辑
- 在用户列表或密钥列表中，点击左侧的选择框选中要编辑的项目
- 选中后，页面顶部会出现批量编辑工具栏
- 点击「批量编辑」按钮打开批量编辑对话框
用户批量编辑
可批量修改的用户字段：
| 字段 | 说明 |
|---|---|
| 备注 | 用户描述信息 |
| 标签 | 用户分类标签 |
| 每日额度 | 每日消费上限（美元） |
| 5 小时限额 | 5 小时内的消费上限（美元） |
| 周限额 | 每周消费上限（美元） |
| 月限额 | 每月消费上限（美元） |
密钥批量编辑
可批量修改的密钥字段：
| 字段 | 说明 |
|---|---|
| 供应商分组 | 限制密钥可使用的供应商分组 |
| 5 小时限额 | 5 小时内的消费上限（美元） |
| 每日限额 | 每日消费上限（美元） |
| 周限额 | 每周消费上限（美元） |
| 月限额 | 每月消费上限（美元） |
| Web UI 登录 | 是否允许通过此密钥登录 Web UI |
| 启用状态 | 密钥是否启用 |
批量操作限制
- 每次最多可批量编辑 500 条记录
- 只有勾选的字段会被更新，未勾选的字段保持不变
- 提交前会显示确认对话框，展示将要修改的字段和影响范围
- 如果部分记录更新失败，对话框不会自动关闭，允许查看结果并重试
批量编辑是强大的管理功能，请在操作前仔细确认选中的记录和要修改的字段，避免意外修改。
用户角色
系统支持两种用户角色：
| 角色 | 权限说明 |
|---|---|
admin | 管理员，可以管理所有用户、供应商和系统配置 |
user | 普通用户，只能查看和管理自己的 API Key |
用户角色目前无法通过 Web UI 修改，需要直接在数据库中更新。初始管理员账户在系统部署时自动创建。
API Key 管理
选中用户后，右侧面板显示该用户的所有 API Key。
Key 列表头部
头部区域显示：
- 用户名：当前选中的用户
- 今日消耗：今日已消费金额 / 每日额度
- 实时状态：活跃请求数、最后一次请求的供应商和模型
Key 列表
每个 Key 显示以下信息：
| 列 | 说明 |
|---|---|
| 名称 | Key 的描述性名称，可展开查看详情 |
| Key | 脱敏显示的 API Key，可复制完整值 |
| 今日调用 | 今日 API 调用次数 |
| 今日消耗 | 今日消费金额 |
| 最后使用 | 最后一次使用时间和使用的供应商 |
| 操作 | 查看日志、编辑、删除 |
Key 详情
点击「详情」按钮可展开查看：
- 模型统计：今日各模型的调用次数和消费金额
- 限额使用情况：各维度限额的当前使用进度
创建 API Key
点击「添加 Key」按钮可为当前用户创建新的 API Key。创建成功后会显示完整的 Key 值。
API Key 只在创建时显示一次，请务必妥善保存。如果丢失，需要创建新的 Key。
编辑 API Key
可以修改 Key 的以下配置：
- 名称
- 启用/禁用状态
- 过期时间
- Web UI 登录权限
- 各维度限额配置
独立余额查询页面
v0.3.33 修复
v0.3.33 版本修复了余额查询页面的开关行为逻辑和描述文案。
在 API Key 编辑表单的「特殊功能」区域，可以配置独立余额查询页面。
开关逻辑说明
| 开关状态 | canLoginWebUi 值 | 效果 |
|---|---|---|
| 关闭（默认） | true | 用户使用完整 Web UI，可查看所有功能页面 |
| 开启 | false | 用户使用独立余额查询页面，只能查看配额和用量 |
开关的显示文案为「独立个人用量页面」，代表的是 !canLoginWebUi 的含义，即开关开启时实际禁用了完整 Web UI 登录权限。
默认值说明：
- 通过「添加 Key」表单新增的 Key，默认
canLoginWebUi=true（开关关闭） - 创建用户时自动生成的默认 Key，默认
canLoginWebUi=false（开关开启）
使用场景
- 完整 Web UI：适合需要管理自己 Key 的用户
- 独立余额页面：适合只需要查看用量统计的用户，提供更简洁的界面
独立页面功能
独立余额查询页面提供以下功能：
- 查看当前配额使用情况
- 查看各维度限额的使用进度
- 查看使用日志摘要
- 查看账户过期时间
删除 API Key
每个用户至少需要保留一个 API Key，因此当用户只有一个 Key 时，删除按钮会被禁用。
客户端限制
客户端限制功能允许管理员限制用户只能通过特定的 CLI/IDE 客户端访问 API。此功能在 v0.3.31 版本中引入。
工作原理
系统通过检查请求的 User-Agent 头来识别客户端类型：
- 空数组：无限制，允许所有客户端访问
- 非空数组：仅允许列表中的客户端访问
匹配规则：
- 使用大小写不敏感的子字符串匹配
- 只要
User-Agent包含列表中任意一个模式即可通过验证
配置方式
在创建或编辑用户时，可以在「访问限制」区域配置客户端限制：
预设客户端
系统提供以下常用客户端的快捷选项：
| 预设选项 | 匹配模式 | 说明 |
|---|---|---|
| Claude Code CLI | claude-cli | Anthropic 官方 Claude Code CLI |
| Gemini CLI | gemini-cli | Google Gemini CLI |
| Droid CLI | factory-cli | Droid CLI 工具 |
| Codex CLI | codex-cli | OpenAI Codex CLI |
自定义客户端模式
除预设选项外，还可以添加自定义的客户端模式：
- 每个模式最长 64 字符
- 最多可添加 50 个模式
- 输入后按回车添加
验证行为
当用户配置了客户端限制时：
| 情况 | 结果 |
|---|---|
| User-Agent 匹配任一允许的模式 | 请求通过 |
| User-Agent 不匹配任何模式 | 返回 400 错误：Client not allowed |
| 请求缺少 User-Agent 头 | 返回 400 错误：User-Agent header is required |
配置客户端限制后，User-Agent 请求头变为必需项。如果客户端不发送 User-Agent，请求将被拒绝。
查看用户的客户端限制
在用户列表中选择用户后，右侧面板的头部区域会显示该用户的客户端限制状态：
- 如果未配置限制，显示「允许的客户端：无限制」
- 如果已配置限制，显示允许的客户端列表
模型限制
模型限制功能允许管理员限制用户只能使用特定的 AI 模型。此功能在 v0.3.31 版本中引入。
工作原理
系统在处理请求时验证请求的模型是否在用户允许的模型列表中：
- 空数组：无限制，允许使用所有模型
- 非空数组：仅允许使用列表中的模型
匹配规则：
- 使用大小写不敏感的精确匹配
- 请求的模型名称必须与列表中某个模型完全一致
配置方式
在创建或编辑用户时，可以在「访问限制」区域配置模型限制：
- 输入模型名称后按回车添加
- 系统会提供当前已启用供应商支持的模型作为建议选项
- 每个模型名称最长 64 字符
- 最多可添加 50 个模型
支持的模型名称格式
模型名称支持以下字符：字母、数字、点号(.)、冒号(:)、斜杠(/)、下划线(_)、连字符(-)
示例：claude-3-opus-20240229、gpt-4.1、gemini-1.5-pro、o1-mini
验证行为
当用户配置了模型限制时：
| 情况 | 结果 |
|---|---|
| 请求的模型在允许列表中 | 请求通过 |
| 请求的模型不在允许列表中 | 返回 400 错误：Model not allowed |
| 请求未指定模型 | 返回 400 错误：Model specification is required |
模型限制使用精确匹配，配置时请确保模型名称与实际请求中使用的名称完全一致。建议从系统提供的建议列表中选择模型。
查看用户的模型限制
在用户列表中选择用户后，右侧面板的头部区域会显示该用户的模型限制状态：
- 如果未配置限制，显示「允许的模型：无限制」
- 如果已配置限制，显示允许的模型列表
客户端限制和模型限制是独立的功能，可以单独使用或组合使用。两者都配置时，请求需要同时通过两项验证。
关于供应商分组、Key 分组、用户分组的详细说明，请参阅 用户权限与分组 文档。
用户标签
用户标签功能允许管理员对用户进行灵活分类管理：
- 添加标签：在用户创建/编辑表单中输入标签名称，按回车添加
- 删除标签：点击标签上的删除图标移除
- 筛选用户：在用户列表页使用标签筛选器快速定位
标签可用于区分用户类型（如 VIP、测试用户）、部门归属或其他自定义分类。
权限说明
v0.3.33 增强
自 v0.3.33 版本起，系统实现了更细粒度的字段权限控制，普通用户无法修改任何配额相关的敏感字段。
操作权限
| 操作 | 管理员 | 普通用户 |
|---|---|---|
| 查看用户列表 | 可以 | 不可以 |
| 创建用户 | 可以 | 不可以 |
| 编辑用户 | 可以 | 不可以 |
| 删除用户 | 可以 | 不可以 |
| 查看自己的 Key | 可以 | 可以 |
| 创建自己的 Key | 可以 | 可以 |
| 编辑自己的 Key | 可以 | 部分可以 |
| 删除自己的 Key | 可以 | 可以（保留至少一个） |
| 查看他人的 Key | 可以 | 不可以 |
| 管理他人的 Key | 可以 | 不可以 |
仅管理员可修改的字段
以下敏感字段仅管理员有权修改，普通用户在编辑页面无法更改这些配置：
| 字段 | 说明 |
|---|---|
rpm | 每分钟请求数限制 |
dailyQuota | 每日消费额度（美元） |
providerGroup | 供应商分组限制 |
limit5hUsd | 5 小时消费限额 |
limitWeeklyUsd | 每周消费限额 |
limitMonthlyUsd | 每月消费限额 |
limitTotalUsd | 总消费上限 |
limitConcurrentSessions | 并发会话限制 |
dailyResetMode | 每日重置模式 |
dailyResetTime | 每日重置时间 |
isEnabled | 启用/禁用状态 |
expiresAt | 过期时间 |
allowedClients | 允许的客户端列表 |
allowedModels | 允许的模型列表 |
普通用户可执行的操作
普通用户登录后可以执行以下操作：
- 查看自己的 API Key 列表：包括 Key 的调用统计、消费情况等信息
- 创建新的 API Key：新创建的 Key 会继承用户级别的配置（限额、分组等）
- 修改自己 Key 的名称：可以更新 Key 的描述性名称
- 删除自己的 API Key：系统要求每个用户至少保留一个 Key，因此最后一个 Key 无法删除
