From e2e5e437cb3866f69bd75d3eb9e015234aefe331 Mon Sep 17 00:00:00 2001 From: JustMe Date: Sat, 10 Oct 2026 03:00:47 +0800 Subject: [PATCH] docs(deploy): document QUIC runtime and port requirements [CI] --- README.md | 4 ++-- backend/agent/README.md | 2 +- docs/design/architecture.md | 6 +++--- docs/design/measurement.md | 6 +++--- docs/design/protocol.md | 6 +++--- docs/dev/project-layout.md | 6 +++--- docs/ops/deployment.md | 6 +++--- docs/security/enrollment.md | 8 ++++---- docs/security/security.md | 4 ++-- packaging/install.sh | 2 +- 10 files changed, 25 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 54f8cad..5595be4 100644 --- a/README.md +++ b/README.md @@ -58,7 +58,7 @@ MoShiro 是一个自托管的**网络线路质量观测工具**。它在若干 P │ Agent × 10+ │ ◀── 测量会话 ── │ Probe × N │ │ 有公网 IP，监听 │ 先敲门再 TLS │ 家宽等出口，NAT 后 │ └────────────────────┘ └──────────────────────┘ - 测量会话：TLS 控制通道 + UDP/TCP 数据通道，由 Probe 主动拨出 + 测量会话：TLS 控制通道 + QUIC Datagram/TCP 数据通道，由 Probe 主动拨出 宿主机更新器（容器节点）：用本机公钥验签 → 按 digest 拉镜像 → 重启，失败回滚 ``` @@ -75,7 +75,7 @@ Backend 用段文件保存原始数据，用 SQLite 保存索引、指标与配 - **控制链路（Fleet）**：节点到 Backend 的 `wss` 长连接（`/api/agent/v1/rpc`），JSON-RPC 2.0 信封加二进制通道；挑战加签名认证，`hello` 协商版本和能力，心跳；**期望状态同步**（Backend 下发完整快照，节点调和并回报已应用的版本和被拒绝的条目）；**可靠发件箱**（原始块至少一次投递，按 id 去重）。Fleet 与业务无关，放在 `backend/fleet/`。 - **业务方法**：`moshiro.*`（按需测试、Probe 断开、事件、主机汇总、更新通知等），状态文档有 `task_set`（Agent 的任务集）和 `probe_agents`（Probe 的 Agent 列表）。 -- **测量数据面**：Probe 到 Agent 的 TLS 控制通道、UDP 和 TCP 数据通道（默认 `7443/tcp`、`7443/udp`、`7444/tcp`）；会话用 `session_id` 和 MAC 认证、不绑定五元组，NAT 映射变化后自动跟随。 +- **测量数据面**：Probe 到 Agent 的 TLS 控制通道、QUIC Datagram 和 TCP 数据通道（默认 `7443/tcp`、`7443/udp`、`7444/tcp`）；测量包不走可靠重传，继续由会话 MAC、序号窗口和速率准入校验。 - **REST + SSE**：`/api/public`（展示，可匿名）、`/api/admin`（管理）；OpenAPI 在 `backend/openapi/v1.json`，前端据此生成类型。 细节见 [`docs/design/protocol.md`](docs/design/protocol.md)、[`backend/fleet/README.md`](backend/fleet/README.md)、[`docs/api/api.md`](docs/api/api.md)、[`docs/security/enrollment.md`](docs/security/enrollment.md)。 diff --git a/backend/agent/README.md b/backend/agent/README.md index 14238f5..90c8e0b 100644 --- a/backend/agent/README.md +++ b/backend/agent/README.md @@ -7,7 +7,7 @@ Agent 仅开放配置的控制和数据端口。它不提供远程终端、命 ## 工作流程 ```text -Probe ──TLS 控制 / UDP、TCP 测量──> Agent ──长连接与数据上报──> Backend +Probe ──TLS 控制 / QUIC Datagram、TCP 测量──> Agent ──长连接与数据上报──> Backend ▲ fleet-enroll 注册 ``` diff --git a/docs/design/architecture.md b/docs/design/architecture.md index 4a90219..6919ed9 100644 --- a/docs/design/architecture.md +++ b/docs/design/architecture.md @@ -30,7 +30,7 @@ │ Agent × 10+ │ ◀── 测量会话 ── │ Probe × N │ │ 有公网 IP，监听 │ 先敲门再 TLS │ 家宽等出口，NAT 后 │ └────────────────────┘ └──────────────────────┘ - 测量会话：TLS 控制通道 + UDP/TCP 数据通道，由 Probe 主动拨出 + 测量会话：TLS 控制通道 + QUIC Datagram/TCP 数据通道，由 Probe 主动拨出（Agent 固定 QUIC 端口，Probe 本地源端口轮换） 宿主机更新器（容器节点）：用本机公钥验签 → 按 digest 拉镜像 → 重启，失败回滚 ``` @@ -64,7 +64,7 @@ | 任务模型 | `Task = {kind, target, params, schedule}`；持续采集、按需测试、目标任务统一建模；下发“期望任务集”，由节点自行调和 | [measurement.md](measurement.md) | | 采集扩展 | Kind 由积木组合声明；采集密度靠参数调整；原始块自描述 | [measurement.md](measurement.md) | | 统计扩展 | 指标注册制：少数几种累加器 + 统计算子；一行 `MetricDef` 就是一个新指标 | [analysis.md](analysis.md) | -| 协议 | 控制链路使用 Fleet（JSON-RPC 2.0 + 二进制通道）；MoShiro 只定义 `moshiro.*` 方法、`TaskSet` 状态文档和 UDP/TCP 数据面 | [protocol.md](protocol.md) | +| 协议 | 控制链路使用 Fleet（JSON-RPC 2.0 + 二进制通道）；MoShiro 只定义 `moshiro.*` 方法、`TaskSet` 状态文档和 QUIC Datagram/TCP 数据面 | [protocol.md](protocol.md) | | 存储 | 原始块追加写入段文件，SQLite 记录偏移量；指标窗口通用存储并降采样 | [storage.md](storage.md) | | 展示查询 | 任意时间段（相对或绝对）；自动步长（每条曲线最多约 720 个点）；1s 内存热层（1 小时）加上 10s/1m/5m/1h 各层；累加器现场合并，汇总精确；列式响应；SSE 实时跟随 | [query.md](query.md) | | API | `/api/public`（只读，可设为公开）、`/api/admin`（登录）、`/api/agent`（注册与 RPC）；实时数据用 SSE | [api.md](../api/api.md) | @@ -157,7 +157,7 @@ Kind 目录编译在二进制中，节点不接受远程下发代码（安全边 | D15 | 注册独立为 `fleet-enroll` 工具；常驻进程不包含注册代码 | 常驻进程去掉 HttpClient，边界更纯 | | D16 | 更新与业务进程分离：发布密钥签名、本地策略、健康确认与回滚。已实现：宿主机 `moshiro-update`（Backend、脚本装的节点，清单里是镜像 digest），Quadlet 节点则靠退出后由 systemd 重新拉镜像；纯二进制节点的更新见 [TODO.md](../../TODO.md) | 面板被攻破时也无法推送恶意二进制 | | D17 | Probe 支持 OpenWrt：正式支持 `linux-musl-x64`、`linux-musl-arm64`；armv7 视工具链验证结果决定；MIPS 不支持，改为在局域网设备上运行 Probe | 由用户确认；NativeAOT 不支持 MIPS | -| D18 | 默认测量端口不使用 443：控制 7443/tcp，UDP 数据 7443/udp，TCP 数据 7444/tcp；443 只在 Agent 本地显式开启时才允许使用 | 由用户确认；避免与 VPS 上的真实服务冲突；结果会记录实际端口 | +| D18 | 默认测量端口不使用 443：控制 7443/tcp，QUIC Datagram 数据 7443/udp，TCP 数据 7444/tcp；443 只在 Agent 本地显式开启时才允许使用 | 由用户确认；避免与 VPS 上的真实服务冲突；结果会记录实际端口 | | D19 | 展示查询最细 1s：最近 1 小时来自内存热层，更早的数据来自 10s/1m/5m/1h 各层，现场合并；时间段内的汇总由累加器精确合并得出 | 由用户确认；5 分钟、15 分钟这类视图足够精细且快 | | D20 | 时序响应采用列式格式（`t[]` + `values{}`，时间轴使用 Unix 毫秒） | 由用户确认；体积小，可以直接交给图表库 | | D21 | 国家和运营商只由 Backend 向 IP 归属服务查询（缺省 `https://ip.007995.xyz`，可关闭），只查公网地址；节点不访问任何外部服务；公开接口不返回 IP、城市、ASN | 客户的防火墙常常要审计节点的出站连接；访客拿不到敏感信息（有测试保证） | diff --git a/docs/design/measurement.md b/docs/design/measurement.md index a581eb2..bdebb6a 100644 --- a/docs/design/measurement.md +++ b/docs/design/measurement.md @@ -145,10 +145,10 @@ MoShiro.Measurement/ 依赖：MoShiro.Protocol（仅 BCL， │ ├─ MonoClock.cs 单调时钟（微秒）与 UTC 锚点 │ └─ RunningBlock.cs 一个运行中的积木（取消令牌 + 后台任务） ├─ Net/ -│ ├─ UdpMux.cs UDP 数据面：按 stream 分发；校验顺序固定；准入策略（重放、限速）通过 IAdmission 注入 +│ ├─ QuicDatagramTransport.cs、MeasurementDatagramRouter.cs MsQuic 数据面与逐流认证分发 │ └─ Tcp.cs TcpLink（拨号：TLS 按指纹固定 + 认证首帧）、TcpAcceptor（监听：TLS 自动识别 + 认证首帧） ├─ Blocks/ 一个文件 = 一种采集方法的两个角色 -│ ├─ Echo.cs UdpEchoDialer/Listener、TcpEchoDialer/Listener +│ ├─ Echo.cs DatagramEchoDialer/Listener、TcpEchoDialer/Listener │ ├─ Session.cs ConnectDialer、HoldDialer、IcmpEchoSolo（没有对端）、IdleListener │ ├─ Train.cs TrainDialer（接收，记 t_recv）、TrainListener（按码率发包，记发送行） │ └─ BlockCatalog.cs Kind → (拨号方, 监听方)；capabilities、本地预算的支持列表都从这里推出来 @@ -174,7 +174,7 @@ MoShiro.Measurement/ 依赖：MoShiro.Protocol（仅 BCL， | 用途 | 默认端口 | 说明 | | --- | --- | --- | | Probe 控制通道（TLS，Fleet 点对点会话） | 7443/tcp | | -| UDP 数据（`udp_echo`、`udp_train`） | 7443/udp | | +| QUIC Datagram 数据（`udp_echo`、`udp_train`） | 7443/udp | Agent 固定监听；Probe 每次新连接轮换本地源端口 | | TCP/TLS 数据（`tcp_echo`、`tcp_bulk`、`connect`、`hold`） | 7444/tcp | 按首帧中的 `stream_id` 分发 | - **默认不使用 443**，避免与 VPS 上已有的 REALITY 或 Hysteria2 服务冲突，也不需要特权端口权限。 diff --git a/docs/design/protocol.md b/docs/design/protocol.md index 71c1874..67f1f4c 100644 --- a/docs/design/protocol.md +++ b/docs/design/protocol.md @@ -5,14 +5,14 @@ MoShiro 的两条控制链路都建立在 Fleet 之上： - **Agent ↔ Backend**：Fleet 连接服务端（wss），见 [../backend/fleet/README.md](../../backend/fleet/README.md)； - **Probe ↔ Agent**：Fleet 节点间点对点会话（TLS），见 [../backend/fleet/README.md](../../backend/fleet/README.md) 的「点对点会话」一节。 -认证、心跳、重连、能力协商、可靠发件箱、期望状态同步、JSON-RPC 信封都由 Fleet 负责。本文只定义 **MoShiro 自己的内容**：`moshiro.*` 方法、状态文档、二进制通道，以及 Fleet 之外的数据面（UDP 包和数据连接）。所有类型都放在 `MoShiro.Protocol` 中。 +认证、心跳、重连、能力协商、可靠发件箱、期望状态同步、JSON-RPC 信封都由 Fleet 负责。本文只定义 **MoShiro 自己的内容**：`moshiro.*` 方法、状态文档、二进制通道，以及 Fleet 之外的数据面（QUIC Datagram 和 TCP 数据连接）。所有类型都放在 `MoShiro.Protocol` 中。 ## 1. Fleet 能力的映射 | MoShiro 需要的能力 | 使用的 Fleet 机制 | MoShiro 提供的内容 | | --- | --- | --- | | 下发任务 | 期望状态 `fleet.state.sync` | 文档类型 `TaskSet`，包括 `tasks[]`、`peers`（允许连这个 Agent 的 Probe 公钥，已按线路开关过滤） | -| 下发 Agent 列表给 Probe | 期望状态 `fleet.state.sync`（Probe 直连面板） | 文档类型 `probe_agents`：`version`、`agents[]`（`agent_id`、`host`、`tcp_port`、`udp_ports`、`public_key`），`public_key` 是 Agent 面向 Probe 的 TLS 证书公钥（SPKI，base64）：Probe 用它固定证书并派生敲门密钥；没有上报公钥的 Agent 不会下发。已按线路开关过滤；Agent 集合或线路开关变化时重新推送 | +| 下发 Agent 列表给 Probe | 期望状态 `fleet.state.sync`（Probe 直连面板） | 文档类型 `probe_agents`：`version`、`agents[]`（`agent_id`、`host`、`tcp_port`、`quic_ports`、`public_key`），`public_key` 是 Agent 面向 Probe 的 TLS 证书公钥（SPKI，base64）：Probe 用它固定证书并派生敲门密钥；没有上报公钥的 Agent 不会下发。已按线路开关过滤；Agent 集合或线路开关变化时重新推送 | | 定时重启 | 通知 `moshiro.schedule`（B→A、B→P） | `{restart_at}`，形如 `04:30+08:00`，空表示关闭；连上时补发、管理端改了设置就群发。节点本地写了 `restart_at` 或 `MOSHIRO_RESTART_AT` 时以本地为准；节点只是到点自己有序退出，由服务管理器拉起 | | 更新 | 通知 `moshiro.update.offer` / `moshiro.update.apply`（B→A、B→P），心跳附加字段 `update` | `offer` 带 CI 签名的发布清单原文和签名，节点只写进数据目录；`apply` 请求更新；`update` 是宿主机更新器的状态（`state`、`current`、`available`、`error`、`at`），见 [deployment.md](../ops/deployment.md) | | 上报原始块 | 发件箱，二进制通道 **16** | `RawChunk`（自描述，见 [measurement.md](measurement.md) 第 4 节），`msg_id = chunk_id` | @@ -113,5 +113,5 @@ Probe 只记录自己一侧的列，Agent 在数据面记录另一侧，由 Agen - Fleet 层的兼容规则见 [../backend/fleet/README.md](../../backend/fleet/README.md)。 - `moshiro.*` 方法：新增方法或可选字段不需要升级版本，接收方忽略未知字段。 - RawChunk：块头自描述，新增列或新增 Kind 不需要升级 `container_version`；只有容器格式变化时才升级。 -- UDP 包和数据连接首帧的布局变化时，必须升级 `protocol_version`，并更新黄金字节测试。 +- QUIC Datagram 和 TCP 数据连接首帧的布局变化时，必须升级 `protocol_version`，并更新黄金字节测试。 - Agent 同时支持当前版本和上一个版本的 Probe；Backend 能解码保留期内所有的 `container_version`。 diff --git a/docs/dev/project-layout.md b/docs/dev/project-layout.md index 96fcdae..95307f7 100644 --- a/docs/dev/project-layout.md +++ b/docs/dev/project-layout.md @@ -3,7 +3,7 @@ ## 1. 目标 1. **三个独立项目加一个前端**：Probe、Agent、Backend 各自拥有解决方案，可以单独构建、测试和发布；Web 是独立的 Vite 项目（`web/`）。 -2. **通用能力只写一次**：TCP/UDP/TLS/ICMP 采集积木（类似 iperf3 的能力，但只记录原始数据）放在 `MoShiro.Measurement` 中，Probe 和 Agent 共用；采集方法（Kind）由积木组合声明而成。 +2. **通用能力只写一次**：TCP/QUIC Datagram/TLS/ICMP 采集积木（类似 iperf3 的能力，但只记录原始数据）放在 `MoShiro.Measurement` 中，Probe 和 Agent 共用；采集方法（Kind）由积木组合声明而成。 3. **节点机制通用化**：注册、身份、连接、RPC、可靠上报、状态同步、宿主，由与业务无关的 **Fleet** 框架提供（见 [../backend/fleet/README.md](../../backend/fleet/README.md)）。MoShiro 只写业务，其他产品也可以复用 Fleet。 4. **改一处，整条链路受益**：协议、原始数据格式、测试方案、指标、错误码、版本号、编译设置、代码风格都只有**一个真源**。改动之后，下游要么自动更新，要么在编译期或 CI 中直接报错。 5. **模块化**：Probe/Agent 由可插拔的模块组成；Backend 按层分成多个项目，层之间的依赖在编译期强制。 @@ -111,7 +111,7 @@ MoShiro.Protocol/ │ └─ ParamSpec 参数定义（类型、默认值、上下限），节点与 Backend 共用同一套校验 ├─ Tasks/ TaskSet（Fleet 期望状态的文档类型）、调和结果 ├─ Rpc/ moshiro.* 方法名、params/result、二进制通道号（从 16 开始） -├─ Wire/ UDP 包、数据连接首帧 +├─ Wire/ QUIC Datagram 测量包 └─ Raw/ 自描述 RawChunk：头部、列类型、列编解码、Brotli、crc32c ``` @@ -142,7 +142,7 @@ AgentApp Probe（ProbeApp） 发件箱 RawChunk（通道 16） 心跳带更新器的状态；moshiro.update.* 通知 心跳带更新器的状态；moshiro.update.* AgentDirectory → 每个 Agent 一个 AgentConnection（点对点会话） PeerListener / PeerHub（Probe 会话） 会话内：线路任务集 line_task_set 的调和、角色、列块发件箱（通道 17） - UdpMux / TcpAcceptor（数据端口） + QuicDatagramTransport / TcpAcceptor（数据端口） TaskManager / TestRunner / ChunkAssembler RestartUpdater（只报告有无新版本、请求时退出） RestartUpdater ``` diff --git a/docs/ops/deployment.md b/docs/ops/deployment.md index 218e4db..eef88db 100644 --- a/docs/ops/deployment.md +++ b/docs/ops/deployment.md @@ -1,6 +1,6 @@ # 部署 -节点（Agent、Probe）是单个 NativeAOT 可执行文件，没有运行时依赖，只需要系统的 OpenSSL 3（`libssl.so.3`）。启动时会自检，缺少时第一步就明确报错。 +节点（Agent、Probe）使用 NativeAOT。QUIC 目前通过应用目录优先加载 MsQuic v2；Linux 还需要 OpenSSL 3（`libssl.so.3`）和 MsQuic 依赖的 `libnuma.so.1`。CI 发布包尚需补上这些原生 sidecar；在这项打包接通前，Linux 主机要从系统包安装 MsQuic 和 libnuma，发布包不能视为免依赖安装包。启动时会检查 MsQuic 是否可加载。 ## 1. 构建与打包 @@ -12,7 +12,7 @@ Agent 和 Probe 在 hello 初始化及心跳中上报 IPv6 检测结果，包括 升级 Backend、Agent、Probe 后，在管理端的 Agent 编辑页保留 IPv4 地址，并填写 IPv6 地址或带 AAAA 记录的域名。未填写 IPv6 地址的 VPS 只采集 IPv4；Probe 没有 IPv6 路由或 IPv6 连接失败时，IPv4 会话继续工作。 -Agent 的新默认监听地址为 `::`（双栈）；现有 `agent.json` 如果显式配置了 `0.0.0.0`，需要在宿主机改为 `::` 并重启节点。系统不支持 IPv6 套接字时，新默认值退回 IPv4 监听。防火墙需允许 IPv6 的 `7443/tcp`、`7443/udp`、`7444/tcp`（自定义端口时用实际端口）；容器推荐宿主网络。管理端的「IPv6 监听」显示节点实际是否启用。 +Agent 的新默认监听地址为 `::`（双栈）；现有 `agent.json` 如果显式配置了 `0.0.0.0`，需要在宿主机改为 `::` 并重启节点。系统不支持 IPv6 套接字时，新默认值退回 IPv4 监听。防火墙需允许 IPv6 的 `7443/tcp`、`7443/udp`（QUIC）、`7444/tcp`（自定义端口时用实际端口）；容器推荐宿主网络。管理端的「IPv6 监听」显示节点实际是否启用。 原来的 SQLite 数据库自动迁移，旧原始块、指标和测试结果继续属于 IPv4。先升级 Backend，再升级节点，最后填写 IPv6 地址；旧 Agent 不会上报 IPv6 支持，Backend 不会给它安排第二条会话。 @@ -155,7 +155,7 @@ Linux 上比 Windows 大，是因为 .NET 的加密、压缩、网络本机库 以 `moshiro` 用户运行，沙箱：`NoNewPrivileges`、`ProtectSystem=strict`、`ProtectHome`、`PrivateTmp/Devices`、`ProtectKernel*`、`RestrictAddressFamilies=AF_INET AF_INET6`、`RestrictNamespaces`、`MemoryDenyWriteExecute`（NativeAOT 不 JIT）、`SystemCallArchitectures=native`，`MemoryMax`（Agent 128 MB、Probe 64 MB）。 - **Agent** 只保留 `CAP_NET_RAW`（ICMP 目标任务用），`/etc/moshiro` 只读；Probe 没有任何 capability，只对 `agents.json` 所在的目录可写。 -- 监听 1024 以下的端口（例如把数据面放到 443）需要在 drop-in 里加 `AmbientCapabilities=CAP_NET_BIND_SERVICE` 和对应的 `CapabilityBoundingSet`。默认端口是 7443/tcp+udp（Probe 控制通道和 UDP 数据面）、7444/tcp。 +- 监听 1024 以下的端口（例如把数据面放到 443）需要在 drop-in 里加 `AmbientCapabilities=CAP_NET_BIND_SERVICE` 和对应的 `CapabilityBoundingSet`。默认端口是 7443/tcp（Probe 控制通道）、7443/udp（QUIC Datagram 数据面）、7444/tcp（TCP 测量）。Agent 在 UDP 端口固定监听；Probe 的 QUIC 连接使用轮换的临时本地源端口。 ### OpenWrt（`packaging/openwrt/`） diff --git a/docs/security/enrollment.md b/docs/security/enrollment.md index cdec579..a24ca94 100644 --- a/docs/security/enrollment.md +++ b/docs/security/enrollment.md @@ -25,7 +25,7 @@ ├─ 用 Docker 或 Podman 起容器，身份和配置存在命名卷里；节点名字默认取主机名 └─ 容器入口用代码注册：fleet-enroll --server … --join jt_… --genesis … --controllers … ├─ 先验操作员集合链（创世指纹、属主在集合里），验不过就不交出密钥 - ├─ 注册元数据（MoShiro 定义）：{ probe_tcp_port, probe_udp_ports, public_host?, kinds[] } + ├─ 注册元数据（MoShiro 定义）：{ probe_tcp_port, probe_quic_ports, public_host?, kinds[] } └─ 写 trust.json（创世指纹、链、属主）和 agent.json（本地硬上限） 下载压缩包的二进制安装（packaging/install.sh）做同样的注册，另外创建系统用户 moshiro、启用 moshiro-agent.service，见 deployment.md。 @@ -52,7 +52,7 @@ probe.json：{ fleet: { server, identity_dir }, restart_at?, limits? } ← lim Probe 启动 ├─ 连接 server：Fleet 长连接（用 probe_id 和私钥认证），fleet.hello 带上系统、架构和构建信息 - ├─ 面板推送期望状态 probe_agents：{ version, agents: [ {agent_id, host, tcp_port, udp_ports, public_key}... ] } + ├─ 面板推送期望状态 probe_agents：{ version, agents: [ {agent_id, host, tcp_port, quic_ports, public_key}... ] } ├─ 调和：新增的 Agent → 建立点对点会话（peer 用途签名）；被移除或禁用的 → 断开 └─ 之后列表的任何变化（Agent 注册、禁用、地址或证书变化），面板都重新推送同一种期望状态； Probe 用 Fleet.Hosting.ConfigStore 把最新列表写回 agents.json（这是配置，不是测量数据；面板暂时连不上时，Probe 靠它继续测量） @@ -67,7 +67,7 @@ Probe 启动 ```json { "fleet": { "server": "https://panel.example.com", "identity_dir": "/etc/moshiro" }, - "listen": { "control_port": 7443, "udp_ports": [7443], "tcp_ports": [7444] }, + "listen": { "control_port": 7443, "quic_ports": [7443], "tcp_ports": [7444] }, "limits": { "max_total_mbps": 200, "max_total_pps": 20000, @@ -80,7 +80,7 @@ Probe 启动 - `limits` 是**本地硬上限**：期望任务集超出这些范围时，调和器拒绝执行，并在 `rejected[]` 中给出原因。 - `allowed_target_cidrs` 默认为空，即不允许执行任何目标任务；需要时由节点所有者在本机显式开启。 -- `listen` 默认不包含 443。要用 443 测量，需要在本机把它加入 `udp_ports` 或 `tcp_ports`（端口不能被真实服务占用），见 [measurement.md](../design/measurement.md) 第 8 节。 +- `listen` 默认不包含 443。要用 443 测量，需要在本机把它加入 `quic_ports` 或 `tcp_ports`（端口不能被真实服务占用），见 [measurement.md](../design/measurement.md) 第 8 节。 - `fleet_policy.allow_methods` 在 Fleet 默认值的基础上进一步收窄。 ## 5. 相关 API diff --git a/docs/security/security.md b/docs/security/security.md index e738e52..28396c7 100644 --- a/docs/security/security.md +++ b/docs/security/security.md @@ -143,7 +143,7 @@ Agent、Backend、Probe 之间互相不信任。这份文档回答三个问题 - 被攻破的 Probe 只能拿到 Backend 授权的会话，Agent 的速率上限由本地兜底；被攻破的 Agent 发来的数据只会影响它自己的线路。 - **Probe 只拨公网地址**（G3）：固定 SPKI 只能防止建立会话，防不了探测本身；要在 Probe 本地拒绝私网、回环、链路本地地址。 - **名册里的主机名解析之后再检查地址**：签名保护的是字符串，不是解析结果；默认只放行公网地址，内网需要节点本地显式允许。 -- **UDP 会话迁移要做路径验证**：协议允许会话在 NAT 映射变化后跟随新的源地址，路径上的攻击者可以借此把会话牵到自己的地址。迁移前先做一次挑战应答，验证前限制发送量（不超过收到字节数的 3 倍），类似 QUIC 的 path validation。 +- **QUIC 会话迁移要做路径验证**：协议允许会话在 NAT 映射变化后跟随新的源地址，路径上的攻击者可以借此把会话牵到自己的地址。迁移前先做一次挑战应答，验证前限制发送量（不超过收到字节数的 3 倍），由 QUIC path validation 提供。 - **不协商、不降级**：现在固定 ECDSA P-256 和固定的签名串格式，没有算法协商，保持这一点。 - Agent 的 `max_total_mbps` 默认是 1200，对 1 核 1 GB 的小机器没有意义，却是被攻破的 Backend 能让 Agent 向某个 Probe 打出去的上限。默认值应该保守，需要的人再调高；`allowed_target_cidrs` 默认为空是对的。 @@ -181,7 +181,7 @@ Agent 和 Probe 的核心永远是纯采集器。**所有敏感能力**（exec | 用途 | 现状 | | --- | --- | | 身份签名 | ECDSA P-256 加 SHA-256（BCL） | -| 数据面逐包认证 | HMAC-SHA256 截断到 16 字节（`UdpPacket`、`TcpWire`） | +| 数据面逐包认证 | HMAC-SHA256 截断到 16 字节（`MeasurementDatagram`、`TcpWire`） | | 会话密钥派生 | HKDF-SHA256（`SessionKeys`） | | 控制链路加密 | AES-256-GCM（每个方向一把密钥，严格递增的计数器） | | 令牌哈希、SPKI 指纹 | SHA-256 | diff --git a/packaging/install.sh b/packaging/install.sh index 371f975..c0b2554 100644 --- a/packaging/install.sh +++ b/packaging/install.sh @@ -67,7 +67,7 @@ write_config() { cat >"$CONFIG/agent.json" <