docs: redraw the architecture diagrams and update the README [SKIP TESTS]
This commit is contained in:
justme committed
1 parent
710aa9e99f
commit
ad17170664
2 files changed
+52
-16
No files matched your search
@@ -10,16 +10,33 @@ Monitor 是一个自托管的网络线路质量观测工具。它在 Probe 与
|
||||
- **线路分析**：从原始测量数据生成时间序列指标，并比较线路在不同服务模型下的体验。
|
||||
- **节点管理**：通过 Fleet 节点框架处理身份、注册、连接、任务同步和数据上报。
|
||||
- **实时面板**：展示端查看线路状态和历史趋势；管理端负责节点、任务和系统配置。
|
||||
- **线路管理**：Backend 决定哪些 Probe 连哪些 Agent（自动连接开关加手动选择），在管理端的线路矩阵里一键开关。
|
||||
- **节点信息与更新**：节点自报系统、架构和构建信息（版本、tag、提交、构建时间），国家和运营商由 Backend 查询；容器节点的更新由 CI 签名、Backend 转发、节点宿主机上的更新器验签并执行，失败自动回滚，管理端可以看状态和点「更新」。
|
||||
- **自托管**：Backend 使用段文件和 SQLite 保存数据；提供 Linux、systemd 和 OpenWrt 相关部署文件。
|
||||
|
||||
## 架构
|
||||
|
||||
```text
|
||||
Probe <──测量会话──> Agent ──长连接与数据上报──> Backend <──REST / SSE──> Web 展示端与管理端
|
||||
├── 段文件：原始数据
|
||||
└── SQLite：索引、指标与配置
|
||||
Web（展示端 · 管理端）
|
||||
▲ REST + SSE
|
||||
┌──────────────────────────────────────────────────────────┐
|
||||
│ Backend（面板） │
|
||||
│ Api · Registry · Planner · Links │
|
||||
│ Releases · Analysis · LiveHub │
|
||||
│ Store（段文件 + SQLite） │
|
||||
└──────────────────────────────────────────────────────────┘
|
||||
▲ ▲
|
||||
│ wss 长连接（节点发起） │ wss 长连接（节点发起）
|
||||
│ 任务、数据、状态、更新通知 │ 身份、Agent 列表、状态、更新通知
|
||||
┌────────────────────┐ ┌──────────────────────┐
|
||||
│ Agent × 10+ │ ◀── 测量会话 ── │ Probe × N │
|
||||
│ 有公网 IP，监听 │ │ 家宽等出口，NAT 后 │
|
||||
└────────────────────┘ └──────────────────────┘
|
||||
测量会话：TLS 控制通道 + UDP/TCP 数据通道，由 Probe 主动拨出
|
||||
```
|
||||
|
||||
两种连接：**Probe 和 Agent 都用长连接连 Backend**（身份、任务、状态、更新通知），**测量只走 Probe → Agent**（Probe 主动拨出，不需要入站端口）。哪些 Probe 连哪些 Agent 由 Backend 决定：默认自动全连，也可以在管理端手动选择。数据存储：段文件保存原始数据，SQLite 保存索引、指标与配置。
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 环境要求
|
||||
|
||||
+32
-13
@@ -11,19 +11,22 @@
|
||||
## 2. 拓扑
|
||||
|
||||
```text
|
||||
┌────────────────── Backend（面板）───────────────────┐
|
||||
前端（展示端+管理端）◀─────────┤ Api(public|admin) │ 注册中心 │ 任务编排 │ 结果管线 │
|
||||
REST + SSE 实时 │ Analysis(指标注册表) │ LiveHub │ 存储(段文件+SQLite) │
|
||||
└────▲──────▲──────▲───────────────▲─────────────────┘
|
||||
wss JSON-RPC │ │ │ │ 每个 Agent 一条长连接（由 Agent 发起）
|
||||
┌─────┴┐ ┌───┴──┐ ┌─┴────┐ ┌───┴──┐
|
||||
│ HK-1 │ │ JP-1 │ │ SG-1 │ ... │ US-3 │ 10+ 台 VPS Agent（有公网 IP）
|
||||
└──▲───┘ └──▲───┘ └──▲───┘ └──▲───┘
|
||||
│ │ │ │ 每个 Agent 一个会话：
|
||||
└────────┴───┬────┴─────────────┘ TLS 控制通道 + UDP/TCP 数据通道
|
||||
┌─────┴──────┐
|
||||
│ Probe │ 家宽，NAT/CGNAT 后，测量的起点
|
||||
└────────────┘ 直连 Backend（身份、列表），测量只连 Agent
|
||||
Web（展示端 · 管理端）
|
||||
▲ REST + SSE
|
||||
┌──────────────────────────────────────────────────────────┐
|
||||
│ Backend（面板） │
|
||||
│ Api · Registry · Planner · Links │
|
||||
│ Releases · Analysis · LiveHub │
|
||||
│ Store（段文件 + SQLite） │
|
||||
└──────────────────────────────────────────────────────────┘
|
||||
▲ ▲
|
||||
│ wss 长连接（节点发起） │ wss 长连接（节点发起）
|
||||
│ 任务、数据、状态、更新通知 │ 身份、Agent 列表、状态、更新通知
|
||||
┌────────────────────┐ ┌──────────────────────┐
|
||||
│ Agent × 10+ │ ◀── 测量会话 ── │ Probe × N │
|
||||
│ 有公网 IP，监听 │ │ 家宽等出口，NAT 后 │
|
||||
└────────────────────┘ └──────────────────────┘
|
||||
测量会话：TLS 控制通道 + UDP/TCP 数据通道，由 Probe 主动拨出
|
||||
```
|
||||
|
||||
- **线路（line）** = 一对（Probe，Agent）。可以有多个 Probe（身份由 Backend 生成，可以吊销、删除），每个 Probe 连接多个 Agent，每个 Agent 同时服务多个 Probe；一条线路的数据按 `line:<probe_id>` 单独存放，互不混合。对外的线路 id 是 `<agent_id>~<probe_id>`。
|
||||
@@ -61,6 +64,20 @@
|
||||
| 展示查询 | 任意时间段（相对或绝对）；自动步长（每条曲线最多约 720 个点）；1s 内存热层（1 小时）加上 10s/1m/5m/1h 各层；累加器现场合并，汇总精确；列式响应；SSE 实时跟随 | [query.md](query.md) |
|
||||
| API | `/api/public`（只读，可设为公开）、`/api/admin`（登录）、`/api/agent`（注册与 RPC）；实时数据用 SSE | [api.md](api.md) |
|
||||
|
||||
### 4.0 容器节点的更新
|
||||
|
||||
```text
|
||||
CI ──签名的发布清单（镜像 digest）──▶ Backend ──原样转发（offer）──▶ Agent / Probe 进程
|
||||
│ 只写进数据目录的 update/
|
||||
▼
|
||||
宿主机 monitor-update（root）：用本机公钥验签 → 核对组件、仓库和 seq → podman pull 仓库@digest → 重启 → 不健康就回滚
|
||||
│ 状态写进只读的 update-status/
|
||||
▼
|
||||
节点随心跳上报更新状态 ──▶ Backend ──▶ 管理端（有新版本时点「更新」）
|
||||
```
|
||||
|
||||
细节见 [deployment.md](deployment.md)「容器节点的更新」。
|
||||
|
||||
### 4.1 回显的四个时间戳
|
||||
|
||||
回显类 Kind 记录 `t1..t4`（Probe 发出、Agent 收到、Agent 回复、Probe 收到）。借此可以扣除 Agent 的处理耗时得到 RTT，可以分别判断上行和下行的丢包，并在去除时钟偏移和漂移后，得到**每个方向各自的抖动**，不需要两端时钟同步。
|
||||
@@ -81,9 +98,11 @@ Agent / Probe 能做的 执行编译在二进制中的 Kind；监听和访问
|
||||
- **本地硬上限**写在节点本机的配置文件中，Backend 下发的任务如果超出，节点直接拒绝：允许访问的目标网段（默认为空，即不开放目标任务）、总码率和包速率上限、允许监听的端口。
|
||||
- **构建期强制**：常驻节点进程使用 `BannedSymbols.Node.txt`，禁用 `System.Diagnostics.Process`、`Assembly.Load*`、`NativeLibrary.Load`、`HttpClient`，以及 `ConfigStore` 以外的文件写入 API，详见 [project-layout.md](project-layout.md) 第 7 节。
|
||||
- **权限分离**：注册（`fleet-enroll`，一次性运行）、采集（`monitor-agent` / `monitor-probe`）、更新是不同的进程。容器节点里，采集进程在容器内以 UID 1654 运行（只读文件系统、不带额外能力），更新由宿主机上 root 运行的 `monitor-update` 完成：它只读取节点放进 `update/` 的普通文件、复制到自己的临时目录后验签，状态写在节点只读的 `update-status/`；采集进程改写不了自己的二进制，更新器也读不到节点身份私钥。纯二进制安装的 `fleet-updater` 还只是设计。
|
||||
- **容器运行**：Agent、Probe 的镜像基于 Alpine（musl，NativeAOT），宿主机用 rootful podman 加 systemd 运行：UID/GID 1654、只读文件系统、`--cap-drop all`、`no-new-privileges`、`/tmp` 用 tmpfs；配置和身份放在挂载的数据目录里。
|
||||
- **最小权限运行**：非 root 用户；只在需要时授予 `CAP_NET_RAW`（ICMP）；默认端口都高于 1024，不需要 `CAP_NET_BIND_SERVICE`，只有在 Agent 本地显式开启 443 时才授予。
|
||||
- **身份**：节点使用本地生成的 ECDSA P-256 密钥对签名认证（Probe 的密钥由面板生成、只返回一次，同一把用来连面板和连 Agent），Backend 只存公钥，数据库泄露也无法冒充节点。
|
||||
- **防放大**：未认证的包静默丢弃；回复长度与请求相等；每个流按声明速率限速；使用重放窗口。
|
||||
- **容器里的主机指标**：容器里的 Agent 通过只读挂载宿主机的 `/proc`、`/sys`、根目录和 `/etc/os-release`（环境变量 `HOST_PROC`、`HOST_SYS`、`HOST_ROOT`）读取宿主机的资源占用和系统名；读不到的项返回空值，不会退回去读容器自己的数据。Probe 只需要挂载 `/etc/os-release`。
|
||||
- **自身状态**：节点上报进程内的计数（会话数、包速率、队列、丢弃数）；Agent 另外每隔几秒用 `monitor.host` 上报一份主机资源占用的汇总数字（可以在 `agent.json` 里用 `reporting.host_stats = false` 整个关掉），最新值实时推给展示页，Backend 每分钟存一个样本（默认保留 7 天，`retention.host_days`）。
|
||||
|
||||
## 6. 可扩展性目标
|
||||
|
||||
Reference in new issue
Block a user