MoShiro Agent

Agent 是统一的采集节点，默认同时监听和拨号。每个 Agent 独立连接 Backend，接收任务集和拨号目标；节点之间通过 TLS 控制会话、QUIC Datagram 和 TCP 数据连接完成测量。

Agent A <==== 直接测量 ====> Agent B
   |                           |
   +--------- wss -------------+
                |
             Backend

Backend 默认安排 Agent 之间的双向有向线路，自连接被排除。拨号方通过心跳上报控制层、TCP 和 QUIC 状态、失败原因及重试时间；监听方上报接入会话。Backend 汇总这些报告，供 Agent 详情和线路矩阵使用。测量数据由监听方合并后上传。

本地 listen.enabled 默认 true。可显式关闭监听，适用于无需入站测量的节点；这仍是同一种 Agent。NAT 后的节点可主动拨出，入站可达性取决于地址和端口映射。

构建

需要 .NET SDK 10（版本见根目录 global.json）。从 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 或接口名称。

设计说明

每个拨号方使用独立的 TLS 会话和数据密钥；拨号方断开时对应的会话资源会释放。
数据面会校验会话认证、重放窗口和速率限制；无效数据包会静默丢弃。
测量引擎和协议由 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。首次导入和自动更新见部署文档。

README.md Unescape Escape

MoShiro Agent

构建

注册与运行

设计说明

README.md