# Monitor

Monitor 是一个自托管的网络线路质量观测工具。它在 Probe 与多个 Agent 之间执行主动网络测量，记录逐包和逐事件结果；Backend 保存原始数据并生成可查询的线路指标，Web 界面用于查看、比较和管理节点。

它面向需要比较不同网络出口、评估线路稳定性，或观察特定网络服务体验的场景。Agent 与 Probe 专注于测量和上报；它们不提供远程终端、命令执行或文件管理能力。

## 能力概览

- **主动测量**：组合 TCP、UDP 等测量模块，采集延迟、丢包、抖动、吞吐和连接事件。
- **线路分析**：从原始测量数据生成时间序列指标，并比较线路在不同服务模型下的体验。
- **节点管理**：通过 Fleet 节点框架处理身份、注册、连接、任务同步和数据上报。
- **实时面板**：展示端查看线路状态和历史趋势；管理端负责节点、任务和系统配置。
- **线路管理**：Backend 决定哪些 Probe 连哪些 Agent（自动连接开关加手动选择），在管理端的线路矩阵里一键开关。
- **节点信息与更新**：节点自报系统、架构和构建信息（版本、tag、提交、构建时间），国家和运营商由 Backend 查询；容器节点的更新由 CI 签名、Backend 转发、节点宿主机上的更新器验签并执行，失败自动回滚，管理端可以看状态和点「更新」。
- **自托管**：Backend 使用段文件和 SQLite 保存数据；提供 Linux、systemd 和 OpenWrt 相关部署文件。

## 架构

```text
                         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 保存索引、指标与配置。

## 快速开始

### 环境要求
- .NET SDK 10；项目使用 `global.json` 指定 SDK 版本和滚动策略。
- Node.js 与 npm，用于构建 Web 前端。

### 构建

从仓库根目录构建全部 .NET 项目（Backend、Agent、Probe、Fleet、测试和 CI 工具）：

```sh
dotnet build Monitor.slnx -c Release
```

NuGet 包版本统一在根目录 `Directory.Packages.props` 管理，项目中的 `PackageReference` 不写版本号。AotAnywhere 的 MSBuild SDK 版本在根目录 `global.json` 的 `msbuild-sdks` 中管理。`backend/Monitor.slnx` 保留用于只构建后端目录内的项目。

安装前端依赖并构建展示端和管理端（在仓库根目录运行）：

```sh
npm ci --prefix web
npm run build --prefix web
npm run gen:api --prefix web  # API schema changed after Backend edits
npm run lint:css --prefix web
```

前端产物位于 `web/display/dist/` 和 `web/admin/dist/`。NativeAOT 目标平台和 Windows 上使用 AotAnywhere 交叉构建的说明见 [`docs/deployment.md`](docs/deployment.md)。

Backend、Agent 和 Probe 均以 OCI 镜像发布，支持 Linux/amd64 与 Linux/arm64；Agent 和 Probe 另外提供 Linux glibc/musl、macOS 与 Windows 二进制包。容器部署配置见 [`compose.yaml`](compose.yaml)，发布说明见 [`docs/deployment.md`](docs/deployment.md)。

### 本地运行

1. **启动 Backend。** 在仓库根目录运行：

```sh
cd backend
dotnet run --project src/Monitor.Backend -- --urls http://localhost:5000
```

2. **启动前端。** 保持 Backend 运行，在另一个终端的仓库根目录运行：

```sh
npm ci --prefix web
npm run dev --prefix web
```

打开 <http://localhost:5173/> 使用展示端，或访问 <http://localhost:5173/admin/> 进入管理端。依赖安装和前端配置见 [`web/README.md`](web/README.md)；Backend 的首次启动与配置见 [`backend/README.md`](backend/README.md)。

### CI 构建规则

- Pull request 和 `dev` 分支 push：先跑 Backend tests，通过后再构建前端。
- 在需要跳过 Backend tests 的提交信息后加 `[SKIP TESTS]`；Gitea pull request 需要把标记写进 PR 标题。前端构建仍会运行。
- `main` 上的提交信息包含 `[CI]` 时，并行构建 Backend、Agent、Probe 的 Linux/amd64 镜像，推送到 Zot 的 `monitor-dev/` 仓库；普通 main push 不构建。
- 推送 `vMAJOR.MINOR.PATCH` tag 会触发全平台正式构建和 Release 发布。

完整触发条件、开发镜像标签和发布路径见 [`docs/deployment.md`](docs/deployment.md)。

## 项目布局

| 路径 | 说明 |
| --- | --- |
| [`backend/`](backend/README.md) | Backend 服务、Fleet 框架、共享测量代码与 .NET 测试 |
| [`backend/agent/`](backend/agent/README.md) | Agent 节点：注册到 Backend，接受 Probe 测量并上报数据 |
| [`backend/probe/`](backend/probe/README.md) | Probe 节点：发起线路测量并将采集数据交给 Agent |
| `backend/fleet/` | 可复用的节点身份、注册和连接框架 |
| `backend/shared/` | 测量引擎、协议和原始数据格式 |
| `web/display/`、`web/admin/` | 展示端和管理端 |
| `web/shared/` | 前端 API、图表、组件与主题 |
| `packaging/`、`scripts/` | 部署、构建与维护脚本 |
| `docs/` | [架构](docs/architecture.md)、[测量模型](docs/measurement.md)、[API](docs/api.md)、[部署](docs/deployment.md)等文档 |

## 待办

已实现的能力见上面的概览和 `docs/`；还没做的：

- **纯二进制节点的更新**：`fleet-updater`、`fleet-release`、Windows 服务和 OpenWrt（procd）适配器；设计见 [`docs/fleet/update.md`](docs/fleet/update.md)。容器节点（Agent、Probe）的签名发布和宿主机更新已经实现，见 [`docs/deployment.md`](docs/deployment.md)。
- **更新的灰度和自动策略**：按标签分批发布；`POLICY=auto` 的线上验证；后端自身的更新。
- **OpenWrt 打包**：procd 脚本、ipk/apk 包、sysupgrade 保留列表，在 aarch64 路由器上长时间运行验证。
- **安全加固**：对 UDP 包、控制帧、RawChunk、JSON-RPC 做模糊测试；伪造签名和重放的专项测试。
- **以后**：告警（Webhook）、真实 QUIC 握手积木、pcap/eBPF 采集。

## 测试

```sh
dotnet test --solution Monitor.slnx
```

```sh
# 前端样式检查（仓库根目录）
npm run lint:css --prefix web
```

## 许可证

本项目采用 [Apache License 2.0](LICENSE)。