6.3 KiB
用户与访问管理
模块定位
用户与访问管理负责识别调用者，并决定该调用者可以使用哪些模型、请求应由哪个上游账号处理。
本项目不建立独立的用户账号体系，而是采用最小模型：
一个 Key 代表一个用户。
管理员直接管理 Key；Key 的稳定 ID 用于关联用量、额度和历史记录，Key 名称用于界面识别，Key 值用于请求认证。
当前能力
| 能力 | 当前实现 |
|---|---|
| Key 创建 | 支持自动生成或手动指定 Key 值 |
| Key 状态 | 支持启用、禁用和归档 |
| 下游认证 | 支持 Authorization: Bearer <key> 和 X-Api-Key |
| 模型权限 | 支持允许全部模型、精确模型名和 * 通配符 |
| 上游路由 | 支持 CPA 自动选择或严格绑定一个上游账号 |
| 默认迁移 | 首次启动自动创建 default Key，兼容现有调用配置 |
| 历史关联 | Key 的请求、用量、额度和账目均按稳定 ID 关联 |
Key 数据模型
每个 Key 包含以下访问属性：
| 属性 | 说明 |
|---|---|
| ID | 系统生成的稳定标识，用于内部关联，不随名称变化 |
| 名称 | 管理员可读的用户名称，长度为 1–64 个字符 |
| Key 值 | 下游请求凭证；创建后不可修改 |
| 状态 | active、disabled 或 archived |
| 路由模式 | auto 或 strict |
| 上游账号 | 严格路由时绑定的 CPA 上游账号 |
| 模型规则 | 允许全部模型，或一组模型匹配规则 |
Key 值允许 6–256 个非空白、非控制字符。未手动填写时，系统生成以 cpa_ 开头的随机值。
状态规则
| 状态 | 是否可以调用 | 是否可以编辑 | 是否保留历史 | 是否可以恢复 |
|---|---|---|---|---|
active |
是 | 是 | 是 | 不适用 |
disabled |
否 | 是 | 是 | 可以重新启用 |
archived |
否 | 否 | 是 | 不可以 |
禁用用于临时停止用户访问；归档用于永久退出管理。归档不会删除请求、用量、额度或计费账目，默认 Key 列表不再显示已归档项。
模型权限
模型匹配不区分大小写，并忽略规则首尾空白。
- “允许全部模型”开启时，不再读取单独的模型规则。
- “允许全部模型”关闭时，至少需要一条模型规则。
- 手工输入的 Key 必须为 6-256 个不含空白或控制字符的字符；留空时自动生成。
- 不含
*的规则执行精确匹配，例如gpt-5.6-sol。 *可以匹配任意长度的文本，例如deepseek-*、*-flash或gpt-*-codex。- 空模型名不能通过模型准入。
请求模型不符合规则时，请求在到达上游前被拒绝，返回 HTTP 403 和错误码 model_not_allowed。
上游路由
自动路由
auto 模式不绑定具体账号，由 CLIProxyAPI 根据当前可用候选、优先级和自身调度规则选择上游。
切换到自动路由后，Key 原有的上游绑定会被清空。
严格路由
strict 模式必须选择一个已经由 CLIProxyAPI 发现的上游账号。插件在调度阶段只选择该账号，不允许静默回退到其他账号。
出现以下情况时，请求返回 HTTP 503 和错误码 bound_upstream_unavailable：
- 绑定的账号已经不存在；
- 绑定账号不在本次 CPA 实时可用候选中；
- 调度完成后的实际上游与绑定账号不一致。
上游账号信息来自 CLIProxyAPI 的账号列表和实际调度候选。持久化状态用于管理台展示，本次调度候选才是请求时的可用性依据，避免账号恢复后被旧状态继续拦截。插件只保存路由所需的账号标识、提供商、显示名称和状态，不读取或保存上游 Token、Cookie 等凭证内容。
默认 Key 与新建 Key
首次启动且数据库中没有任何 Key 时，插件根据配置创建第一个 Key：
- 默认名称：
default - 默认 Key 值：
000000 - 默认状态：启用
- 默认路由：自动
- 默认模型权限：允许全部模型
该行为用于让已有 Codex/CLIProxyAPI 调用配置无需修改即可迁移到插件管理。
之后创建新 Key 时，系统按稳定 ID key_default 复制默认 Key 当时的模型权限和上游路由，再应用管理员本次明确填写的设置。管理员重命名默认 Key 不影响继承。复制只发生在创建时，后续修改默认 Key 不会影响已经创建的 Key。
如果数据库中已经存在 Key，启动配置不会覆盖或重新创建 default。
请求处理流程
| 阶段 | 模块行为 |
|---|---|
| 1. 提取凭证 | 从 Bearer Token 或 X-Api-Key 读取 Key |
| 2. 身份认证 | 查找 Key，并确认状态为 active |
| 3. 建立调用身份 | 使用稳定 Key ID 作为下游调用者身份 |
| 4. 模型准入 | 使用请求模型匹配该 Key 的模型规则 |
| 5. 上游调度 | 自动委托 CPA，或选择严格绑定的账号 |
| 6. 路由复核 | 严格模式下确认实际选择的账号与绑定一致 |
认证失败不会进入后续访问判断。Key 在请求过程中被停用时，后续拦截仍会再次检查状态，避免仅依赖认证阶段的旧状态。
额度、并发和价格检查发生在同一条请求准入链路中，但分别属于“额度与计费”和“价格配置”模块，不在本文展开。
管理操作
管理员页面当前支持：
- 查看有效 Key，按需包含已归档 Key；
- 创建并复制 Key；
- 修改名称、启用状态、模型规则和上游路由；
- 临时禁用或重新启用 Key；
- 永久归档 Key；
- 同步并选择 CLIProxyAPI 当前可见的上游账号；
- 根据历史请求和价格配置获得模型名称建议；
- 查看该 Key 的累计、今日和最近使用记录。
管理操作通过受 CLIProxyAPI Management Key 保护的管理接口完成。匿名页面只能读取服务端脱敏后的真实数据，不返回完整 Key，也不能创建、修改、重置或归档。
模块边界
本模块负责：
- Key 身份与生命周期；
- 下游请求认证；
- 模型访问规则；
- 上游账号选择策略。
本模块不负责：
- 用户注册、密码、登录会话和角色权限；
- 套餐、充值、支付和订单；
- 额度扣减、周期重置和并发计数；
- 模型价格维护与成本计算；
- CLIProxyAPI 上游账号本身的登录、刷新或凭证维护。