Archived
feat(api): 实装 /api/status 接口——无鉴权公开接口,换算比率权威来源
- endpoints:AuthMode 扩展 'none'(完全公开),追加 /api/status 定义(考证实证文案 + 实测示例响应),置于列表首位 - endpoint-info-line:鉴权徽标三态化(公开/宽松/严格,map 驱动 + none 中性样式) - endpoint-panel:requiresKey——无鉴权接口隐藏 sk-key 输入行、按钮不因空 key 禁用、空态文案区分 - spec:接口数 5→6、顺序、鉴权分布(none+strict×3+lenient×2)断言更新 - docs:接口文档同步 479 行新版(/api/status 详解 + QuotaPerUnit 考证);交互设计 §1 清单加第 0 行;README 与 side-nav 计数更新 - 验证:test 64/64 + type-check + lint + build 四绿
This commit is contained in:
@@ -37,6 +37,14 @@ Authorization: Bearer sk-xxxxxxxxxxxx
|
||||
|------|-----|------|
|
||||
| `QuotaPerUnit` | 500000 | 实测验证:接口① `total_used` ÷ 500000 = 接口④ `total_usage` ÷ 100 |
|
||||
|
||||
**此值是 NewAPI 的默认值(源码 `common/constants.go:22`:`var QuotaPerUnit = 500 * 1000.0 // $0.002 / 1K tokens`),并非硬编码定律**:
|
||||
|
||||
- 它是 `var` 且挂入 OptionMap(`model/option.go:166`),站长可在后台修改(`model/option.go:605` 会用数据库值覆盖)
|
||||
- 接口①④交叉实测吻合的原因:billing 接口内部就是拿 quota `÷ QuotaPerUnit` 换算(`controller/billing.go:50`),同一常量自证,**吻合验证不了管理员是否改过此值**
|
||||
- **正确做法:换算比率不硬编码,从 `/api/status` 的 `quota_per_unit` 字段读取**(见接口⓪),启动时拉取并定期校验,站点改配置后工具自动跟随
|
||||
|
||||
> `500000` 的设计来由:NewAPI(继承自 One API)以 OpenAI 早期基准定价 **$0.002 / 1K tokens** 为锚点,内部用整数 quota 计费避免浮点误差,1 quota = $0.000002,反推 1 美元 = 500,000 quota。
|
||||
|
||||
### 关键开关:DisplayTokenStatEnabled
|
||||
|
||||
| 接口 | 受开关影响? |
|
||||
@@ -54,6 +62,7 @@ Authorization: Bearer sk-xxxxxxxxxxxx
|
||||
|
||||
| 序号 | 方法 | 路径 | 鉴权 | 用途 |
|
||||
|------|------|------|------|------|
|
||||
| ⓪ | GET | `/api/status` | **无(完全公开)** | 站点配置与计费参数(含 `quota_per_unit`),工具校准换算比率的依据 |
|
||||
| ① | GET | `/api/usage/token` | TokenAuthReadOnly | 查 token 的累计已用/剩余/总额(原始 quota) |
|
||||
| ② | GET | `/api/log/token` | TokenAuthReadOnly | 查该 key 最近 1000 条调用日志 |
|
||||
| ③ | GET | `/v1/dashboard/billing/subscription` | TokenAuth | 查总额度上限(OpenAI 兼容,美元) |
|
||||
@@ -73,6 +82,45 @@ Authorization: Bearer sk-xxxxxxxxxxxx
|
||||
|
||||
## 2. 用量/额度查询接口详解
|
||||
|
||||
### ⓪ GET `/api/status` - 站点配置与计费参数(完全公开)
|
||||
|
||||
**鉴权**:无。挂载于 `router/api-router.go:26`,在鉴权中间件组之外,任何人(不持有任何 key)可直接访问。本清单中唯一无需凭证的接口。
|
||||
|
||||
**请求参数**:无
|
||||
|
||||
**请求示例**:
|
||||
|
||||
```
|
||||
GET /api/status
|
||||
```
|
||||
|
||||
**返回结构**(源码:`controller/misc.go:44` -> `GetStatus`):外层为 `{ success, message, data }`,`data` 含 60+ 字段(版本、登录方式、前端模块开关、公告等)。**与本项目相关的计费字段**:
|
||||
|
||||
| 字段 | 类型 | 说明 | 实测值(2026-09-09) |
|
||||
|------|------|------|------|
|
||||
| `quota_per_unit` | float | **QuotaPerUnit 当前生效值**。quota ÷ 该值 = 美元。管理员可改,工具不得硬编码 | `500000` |
|
||||
| `quota_display_type` | string | 站点额度展示模式:`USD` / `CNY` / `TOKENS`。影响 billing 接口(③④)的语义 | `"USD"` |
|
||||
| `usd_exchange_rate` | float | USD→CNY 展示汇率(`quota_display_type=CNY` 时 billing 接口用它换算) | `6.8` |
|
||||
| `display_in_currency` | bool | 是否以货币展示额度(旧字段,兼容保留) | `true` |
|
||||
| `custom_currency_symbol` | string | 自定义货币符号(`¤` = 未自定义) | `"¤"` |
|
||||
| `custom_currency_exchange_rate` | float | 自定义货币汇率 | `1` |
|
||||
| `price` | float | 充值价格(人民币/单位),站点充值汇率相关 | `6.8` |
|
||||
| `version` | string | NewAPI 版本号 | `"v1.0.0-rc.35"` |
|
||||
|
||||
**对本项目的意义**:
|
||||
|
||||
1. **校准换算比率**:`quota_per_unit` 是工具换算美元的唯一权威来源——管理员改配置后,工具启动时拉取 + 定期校验即可自动跟随,不会算错
|
||||
2. **感知展示模式切换**:若管理员把 `quota_display_type` 切到 `CNY` 或 `TOKENS`,billing 接口(③④)返回的数字语义会变(CNY 是先 ÷QuotaPerUnit 再 ×`usd_exchange_rate`;TOKENS 直接返回 token 数),工具可提前探测到,避免拿旧逻辑解析新语义
|
||||
3. **零成本**:完全公开、无鉴权、无调用门槛,可放心定期轮询
|
||||
|
||||
**注意事项**:
|
||||
|
||||
- 返回字段很多且含大量前端 UI 配置(`HeaderNavModules`、`SidebarModulesAdmin` 等),解析时只取计费相关字段,其余忽略
|
||||
- 字段集合随版本演进(如开启公告开关会追加 `announcements`),解析需容忍未知字段
|
||||
- 该接口不泄露敏感信息(secret 类 OptionMap 键已被 NewAPI 过滤),这也是它敢完全公开的原因
|
||||
|
||||
---
|
||||
|
||||
### ① GET `/api/usage/token` - token 级用量汇总
|
||||
|
||||
**鉴权**:`TokenAuthReadOnly()`(宽松版,key 过期/耗尽也能查)
|
||||
@@ -364,7 +412,7 @@ total_usage = 134683.8914 美分 ÷ 100 = 1346.84 美元
|
||||
### 核心换算公式
|
||||
|
||||
```
|
||||
原始 quota ÷ 500000 = 美元
|
||||
原始 quota ÷ quota_per_unit(/api/status 实时读取,当前站点值 500000)= 美元
|
||||
```
|
||||
|
||||
### 实测数据验证
|
||||
@@ -423,7 +471,9 @@ total_usage = 134683.8914 美分 ÷ 100 = 1346.84 美元
|
||||
| billing 查询 | `controller/billing.go:75` | `GetUsage` |
|
||||
| 显示开关 | `common/constants.go` | `DisplayTokenStatEnabled` |
|
||||
| 日志上限 | `common/constants.go` | `MaxRecentItems = 1000` |
|
||||
| 配额单位 | `common/constants.go` | `QuotaPerUnit`(默认 500000) |
|
||||
| 配额单位 | `common/constants.go:22` | `QuotaPerUnit`(var,默认 500000,`// $0.002 / 1K tokens`,可被 OptionMap 覆盖) |
|
||||
| 配额单位(覆盖入口) | `model/option.go:605` | `case "QuotaPerUnit"` 运行时改写 |
|
||||
| 站点配置暴露 | `controller/misc.go:44` + `router/api-router.go:26` | `GetStatus`(`/api/status`,无鉴权,含 `quota_per_unit`) |
|
||||
| token 更新 | `model/token.go` | `Update()`(Select 不含 used_quota) |
|
||||
| 额度增减 | `model/token.go` | `increaseTokenQuota` / `decreaseTokenQuota` |
|
||||
|
||||
|
||||
Reference in New Issue
Block a user