API Keys 与限流
org 级 API key 签发、KV 滑动窗口限流、按天用量聚合，以及如何做你自己的对外 API。
给你的产品做对外 API 需要的三件事——key 的签发/吊销、按套餐限流、用量记录——
这个切片全部接好，并给了一个参考端点 /api/v1/hello 供照抄。
Key 的生命周期
- 签发：
/app/api-keys页面创建，格式fs_+ 48 位 hex（24 字节 CSPRNG）。 原文只在创建响应里出现一次，入库的只有 SHA-256 摘要（key_hash）+ 用于列表展示的 前缀（fs_a1b2c3d4…）。丢了原文没有找回，只能吊销重发——这是设计而不是缺陷。 - 吊销：软删除（置
revoked_at），行保留，用量历史不丢。所有查询都带 org 过滤， 拿到别的组织的 key id 也吊销不了。 - 归属：key 属于组织而非个人（
organization_id级联、created_by删号置空）， 创建者离职/删号后 key 照常工作。签发与吊销要求 org admin（owner 也算）。
请求侧：verifyApiKey 一条流水线
对外 API 的鉴权入口是 apikeys/verify.server.ts#verifyApiKey：提取 key → 哈希查表 →
按套餐限流 → 记一笔用量。参考端点 src/routes/api/v1/hello.ts 展示了完整分支处理：
curl -H "Authorization: Bearer fs_..." https://your.app/api/v1/helloAuthorization: Bearer 优先，x-api-key 头作为兜底。失败分支：401（缺失/无效/已吊销）、
429（限流，带 Retry-After 与 x-ratelimit-limit 头）；成功响应带
x-ratelimit-remaining。做你自己的 /api/v1/* 路由就是抄这 30 行：换掉业务逻辑，
鉴权、限流、用量三件事 verifyApiKey 一次给全。
限流：KV 双桶近似滑动窗口
配额按套餐分档（apikeys.shared.ts）：free 60 次/分钟，pro 600 次/分钟。实现是
KV 上的两个固定窗口桶：上一桶按「还与滑动窗口重叠多少」加权折算——
curr + prev × (1 - fractionElapsed)，纯函数带 node 单测。
限流是近似的，这是刻意取舍：KV 跨 POP 最终一致、也没有原子自增，突发流量可能 略过线。按 key 的 API 配额要的是「量级正确 + 零额外基建」，这个精度足够； 需要硬性上限的钱类扣减（如 credits）在 D1 里用条件更新做，见 Credits 用量计费。
桶的 TTL 覆盖两个窗口，旧桶自动过期，KV 里不会积垃圾。
套餐从哪来：getOrgPlan
限流分档由 verify.server.ts#getOrgPlan 决定：优先看 org 自己的座位订阅
（orgbilling），没有再回退到 owner 的个人权益（个人 Pro 订阅或终身买断）。
这保证「个人 Pro 带团队用」平滑升级到「团队订阅」的过程中功能不降档。
详见组织与团队。
用量：按 key 按天聚合
每次通过验证的请求 upsert 一行 (api_key_id, day) 聚合（UTC 日期，UNIQUE 索引 +
count + 1），同时刷新 key 的 last_used_at。/app/api-keys 页展示近 30 天用量；
按 key 按天的粒度足够日后出账单（用量计费在此之上做加法即可）。
不存每请求明细是刻意的：D1 写放大和存储都要钱，聚合行对「配额 + 账单」这两个 消费方已经无损。要审计单次请求，接 可观测性 的日志。