# MoShiro 的注册与身份

通用注册、认证和信任链由 [Fleet](../../backend/fleet/README.md) 提供。MoShiro 统一使用 Agent 节点；监听方、拨号方描述一次测量会话中的方向，同一 Agent 可以同时承担两侧工作。

## 1. 身份

`fleet-enroll` 在节点本地生成连接 Backend 的 ECDSA P-256 身份密钥，以及 TLS 证书中的独立对等身份密钥。拨号和监听共用该节点的对等身份。Backend 保存公钥与 SPKI 指纹，不接收私钥。节点固定操作员集合的创世指纹和属主，并在注册、连接及状态同步时验证信任链。

面板用户通过密码或 Passkey 登录；API 令牌带有明确的能力集合，服务端保存令牌哈希。发布清单使用独立发布密钥签名，该私钥不进入面板或仓库。更新器在节点进程之外执行，具体边界见 [deployment.md](../ops/deployment.md) 和 [access.md](access.md)。

## 2. 接入

```text
管理端创建加入令牌（统一 agent）
  -> 安装命令携带面板地址、一次性码、创世指纹、属主和脚本哈希
  -> fleet-enroll 验证信任链并在本机生成身份
  -> Agent 连接 Backend，上报监听信息与本地能力
  -> Backend 推送 task_set 和 dial_targets
  -> Agent 调和拨出连接，同时接受名册内其他 Agent 的接入
```

同名节点进入待审批状态，由管理员决定是否接管。激活、停用、接管和删除通过统一的 Agent API 完成。

Backend 默认启用 `fleet.auto_link`，所有 Agent 向其他可拨号 Agent 建立线路，自连接被排除。A→B、B→A 是两个独立方向；手动线路开关优先于自动连接。节点本地 `listen.enabled` 默认 true，可显式关闭，不产生另一种节点角色。

## 3. 任务、拨号目标与状态

- `TaskSet.peers` 下发允许接入的节点公钥。
- `DialTargets` 下发目标节点的地址、端口、证书公钥和 IP 路径。节点在 `dial_targets.json` 中缓存已验证的目标文档。
- 节点集合、地址、证书或线路策略变化后，Backend 重算并推送期望状态。节点断开已移除的目标，并连接新增目标。
- 每个 Agent 通过自身的 Backend 心跳上报运行状态、拨出线路的控制层和任务层健康、错误与重试，以及接入会话快照。测量流量走节点直连，监听方合并列块后上传原始数据。

## 4. Agent 本地配置（`/etc/moshiro/agent.json`，面板无法修改）

```json
{
  "fleet": { "server": "https://panel.example.com", "identity_dir": "/etc/moshiro" },
  "listen": { "control_port": 7443, "quic_ports": [7443], "tcp_ports": [7444] },
  "limits": {
    "max_total_mbps": 200,
    "max_total_pps": 20000,
    "allowed_target_cidrs": [],
    "max_concurrent_tests": 1
  },
  "fleet_policy": { "allow_methods": ["moshiro.test.run", "moshiro.test.cancel"] }
}
```

- `limits` 是本地硬上限：期望任务集超出这些范围时，调和器拒绝执行，并在 `rejected[]` 中给出原因。
- `allowed_target_cidrs` 默认为空，即不允许执行任何目标任务；需要时由节点所有者在本机显式开启。
- `listen` 默认不包含 443。要用 443 测量，需要在本机把它加入 `quic_ports` 或 `tcp_ports`（端口不能被真实服务占用），见 [measurement.md](../design/measurement.md) 第 8 节。
- `fleet_policy.allow_methods` 在 Fleet 默认值的基础上进一步收窄。

## 5. 相关 API

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| POST | `/api/agent/v1/enroll` | 注册节点 |
| GET | `/api/agent/v1/rpc` | WebSocket 节点链路 |
| GET/POST/DELETE | `/api/admin/join-tokens` | 加入令牌 |
| GET | `/api/admin/agents` | 统一节点列表 |
| GET/PATCH/DELETE | `/api/admin/agents/{id}` | 节点详情、修改、删除 |
| POST | `/api/admin/agents/{id}/approve`、`/disable`、`/enable`、`/takeover` | 审批、启停与接管 |
| POST | `/api/admin/agents/{id}/dialers/{dialer_id}/disconnect` | 关闭指定接入会话 |
| GET | `/api/admin/links` | 有向线路矩阵与连接状态 |
| PUT | `/api/admin/links/{dialer_id}/{listener_id}` | 设置单方向线路策略 |
| POST | `/api/admin/links/{dialer_id}/{listener_id}/retry` | 开启并立即重试 |
| GET | `/install`、`/install.ps1` | 静态安装脚本 |
| GET | `/install/manifest?code=…`、`/install/manifest.sig?code=…` | 原样的签名发布清单及签名 |

## Agent 的本地配置：主机状态上报

`agent.json` 的 `reporting` 段（面板无法修改）：

```json
{ "reporting": { "host_stats": true, "host_interval_s": 2 } }
```

`host_stats` 为 true（默认）时，Agent 每隔 `host_interval_s` 秒用 `moshiro.host` 上报一份主机资源占用的汇总数字（CPU、内存、根分区、网卡累计流量与网速、运行时长；没有型号、主机名、IP）；设为 false 就一个字也不上报。