68 lines
4.9 KiB
Markdown
68 lines
4.9 KiB
Markdown
# MoShiro Probe
|
||
|
||
Probe 是网络测量的发起端，通常运行在家宽或其他需要观测的网络出口。它连接 Backend（身份、Agent 列表、状态）和 Agent（测量），执行线路任务，并把本端采集的原始数据交给 Agent 汇总上报。Probe 不提供远程命令或文件管理功能。
|
||
|
||
## 工作流程
|
||
|
||
```text
|
||
Backend ──任务──> Agent <──测量会话──> Probe
|
||
│ ▲ │ │
|
||
│ └──汇总并上报数据 <───┘ │
|
||
└─────Agent 列表、状态（Fleet 长连接）───────────┘
|
||
```
|
||
|
||
Probe 用 `probe.json` 读取面板地址（`fleet.server`）、身份目录（`fleet.identity_dir`，由 `fleet-enroll` 注册时生成）和本地测试限制。连上面板之后，面板下发要连接的 Agent 列表；Probe 将列表缓存到同目录的 `agents.json`，面板暂时连不上时靠它继续测量。身份目录里有私钥，请限制访问权限，不要提交到版本控制。
|
||
|
||
Agent 测量连接失败时，Probe 按 1、2、4、8、16 秒递增等待，再以 32 秒间隔重试 5 次，之后最多每 60 秒重试一次；连接恢复后退避重新从 1 秒开始。管理端把没有任何已启用 Agent 目标的 Probe 标为「暂停探测」，不会将链路断开误显示为已连接。
|
||
|
||
容器节点的运行方式（podman + systemd）和宿主机更新器见 [`../../docs/ops/deployment.md`](../../docs/ops/deployment.md)；Probe 也可以用 OCI 镜像 `registry.oeo.one/moshiro/moshiro-probe:<version>`，容器默认读取 `/etc/moshiro/probe.json`，命名 volume 保存身份配置和缓存，镜像以 UID/GID 1654 运行。
|
||
|
||
## 构建
|
||
|
||
需要 .NET SDK 10。为应用 根目录的 `global.json` 的 SDK 设置，请从 `backend/` 目录构建：
|
||
|
||
```sh
|
||
cd backend
|
||
dotnet build probe/src/MoShiro.Probe -c Release
|
||
```
|
||
|
||
发布 NativeAOT 程序需要对应平台的 C/C++ 工具链；`<RID>` 应与构建环境和目标平台匹配：
|
||
|
||
```sh
|
||
dotnet publish probe/src/MoShiro.Probe -c Release -r <RID> -p:PublishAot=true
|
||
```
|
||
|
||
也可在仓库根目录运行 `bash scripts/publish.sh probe <RID>`，再使用 `scripts/package.sh probe <RID>` 生成部署包。支持平台和安装流程见 [`../../docs/ops/deployment.md`](../../docs/ops/deployment.md)。
|
||
|
||
## 配置与运行
|
||
|
||
### OpenWrt 原生一键部署
|
||
|
||
管理端「添加 Probe」提供 **OpenWrt · 原生二进制** 命令，支持 ARM64/x86_64，以 root 执行即可注册并配置 procd。支持 dev/release 自动验签更新、失败回滚，不需要容器；详见 [部署文档](../../docs/ops/deployment.md#原生一键安装与自动更新)。
|
||
|
||
下面是手动注册方式；现代面板需同时传入面板提供的 `--genesis` 和 `--controllers`，否则默认属主检查会拒绝启动。
|
||
|
||
在管理端添加 Probe（生成 probe 角色的加入令牌），在目标机上注册（密钥由 Probe 自己生成）：
|
||
|
||
```sh
|
||
fleet-enroll --server https://panel.example.com --join <加入令牌> --name home --identity-dir /etc/moshiro --genesis <信任根指纹> --controllers <属主凭证ID>
|
||
```
|
||
|
||
写 `/etc/moshiro/probe.json`：`{"fleet":{"server":"https://panel.example.com","identity_dir":"/etc/moshiro"}}`（`install.sh probe --server … --join … --name …` 会一并完成）。随后运行：
|
||
|
||
```sh
|
||
moshiro-probe --config /etc/moshiro/probe.json
|
||
```
|
||
|
||
不传 `--config` 时默认读取 `/etc/moshiro/probe.json`。配置中的 `limits` 是本地硬上限，Backend 无法远程放宽；路由器等低性能设备可调低测试码率和包速率，避免 Probe 自身成为测量瓶颈。部署时可使用仓库的 `packaging/` 文件和安装脚本。
|
||
|
||
也可使用 OCI 镜像 `registry.oeo.one/moshiro/moshiro-probe:<version>`，自动选择 Linux amd64 或 arm64 镜像。容器默认读取 `/etc/moshiro/probe.json`，并在同一目录维护 `agents.json` 缓存，配置与缓存存放在命名 volume 中。建议使用宿主网络；当前独立 ICMP 目标任务由 Agent 执行。
|
||
|
||
## 设计说明
|
||
|
||
- Probe 只执行编译进程序的测量模块。它不落盘测量数据，也不能执行命令或自行更新（更新由宿主机上的更新器完成，Probe 只写清单和请求文件）。
|
||
- 测量模块由 `backend/shared/MoShiro.Measurement/` 与 Agent 共用；Probe 负责发起连接、调度任务和记录本端数据。
|
||
- 测量模型和协议细节见 [`../../docs/design/measurement.md`](../../docs/design/measurement.md) 与 [`../../docs/design/protocol.md`](../../docs/design/protocol.md)；整体架构见 [`../../docs/design/architecture.md`](../../docs/design/architecture.md)。
|
||
|
||
Podman 系用 Quadlet（`packaging/quadlet/moshiro-probe.container`，默认自动更新），Docker 用 `packaging/compose/probe/compose.yaml`（手动更新）；配置、身份和缓存放在命名 volume 中，无需宿主配置目录、keep-id 或手动 chown。首次导入和自动更新见部署文档。
|