MoShiro/backend/agent/README.md

MoShiro Agent

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

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

工作流程

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

构建

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

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

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

dotnet publish agent/src/MoShiro.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/ops/deployment.md。

注册与运行

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

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

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

启动 Agent：

moshiro-agent --config /etc/moshiro/agent.json

容器节点的运行方式（podman + systemd）和宿主机更新器见 ../../docs/ops/deployment.md。也可使用 OCI 镜像 registry.oeo.one/moshiro/moshiro-agent:<version>，自动选择 Linux amd64 或 arm64 镜像。镜像同时包含 fleet-enroll；可通过 --entrypoint /usr/local/bin/fleet-enroll 执行首次注册。容器默认读取命名 volume 中的 /etc/moshiro/agent.json 与身份文件；建议使用宿主网络，Linux ICMP 优先使用普通用户 ping socket，内核 ping_group_range 需允许映射后的 GID。镜像以 UID/GID 1654 运行，新命名 volume 由引擎按镜像目录初始化权限。

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

IPv6 线路需要 Agent 实际绑定 IPv6。新配置的默认 listen.bind 为 ::，覆盖整个双栈接口；已有配置如果仍写 0.0.0.0，可改为 :: 后重启。Compose 与 systemd 容器部署使用宿主网络，诊断反映宿主 IPv6；自定义容器网络时，Agent 同时报告容器网络以及可读取到的宿主 /proc IPv6 状态。诊断不上传 IP 或接口名称。

设计说明

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

Podman 系用 Quadlet（packaging/quadlet/moshiro-agent.container，默认自动更新），Docker 用 packaging/compose/agent/compose.yaml（手动更新）；配置、身份和缓存放在命名 volume 中，无需宿主配置目录、keep-id 或手动 chown。首次导入和自动更新见部署文档。