# 用户与访问管理

## 模块定位

用户与访问管理负责识别调用者，并决定该调用者可以使用哪些模型、请求应由哪个上游账号处理。

本项目不建立独立的用户账号体系，而是采用最小模型：

> 一个 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 上游账号本身的登录、刷新或凭证维护。