# MoShiro Agent

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

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

## 工作流程

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

## 构建

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

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

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

```sh
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`](../../docs/ops/deployment.md)。

## 注册与运行

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

```sh
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：

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

容器节点的运行方式（podman + systemd）和宿主机更新器见 [`../../docs/ops/deployment.md`](../../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/architecture.md)，协议说明见 [`../../docs/design/protocol.md`](../../docs/design/protocol.md)，部署见 [`../../docs/ops/deployment.md`](../../docs/ops/deployment.md)。

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