简介OneAPI计费系统开源版1.2.0是一套面向开发者与平台运营者的接口计费管理方案适合需要为API接口接入免费、资源包或混合计费模式并配套卡密兑换、余额充值、实名认证与手机号绑定校验等场景。本次更新修复了特定值扣费逻辑增加邮箱/短信验证码防刷机制及注册赠送余额优化了已知问题整体更适合作生产环境的基础搭建。包体共2000个文件以725个md文档、643个php源码、531个json配置为主另含少量js、css、sql及html等涵盖代码逻辑、接口文档、前端样式与数据库脚本8.34MB的压缩包便于快速部署与二次开发。已有95人学习下载。资源提供完整的开源版代码与在线编辑能力包含API文档在线编辑、文件代码在线编辑、多种通知方式等功能。读者可据此部署一套可运行的计费系统参考md文档理解鉴权与计费流程结合php源码调整扣费规则利用json配置定制资源包与通知策略。1. OneAPI计费系统开源版1.2.0一套「统一网关 计量计费 配额管控」能直接落地吗做AI应用的人这两年大概率都被同一个问题卡过项目里同时接了OpenAI、通义、智谱、DeepSeek每个渠道有自己的API Key、自己的计费口径、自己的并发限制业务侧的调用代码被厂商SDK绑死换一个渠道就要改一层封装账单月底对不上更是常态。OneAPI计费系统开源版1.2.0正是冲着「统一渠道接入 计量计费 配额管控」这三件事来的。它不是一堆代码仓库里无人维护的玩具而是一个能直接部署、能在生产环境扛住多模型网关转发的开源方案适合做AI应用中间层的团队也适合给内部算法平台做模型成本核算。这套系统的核心价值在于把「请求转发」和「计费结算」解耦。业务方只认一套OpenAI兼容接口由OneAPI做渠道分发同时按token用量、按模型单价把每条请求折算成金额落到用户/令牌维度配合余额和配额限制天然适合做SaaS化计量或企业内部成本分摊。1.2.0这个版本号意味着它已经过了早期功能堆叠期基础链路是稳的但离「开箱即用」还差一层对计费模型的理解这篇就把它讲透。2. 理解OneAPI计费系统的计量模型先分清Token计量、金额计量和配额限制三件事2.1 为什么说计费系统不是简单的「价格 × 次数」拿一个真实场景开头你的业务方一次流式对话底层可能打了3次模型调用其中一次还因为上下文过长被截断重试。如果只是按调用次数计费成本完全失控。OneAPI计费系统1.2.0的做法是把计费拆成三层原始请求记录每次调用一个日志条目、Token换算每个模型定义自己的计价单位、金额聚合按用户/令牌维度汇总。这三层对应了计费系统的核心表结构。这三层里最容易理解错的点是「Token计量不等于按请求字符串长度数」。常见想法是拿字符串长度除以4近似token数这在中文场景下误差很大。OneAPI处理流式响应的方式是累计所有chunk里的usage字段增量而不是自己数文本长度。也就是说模型返回的usage里写了多少token就认多少网关只做累加不做重算。这个设计有个隐藏前提模型渠道商必须在流式响应里正确上报usage。如果某个渠道漏报或者延迟报账单就会偏少这也是后面排查对账差异时的第一怀疑对象。金额计量则是在token量之上乘以模型单价。OneAPI支持按模型名配置单价单位是「每千token多少美元或人民币」。这里有个坑不同渠道的计价单位不一样有的按输入输出分开计价有的按总token计价有的按字符数计价。1.2.0引入了「倍率ratio」字段来做归一化核心思路是把所有渠道的计价方式对齐到「每百万token成本」这个统一基准上。2.2 配额限制的真正作用不是防超支而是防级联故障很多人把配额理解成「钱够不够」这是最表面的用法。OneAPI的配额体系实际上分了三类用户余额够不够扣、令牌配额单key最大可消费额度、并发/速率限制每分钟最大请求数。后两项才是生产环境最容易踩坑的地方。设想一个场景某业务方接入了OneAPI后端配置了一个渠道池池子里包含3家模型服务商。业务方某个时段请求量暴涨如果只有余额限制没有并发限制OneAPI会把这批流量同时打到3家服务商其中一家的限流策略是快速失败结果这批请求全部报错业务方的日志里出现大量超时和429。这就是典型的「余额够了但并发配额没设」导致下游服务被冲垮。我在部署时习惯把并发限制调成「预估峰值的一半」。即使业务方过来抱怨速度也坚持这个策略因为OneAPI本身不是专用负载均衡器它的转发是同步阻塞式的单个渠道响应慢会占住连接学会让请求排队比让请求无脑打出去更好调。2.3 日志数据保留多久直接决定能不能对上账OneAPI的日志表records会记录每一条调用的渠道、模型、token用量、延迟、花费金额。这个表增长速度极快一天几十万条调用一个月就是千万级。默认不清理数据库膨胀到一定程度后不仅日志查询变慢还会拖累计费结算性能。我一般会配置定时任务把30天前的原始日志转存到冷存储比如按天分表的独立库或对象存储OneAPI的后台保留明细查询入口对账时从冷存储拉取。1.2.0版本里日志清理策略相关配置用的是环境变量或UI设置里用cron表达式控制清理频率建议按业务量设计保留窗口而不是为了省事直接关掉清理。同时在数据库侧建好索引user_id created_at联合索引、token_id created_at联合索引避免对账时全表扫。3. 部署OneAPI计费系统1.2.0用Docker Compose快速跑通最小可用实例3.1 部署架构和最小依赖Docker Compose就够常见做法是用Docker Compose拉起OneAPI服务端 MySQL Redis服务端自身负责Web管理界面和OpenAI兼容网关入口MySQL存配置和账单Redis做令牌配额计数和限流。这套方案在单机2C4G的配置下就能扛住中等规模的压力。先看一眼我推荐的最小目录结构oneapi-deploy/ ├── docker-compose.yml ├── env.example # 环境变量模板 ├── logs/ # 服务日志挂载目录 └── data/ # MySQL数据持久化目录接着给出整套compose配置重点标注了与计费相关的环境变量version: 3.8 services: mysql: image: mysql:8.0 container_name: oneapi-mysql restart: always environment: MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD} MYSQL_DATABASE: oneapi command: --default-authentication-plugincaching_sha2_password volumes: - ./data/mysql:/var/lib/mysql healthcheck: test: [CMD, mysqladmin, ping, -h, localhost] interval: 10s timeout: 5s retries: 5 redis: image: redis:7-alpine container_name: oneapi-redis restart: always command: redis-server --requirepass ${REDIS_PASSWORD} volumes: - ./data/redis:/data healthcheck: test: [CMD, redis-cli, ping] interval: 10s timeout: 5s retries: 5 oneapi: image: ghcr.io/songquanpeng/one-api:1.2.0 container_name: oneapi restart: always depends_on: mysql: condition: service_healthy redis: condition: service_healthy ports: - 3000:3000 environment: SQL_DSN: root:${MYSQL_ROOT_PASSWORD}tcp(mysql:3306)/oneapi?charsetutf8mb4parseTimeTruelocLocal REDIS_CONN_STRING: redis://:${REDIS_PASSWORD}redis:6379/0 SESSION_SECRET: ${SESSION_SECRET} # 计费相关配置 BILLING_USAGE_ENABLED: true BILLING_LOG_RETENTION_DAYS: 30 TZ: Asia/Shanghai volumes: - ./logs:/app/logs这里有几个参数需要认真理解。SQL_DSN里那个charsetutf8mb4和parseTimeTrue是必须的。utf8mb4保证emoji和生僻字不出错因为模型响应文本里可能带任何字符parseTimeTrue保证时间字段被正确解析成Go的time.Time类型否则日志按天清理的cron表达式会因时区错乱导致清理错位。BILLING_USAGE_ENABLED是1.2.0里控制是否记录每次调用token明细的开关关掉后日志只记条数不记token对账就没法做保持true。BILLING_LOG_RETENTION_DAYS控制日志保留天数配合定时任务做冷备常见配置是14到30天。SESSION_SECRET一定不能全网通用它用于签名用户登录会话。如果多实例部署所有实例必须保持一致否则登录态在不同实例间会互相踢下线。提示Redis的密码如果为空连接串要写成redis://127.0.0.1:6379/0不要写redis://:127.0.0.1:6379/0某些版本会解析崩溃。3.2 初始化数据和第一个管理员账号第一次启动后OpenAPI服务端会自动创建数据库表结构。然后手动执行一条命令创建管理员docker exec -it oneapi ./one-api init这条命令会在服务端日志里打印初始管理员账号默认用户名是root密码是随机生成的。登录后第一件事是在「系统设置」里改掉初始密码。注意「create」子命令在1.2.0里做过一次调整旧版本用./one-api create新版本统一用./one-api init。如果你参考的是老文档命令会报找不到这不是部署失败是新版改动。3.3 用HTTP请求验证转发和计费链路是否打通部署起来不算跑通要验证「请求能转发出去、账单能记下来」才算。常见的验证方式是直接调用OpenAI兼容接口curl http://localhost:3000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的令牌 \ -d { model: gpt-4o-mini, messages: [{role: user, content: ping}], stream: false }这条命令做了三件事验证了网关的OpenAI兼容路由、验证了令牌配额校验、验证了计费记录落库。如果返回正常响应去后台「日志」页面看这条请求记录应能看到tokens和花费金额字段。这一步趁早做因为后面配置计费规则时要靠日志确认规则是否生效。没有日志你根本不知道按倍率折算后的金额对不对。4. 配置渠道、令牌与计费规则把单价和倍率设对是核心工程4.1 渠道配置里的「模型重映射」是计费准确性的第一道关OneAPI把「上游渠道」和「下游模型名」做了松耦合。你可以在渠道配置里把上游模型名映射成你对外发布的模型名。这个机制会直接影响计费——因为计费是按「对外模型名」的单价走的而不是按上游渠道的原始计价走。举例上游渠道A把qwen-max的价格定成每千token 0.02元渠道B定成0.015元。你在OneAPI里对外发布的模型名都叫qwen-max统一单价设为0.02元。这样业务方视角价格稳定渠道B成本更低中间差价就是毛利或内部成本差。这种做法的前提是你能拿到渠道的真实成本和价格否则差价会变成糊涂账。配置位置在「渠道 → 新建渠道 → 模型」里填对外模型名再在「模型重定向」里把对外名映射到上游实际接受的名两者用逗号分隔。4.2 倍率ratio到底怎么算从渠道计价单位到统一基准OneAPI后台「系统设置 → 计费设置」里有一个「倍率」列表默认给了一批模型的标准倍率。它的含义是1倍率对应的金额 每1千token的基准单价。打个比方假设基准单价设为0.002美元/1k token模型A的实际上游单价是0.004美元/1k那模型A的倍率就是2。推到真实上游会碰到计价单位不一致的问题。有的渠道按「百万token」计价有的按「字符数」计价有的按「1k字符」计价。倍率计算必须先归一化到「每千token」口径。来看一个具体的换算表格上游计价方式数字表示归一化到每千tokenOpenAI按每1k tokengpt-4o $0.0025 / 1k input$0.0025某厂商按每1k字符qwen $0.0005 / 1k char约$0.0005中文字符与token比约1:1.5某厂商按百万token$0.60 / 1M input$0.0006 / 1k表格里第三行就是最容易出错的点。$0.60每百万token听起来便宜折成每千token是0.0006美元如果你忘了除以1000直接填0.6账单会贵1000倍。这个错误上线后很难在第一时间发现因为单条请求差异小到月底汇总才暴露。设置倍率时还有一个REASONING模型的坑很多推理模型如o1类的用量包含「思维链token」但只报告在output部分里。若渠道方不单独区分统一按输出单价计费成本会偏高。排查时会发现日志里output token数大得异常不是bug是定价口径要考虑进去。4.3 令牌Token维度的配额设置给每个业务方独立的计量户头OneAPI里的「令牌」概念更接近「API Key」一个用户可以创建多个令牌每个令牌可以设独立配额限制。业务方接入时应该给每个下游系统单独一个令牌而不是共用。配置步骤1. 后台「令牌 → 添加令牌」→ 填写名称如数据平台-生产 2. 关联用户选中该业务的实际负责人账号 3. 设置额度按月度预算估算例1000元 4. 设置并发限制例10 次/秒 5. 启用模型范围限制只勾选该业务实际用到的模型 6. 有效期建议配置到期时间避免僵尸令牌第5步容易被忽略。不限制模型范围业务方就拥有所有模型的调用权一旦模型列表里有高倍率模型比如GPT-4对方误调用一天的账单就能顶一个月预算。令牌创建后要等1分钟再测试调用。OneAPI会定期从数据库同步令牌配置到Redis缓存刚创建立即调用可能拿到缓存里不存在的旧数据导致401。4.4 用户充值、预付费与账单导出计费闭环的最后一环如果说渠道配置解决的是「钱怎么算」那么用户体系解决的是「钱从哪扣」。OneAPI按用户维度管理余额支持预充值和手动调账。生产用常见流程是业务方提工单申请额度 → 管理员给用户充值 → 给该用户创建令牌 → 业务方拿令牌调用。这样的闭环让「用量、余额、账单」三张表能在人和系统之间对得上。账单导出的核心是「交易记录」页面可以按用户、时间、令牌导出CSV。对账时和上游渠道的账单做比对不对时优先查日志表的model_name字段和渠道的model_name字段是否一致——如果做过多路转发同一模型在不同渠道的token计量可能不同。我实际遇到过一次对账差异某渠道的账单多收了30%金额排查发现该渠道的上游对多轮对话整体重新计算token而OneAPI记录的是每轮请求独立计费累加两者统计口径不一致。这类差异不是OneAPI的问题是上游计费方式跟网关不一致只能在定价倍率里掺入一定缓冲比例。5. OneAPI计费系统的五个高频坑现象、原因和解决办法5.1 登录后台后立刻被登出返回403现象本地部署好后登录Web后台操作几下提示Token无效或直接跳出登录页。原因SESSION_SECRET用的是默认值或不同实例间不一致。多实例部署时请求被负载均衡分发到另一台机器session校验失败。解决统一所有实例的SESSION_SECRET环境变量用足够随机的值例如openssl rand -base64 32生成的串。改完后重启服务并清空浏览器该站cookie重新登录。5.2 渠道测试通了但真实请求全部超时现象后台测试渠道时用的是/v1/models接口返回正常。但业务侧发真正的chat请求时大量超时和502。原因上游渠道对「流式响应」的支持和OneAPI不一致或是渠道侧对长超时请求主动断开。还有一种情况是出网代理没配上游域名无法连通。解决先在服务器本地用curl直接打上游官方地址确认上游连通性。如果不是网络问题把OneAPI的渠道配置里的「超时时间」从默认的60秒调到120秒不要用「测试模型」这个按钮来判断生产链路它走的是另一套短连接。5.3 日志有调用记录但金额全是0现象后台日志里能看到请求记录tokens也正常但花费金额一栏全是0.0000。原因目标模型在「系统设置 → 定价」里没有配置单价或配置了但对应倍率没有落到该模型名上。解决在计费设置里找到该模型项填上正确的倍率值并保存新的调用才会以该单价核算。历史日志不会自动回溯修正。所以上线初期先小额充值测试确认金额字段非0再放量。5.4 Redis里令牌限额和数据库里的额度不一致现象给某个令牌充值了余额但调用时仍报额度不足。原因OneAPI把配额信息缓存到Redis修改余额后不会立刻同步需要等待下一次缓存刷新周期。在1.2.0里配置文件中CACHE_REFRESH_INTERVAL字段控制刷新间隔默认是几分钟。解决在后台「令牌 → 编辑 → 保存」强迫刷新该令牌的缓存或者直接重启oneapi容器。这不是bug是缓存同步机制习惯就好。批量充值场景下建议调短CACHE_REFRESH_INTERVAL代价是Redis压力略增。5.5 月底账单对不平比上游账单多了几块钱现象对账发现OneAPI统计的金额高于上游用户侧投诉。原因上游原始响应里如果usage字段的completion_tokens包含某些占位符或敏感词过滤过程产生的token而OneAPI的计费设置里没有单独区分输入/输出单价统一按一个高价算了账。解决在渠道配置中按上游实际字段启用「输入倍率」和「输出倍率」分开设置。1.2.0渠道配置里模型项支持分别填写输入输出单价没单独设置的输出价格会跟输入一样推理模型场景差异尤其明显。以上这些坑不是「遇到了再查」建议在部署验证阶段就主动踩一遍尤其是第3条和第4条一个影响账准确度一个影响线上拒绝率。6. 进阶玩法用接入层把OneAPI的失败请求自动二次调度到备渠道基础部署做到「能记账」已经能用了但生产环境的稳定性还要补一层那就是自动重试。OneAPI本身做了一次渠道择优但它不会对同一请求做「失败后换渠道重放」。业务侧直接拿OneAPI的失败结果当最终结果有些丢请求就白白丢了。常见解法是在OneAPI前面再叠一层「接入网关」比如用Nginx或Kong做超时重试或请求排队但这层要自己写转发逻辑。我实际验证过的一种轻量方案业务侧封装一个Python客户端库调用OneAPI失败且code等于upstream_error时自动把同样的payload发到备用的OneAPI实例或直接发到备用渠道两边独立记账再做一次消重。这样做的前提是业务侧能容忍偶尔一次的重复请求。对于幂等的场景比如文本分类完全可行对非幂等场景比如生成类请求可以加一个请求ID在业务库里做唯一约束重放时发现已存在记录则直接丢弃新结果。OneAPI的请求日志里其实有一个request_id字段但它不会把它作为幂等键返回给调用方。更深一层OneAPI的渠道优先级配置可以配合「模型重定向」实现按渠道成本排序优先打低成本渠道达到一定失败率后切到高成本兜底渠道。这个逻辑只能由渠道的「自动禁用」阈值实现在渠道设置里把连续失败次数设为3触发后自动禁用该渠道。但要注意被禁用的渠道不会自动恢复需要定时人工巡检或写脚本调/api/channel/status接口恢复。实际生产里我还会配合一组探活脚本每隔1分钟对齐一下OneAPI和上游账单明细金额误差超过1%就告警。这种对账思路比盲目相信任何一个系统的输出都可靠。最后一句话能把这套系统的「计量、记账、限额」在内部团队里跑出信任别急着开放给外部客户。先拿真实项目用两个月养成每周导账单、查日志、比余额的习惯再谈对外。希望帮到你。本文还有配套的精品资源点击获取