cpa-plugin/docs/modules/admin-console.md

管理台

模块定位

管理台是 billing 各业务模块的统一操作和查看入口。它不单独保存业务事实，而是通过 CLIProxyAPI 受保护的 Management API 读取或修改 SQLite 中的真实配置与记录。

当前管理台采用单页、紧凑布局，直接作为插件资源嵌入，不依赖 CDN、外部前端框架或独立构建服务。

页面结构

页面	主要用途
用户 Key	管理用户、访问策略、路由、额度和并发，查看用户汇总与账目
请求明细	分页查看请求结果、上游、Token、性能和成本，执行组合筛选
价格配置	维护本地价格，并搜索、导入和确认更新 models.dev 参考价格

页面顶部保留 CPA 管理密钥输入。留空时页面进入匿名只读模式；输入有效密钥后进入管理模式。

用户 Key 页面

页面顶部展示今日请求、今日 Token、今日成本、各用户今日用量以及近 7 日 Token 趋势。

Key 列表展示：

• 用户名称和脱敏 Key；
• 启用、禁用或归档状态；
• 当前余额和额度；
• 活跃并发与并发上限；
• 自动或严格上游路由；
• 允许的模型规则。

管理员可以创建 Key，并通过侧边抽屉完成以下操作。列表默认不显示已归档项：

• 修改名称和状态；
• 选择自动路由或指定上游账号；
• 允许全部模型或填写逗号分隔的模型规则；
• 设置额度、并发上限、重置周期和下一次重置时间；
• 立即重置额度；
• 查看最近计费账目；
• 永久归档 Key；
• 查看该用户累计、今日和最近请求。

业务规则和拒绝条件分别由“用户与访问管理”“额度与计费”模块执行，管理台只负责提交和呈现。

请求明细页面

请求明细默认每页显示 100 条，页码、上一页、下一页、查询过滤、列和刷新操作位于同一顶部工具区。查询过滤默认折叠，按需展开。

当前筛选项包括：

• 开始和结束时间；
• 用户；
• 模型；
• 成功、失败、拒绝或取消；
• 实际上游；
• Responses、Compact 或 Chat 端点；
• 完整 Request ID。

筛选和分页由服务端执行。应用新筛选会返回第一页；刷新保持当前页和筛选条件。只有页面可见、位于请求明细且处于第一页时才每三秒自动刷新，避免用户查看历史页时列表自行跳动。

“列”用于控制明细表可见字段，不改变服务端保存的数据。

价格配置页面

价格页面采用左侧模型列表、右侧编辑区。未选择模型时右侧留空，点击左侧任意模型项后加载价格详情：

• 新增或选择一个精确模型名称；
• 设置输入、缓存读取、缓存写入和输出的基础价格；
• 可选启用长上下文价格；
• 设置长上下文输入门槛及“大于/大于等于”比较方式；
• 可选启用 Fast 价格并设置倍率；
• 保存或删除模型价格。
• 手动更新 models.dev 供应商价格目录；
• 按模型或供应商搜索参考价格，并导入到当前本地模型；
• 查看价格是手动配置还是关联到具体 models.dev 供应商与模型；
• 目录价格变化时先查看输入/输出差异，再确认是否更新本地价格。

价格单位统一显示为 $ / 1M Token。保存前由管理接口完成严格字段校验，页面不会自行推断缺失价格。

点击普通“保存价格”始终把该模型切换为手动配置。目录更新或下载失败不会改变本地价格，也不会影响用户请求。

匿名只读模式

直接打开资源 URL 且不填写管理密钥时，页面读取当前 CLIProxyAPI 实例的真实数据：

• 可以查看汇总、请求明细和已配置价格；完整用户 Key 管理表不展示；
• 可以执行分页、筛选、刷新和选择显示列；
• Key 只由服务端返回 00******0000 形式的脱敏值，不能复制完整 Key；
• 历史 Usage 中可能存在的旧 api_key 值在匿名响应中统一清空；
• 创建、管理、保存、删除、归档、重置、目录更新和参考价导入入口不显示。

匿名读取使用单独的 GET-only 插件资源，不复用受保护的完整 Key 接口，也不提供任何修改方法。

管理模式

输入有效 CPA Management Key 后，页面切换到受保护的 Management API：

• 读取完整管理数据，脱敏 Key 可以点击复制完整值；
• 显示创建、管理、归档、额度重置、价格保存和目录更新等操作；
• 所有修改仍由 CLIProxyAPI 管理认证和 billing 服务端规则校验；
• 密钥无效时回退匿名只读数据，不额外显示状态标签。

管理接口

管理接口统一挂载在：

/v0/management/plugins/billing

路径	方法	用途
/keys	GET、POST、PATCH、DELETE	查询、创建、更新和归档 Key
/key-stats	GET	查询单个 Key 的统计和最近请求
/upstreams	GET	同步并查询 CPA 上游账号
/model-suggestions	GET	查询已知模型名称建议
/billing-reset	POST	立即重置指定 Key 的额度
/billing-ledger	GET	查询指定 Key 的计费账目
/usage	GET	查询分页请求明细
/usage-summary	GET	查询今日、用户和每日汇总
/prices	GET、PUT、DELETE	查询、保存和删除模型价格
/prices/import	POST	将指定 models.dev 参考价格导入本地模型
/price-catalog	GET	查看目录状态并搜索供应商级参考价格
/price-catalog/refresh	POST	下载新目录并返回已关联价格差异，不修改本地价格
/price-catalog/apply	POST	按目录 revision 确认应用选中的价格变化

管理台 HTML 由以下插件资源提供：

/v0/resource/plugins/billing/ui

匿名只读 JSON 复用同一个 GET-only 页面资源，页面通过 view 查询参数选择数据：

/v0/resource/plugins/billing/ui?view=keys

管理接口返回结构化 JSON 和明确的 HTTP 状态码；未知路径返回 not_found，数据库不可用、请求字段错误等情况返回对应错误码和消息。

界面与数据原则

• 管理台不直接操作 SQLite，只调用公开管理接口。
• 统计卡片和图表使用服务端汇总，不从当前明细页推算。
• 业务校验由服务端完成，前端校验只用于尽早提示。
• 完整 Key 仅由受管理认证保护的 Key 接口返回；匿名接口只返回服务端生成的脱敏值。
• 上游 Token、Cookie 和原始凭证不进入管理台。
• 界面保持单个嵌入资源，避免运行时依赖外部 CDN。
• 窄屏下表单和工具栏自动重排，明细表保留横向滚动能力。

模块边界

本模块负责：

• 提供统一管理页面；
• 调用并呈现 billing Management API；
• 提供匿名只读和密钥管理两种访问状态；
• 提供紧凑、可筛选、可分页的操作界面。

本模块不负责：

• 允许匿名调用任何修改接口；
• 在浏览器中直接执行业务扣费或访问控制；
• 保存真实业务数据；
• 提供普通用户自助修改能力；
• 提供登录、角色和多管理员权限体系。