MoShiro/backend/agent/README.md

Monitor Agent

Agent 是部署在 VPS 或其他可达网络节点上的采集进程。它向 Backend 注册并保持连接，接受 Probe 的测量会话，执行线路任务中的 Agent 侧工作，再将两端数据合并后上报。

Agent 仅开放配置的控制和数据端口。它不提供远程终端、命令执行或文件管理；本地配置中的网络范围、速率和并发限制由节点自行执行，Backend 下发的任务不能越过这些限制。

工作流程

Probe ──TLS 控制 / UDP、TCP 测量──> Agent ──长连接与数据上报──> Backend
                                      ▲
                                fleet-enroll 注册

构建

需要 .NET SDK 10。为应用 backend/global.json 的 SDK 设置，请从 backend/ 目录构建：

cd backend
dotnet build agent/src/Monitor.Agent -c Release
dotnet build fleet/tools/fleet-enroll -c Release

发布 NativeAOT 程序需要对应平台的 C/C++ 工具链；<RID> 应与构建环境和目标平台匹配：

dotnet publish agent/src/Monitor.Agent -c Release -r <RID> -p:PublishAot=true
dotnet publish fleet/tools/fleet-enroll -c Release -r <RID> -p:PublishAot=true

也可在仓库根目录运行 bash scripts/publish.sh agent <RID> 和 bash scripts/publish.sh fleet-enroll <RID>。部署包和平台说明见 ../../docs/deployment.md。

注册与运行

先在管理端创建加入令牌，然后在 Agent 主机上运行一次性注册工具：

fleet-enroll --server https://<backend> --join <token> --name <agent-name> --identity-dir /etc/monitor

注册工具会在身份目录写入节点身份和证书。准备本地 agent.json，其中 fleet.server 指向 Backend，fleet.identity_dir 指向上述目录；listen、limits 和 reporting 可按节点环境调整。配置文件不会由 Backend 修改。限制目标网段和测量预算时，应按实际网络与机器能力配置；allowed_target_cidrs 默认为空，不允许 Agent 执行目标探测任务。

启动 Agent：

monitor-agent --config /etc/monitor/agent.json

也可使用 OCI 镜像 registry.oeo.one/monitor/monitor-agent:<version>，自动选择 Linux amd64 或 arm64 镜像。镜像同时包含 fleet-enroll；可通过 --entrypoint /usr/local/bin/fleet-enroll 执行首次注册。容器默认读取 /etc/monitor/agent.json，需要挂载配置与身份目录；建议使用宿主网络，并按 ICMP 测量需求添加 NET_RAW 能力。镜像以 UID/GID 1654 运行，挂载目录必须允许该用户读取配置和身份文件。

不传 --config 时默认读取 /etc/monitor/agent.json。Agent 默认监听控制端口 7443/tcp，数据端口 7443/udp 和 7444/tcp；防火墙和面板中的节点端口配置需与本地配置一致。reporting.host_stats 可关闭主机状态上报；启用时只上报资源使用等汇总数据，不包含主机名、进程或 IP。

设计说明

• 每个 Probe 使用独立的 TLS 会话和数据密钥；Probe 断开时对应的会话资源会释放。
• 数据面会校验会话认证、重放窗口和速率限制；无效数据包会静默丢弃。
• 测量引擎和协议由 backend/shared/ 提供；节点身份、注册和连接由 backend/fleet/ 提供。
• 详细安全边界与拓扑见 ../../docs/architecture.md，协议说明见 ../../docs/protocol.md，部署见 ../../docs/deployment.md。