订阅交付与流量展示

Zboard 从协议服务、节点组、订阅模板和用户订阅生成客户端配置。公开订阅链接的授权边界始终是单个订阅，筛选参数和输出模板只能缩小该订阅已经授权的内容，不能聚合或扩展到同一账号下的其他订阅。

订阅生成链路

协议服务 → 节点组 → 订阅模板 → 用户订阅 → 单订阅访问令牌 → 客户端输出

协议服务决定节点、凭据、启用状态和交付顺序，节点组决定可选范围，订阅模板决定策略组、规则集、本地入口和客户端格式。修改任一层后，应通过管理端预览确认最终输出。

禁用协议服务后，该服务会同时从公开订阅输出和节点运行时发布中移除；重新启用后通过现有发布流程恢复。

单订阅访问边界

每个公开订阅 URL 只绑定一个 subscription_id。Zboard 会依次验证令牌、用户归属、订阅状态、有效期和剩余流量，然后只从该订阅解析节点、协议端点和凭据。

筛选是只读投影，不是授权机制：

• plan、sku、node_group、protocol、region、tag、exclude_tag 和 q 只能继续减少结果；
• 筛选不能选择同一账号下的另一份订阅，也不能增加未授权节点或凭据；
• 合法筛选没有匹配项时返回有效的空订阅，而不是越过边界回退到其他订阅；
• Subscription-Userinfo 和配额元数据只描述令牌绑定的订阅，不跨订阅累计。

登录用户按目标订阅管理访问凭据：

方法	路径	作用
GET	/api/v1/account/subscriptions/{id}/access	读取或按需创建该订阅的访问链接
POST	/api/v1/account/subscriptions/{id}/access/rotate	只轮换该订阅的令牌
DELETE	/api/v1/account/subscriptions/{id}/access	只撤销该订阅的令牌

旧的账号级聚合访问接口已经移除。没有 subscription_id 的历史聚合令牌会在数据协调时失效，并为每份可用订阅分别创建访问令牌。

客户端识别与输出格式

公开交付只接受明确的订阅客户端 User-Agent。当前内置识别包括：

• 严格的 ZNet-Sink/<版本>，例如 ZNet-Sink/0.0.1；
• Clash / Mihomo；
• sing-box；
• Shadowrocket；
• Quantumult X；
• v2rayN。

浏览器、curl、空 User-Agent 或仅包含 ZNet-Sink 子串的伪造值会在令牌解析前进入订阅伪装跳转，避免公开接口泄露令牌是否存在。

当前支持两类输出：

模板 / Renderer	类型	输出
zero	完整配置	Base64 编码的 Zero JSON
clash	完整配置	Clash / Mihomo 原生配置
sing-box	完整配置	sing-box 原生配置
shadowrocket	节点订阅	Base64 编码的标准协议分享链接
quantumult-x	节点订阅	Quantumult X server_remote 兼容节点资源
v2rayn	节点订阅	Base64 编码的标准协议分享链接

Shadowrocket 和 v2rayN 的节点订阅可导出当前支持的 VMess、VLESS、Trojan、Shadowsocks、Hysteria2 等标准分享链接；Quantumult X 只生成当前 renderer 明确支持的节点类型。节点订阅 renderer 不会伪装成完整配置，因此不导出 Zboard 的策略组或规则集。

zero-json、zero-base64-json、znet-sink 等历史别名会归一化到 zero，不能借助旧名称请求明文 Zero JSON。管理端预览可以保持可读，但公开 Zero 交付只输出编码文本。

内置模板只在缺失时进行一次 seed。管理员之后对模板的编辑或删除是权威状态，升级不会反复覆盖运营侧定制。

Base64 不是加密。真正的安全边界仍然是随机令牌、HTTPS、令牌轮换与撤销，以及避免在日志、截图和工单中公开完整 URL。

无效订阅链接

无效、已撤销或非客户端请求会返回不可缓存的 HTTP 302，并跳转到系统配置中的“订阅伪装跳转地址”。该值留空时使用站点公开访问地址。

伪装跳转不能替代令牌安全，也不应被客户端当作有效订阅响应。排查同步失败时应同时检查响应状态、最终 URL、User-Agent 和订阅令牌状态。

本地 Mixed 端口

版本 2 订阅模板包含 mixed_port，默认值为 7890，允许范围为 1–65535。

启用本地 Mixed 时，Zboard 会为不同完整配置客户端生成以下入口；模板也可只启用 TUN，但 Mixed 与 TUN 不能同时关闭：

输出格式	本地入口
ZNet Sink / Zero	loopback mixed 入站
Clash / Mihomo	mixed-port 和 loopback 绑定
sing-box	loopback mixed 入站

因此完整配置订阅不依赖客户端在导入后临时补建入口。Shadowrocket、Quantumult X 和 v2rayN 属于节点订阅输出，不由 Zboard 给它们生成完整本地入站配置。

端口已被占用时，应在订阅模板中修改 mixed_port，而不是手工编辑每个用户的生成结果。

托管规则与 ZRS

可交付给 Zero 的网络匹配规则集由平台维护，而不是由节点内核临时生成；含客户端进程条件时适用下方客户端兼容性限制：

1. 管理端写入或导入规则源；
2. Zboard 归一化并校验为 canonical Zero Rule IR；
3. 内置的固定版本 zero-rule 编译器生成 ZRS；
4. 只有验证通过的 ZRS 才会成为 Zero 客户端可引用的发布产物；
5. Clash 和 sing-box 输出继续使用各自的规则表示。

Zero 客户端拿到的是 ZRS 产物，不是公开的 IR 文本。规则元数据保存在数据库，源文件和编译产物保存在 ZBOARD_MANAGED_RULE_HOST_DIR，容器内挂载到 /var/lib/zboard/artifacts/rules。

数据库与托管规则目录必须作为一个备份、恢复和回滚单元；蓝绿实例也必须共享同一可写规则目录。只恢复数据库而不恢复匹配的规则快照，会造成元数据与发布产物不一致。

策略组输出

完整配置模板中的 selector 可以显式控制是否提供 DIRECT 和 REJECT。新建或从旧版 v2 customization 迁移的 selector 默认同时启用两项，以保持历史行为；管理员可以分别关闭任意一项。

因此 DIRECT / REJECT 不再是无法配置的隐式固定插入项：

• selector 只生成模板明确允许的 special targets；
• URLTest 和 fallback 不包含 DIRECT / REJECT，因为它们不是可探测节点；
• Shadowrocket、Quantumult X、v2rayN 等节点订阅 renderer 不输出策略组，因此也不存在 special-target 配置。

订阅中的节点名称默认沿用协议服务名称，不再附加内部端点或订阅 ID。名称为空时才使用协议名作为回退。协议服务的交付顺序是所有渲染器共享的权威顺序，端点 ID 只作为稳定的最终排序条件。

默认延迟测试地址为：

http://www.gstatic.com/generate_204

系统只会迁移旧的内置默认值，不会覆盖运营人员自定义的测速 URL。

规则集与客户端兼容性

托管规则导入接受独立 Provider 规则集，例如 Clash Classical 的域名、IP/CIDR、PROCESS-NAME 与 PROCESS-PATH。配置片段不能当成独立规则集导入；未知匹配项或空内容会报错，同步失败保留上一份有效内容。

进程条件可以导出给 Clash/sing-box，仍取决于实际客户端和平台能否识别进程。Zero 当前不能执行进程规则：含这类条件的来源不生成 ZRS、不出现在 Zero 模板选择器中，显式绑定会拒绝；已被 Zero 模板引用的来源也不能直接更新成含进程规则的内容。不会通过静默删除条件来生成“部分可用”配置。

完整配置模板还提供 DNS、TUN、本地入口、控制接口和路由偏好。按目标 renderer 填写，不能把客户端专属字段当成跨客户端合同。sing-box 的非 TUN 配置可选择自动设置系统代理；启用 TUN 时由客户端通过平台 HTTP 代理配置管理开关，不再生成会调用桌面命令的 set_system_proxy。

流量计费与分钟级使用明细

Zboard 以 Zero 上报并成功归属到订阅用户的完成流量事实为来源：

1. Zero 建立并记录真实连接；
2. 完成事实包含连接的上下行字节和用户归属；
3. Zboard 幂等写入原始流量记录；
4. 应用协议服务或套餐配置的计费倍率；
5. 累加该订阅的已用流量；
6. 剩余流量由套餐额度减去已用流量得到。

客户端本地显示一次测速成功，不代表服务端一定建立了可归属连接。Zboard 不会根据客户端报告凭空生成流量费用。

系统将计费事实和人类阅读的历史列表分开：原始 TrafficRecord 继续作为计费、审计和对账事实；管理端和账户端的分页使用明细默认由后端聚合为分钟 bucket。

聚合维度保留会影响计费解释的语义：分钟、用户、订阅、节点、协议端点和倍率。同一分钟里只有这些维度都一致的记录才会合并，并返回 record_count 表示底层原始记录数量。

需要排障或审计原始分页记录时可以显式请求：

?view=raw&paged=true

非分页历史调用保持既有原始记录语义。前端不需要下载全量明细再自行聚合。

趋势与活跃连接

管理端和个人中心的趋势图从后端按时间范围聚合的结果读取，并使用订阅、用户、节点等业务标签展示关联实体。趋势图支持悬浮 crosshair/tooltip、序列开关和键盘浏览；流量 tooltip 可以同时展示计费量、上行、下行与原始记录数量。

连接数使用 Principal flow 的服务观测事实。未采集到 Principal flow 观测时应显示为“未采集”/空值，不应伪造为 0；active_flows = 0 只表示当前没有活跃连接，不代表节点或 Connector 离线。

系统时区会参与日期型趋势读取：日期 from / to、每日 bucket 以及 Dashboard 的 today/7d/30d 都按配置的 IANA system_timezone 计算本地日历边界，再转换为 UTC 查询。数据库和绝对 API 时间继续使用 UTC；夏令时地区的 23/25 小时日按真实日历处理。

后台存储和计费使用精确字节。界面根据数值自动显示 B、KB、MB 或 GB；单位变化只影响显示，不改变数据库、API 或计费结果。

排查订阅与流量

订阅无法导入时，依次确认：

1. 请求使用受支持的订阅客户端 User-Agent；
2. 令牌未撤销且令牌绑定的用户、订阅处于有效状态；
3. HTTP 响应不是伪装跳转；
4. 客户端选择了正确模板或自动检测；
5. zero 响应能够完整 Base64 解码，且不是明文 JSON；
6. 完整配置模板包含预期本地入口；节点订阅模板不要按完整配置解析；
7. 节点组至少包含已启用、可发布的协议服务；
8. 引用的托管规则 ZRS URL 可读取且与当前数据库快照匹配。

流量未增加时，确认节点侧是否存在归属到该订阅用户的完成事件。只有客户端本地探测记录、但节点没有会话和字节事实时，应排查客户端到节点的实际连接路径，而不是修改计费逻辑。

分页使用明细和原始账务事实不一致时，先用 view=raw 检查底层记录，再确认分钟聚合维度和倍率是否一致；不要把聚合行数量误当成实际连接/计费记录数量。

在页面中查用量与对账

1. 管理员进入“节点与协议 → 流量与对账”；用户进入“流量明细”。
2. 先选择时间范围，再按用户、具体订阅或节点缩小范围。用户端订阅选择器可搜索历史订阅，不应根据概览中的几条预览判断全部订阅已加载。
3. 区分统计摘要、趋势图和分页明细：翻页只改变明细页，不能把当前页合计当作整个区间用量。
4. 管理员核对原始记录与订阅累计值时使用对账结果；存在错误归属、倍率或缺失事实时保留原记录调查，不靠修改页面统计掩盖差异。

当前明细支持实时页和游标前后翻页；总条数未提供时不会把未知总数当作零。非法用户或订阅筛选应报错，不会自动退回全站查询。加载失败时先处理错误，不能据此判断“没有流量”。

套餐购买及续费操作见套餐、订单与用户交付。