1 Fork 0

Files

T

justme c9beeee8e3 docs: describe the unified Agent topology and link controls

Align architecture, protocol, API, storage, security and deployment documentation with default mutual measurements and the Agent link board.

2026-10-21 11:55:55 +08:00

4.8 KiB

Raw Permalink Blame History

MoShiro 的注册与身份

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

1. 身份

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

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

2. 接入

管理端创建加入令牌（统一 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`，面板无法修改）

{
  "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 第 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 段（面板无法修改）：

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

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

4.8 KiB Raw Permalink Blame History