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

1. 为什么需要自己造一套大模型Key体系1.1 从共享Key的混乱说起我之前在某公司内部做模型开放平台的时候最开始偷了个懒直接申请了一个大模型供应商的密钥把密钥写死在业务代码里或者放在配置中心让大家共用。结果上线不到一周就发现问题了——业务线A跑了一个夜间批处理任务把整个账号的并发额度打满业务线B的实时对话接口全部超时。那个时候我们连谁在调用、调了多少、哪个接口最贵都说不清楚更别提给不同团队做配额隔离了。后来我们决定自己搭一套面向大模型的API Key生成及校验方案。这个方案不是简单地在数据库里生成一个随机字符串就完事而是把身份识别、权限控制、配额计量、调用审计、密钥轮换、缓存降级全部串起来。做完之后整个平台的稳定性、可追溯性、以及计费能力都发生了质变。这篇文章我就把整个方案的设计思路和踩坑记录完整分享出来涉及的核心内容可以抽象成一句话用廉价且可靠的方式创建一个无法伪造、便于归因、可以吊销、支持配额与计量的大模型访问凭证。1.2 大模型API Key和传统API Key到底不一样在哪里如果你以前做过传统平台OpenAPI可能会觉得Key生成很常见——无非就是生成UUID、存数据库、请求头里带上校验。但大模型场景有个非常特殊的地方调用成本不是恒定的而是跟输入输出token数强相关。一次对话调用可能消耗几百个token一个长文档总结可能消耗几万个token而且不同模型比如对话模型、向量模型、图像模型的单价完全不同。这就意味着Key体系不能只回答你是谁还要回答三件事你能用哪些模型一个内部工具业务可能只需要对话模型不需要给图像生成模型的权限。你最多能花多少钱如果做企业客户接入token经费上限是合同里白纸黑字写的超了就要熔断。你这次调用花了多少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表用来存身份和授权信息核心字段如下字段含义说明app_id唯一身份标识形如ap-2b7d9f对外开放app_name应用名称便于控制台展示owner归属团队或负责人用于告警与审批root_key加密保存的SecretKey控制台只允许在创建时展示一次status启用/禁用/吊销状态机控制model_scopes允许访问的模型列表JSON数组或单独关联表quota配额定义包括token上限、金额上限、QPS上限expire_at过期时间支持短期凭证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_8f3kDx9qZt2mW7vPsk_固定前缀方便代码识别和日志过滤。live/test环境标识测试Key和生产Key一眼区分避免有人把测试Key带到生产环境。8f3kDx9qZt2mW7vP16位随机主体部分采用自定义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 fsk_{env}_{body} def generate_app_id() - str: # 身份ID故意短一些好记且必须保持唯一 return ap- secrets.token_hex(4)这里最关键的细节是必须用secrets模块不能图省事用random。random是伪随机数生成器内部状态可被预测一旦攻击者拿到多个样本就能推算出后续值这在密钥场景是致命的。3.2 存储策略不能存明文也不能完全不存明文这是整个方案最容易被做错的地方。如果只做校验我们可以像密码一样只存哈希但作为Key管理平台还必须能够在控制台展示Key比如给某个客户发找回凭证或者对旧密钥进行解密审计。所以我们的存储设计是双轨制用于校验的哈希值对完整的secret_key做带盐哈希建议Argon2id或至少bcrypt存入secret_hash字段。网关校验时只比对哈希不需要解密。用于找回的解密值用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 一次完整的调用怎么走通整个网关校验链路我建议这样设计客户端在HTTP请求头带上Authorization: Bearer sk_live_8f3kDx9qZt2mW7vP X-App-Id: ap-2b7d9f网关先用X-App-Id查本地缓存拿到该app的profile状态、scope、配额快照。网关用Authorization对应的secret_key做哈希比对确认凭证匹配。校验通过后网关按profile.model_scopes做模型路由鉴权——如果当前请求的模型不在允许列表里直接返回403。鉴权通过后进入配额校验检查当前已用token/金额是否达到上限。真正调用上游大模型供应商之前执行限流检查和并发信号量检查。得到上游响应后从响应里解析usage字段异步写入计量消息队列。网关返回正常响应给客户端。整个过程里第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各自都认为可以放行结果实际消耗超过上限。所以我们最终选择预扣方案请求进来时根据模型单价和估计的最大token大小先预扣一个数额比如预扣1000 token。调用完成之后用实际usage更正多退少补。如果调用失败直接退还预扣额度。预扣值怎么定我建议不要按估计值而是按这个模型单次请求的最大可能token数通常就是模型上下文上限。虽然这样做会让客户在开始阶段看到一个较大的可用余额减少但对防止超卖非常有效。如果不做预扣高并发下很容易出现两条请求同时通过校验、加起来把月度配额打爆的情况。在数据库或者Redis里配额扣减要使用原子操作Redis用DECRBY数据库用UPDATE ... SET quota_used quota_used ? WHERE quota_used ? quota_limit这种条件更新。千万不要先读后写否则并发必然出问题。4.4 限流算法怎么选很多文章会把限流单独拎出来讲这里我就结合大模型场景直接给结论。大模型网关的限流目标有两个一是限制每秒请求数RPS二是限制同时进行中的并发请求数。为什么并发也很重要因为一个长文本生成请求可能持续10秒以上如果只看RPS100个并发请求照样能把上游打爆。限流算法是否平滑是否适合大模型场景说明固定窗口否不推荐窗口切换瞬间可能出现双倍流量滑动窗口是较合适精确但需要存时间戳列表内存开销略高令牌桶是推荐允许突发又能限制均值实现简单并发信号量是必须搭配限制同时处理的请求数防止慢请求堆积我们的做法是令牌桶控制RPS再加一个分布式信号量控制并发数。比如某个可用Key的配置是RPS10并发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分开设计把配额计量放到与鉴权平级的位置把缓存失效当成一个和生成随机数同等重要的核心问题对待。这些看起来不起眼的取舍会在流量上来之后变成你睡得着觉还是被拉起来处理事故的区别。