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。保存前由管理接口完成严格字段校验，页面不会自行推断缺失价格。

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

实时模式

实时模式连接当前 CLIProxyAPI 实例：

• 需要输入 CPA Management Key；
• 所有读取来自真实管理接口；
• 创建、编辑、归档、重置和价格保存会修改真实数据；
• 请求明细和汇总反映真实请求事实。

管理台资源本身可以被 CPA 加载，但敏感管理接口仍由 CLIProxyAPI 的管理认证保护。

测试模式

测试模式用于管理员熟悉页面和验证交互，与真实数据完全隔离：

• 不需要管理密钥；
• 不访问任何真实 billing 管理接口；
• 使用浏览器本地的模拟 Key、上游、请求、价格和账目；
• 使用浏览器本地的参考价格样例测试搜索和导入，不访问 models.dev；
• 创建、编辑、归档、重置和删除只修改本地模拟状态；
• 提供放大的请求记录量，便于测试分页、筛选和表格布局；
• 可以一键恢复初始测试数据。

测试数据保存在浏览器本地存储中，当前选择的实时/测试模式保存在当前会话。切换模式不会把测试数据导入真实数据库，也不会用真实数据覆盖测试样例。

管理接口

管理接口统一挂载在：

/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 和明确的 HTTP 状态码；未知路径返回 not_found，数据库不可用、请求字段错误等情况返回对应错误码和消息。

界面与数据原则

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

模块边界

本模块负责：

• 提供统一管理页面；
• 调用并呈现 billing Management API；
• 管理实时和测试数据模式；
• 提供紧凑、可筛选、可分页的操作界面。

本模块不负责：

• 绕过 CLIProxyAPI 管理认证；
• 在浏览器中直接执行业务扣费或访问控制；
• 保存真实业务数据；
• 提供普通用户自助页面；
• 提供登录、角色和多管理员权限体系。