企业官网建设流程全解析

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 应该是一本独立的、平行的账，而不是挂在套餐下面的子账。

下面这张表把四本账的核心差异列清楚：

3. 账本数据结构设计：四张表怎么建才不打架

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 只要一个 balance，API 则要按模型维度统计。

注意：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_reset，amount为 0，但reason里记录新周期的总额度。这样对账时能清楚看到每次重置的时间和额度。

4. 对账逻辑：怎么证明四本账没有算错

4.1 日终对账的三步校验

账本系统最怕的不是算错，而是算错了还不知道。所以我设计了一套日终对账流程，每天凌晨跑一次，做三步校验：

第一步，流水求和校验。把usage_ledger里当天的所有记录按ledger_type分组求和，和余额表的当日变化量对比。如果对不上，说明有流水漏记或余额被直接修改了。

第二步，跨账本一致性校验。检查是否存在同一笔ref_id在多个账本里都有扣减记录的情况。正常情况下，一个请求只应该扣一本账（API 除外，API 是独立的）。如果发现跨账本重复扣减，说明扣减状态机有 bug。

第三步，余额非负校验。所有账本的余额都不应该为负。如果出现负数，要么是并发问题，要么是预扣减没有正确回补。

4.2 对账差异的常见来源

实测下来，对账差异 90% 来自这几个地方：

• 时区问题：流水表用 UTC 存，对账时用本地时间切分，导致跨天的记录被算错天。解决办法是统一用 UTC 做对账。
• 浮点精度：金额和额度用 float 存，累加后出现 0.000001 的误差。必须用 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 model's maximum context length is 1048576 tokens。这个报错表面上是模型限制，但在账本系统里它有个隐藏影响：超限的请求不应该被计费。如果账本在请求失败后仍然扣了 token，就会导致账实不符。

我的处理方式是把计费点放在响应成功返回之后，而不是请求发出时。预扣减可以做，但最终结算必须以成功响应为准。失败请求的预扣减要全额回补，并在流水里标记status=failed。

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 的过程。这个过程本身，就是你对用量理解不断加深的过程。