API 配额分级：免费累计 1000 次 + 公开注册自助领取更高配额密钥 #17

2026-06-21T15:27:46+08:00

lixu commented

2026-06-21 15:27:46 +08:00

概述

为公开 API 增加累计总配额与公开用户注册：

匿名调用按来源 IP 累计共 1000 次，用满后返回 403 quota_exhausted，提示注册。
公开用户可自助注册（邮箱 + 密码）领取一枚更高配额密钥（默认每分钟 300 次、累计 100000 次），可查看用量、重置密钥。
配额计数存于 Redis，公开 API 仍保持只读契约（仅注册写入 app_user/api_key）。

后端

迁移 0011：新增 app_user 表；api_key 增加 quota_total（0=不限）；tier 增加 registered。
ratelimit：IncrTotal/TotalUsed/CopyTotal 维护终身计数器 usage:total:<subject>。
middleware：每分钟限流之外叠加累计配额校验，回写 X-Quota-Limit/Used/Remaining；匿名按 ip:<ip>、密钥按 keyID 计量。
store：RegisterUser/Authenticate/RegenerateKey（bcrypt 哈希、邮箱大小写不敏感唯一）。重置密钥时累计用量随 CopyTotal 延续，防止靠重置清零配额。
handlers：POST /api/v1/register、/account、/account/regenerate（独立 IP 轻限流，不占用免费配额）。

前端

公开站新增「API 密钥」页：注册领取 / 查看 / 重置密钥，明文密钥仅显示一次。
API 文档新增「鉴权与配额」说明、配额响应头与三个账号接口。
后台 API 密钥页新增「累计配额」列与签发时的配额输入，tier 增加 registered。

测试

store：注册 / 登录 / 重置 / 邮箱占用 / 密钥吊销-轮换全流程。
handler：匿名累计配额耗尽返回 403；注册签发高配额密钥；重复邮箱冲突。
go test ./... && go vet ./... && gofmt 全通过；两端前端 tsc && vite build 通过；迁移 up/down 往返通过。

## 概述为公开 API 增加**累计总配额**与**公开用户注册**： - 匿名调用按来源 IP 累计共 **1000** 次，用满后返回 `403 quota_exhausted`，提示注册。 - 公开用户可自助注册（邮箱 + 密码）领取一枚**更高配额**密钥（默认每分钟 300 次、累计 100000 次），可查看用量、重置密钥。 - 配额计数存于 **Redis**，公开 API 仍保持只读契约（仅注册写入 `app_user`/`api_key`）。 ## 后端 - **迁移 0011**：新增 `app_user` 表；`api_key` 增加 `quota_total`（0=不限）；tier 增加 `registered`。 - **ratelimit**：`IncrTotal`/`TotalUsed`/`CopyTotal` 维护终身计数器 `usage:total:<subject>`。 - **middleware**：每分钟限流之外叠加累计配额校验，回写 `X-Quota-Limit/Used/Remaining`；匿名按 `ip:<ip>`、密钥按 keyID 计量。 - **store**：`RegisterUser`/`Authenticate`/`RegenerateKey`（bcrypt 哈希、邮箱大小写不敏感唯一）。重置密钥时累计用量随 `CopyTotal` 延续，防止靠重置清零配额。 - **handlers**：`POST /api/v1/register`、`/account`、`/account/regenerate`（独立 IP 轻限流，不占用免费配额）。 ## 前端 - 公开站新增「API 密钥」页：注册领取 / 查看 / 重置密钥，明文密钥仅显示一次。 - API 文档新增「鉴权与配额」说明、配额响应头与三个账号接口。 - 后台 API 密钥页新增「累计配额」列与签发时的配额输入，tier 增加 registered。 ## 测试 - `store`：注册 / 登录 / 重置 / 邮箱占用 / 密钥吊销-轮换全流程。 - `handler`：匿名累计配额耗尽返回 403；注册签发高配额密钥；重复邮箱冲突。 - `go test ./... && go vet ./... && gofmt` 全通过；两端前端 `tsc && vite build` 通过；迁移 up/down 往返通过。

lixu added 1 commit 2026-06-21 15:27:46 +08:00

feat(api): tiered cumulative quota + self-service registration

CI / Go (api) (pull_request) Successful in 15s

Details

CI / Python (ingestion) (pull_request) Successful in 10s

Details

CI / Migrations (postgres) (pull_request) Successful in 16s

Details

7434e5195e

Anonymous callers get a free cumulative quota (1000 calls per IP); once
exhausted they get 403 quota_exhausted and must register. Public users can
self-register (email+password) to obtain a higher-quota API key, view usage,
and regenerate the key. Quota counters live in Redis; the public API stays
read-only except for the registration writes.

- migration 0011: app_user table + api_key.quota_total + 'registered' tier
- ratelimit: IncrTotal/TotalUsed/CopyTotal lifetime counters
- middleware: enforce cumulative quota + X-Quota-* headers
- store: RegisterUser/Authenticate/RegenerateKey (bcrypt)
- handlers: POST /api/v1/register, /account, /account/regenerate
- admin: quota_total column + registered tier
- public: 'API 密钥' account page + API docs quota section

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

lixu merged commit 3178f8a85a into main

2026-06-21 15:28:59 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: lixu/goods#17