项目架构
NIE-SLA 将采集、探测、存储、展示与第三方扩展划分为不同信任区域。理解这些边界，可以避免把“VPS 在线”“Cloudflare 可达”和“外部节点延迟”误认为同一种数据。
核心组件
| 组件 | 运行位置 | 主要职责 |
|---|---|---|
| Rust Agent | 被监控 VPS | 秒级采样系统指标、执行 TCP Ping、按批次上传 |
| Latency Agent | 独立 Linux 节点 | 从不同网络位置探测公开 TCP 目标 |
| Worker | Cloudflare 边缘 | 路由、认证、调度、聚合、告警与公开 API |
| Durable Objects | Cloudflare | 协调主动探测和区域执行 |
| D1 | Cloudflare | 配置、状态、聚合、事件与索引 |
| R2 | Cloudflare | 高频历史、状态快照、归档与扩展包文件 |
| Pages | Cloudflare | 公开状态页、管理后台与同源 API 代理 |
数据链路
text
Rust Agent ──scoped token──> Worker ──> D1 / R2 ──> Public status
│
Cloudflare probe ─────────────────┤
│
Latency Agent ─scoped token───────┘Agent 采样、上传、Ping 和更新检查由不同调度器负责。VPS 上可以每秒采样，但 Worker 只会按批次收到上传；网络短暂变慢不会阻塞下一次本地采样。
四类延迟与在线状态
| 数据源 | 发起位置 | 回答的问题 |
|---|---|---|
| Cloudflare 探测 | Worker / Durable Object | Cloudflare 边缘能否连接目标，延迟多少 |
| Agent 在线状态 | 被监控 VPS | 指标 Agent 最近是否持续上报 |
| Agent TCP Ping | 被监控 VPS | 该 VPS 到指定 Ping 目标的网络质量 |
| 外部 Latency | 独立网络节点 | 额外地区或运营商到公开 TCP 目标的延迟 |
客户端必须保留来源标签。一个 VPS 的 Agent 在线，不代表 Cloudflare 探测一定成功；反过来，端口可达也不代表指标 Agent 正在运行。
存储策略
NIE-SLA 不会把每秒原始指标全部写入 D1：
- 当前状态和索引保存在 D1；
- 高频指标历史优先写入 R2；
- SLA 历史按固定桶聚合后写入 D1；
- 状态接口使用短缓存降低重复读取；
- 清理任务按周期运行，而非在每次请求中扫描历史。
这套设计让公开状态保持较快更新，同时控制 Worker 请求、D1 写入和 R2 操作量。
接口与信任边界
| 接口 | 认证 | 可执行操作 |
|---|---|---|
/api/v1/* | 无 | 读取脱敏后的公开状态与历史 |
/api/agent/* | 节点 scoped Token | 对应 Rust Agent 上报与读取策略 |
/api/latency-agent/* | 节点 scoped Token | 对应 Latency 节点取目标、上报与更新 |
| Admin API | 短期 Session，可叠加 TOTP | 修改配置、上传扩展、查看管理数据 |
凭据边界
主题、插件和替代前端只能使用公开 v1 API。不得向扩展传递管理员 Session、密码、TOTP、Agent 主 Token或节点 scoped Token。
当前状态与长期 SLA
Worker Cron 可以每分钟刷新当前探测和报警状态；长期 SLA 与日格仍使用 5 分钟桶。FAST_STATUS_ENABLED 关闭时，主动探测的当前状态也会退回持久化桶的粒度。
因此“公开页面最新状态”和“日格新增一格”并不要求同一频率。集成端应读取 checked_at、updated_at 和来源字段，而不是用数组长度推断 Agent 是否仍在线。
扩展运行时
CSS 主题只加载经过校验的样式文件。Canvas 主题和插件运行在 sandbox="allow-scripts" iframe 中，没有同源权限，CSP 禁止直接联网、表单和顶层导航；需要的数据由宿主通过受限消息协议提供。