9Router 配额跟踪与用量监控实战指南：实时追踪 Token 消耗、配额重置与成本预估
项目地址: https://gitcode.com/GitHub_Trending/9r/9router 导读
本文以 9Router 的配额跟踪（Quota Tracking）与用量监控功能为主线，完整讲解如何通过 Web 仪表盘实时查看各 AI 提供商（Claude Code、Codex、Gemini CLI、GLM、MiniMax、iFlow 等）的 Token 消耗、配额上限与剩余量、重置倒计时、成本估算与预算告警，并深入剖析仓库中用量统计（usageRepo.js）、配额 API（API 路由）与配额自动预热调度器（quotaAutoPing.js）的实现原理。读完本文，你将掌握 9Router 用量监控的完整使用方式与底层数据流，能够结合智能路由（smart-routing）与组合（combos）把订阅配额与预算花在刀刃上。
概述：9Router 的配额跟踪能力
9Router 对所有接入的提供商提供统一的配额跟踪与用量监控，核心能力包括：
- 实时 Token 消耗：按请求展示每次调用的输入、输出与总 Token 数；
- 配额上限与剩余量：将实际用量与提供商配额上限对比，以百分比进度呈现；
- 重置倒计时：精确展示配额将在何时重置（滚动窗口、每日、每月等不同策略）；
- 成本估算：对按量计费的提供商实时计算当日、当月支出；
- 月度报告：按周、按提供商、按模型分析使用模式并给出趋势预测；
- 告警与通知：在配额用尽之前通过仪表盘、邮件或 Webhook 提前警告。
这些能力在仓库中有着完整的实现支撑：前端用量页面位于 dashboard/usage/page.js/dashboard/usage/page.js)，支持 Today / 24h / 7D / 30D / 60D 多时间粒度；后端统计逻辑集中在 usageRepo.js（经由 usageDb.js 重导出），以 SQLite 数据库 usageHistory、usageDaily 与 _meta 三张表为核心存储（见 001-initial.js）。
仪表盘概览：配额一览无余
配额摘要卡片
登录 Web 仪表盘后，进入 Dashboard → Home → Quota Overview，每个已连接的提供商账户都会呈现一张配额摘要卡片，直观展示当前用量状态：
┌─────────────────────────────────────────────┐
│ Claude Code (cc/) │
│ ████████████░░░░░░░░ 2.5h / 5h (50%) │
│ Resets in: 2h 30m │
│ Cost: $0 (subscription) │
└─────────────────────────────────────────────┘
┌─────────────────────────────────────────────┐
│ Gemini CLI (gc/) │
│ ████████░░░░░░░░░░░░ 450 / 1000 (45%) │
│ Daily reset in: 18h 30m │
│ Monthly: 45K / 180K (25%) │
│ Cost: $0 (free tier) │
└─────────────────────────────────────────────┘
┌─────────────────────────────────────────────┐
│ GLM-4.7 (glm/) │
│ ██████████████░░░░░░ 7M / 10M tokens (70%) │
│ Resets: Daily 10:00 AM (in 5h 35m) │
│ Cost today: $4.20 │
└─────────────────────────────────────────────┘
┌─────────────────────────────────────────────┐
│ MiniMax M2.1 (minimax/) │
│ ████████████████░░░░ 4M / 5M tokens (80%) │
│ Rolling 5h window │
│ Cost (5h): $0.80 │
└─────────────────────────────────────────────┘
┌─────────────────────────────────────────────┐
│ iFlow (if/) │
│ ████████████████████ Unlimited │
│ Cost: $0 (free forever) │
└─────────────────────────────────────────────┘
不同提供商的配额语义差异巨大（小时、请求数、Token 数、无限），9Router 通过「ProviderLimits」组件（src/app/(dashboard)/dashboard/usage/components/ProviderLimits/dashboard/usage/components/ProviderLimits/index.js)）统一渲染为进度条与剩余时间，其中 QuotaProgressBar.js/dashboard/usage/components/ProviderLimits/QuotaProgressBar.js) 负责进度可视化，utils.js/dashboard/usage/components/ProviderLimits/utils.js) 提供 calculatePercentage、getConnectionQuotaRemaining、sortVisibleConnections 等解析与排序逻辑。
提示：ProviderLimits 组件支持按提供商过滤、按账户状态过滤、按配额剩余量排序，并提供 "Expiring first"（最先过期优先）开关与"批量关闭空配额账户 / 批量开启有配额账户"的快捷操作（对应源码中的
handleDisableDepleted/handleEnableAvailable，阈值常量DEPLETED_QUOTA_THRESHOLD）。
配额刷新机制
配额数据不是一次性快照：ProviderLimits 默认开启 Auto-refresh（自动刷新），按 REFRESH_INTERVAL_MS 周期轮询 /api/usage/[connectionId]，页面上有 60 秒倒计时提示；当浏览器标签页隐藏时（Page Visibility API）自动暂停轮询，回到前台立即恢复，避免无谓的网络请求。
源码中还存在一个对 Claude 的节流策略：Claude 的配额每 N 个 tick 才轮询一次（CLAUDE_REFRESH_INTERVAL_MS / REFRESH_INTERVAL_MS 取整），而手动点击 "Refresh all" 会强制全量刷新，平衡实时性与上游接口压力。
实时 Token 消耗
请求级跟踪
每次请求完成后，9Router 都会记录该请求的完整 Token 明细。进入 Dashboard → Activity → Recent Requests 可查看：
Request #1234
Model: cc/claude-opus-4-5-20251101
Timestamp: 2026-02-04 04:15:32
Tokens:
Input: 1,250 tokens
Output: 850 tokens
Total: 2,100 tokens
Cost: $0 (subscription quota)
Duration: 3.2s
Status: ✅ Success
这一能力的底层是 usageRepo.js 的 saveRequestUsage：它在一个数据库事务内完成三件事——向 usageHistory 表插入单次请求明细、向 usageDaily 表按本地日期做每日聚合（aggregateEntryToDay 同时维护 byProvider / byModel / byAccount / byApiKey / byEndpoint 五个维度）、并对 _meta 表中的 totalRequestsLifetime 做原子自增。Token 字段同时兼容 prompt_tokens / input_tokens（输入）与 completion_tokens / output_tokens（输出）两套命名（见 001-initial.js 的表结构），并对 cached_tokens（缓存命中）单独计数，为后续成本核算与缓存分析留出数据基础。
实时用量监视器
Dashboard → Live Monitor 展示正在进行的请求（进行中、尚未完成）：
Current request:
Model: glm/glm-4.7
Tokens streamed: 450 / ~800 estimated
Cost so far: $0.0009
Duration: 1.8s
进行中请求由 trackPendingRequest 维护在内存态 pendingRequests.byModel / byAccount 中，并带 60 秒超时兜底（PENDING_TIMEOUT_MS）；getActiveRequests 汇总活动请求与最近 20 条去重后的请求记录返回给前端。前端 UsageStats.js 通过 /api/usage/stats 拉取统计，并通过 EventSource("/api/usage/stream")（SSE 实时流）订阅 statsEmitter 发出的事件，从而让图表与数字随请求完成自动刷新。
按模型 Token 分解
Dashboard → Analytics → Token Usage 按模型汇总当日 Token：
Today (Feb 4, 2026):
cc/claude-opus-4-5: 15M tokens ($0, subscription)
glm/glm-4.7: 8M tokens ($4.80)
if/kimi-k2-thinking: 3M tokens ($0, free)
Total: 26M tokens
Cost: $4.80
getUsageStats(period) 对 Today/24h 直接扫描 usageHistory 明细，对 7D/30D/60D 则读取 usageDaily 预聚合数据（loadDaysInRange），并用历史表回填精确的 lastUsed 时间戳；图表数据由 getChartData(period) 按小时（Today/24h）或按天（7d/30d/60d）分桶生成。
配额上限与重置时间
9Router 将提供商划分为三类，分别处理其配额语义。
订阅型提供商
Claude Code（Pro/Max）
配额类型: 时间制（5小时滚动窗口）
上限: 5小时使用时长
重置: 5小时滚动窗口 + 每周更新
跟踪: 按模型记录使用时长
仪表盘显示:
Opus: 2.5h / 5h 使用
Sonnet: 1.2h / 5h 使用
Haiku: 0.8h / 5h 使用
周重置: 每周一 00:00 UTC
OpenAI Codex（Plus/Pro）
配额类型: 时间制（5小时滚动窗口）
上限: 5小时（Plus）/ 10小时（Pro）
重置: 5小时滚动窗口 + 每周更新
仪表盘显示:
GPT-5.2 Codex: 3.5h / 5h 使用
Resets in: 1h 30m
Gemini CLI（免费版）
配额类型: 请求数 + 月度 Token
日上限: 1,000 次请求
月上限: 180,000 次补全
重置: 每日 00:00 UTC + 每月 1 日
仪表盘显示:
Today: 450 / 1,000 requests (45%)
This month: 45K / 180K completions (25%)
Daily reset in: 18h 30m
Monthly reset in: 26 days
GitHub Copilot
配额类型: 月度用量
上限: 视套餐而定
重置: 每月 1 日
仪表盘显示:
Usage: 60% of monthly quota
Resets: March 1, 2026 (in 25 days)
源码佐证：Codex 的配额接口由 open-sse/services/usage/codex.js 实现，前端 ProviderLimits 还提供了 Codex 专属的 "Reset Codex Limit" 按钮（调用
/api/usage/[connectionId]/codex-reset-credits）与重置积分（reset credits）查看功能（getCodexResetCreditCount、formatCreditDate），详见 index.js/dashboard/usage/components/ProviderLimits/index.js#L97-L125)。
低价型提供商
GLM-4.7
配额类型: 每日 Token 上限
上限: 10M Token/日（Coding Plan）
重置: 每日上午10点（北京时间 UTC+8）
仪表盘显示:
Used: 7M / 10M tokens (70%)
Remaining: 3M tokens
Resets in: 5h 35m
Cost today: $4.20
MiniMax M2.1
配额类型: 5小时滚动窗口
上限: 每5小时 5M Token
重置: 连续滚动窗口
仪表盘显示:
Used (5h): 4M / 5M tokens (80%)
Oldest usage expires in: 45m
Cost (5h): $0.80
Kimi K2
配额类型: 月度订阅
上限: 10M Token/月（固定 $9）
重置: 订阅日每月重置
仪表盘显示:
Used: 6M / 10M tokens (60%)
Resets: Feb 15, 2026 (in 11 days)
Cost: $9/month (prepaid)
免费型提供商
iFlow / Qwen / Kiro
配额类型: 无限制（限速）
上限: 无硬性限制
重置: 无
仪表盘显示:
Used today: 5M tokens
Cost: $0 (free forever)
Status: ✅ Available
源码佐证：配额上限数据来自各提供商 usage 服务（open-sse/services/usage 目录下的 claude.js、codex.js 等），通过 API 路由 route.js 暴露：OAuth 连接先经
refreshAndUpdateCredentials刷新令牌（必要时对鉴权过期消息强制刷新并重试一次），再调用getUsageForProvider拉取实时配额，并解析连接级代理配置（strictProxy: false，代理失败时回退直连）。
成本估算
实时成本跟踪
Dashboard → Costs → Today 将当日成本按订阅 / 按量 / 免费三类汇总：
Subscription providers: $0
Claude Code: 15M tokens ($0, included)
Gemini CLI: 3M tokens ($0, free tier)
Paid providers: $4.80
GLM-4.7: 8M tokens ($4.80)
Input: 6M × $0.60/1M = $3.60
Output: 2M × $2.20/1M = $4.40
Total: $4.80
Free providers: $0
iFlow: 3M tokens ($0)
Total today: $4.80
成本核算链路在源码中清晰可见：saveRequestUsage 在落库前调用 calculateCost(provider, model, tokens)，通过 pricingRepo.js 的 getPricingForModel 获取定价，最终委托给 open-sse/providers/pricing.js 的 calculateCostFromTokens 完成乘法计算——源码注释明确说明这是"单一事实来源"，避免多份实现漂移（见 usageRepo.js）。
月度支出报告
Dashboard → Costs → This Month 按周拆解并给出月度预测：
Week 1 (Feb 1-7):
Subscription: $0 (80M tokens)
Paid: $15.20 (25M tokens)
Free: $0 (10M tokens)
Total: $15.20
Week 2 (Feb 8-14):
Subscription: $0 (75M tokens)
Paid: $12.80 (20M tokens)
Free: $0 (8M tokens)
Total: $12.80
Month to date: $28.00
Projected (30 days): ~$120
Breakdown by provider:
GLM-4.7: $22.00 (78%)
MiniMax M2.1: $6.00 (22%)
Average cost per 1M tokens: $0.62
成本预测
Dashboard → Costs → Projections 基于最近 7 天用量外推月度成本，并与预算对比：
Based on last 7 days usage:
Daily average: 50M tokens
Daily cost: $4.50
Monthly projection:
Tokens: 1,500M (1.5B)
Cost: $135
Budget status:
Daily limit: $5 → 90% used today
Monthly limit: $150 → 90% projected
⚠️ Warning: May exceed monthly budget
提示：预测基于仓库实际统计的每日聚合数据（
usageDaily）计算，属于可复现的统计推演，而非固定经验值；实际数值以你自己的历史用量为准。
使用量仪表盘
概览统计
Dashboard → Analytics → Overview 提供日 / 周 / 月三级汇总：
Today (Feb 4, 2026):
Requests: 1,234
Tokens: 26M
Cost: $4.80
Avg response time: 2.1s
This week:
Requests: 8,456
Tokens: 180M
Cost: $28.00
Success rate: 99.2%
This month:
Requests: 15,234
Tokens: 320M
Cost: $52.00
Top model: cc/claude-opus-4-5 (45%)
按模型用量
Dashboard → Analytics → Models 展示模型排行与成本分解：
Top models (this month):
1. cc/claude-opus-4-5: 145M tokens (45%)
2. glm/glm-4.7: 95M tokens (30%)
3. if/kimi-k2-thinking: 50M tokens (16%)
4. minimax/MiniMax-M2.1: 20M tokens (6%)
5. gc/gemini-3-flash: 10M tokens (3%)
Cost breakdown:
cc/claude-opus: $0 (subscription)
glm/glm-4.7: $45.00
if/kimi-k2-thinking: $0 (free)
minimax/MiniMax-M2.1: $7.00
gc/gemini-3-flash: $0 (free)
按时段用量
Dashboard → Analytics → Timeline 按小时展示当日流量曲线，用于发现高峰时段：
Hourly usage (today):
00:00 - 01:00: 0.5M tokens
...
08:00 - 09:00: 3.2M tokens (peak)
...
23:00 - 00:00: 0.8M tokens
Peak hours: 08:00 - 12:00 (morning coding)
Low hours: 00:00 - 06:00 (night)
按组合（Combo）用量
Dashboard → Analytics → Combos 按 combos 组合维度拆解用量，直观看到每个组合中哪个模型消耗了多少成本：
premium-coding:
Requests: 456
Tokens: 12M
Cost: $2.40
Breakdown:
cc/claude-opus: 8M tokens (67%, $0)
glm/glm-4.7: 3M tokens (25%, $1.80)
minimax/MiniMax-M2.1: 1M tokens (8%, $0.20)
budget-combo:
Requests: 234
Tokens: 6M
Cost: $1.20
源码佐证：
usageDaily的byAccount/byApiKey/byEndpoint维度支持从账户、API Key、目标端点三个视角交叉分析（见 usageRepo.js 的aggregateEntryToDay），这正是 Combos 拆解与多账户用量对比的数据基础。
告警与通知
配额告警
Dashboard → Settings → Alerts 支持多级阈值：
Quota warnings:
✅ Alert at 80% quota used
✅ Alert at 90% quota used
✅ Alert when quota exhausted
✅ Notify when quota resets
Delivery:
✅ Dashboard notification
✅ Email (optional)
✅ Webhook (optional)
通知示例：
⚠️ Claude Code quota 80% used
2.5h remaining (resets in 1h 30m)
⚠️ GLM-4.7 quota 90% used
1M tokens remaining (resets in 5h)
✅ Gemini CLI quota reset
1,000 requests available (daily limit)
预算告警
Dashboard → Settings → Budget Alerts 支持日 / 月两级预算与自动降级：
Daily budget: $5
✅ Alert at 80% ($4)
✅ Alert at 100% ($5)
✅ Auto-switch to free tier when exceeded
Monthly budget: $150
✅ Alert at 50% ($75)
✅ Alert at 80% ($120)
✅ Alert at 100% ($150)
通知示例：
⚠️ Daily budget 80% used
$4.00 / $5.00 spent today
🚨 Daily budget exceeded
$5.20 / $5.00 spent today
Auto-switched to free tier
"超额自动切换到免费层"这一行为与 smart-routing 的配额感知路由紧密联动：当某提供商配额耗尽时，路由层会自动把流量转发到组合中的下一个可用提供商。
成本异常检测
Dashboard → Settings → Anomaly Detection 识别异常支出模式：
✅ Detect unusual spending patterns
✅ Alert on cost spikes (>2× daily average)
✅ Warn on quota exhaustion patterns
Example alert:
⚠️ Cost spike detected
Today: $12.50 (2.5× daily average)
Reason: High GLM-4.7 usage (20M tokens)
Suggestion: Check if primary models quota-exhausted
最佳实践
1. 每天监控配额
日课:
1. 查看仪表盘配额概要（30 秒）
2. 确认重置时间
3. 按配额可用性规划当日用量
例（早晨检查）:
✅ Claude Code: 5小时可用（刚重置）
✅ Gemini CLI: 1K 请求可用
⚠️ GLM-4.7: 剩余 2M Token（上午10点重置）
行动: 上午工作优先使用 Claude Code
2. 设置预算上限
Dashboard → Settings → Budget:
Daily: $5（防止过度花费）
Monthly: $150（与预算对齐）
效果：达到上限后自动切换到免费层，杜绝预算超支。
3. 优化组合使用
Dashboard → Analytics → Combos:
观察哪些模型使用最频繁
调整组合顺序以最小化成本
例:
当前: cc/claude-opus → glm/glm-4.7
80% 经 Claude（良好）
20% 经 GLM（$12/月）
优化后: gc/gemini-3-flash → cc/claude-opus → glm/glm-4.7
50% 经 Gemini（免费）
40% 经 Claude（订阅）
10% 经 GLM（$6/月）
节省: $6/月
4. 跟踪重置时间
Dashboard → Quota → Reset Schedule:
Claude Code: 5小时滚动 + 每周一
Gemini CLI: 每日 00:00 UTC + 每月 1 日
GLM-4.7: 每日上午10点（北京时间）
MiniMax: 5小时滚动窗口
策略：在配额刚重置时优先使用该提供商。
5. 定期查看月度报告
Dashboard → Analytics → Monthly Report:
Total tokens: 1.5B
Total cost: $120
洞察:
- 60% 经订阅（$0）
- 30% 经 GLM（$90）
- 10% 经免费层（$0）
优化:
- 增加 Gemini CLI 使用（免费）
- 减少 GLM 使用（较贵）
进阶技巧：9Router 还提供 Quota Auto-Ping（配额自动预热）功能（quotaAutoPing.js）。针对 Claude / Codex 这类"5 小时滚动窗口"配额，可开启
claudeAutoPing/codexAutoPing设置：调度器会在配额重置后的瞬间发送一个极小 Token 的探针请求（Claude 用max_tokens很小的 messages 请求，Codex 走 executor 流式请求并排空响应体），从而立即开启新的 5 小时窗口，让"重置即满血"。调度器内部维护resetCache/failureCache，带失败冷却（failureCooldownMs）与最小 ping 间隔（minPingIntervalMs）防抖，避免对上游造成压力。
API 访问
除仪表盘外，9Router 提供 HTTP API 供脚本与外部工具读取配额与用量。
获取配额状态
GET http://localhost:20128/api/quota
Authorization: Bearer your-api-key
Response:
{
"providers": [
{
"id": "cc",
"name": "Claude Code",
"quota": {
"used": 2.5,
"limit": 5,
"unit": "hours",
"percentage": 50
},
"reset": {
"type": "rolling",
"window": "5h",
"nextReset": "2026-02-04T06:45:00Z"
},
"cost": {
"today": 0,
"month": 0,
"currency": "USD"
}
},
{
"id": "glm",
"name": "GLM-4.7",
"quota": {
"used": 7000000,
"limit": 10000000,
"unit": "tokens",
"percentage": 70
},
"reset": {
"type": "daily",
"time": "10:00 AM UTC+8",
"nextReset": "2026-02-04T10:00:00+08:00"
},
"cost": {
"today": 4.20,
"month": 52.00,
"currency": "USD"
}
}
]
}
获取使用统计
GET http://localhost:20128/api/usage?period=today
Authorization: Bearer your-api-key
Response:
{
"period": "today",
"date": "2026-02-04",
"summary": {
"requests": 1234,
"tokens": 26000000,
"cost": 4.80
},
"byModel": [
{
"model": "cc/claude-opus-4-5",
"requests": 456,
"tokens": 15000000,
"cost": 0
},
{
"model": "glm/glm-4.7",
"requests": 234,
"tokens": 8000000,
"cost": 4.80
}
]
}
说明：以上 API 响应结构为文档约定格式。从当前仓库源码看，仪表盘实际使用的端点以
/api/usage/*为主，包括/api/usage/[connectionId]（单连接配额，见 route.js）、/api/usage/providers（route.js）、/api/usage/stats、/api/usage/chart、/api/usage/request-details、/api/usage/request-logs等（统一挂载在 dashboardGuard.js 的受保护路由列表下）。若你的版本端点有出入，请以当前运行版本Dashboard → Network面板中的实际请求路径为准。
故障排除
问题：配额显示 0% 但请求仍失败
解决：
- 检查提供商连接（Dashboard → Providers）；
- 确认 API Key 是否有效；
- 查看提供商状态页是否宕机；
- 尝试重新连接 OAuth 提供商。
补充：配额 API 在 OAuth 令牌过期时会尝试自动刷新并重试一次（见 route.js）；若返回 401，说明凭据已失效，需要重新授权。
问题：成本估算不正确
解决：
- 进入 Dashboard → Settings → Pricing；
- 确认各提供商单价与最新费率一致；
- 提供商调价后及时更新费率；
- 持续不一致请联系支持。
问题：重置时间不更新
解决：
- 刷新仪表盘（F5）；
- 确认系统时间准确；
- 检查时区设置；
- 重启 9Router。
问题：收不到告警
解决：
- 检查 Dashboard → Settings → Alerts 配置；
- 确认邮箱地址正确；
- 检查垃圾邮件文件夹；
- 点击 Send Test 按钮测试通知。
相关文档
- 智能路由（smart-routing） —— 基于配额状态的自动故障转移
- 组合（combos） —— 创建自定义故障转移链
延伸阅读（源码入口）：想深入了解配额跟踪实现，可依次阅读 usageRepo.js（统计核心）、pricingRepo.js 与 pricing.js（成本计算）、quotaAutoPing.js（配额预热）、ProviderLimits/index.js/dashboard/usage/components/ProviderLimits/index.js)（配额卡片 UI），以及 tests/unit/quota-auto-ping.test.js、tests/unit/provider-quota-visibility.test.js 等测试用例。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
