限额与流量计量¶

入口计量¶

上传和下载字节都在入口节点计量一次。直连规则按入口转发写入量计数；经出口组转发时，计数点是入口成功写入内部 QUIC 转发流。QUIC 写入成功表示本机传输层接受了这些字节，不代表出口目标 socket 已确认写入。管理页面将其标为“入口计量流量”。

用户组流量上限是所有当前有效成员共享的累计池；多个有效组均设置非零上限时，租约受每个组剩余额度中最小值约束。规则流量上限单独约束该规则。计量包括入口上传与下载方向之和。

控制面会为入口节点分配有限字节租约。入口只允许使用本机持久化租约内的字节额度，额度耗尽后拒绝该规则的新连接。控制面在所有入口节点之间原子预留共享组额度，避免多台离线入口重复领取同一额度。

相同规则配置下，过期租约会续用原租约 ID 和剩余额度，不会重复预留。规则或组配置版本变化后，旧租约在节点侧失效；旧租约尚未报告的额度按已用处理，不会自动释放到共享池。此行为优先防止离线节点额度被重复分配，配置修改可能永久减少可用额度。后续可通过专门的租约释放确认协议改进回收。

本地租约簿和待上报队列都绑定节点 ID；租约还绑定节点证书序列号。节点证书轮换后，旧序列号的本地租约不能继续使用；服务端保留旧租约剩余预留，不会发给新证书。若租约簿或队列缺失、损坏或属于另一个节点，agent 会拒绝启动/上报，避免把额度或旧计量数据迁移到其他节点。

流量上限按累计入口计量使用，不自动按月清零。零表示不限。

速率使用入口节点本地令牌桶实现，每条规则在每个入口节点共享一个桶。用户组速率作为规则上限的收紧值。多个规则或入口节点会各自限速，整体带宽可能叠加；此设置不是跨节点的全局用户总速率。零表示不限。

GET /api/v1/admin/usage?from=<RFC3339>&to=<RFC3339>：按规则、节点、节点组、方向汇总，可筛选日期范围。普通用户只能查询自己的数据；管理员省略 owner_user_id 时查看全站，传入后按指定用户过滤。
GET /api/v1/admin/usage/trend?range=24h|7d|30d：按小时或日期返回入口计量趋势。普通用户只看自己的数据；管理员默认查看全站数据。
GET /api/v1/admin/usage/breakdown?dimension=user|rule|node|group|day|month：按用户、规则、节点、节点组或 UTC 日期汇总。管理员省略 owner_user_id 时查看全站，传入后按指定用户过滤；普通用户固定为本人。日期范围使用 RFC3339。
GET /api/v1/admin/node-errors：管理员查看最近 24 小时按节点、规则和固定错误类别汇总的数量；不返回目标地址或原始错误文本。

聚合值以 JSON int64 返回；如果跨记录求和超过 int64 上限，接口将该聚合值封顶为 9223372036854775807。

新格式用量按规则 config_version 匹配历史所有者与节点组；运行时会按规则版本分桶，因此同一批次可分别包含修改前后的版本。旧持久队列中缺少版本字段的批次仍按结束时间 ended_at 归属整批；节点时钟偏差也可能影响这类旧批次的归属精度。