大模型API Key体系设计：身份、鉴权与计量全解析

1. 为什么需要自己造一套大模型Key体系

1.1 从共享Key的混乱说起

我之前在某公司内部做模型开放平台的时候，最开始偷了个懒：直接申请了一个大模型供应商的密钥，把密钥写死在业务代码里，或者放在配置中心让大家共用。结果上线不到一周就发现问题了——业务线A跑了一个夜间批处理任务，把整个账号的并发额度打满，业务线B的实时对话接口全部超时。那个时候我们连谁在调用、调了多少、哪个接口最贵都说不清楚，更别提给不同团队做配额隔离了。

后来我们决定自己搭一套面向大模型的API Key生成及校验方案。这个方案不是简单地在数据库里生成一个随机字符串就完事，而是把身份识别、权限控制、配额计量、调用审计、密钥轮换、缓存降级全部串起来。做完之后，整个平台的稳定性、可追溯性、以及计费能力都发生了质变。这篇文章我就把整个方案的设计思路和踩坑记录完整分享出来，涉及的核心内容可以抽象成一句话：用廉价且可靠的方式，创建一个无法伪造、便于归因、可以吊销、支持配额与计量的大模型访问凭证。

1.2 大模型API Key和传统API Key到底不一样在哪里

如果你以前做过传统平台OpenAPI，可能会觉得Key生成很常见——无非就是生成UUID、存数据库、请求头里带上校验。但大模型场景有个非常特殊的地方：调用成本不是恒定的，而是跟输入输出token数强相关。一次对话调用可能消耗几百个token，一个长文档总结可能消耗几万个token，而且不同模型（比如对话模型、向量模型、图像模型）的单价完全不同。

这就意味着Key体系不能只回答"你是谁"，还要回答三件事：

1. 你能用哪些模型：一个内部工具业务可能只需要对话模型，不需要给图像生成模型的权限。
2. 你最多能花多少钱：如果做企业客户接入，token经费上限是合同里白纸黑字写的，超了就要熔断。
3. 你这次调用花了多少token：要在调用成功之后把usage精确记录到某个Key名下，形成账单。

传统API Key的"鉴权+路由"思维在大模型场景下撑不住，因为缺少计量这个核心环节。如果直接把一套传统方案拿来用，后面做成本分析、做容量规划、做客户账单都会很痛苦。

2. 身份模型设计：把"身份"和"凭证"彻底拆开

2.1 双层结构：app_id与secret_key

我们最终的方案采用了一个非常经典的双层结构：每个调用方拥有一个app_id和一个secret_key。

• app_id：明文传输，用来标识身份。它像银行借记卡的卡号，可以印在名片上、写在配置里，不怕泄露。
• secret_key：机密凭证，用来证明你确实拥有这个app_id。它像银行卡密码，绝对不能出现在日志、URL、前端代码里。

为什么非要分两层？因为在实际运维中，我们需要在不暴露密钥的前提下，让各个业务方能够拿着app_id去控制台查用量、看报表、申请配额变更。如果只有一个token，那业务方查用量的时候就必须把完整密钥贴出来，泄密风险成倍增加。而且当密钥需要轮换时，app_id可以保持不变，所有关联的授权策略、报表历史、成本归因数据都不需要跟着迁移。

举个例子：某条业务线的密钥在某个外包项目里泄露了，我们只需要吊销secret_key重新生成一份，app_id还是原来那个；如果当初只用一个token，那可能连历史账单都查不出来了。

2.2 Key属性与scope授权

在数据模型层面，一张api_app表用来存身份和授权信息，核心字段如下：

model_scopes这个字段很容易被忽略，但实际非常重要。我们的做法是：secret_key本身不绑定模型，而是通过app_id上的scope来控制。这样同一个Key在网关侧拿到之后，先去查scope，再决定是否放行某个模型路由。好处是：Key的校验只需要一次缓存查询，而具体的权限判定可以复用已有的权限中心。

2.3 密钥版本化与轮换机制

还有一个容易被忽略的设计：secret_key要支持多版本。为什么要版本化？因为轮换时如果只保留一份密钥，那么旧的调用方会在某个瞬间全部鉴权失败。

我们的做法是：在api_app_secret表里维护多条记录，每条记录带secret_version和status。默认情况下，网关校验当前正在使用的版本；当某个调用方要轮换Key时，控制台生成一个新版本，同时保留旧版本一定时间（比如24小时）作为过渡。等监控确认旧版本流量已经降到零，再手动下线旧版本。

建议在网关日志里增加一个维度：按照secret_version聚合调用量。你在控制台就能看到还有多少请求在用旧Key，这样可以避免"上午改完Key，下午某条python脚本报警401"的尴尬。

3. Key生成算法选择与安全落库

3.1 生成方案：既要可读，也要不可猜测

生成Key最常见的选择是UUID，但我强烈不建议直接用它做secret_key。UUID确实没法猜测，但有两个问题：一是太长了，放在HTTP Header或客户端配置里都很啰嗦；二是没有任何业务信息，出了问题很难快速定位归属。

我们的生成方案分三段，整体结构如下：

sk_live_8f3kDx9qZt2mW7vP

• sk_：固定前缀，方便代码识别和日志过滤。
• live/test：环境标识，测试Key和生产Key一眼区分，避免有人把测试Key带到生产环境。
• 8f3kDx9qZt2mW7vP：16位随机主体部分，采用自定义Base32字符集，去掉容易混淆的字符，比如0/O、1/I、l/1等。

生成逻辑可以参考这段Python伪代码：

import secrets import base64 # 去掉易混淆字符：不含0 O 1 I l CHARSET = "abcdefghijkmnpqrstuvwxyz23456789ABCDEFGHJKLMNPQRSTUVWXYZ" def generate_secret(env: str = "live") -> str: # 用secrets而不是random，保证密码学强度 body = ''.join(secrets.choice(CHARSET) for _ in range(16)) return f"sk_{env}_{body}" def generate_app_id() -> str: # 身份ID故意短一些，好记，且必须保持唯一 return "ap-" + secrets.token_hex(4)

这里最关键的细节是：必须用secrets模块，不能图省事用random。random是伪随机数生成器，内部状态可被预测，一旦攻击者拿到多个样本就能推算出后续值，这在密钥场景是致命的。

3.2 存储策略：不能存明文，也不能完全不存明文

这是整个方案最容易被做错的地方。如果只做校验，我们可以像密码一样只存哈希；但作为Key管理平台，还必须能够在控制台展示Key（比如给某个客户发找回凭证），或者对旧密钥进行解密审计。所以我们的存储设计是双轨制：

1. 用于校验的哈希值：对完整的secret_key做带盐哈希（建议Argon2id或至少bcrypt），存入secret_hash字段。网关校验时只比对哈希，不需要解密。
2. 用于找回的解密值：用AES-256-GCM加密后存储根密钥（root_key），密钥由独立的密钥管理服务（如云KMS或Vault）持有，即使数据库被拖走，也没有能力解密。

为什么校验不用密文解密来比对？因为解密一次大几百微秒，QPS一高完全扛不住；哈希比对虽然也有计算开销，但可以通过缓存避免大部分重复计算。所以实际校验路径上，我们根本不会碰密文。

3.3 数据库表设计与过期策略

密钥相关表结构大概是这样：

CREATE TABLE api_app ( id BIGINT PRIMARY KEY AUTO_INCREMENT, app_id VARCHAR(64) NOT NULL UNIQUE, app_name VARCHAR(128) NOT NULL, owner VARCHAR(64), status TINYINT NOT NULL DEFAULT 1, model_scopes JSON, quota_json JSON, created_at DATETIME NOT NULL, updated_at DATETIME NOT NULL ); CREATE TABLE api_app_secret ( id BIGINT PRIMARY KEY AUTO_INCREMENT, app_id VARCHAR(64) NOT NULL, secret_version INT NOT NULL, secret_hash VARCHAR(256) NOT NULL, secret_encrypted TEXT, status TINYINT NOT NULL DEFAULT 1, expire_at DATETIME, created_at DATETIME NOT NULL, KEY idx_app_version (app_id, secret_version) );

这里有几个细节需要注意：

• expire_at不是物理删除，而是软过期。过期之后网关直接拒绝，但数据还留存在库里，方便分析过期Key的历史费用。
• 每个app_id最多保留3个活跃版本，避免版本无限膨胀。
• 所有查询尽量通过app_id定位，因为它是唯一对外公开的标识，secret_key本身不应该作为主键。

4. 校验与网关链路的完整设计

4.1 一次完整的调用怎么走通

整个网关校验链路我建议这样设计：

1. 客户端在HTTP请求头带上：

Authorization: Bearer sk_live_8f3kDx9qZt2mW7vP X-App-Id: ap-2b7d9f

2. 网关先用X-App-Id查本地缓存，拿到该app的profile（状态、scope、配额快照）。
3. 网关用Authorization对应的secret_key做哈希比对，确认凭证匹配。
4. 校验通过后，网关按profile.model_scopes做模型路由鉴权——如果当前请求的模型不在允许列表里，直接返回403。
5. 鉴权通过后，进入配额校验：检查当前已用token/金额是否达到上限。
6. 真正调用上游大模型供应商之前，执行限流检查和并发信号量检查。
7. 得到上游响应后，从响应里解析usage字段，异步写入计量消息队列。
8. 网关返回正常响应给客户端。

整个过程里，第2步和第3步是性能关键，第5步和第7步是计费关键，第6步是稳定性关键。哪一个掉链子都会出线上事故。

4.2 缓存层怎么扛住高并发回源

最笨的校验方式是每个请求都查一次数据库，但大模型网关的QPS虽然不像交易系统那么夸张，却也可能有几百到几千的峰值。如果每个请求都回源，数据库和鉴权服务立刻被打爆。

我们做了两层缓存：

• 本地缓存（Caffeine/Guava）：存储app_id的profile，设置5分钟过期，容量上限20万条。
• 分布式缓存（Redis）：存储profile之外，还存配额计数器的实时值。

这里的难点是缓存一致性。比如用户在控制台吊销了某个Key，如果缓存没及时失效，权限会继续开放一段时间。我们的解法是：所有变更操作发一个Redis Pub/Sub消息，网关侧订阅到消息后主动淘汰本地缓存；同时保留一个最大过期兜底时间，比如5分钟。这样即使pub/sub链路抖动，最坏情况下5分钟也会自动收敛。

另外要特别注意防击穿：本地缓存miss时，不要每个请求都直接打数据库，而是用一个单飞（singleflight）机制，只让一个请求去加载，其余请求等待同一个结果。否则缓存刚过期那几十毫秒，可能有上千个请求同时穿透打到数据库上。

4.3 配额校验与并发扣减的正确姿势

配额这块，我们比较过两种方案：一种是每次请求前实时查询累计用量；另一种是预扣+完成后更正。

实时查询的问题在于：查询和扣减不是原子的，两个并发请求可能同时读到剩余额度5000，各自都认为可以放行，结果实际消耗超过上限。所以我们最终选择预扣方案：

1. 请求进来时，根据模型单价和估计的最大token大小，先预扣一个数额（比如预扣1000 token）。
2. 调用完成之后，用实际usage更正：多退少补。
3. 如果调用失败，直接退还预扣额度。

预扣值怎么定？我建议不要按估计值，而是按"这个模型单次请求的最大可能token数"，通常就是模型上下文上限。虽然这样做会让客户在开始阶段看到一个较大的"可用余额减少"，但对防止超卖非常有效。如果不做预扣，高并发下很容易出现两条请求同时通过校验、加起来把月度配额打爆的情况。

在数据库或者Redis里，配额扣减要使用原子操作，Redis用DECRBY，数据库用UPDATE ... SET quota_used = quota_used + ? WHERE quota_used + ? <= quota_limit这种条件更新。千万不要"先读后写"，否则并发必然出问题。

4.4 限流算法怎么选

很多文章会把限流单独拎出来讲，这里我就结合大模型场景直接给结论。大模型网关的限流目标有两个：一是限制每秒请求数（RPS），二是限制同时进行中的并发请求数。为什么并发也很重要？因为一个长文本生成请求可能持续10秒以上，如果只看RPS，100个并发请求照样能把上游打爆。

我们的做法是：令牌桶控制RPS，再加一个分布式信号量控制并发数。比如某个可用Key的配置是：RPS=10，并发=5。请求先拿令牌，再尝试获取并发信号量；获取不到就快速返回429，而不是排队等。

5. Key生命周期管理与自助化运维

5.1 创建、续期、吊销的完整操作流

Key管理如果不做成自助化，运维会忙死。我们控制台支持以下操作：

• 创建Key：选择环境、模型范围、配额上限，生成后只展示一次完整secret_key，之后只能看到脱敏串（sk_live_****）。
• 续期：对即将过期的Key发起续期，本质是生成新版本secret_key，而app_id不变。
• 吊销：立即失效某个密钥版本，或者整个app全部失效。吊销之后，网关通过缓存淘汰让配置秒级生效。
• 配额调整：比如某个客户要临时加量，控制台改quota_json后，同样通过pub/sub通知网关刷新本地缓存。

这个过程中的一个重点经验是：吊销和创建尽量异步化，但结果必须可感知。例如吊销操作返回"已提交"，后台执行"写库-发消息-淘汰缓存-记录审计日志"，执行结果写到操作记录里。否则一个操作耗时超过1秒，前端反复刷新还以为没提交成功。

5.2 审计与追踪

Key体系的复杂度不在于生成，而在于"出了问题能不能追溯"。我们要求每条调用日志必须包含app_id、secret_version、model、tokens、latency、status_code这些字段。日志的trace_id必须与业务请求的trace_id打通，否则客户报障时根本没法定位。

控制台的用量报表也要按维度聚合：按app按模型按天，按版本按小时。这样做有几个实际价值：一是能发现某个密钥版本异常变高，可能是泄露导致的盗用；二是能分析模型使用比例，为后续采购和容量规划提供依据。

5.3 配额超限后的熔断

最后再提一个熔断策略。当某个app的配额用尽时，网关直接返回429 Quota Exceeded，同时给owner发送告警。但如果只是写死拒绝，客户那边的定时任务会一直重试，造成不必要的噪音。

我们的做法是返回一个标准的错误体，带上retry_after_ms字段。调用方拿到这个字段后，可以按时间退避重试，而不是死循环。这个在对接外部客户时特别重要，能显得你的API设计很专业。

6. 从线上事故里总结出的六个坑

6.1 缓存过期时间与吊销之间的竞态

有一次某外包项目的密钥需要紧急吊销。我们直接在数据库里把status置为0，但忽略了网关本地缓存的最大过期时间是5分钟。结果这5分钟内，流量还在使用这个Key正常调用大模型，业务方收到通知说Key已废，但线上调用还是通的。虽然最后没有产生实际资损，但这个漏洞是致命的。

解决方式：吊销操作必须走"DB更新 + 消息通知 + 本地缓存淘汰"的完整链路，而且在缓存淘汰完成前，不允许吊销接口返回成功。做一次主动验证，让控制台能实时查询缓存中该app的存活状态。

6.2 计量数据丢失与幂等缺失

计费链路用的是异步消息队列。有一次消息队列抖动，一批usage记录没有成功写入，导致当天账单少记了几十万token。排查后发现，我们是"调用完成之后发一条消息"，如果消息丢了，没有任何补偿。

修复方案有两个：一是增加本地文件兜底，网关在推送消息失败时，把usage记录写到本地磁盘的一个复核目录，由定时任务扫盘重推；二是要求所有计量消费端做幂等，以trace_id作为唯一键，重复消息直接丢弃。这样即使在网关和队列之间发生重复投递，也不会导致重复计费。

6.3 日志和埋点泄露密钥

这是个低级但极易犯的错。我们的网关框架日志默认会打印完整的HTTP请求头，Authorization: Bearer sk_live_xxx就出现在日志里了。日志系统如果权限管控不严，等于把密钥明文送给了所有能看日志的人。

解决方式：日志过滤器里对Authorization、X-App-Key等字段做脱敏，只保留前几位和后四位，中间用****代替。同时禁止开发者在业务日志里手动打印header。上线前用模拟请求跑了全套日志扫描，确保没有哪个中间件会悄悄打明文。

6.4 字符串比较的时序攻击

Key校验时，如果用普通的==比较哈希值，理论上存在时序攻击的风险：攻击者可以通过比较时间的细微差别来逐步猜测hash，虽然哈希值本身就是随机串、这个攻击很难实际利用，但作为Key体系，还是应该直接用常量时间比较。

在Java里用MessageDigest.isEqual()，在Go里用crypto/subtle.ConstantTimeCompare，在Python里用hmac.compare_digest。这个改动成本极低，但专业程度完全不同。

6.5 旧Key版本迁移时忘了灰度

有一次我们给某客户做密钥轮换，生成了新版本secret_key之后，旧版本还保留着。但网关校验逻辑写死了"只查最新版本"，导致旧版Key在那段时间里全部401，客户小程序直接一片报错。

所以版本管理的代码路径一定要设计成：按app_id查到所有active的secret_version，逐个校验。虽然多一次查询，但换来版本轮换时的无损迁移。active版本通常不超过3个，性能影响可忽略。

6.6 限流器在单实例与多实例之间的口径不一致

早期我们的限流器是纯本地的Caffeine + 本地计数器，单机部署时没问题。后来网关扩到多台，每台机器各自维护令牌桶，总QPS变成原来机器数的N倍，客户配额直接形同虚设，某天一个客户的定时任务把上游供应商的限流都打爆了。

后来把限流计数器迁到Redis，用Lua脚本保证原子性。虽然每个请求多了一次Redis往返，但多机一致性有了保障。这里有个折中建议：RPS限流用Redis分布式，并发信号量也可以用Redis，但本地可以加一层粗粒度保护，两者取交集，避免一次Redis超时就完全失去限流能力。

7. 整个方案的最终形态

经历了若干次迭代之后，这套方案已经变成一个相对稳定的体系：控制台负责Key的全生命周期管理，网关负责鉴权、限流、计量，消息队列异步处理账单，监控系统持续盯指标。

整个链路最关键的体会是：不要为了"省事"而把生成和校验做得太薄。大模型API Key本质上是一个绑定成本结算的访问凭证，它必须同时具备"身份可信、权限可控、成本可计、行为可审"四个属性。少一个，线上运营就会出问题。

如果你正要搭建类似系统，我的建议是：一开始就把app_id和secret_key分开设计，把配额计量放到与鉴权平级的位置，把缓存失效当成一个和"生成随机数"同等重要的核心问题对待。这些看起来不起眼的取舍，会在流量上来之后变成你睡得着觉还是被拉起来处理事故的区别。