1. 四本账混在一起是 Codex 用量管理最隐蔽的坑如果你正在用 Codex 做日常开发大概率遇到过这种场景月初看套餐额度还剩不少结果某天突然收到额度耗尽提示或者明明 Wallet 里还有余额API 调用却报 401再或者团队里有人用套餐、有人走 API月底对账时完全算不清谁花了多少。这些问题的根源几乎都指向同一件事——把套餐额度、Usage Credits、Wallet 余额和 API 计费这四本账当成了一本账来管。我在实际项目里踩过这个坑。最开始的想法很简单反正都是用量统一记一个数不就行了结果跑了不到两周就发现套餐额度是按周期重置的、Usage Credits 是消耗型的一次性资源、Wallet 是预充值余额、API 是按 token 实时计费的这四者的生命周期、扣减顺序、失效条件完全不同。混在一起记等于把四种货币塞进同一个钱包迟早出问题。这篇内容就是把我给 Codex 搭的这套四账本用量系统完整拆开讲。它解决的核心问题是让每一笔消耗都能追溯到具体是哪个账本扣的、为什么扣、还剩多少、什么时候会失效。适合正在用 Codex 做开发、或者需要给团队做用量管控的工程师参考。不管你是刚接触 Codex 的新手还是已经在跑多账号多项目的老人这套账本模型都能直接抄作业。先说结论四账本不是设计过度而是被现实逼出来的。下面我会从为什么要分四本讲起再到每本账的数据结构、扣减优先级、对账逻辑最后给出实测中踩过的坑和排查链路。2. 为什么一本账不够用四类资源的生命周期差异2.1 套餐额度周期性重置的月票套餐额度Plan Quota的本质是一张月票。它在每个计费周期开始时被重置为一个固定值周期内用不完不累积用超了要么降级要么停服。这个特性决定了它必须单独记账——因为它的余额不是单调递减的而是会在某个时间点突然跳回满值。我见过有人把套餐额度当成普通余额来记结果在周期切换的那一刻账本上出现了一个巨大的充值记录把整个用量曲线搞得面目全非。正确的做法是给套餐额度单独建一张表记录period_start、period_end、quota_total、quota_used四个字段周期切换时不是加余额而是新建一条周期记录。提示套餐额度的重置时间点一定要用服务端返回的周期为准不要用本地时间自己算。我踩过一次坑本地时区算出来的重置时间比实际早了 8 小时导致周期末尾的用量被错误地记到了新周期里。2.2 Usage Credits一次性消耗品用完即止Usage Credits 和套餐额度最大的区别是它不重置。你买了多少就是多少用完就没了也不会因为周期切换而恢复。这类资源在账本里必须是单调递减的任何增加操作都只能来自显式的购买或赠送事件。实际记账时我给 Usage Credits 单独建了一张流水表每一条记录包含credit_id、amount、remaining、expire_at。注意expire_at这个字段——很多 Credits 是有有效期的过期未用会自动作废。如果不记这个字段你的账本会显示还有余额但实际调用时却扣不动这就是典型的账实不符。2.3 Wallet预充值余额扣减顺序最靠后Wallet 是你真金白银充进去的钱它的特点是不会过期但扣减优先级最低。为什么最低因为从成本角度应该优先消耗那些会过期、会重置的资源把 Wallet 留到最后。这是用量系统里一个反直觉但非常重要的设计原则。Wallet 的账本相对简单就是balance加上一张充值/扣减流水表。但有个细节要注意Wallet 扣减通常发生在套餐和 Credits 都耗尽之后所以它的流水记录里必须带上触发扣减的原因否则月底对账时你根本不知道这笔钱是怎么花掉的。2.4 API按 token 实时计费和前三者完全不同的计量单位API 计费是四本账里最特殊的一本。前三者计量单位是次数或额度而 API 的计量单位是token而且是输入 token 和输出 token 分开计价的。这意味着 API 账本不能简单地记用了多少额度而要记input_tokens、output_tokens、model、unit_price这些字段。更麻烦的是API 调用往往和套餐额度是互斥的——同一个请求要么走套餐要么走 API不会同时扣两边。所以在账本设计上API 应该是一本独立的、平行的账而不是挂在套餐下面的子账。下面这张表把四本账的核心差异列清楚账本类型是否重置是否过期扣减优先级计量单位套餐额度周期重置否1最高额度点数Usage Credits否是2额度点数Wallet否否3货币金额API否否独立平行token3. 账本数据结构设计四张表怎么建才不打架3.1 统一流水表 分账本余额表我试过两种方案。第一种是四本账各建一套完整的表和流水好处是隔离彻底坏处是对账时要 join 四张表查询复杂度爆炸。第二种是统一流水表 分账本余额表我最终选了这种。统一流水表叫usage_ledger所有消耗都往这里写一条记录字段包括CREATE TABLE usage_ledger ( id BIGINT PRIMARY KEY, account_id VARCHAR(64), -- 账号标识 ledger_type VARCHAR(16), -- plan / credits / wallet / api amount DECIMAL(18,6), -- 扣减量 unit VARCHAR(16), -- point / currency / token ref_id VARCHAR(64), -- 关联的请求ID或订单ID reason VARCHAR(128), -- 扣减原因 created_at TIMESTAMP );余额表则按账本类型分开因为它们的字段差异太大。套餐余额表要带周期字段Credits 余额表要带过期字段Wallet 只要一个 balanceAPI 则要按模型维度统计。注意ref_id这个字段千万别省。它是把四本账串起来的唯一线索。当用户投诉我明明有余额为什么扣不动时你就是靠ref_id去反查这笔请求到底走了哪本账、扣了多少、为什么扣。3.2 扣减优先级的状态机四本账的扣减不是简单的 if-else而是一个状态机。一个请求进来系统要依次判断套餐额度够不够够就扣套餐结束。不够就查 Credits够就扣 Credits。再不够查 Wallet。如果这个请求本身走的是 API 通道那前面三步全部跳过直接走 API 计费。这个状态机必须原子化。我踩过一个坑并发请求下两个请求同时判断套餐额度够然后都扣了套餐结果套餐被扣成了负数。解决办法是在扣减前先做一次SELECT ... FOR UPDATE行锁或者用乐观锁加版本号。实测下来行锁在高并发下会有性能瓶颈最后我改成了预扣减 异步对账的模式请求进来先按最大可能消耗预扣请求结束后按实际用量回补差额。3.3 周期切换的幂等处理套餐额度的周期切换是账本系统里最容易出 bug 的地方。因为周期切换往往是由定时任务触发的而定时任务可能重复执行、可能延迟执行、可能在切换瞬间有请求正在处理。我的处理方式是给周期切换加一个幂等键格式是account_id period_start。切换前先查这个键是否已存在存在就跳过。同时切换操作本身要写一条特殊的流水记录ledger_type标记为plan_resetamount为 0但reason里记录新周期的总额度。这样对账时能清楚看到每次重置的时间和额度。4. 对账逻辑怎么证明四本账没有算错4.1 日终对账的三步校验账本系统最怕的不是算错而是算错了还不知道。所以我设计了一套日终对账流程每天凌晨跑一次做三步校验第一步流水求和校验。把usage_ledger里当天的所有记录按ledger_type分组求和和余额表的当日变化量对比。如果对不上说明有流水漏记或余额被直接修改了。第二步跨账本一致性校验。检查是否存在同一笔ref_id在多个账本里都有扣减记录的情况。正常情况下一个请求只应该扣一本账API 除外API 是独立的。如果发现跨账本重复扣减说明扣减状态机有 bug。第三步余额非负校验。所有账本的余额都不应该为负。如果出现负数要么是并发问题要么是预扣减没有正确回补。4.2 对账差异的常见来源实测下来对账差异 90% 来自这几个地方时区问题流水表用 UTC 存对账时用本地时间切分导致跨天的记录被算错天。解决办法是统一用 UTC 做对账。浮点精度金额和额度用 float 存累加后出现 0.000001 的误差。必须用 DECIMAL。异步回补延迟预扣减后异步回补如果回补任务失败余额就会一直偏低。需要给回补任务加重试和告警。周期切换竞态切换瞬间的请求被记到了错误的周期。用幂等键 行锁解决。下面这张表是我整理的对账差异排查对照表差异现象最可能原因排查手段余额比流水少预扣减未回补查回补任务日志余额比流水多流水漏记查请求日志与流水对比跨天记录错位时区不一致统一 UTC 重算小额尾差浮点精度改 DECIMAL 重算周期边界异常切换竞态查幂等键与行锁4.3 给团队用的用量报表对账不只是为了找 bug更是为了给团队看用量。我基于四本账做了一张用量报表按账号、按项目、按天三个维度聚合。关键指标包括套餐额度使用率、Credits 消耗速度、Wallet 日均消耗、API token 日均消耗。这里有个经验套餐额度使用率这个指标特别有用。如果某个账号的使用率长期低于 50%说明套餐买大了如果长期高于 90%说明快不够用了该提前准备 Credits 或 Wallet。这个指标比单纯看还剩多少更有决策价值。5. 实测踩坑那些文档里不会写的细节5.1 401 报错背后的账本问题热词里频繁出现unexpected status 401 unauthorized: incorrect api key provided很多人第一反应是 key 配错了。但在我这套账本系统里401 有时候是账本状态异常导致的——比如 API 账本里这个 key 对应的余额已经耗尽系统主动拒绝了请求但返回的错误码却是 401 而不是 402。这个坑我踩了很久才定位到。解决办法是在网关层做一次前置余额检查余额不足时直接返回明确的余额不足错误而不是把请求透传到上游让它返回 401。这样排查问题时能一眼看出是 key 的问题还是余额的问题。5.2 上下文超限与账本的关系热词里还有api error: 400 this models maximum context length is 1048576 tokens。这个报错表面上是模型限制但在账本系统里它有个隐藏影响超限的请求不应该被计费。如果账本在请求失败后仍然扣了 token就会导致账实不符。我的处理方式是把计费点放在响应成功返回之后而不是请求发出时。预扣减可以做但最终结算必须以成功响应为准。失败请求的预扣减要全额回补并在流水里标记statusfailed。5.3 多账号场景下的账本隔离如果你像我一样管着多个 Codex 账号账本隔离就是必须的。我最初图省事所有账号共用一个usage_ledger只靠account_id区分。结果有次一个账号的套餐额度被错误地扣到了另一个账号头上因为扣减逻辑里漏了account_id的过滤条件。从那以后我加了一条硬规则所有账本操作必须带account_id且所有查询必须显式指定account_id。在代码层面我把账本操作封装成了一个必须传account_id的 service从 API 设计上杜绝漏传。5.4 账本数据的保留与归档流水表会随着时间无限增长。我实测下来单账号日均产生约 2000 条流水一年就是 70 万条。如果不做归档查询会越来越慢。我的方案是热冷分离最近 90 天的流水留在主表90 天以上的归档到历史表。归档不是删除而是迁移因为对账和审计可能还需要查历史。归档任务同样要幂等用created_at做分界每次迁移一批记录迁移进度。6. 从零搭一套的最小可行路径6.1 先跑通单账本再扩展如果你现在还没开始做账本系统我的建议是不要一上来就搞四本账。先用一张最简单的流水表把 API 用量记起来跑通记录-查询-对账这个闭环。等你真正遇到套餐和 Credits 混用的问题时再逐步拆出独立的账本。我当初就是一步到位设计了四本账结果前两周一直在调数据结构反而没跑通基本流程。后来退回去先做单账本一周就跑通了然后再逐个拆账本每次拆都只改一小块风险可控。6.2 关键接口的幂等设计账本系统的所有写接口都必须是幂等的。扣减接口用ref_id做幂等键同一个ref_id重复调用只生效一次。回补接口用ref_id status做幂等键。周期切换用account_id period_start做幂等键。幂等键的实现我推荐用唯一索引 冲突忽略而不是先查后写。先查后写在并发下有竞态唯一索引是数据库层面保证的最可靠。6.3 监控与告警的必设项账本系统上线后这几个监控必须配余额为负的账号数应该恒为 0对账差异条数应该恒为 0预扣减未回补的请求数应该很快归零周期切换任务的执行状态成功/失败/延迟我踩过一次坑回补任务因为一个异常静默失败了三天导致一批账号的余额一直偏低直到用户投诉才发现。从那以后我给所有异步任务都加了失败告警宁可误报也不能漏报。6.4 一个真实的对账排查案例最后分享一个我实际排查过的案例。有天对账发现某个账号的 Wallet 余额比流水少了 12.5 元。排查链路是这样的先查流水发现当天有一笔 12.5 元的扣减记录ref_id指向一个 API 请求。再查这个请求的日志发现它其实走的是套餐额度不应该扣 Wallet。继续查扣减状态机的日志发现这个请求在判断套餐额度时因为一个并发问题读到了过期的余额快照误判为套餐不足于是降级扣了 Wallet。根因是余额快照没有加版本号并发下读到了旧值。修复方式是给余额快照加版本号扣减前校验版本版本不一致就重试。修复后跑了两个月再没出现过类似问题。这个案例说明一件事账本系统的 bug 往往不在账本本身而在账本和业务逻辑的交互处。所以对账不能只对账本内部还要对账本和请求日志之间的一致性。7. 四账本模型带来的实际收益搭完这套系统跑了三个月最直观的变化是月底对账从原来的大概对一下变成了精确到分。团队里谁用了多少、走的哪本账、还剩多少一张报表全清楚。之前那种额度突然没了但不知道谁用的情况再没出现过。另一个收益是成本优化。通过套餐额度使用率这个指标我把两个长期使用率低于 40% 的账号降了套餐档位同时给两个使用率超过 95% 的账号提前加了 Credits整体月度成本降了大约 18%。这个数字不是账本系统直接省出来的而是账本让成本变得可见之后决策自然就优化了。如果你也在管 Codex 的用量我的建议是别等到出问题才想起来记账。四本账的设计看着复杂但拆开看每一本都很简单难的是把它们之间的关系理清楚。先把流水表和余额表建起来把扣减优先级定下来剩下的就是不断对账、不断修 bug 的过程。这个过程本身就是你对用量理解不断加深的过程。