From 71d2866b9c2c3db4697a94f8cb355afda74252fb Mon Sep 17 00:00:00 2001 From: JustMe Date: Wed, 7 Oct 2026 01:02:05 +0800 Subject: [PATCH] docs: update the architecture [SKIP TESTS] --- docs/architecture.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index 83f7f4e..1da3cc7 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -4,9 +4,9 @@ 一个**只关注网络层**的线路质量面板：单体面板（Backend）+ 轻量节点（Probe、Agent）+ 长连接 RPC + 任务下发。核心能力： -- 在**一个家宽 Probe** 与**多台海外 VPS Agent**（10 几台）之间，采集**最原始的逐包、逐事件数据**； +- 在**若干 Probe**（家宽等需要观测的出口，可以有多个）与**多台海外 VPS Agent**（10 几台）之间，采集**最原始的逐包、逐事件数据**；哪些 Probe 连哪些 Agent 由面板决定（自动全连，也可以手动选择）； - 由 Backend 的分析层推算：**如果在某条线路上部署 REALITY 类、Hysteria2 类或 Minecraft 服务，体验会怎样**，并对多条线路排序和对比； -- **主机层信息只上报只读的汇总数字**（2026-10 起，由用户确认放开）：Agent 读 `/proc` 得到 CPU 占用、内存、根分区、网卡累计流量与瞬时网速、运行时长，不采集 CPU 型号、主机名、网卡名和任何 IP，不采集进程；Probe 不上报。展示页只能拿到这些数字。Agent 和 Probe 仍然是**纯采集器**，不具备 SSH、远程执行、终端、文件读写、远程更新等能力。 +- **主机层信息只上报只读的汇总数字**（2026-10 起，由用户确认放开）：Agent 读 `/proc` 得到 CPU 占用、内存、根分区、网卡累计流量与瞬时网速、运行时长，不采集 CPU 型号、主机名、网卡名和任何 IP，不采集进程；Probe 不上报主机资源。节点只在连接面板时自报粗粒度的系统、架构和构建信息（版本、tag、提交、构建时间），用于展示和更新；国家和运营商由 Backend 用节点的来源地址查询，节点自己不访问任何外部服务。展示页看不到任何 IP。Agent 和 Probe 仍然是**纯采集器**，不具备 SSH、远程执行、终端、文件读写、自更新等能力：更新由节点宿主机上的更新器完成，节点进程只往数据目录放面板转来的发布清单和更新请求。 ## 2. 拓扑 @@ -22,7 +22,7 @@ │ │ │ │ 每个 Agent 一个会话： └────────┴───┬────┴─────────────┘ TLS 控制通道 + UDP/TCP 数据通道 ┌─────┴──────┐ - │ Probe │ 家宽，NAT/CGNAT 后，唯一的测量起点 + │ Probe │ 家宽，NAT/CGNAT 后，测量的起点 └────────────┘ 直连 Backend（身份、列表），测量只连 Agent ``` @@ -73,16 +73,16 @@ ```text Agent / Probe 能做的 执行编译在二进制中的 Kind；监听和访问本地配置允许的端口与网段；受本地硬上限约束 -不能做的 exec / shell / 终端 / 文件读写（配置目录除外）/ 远程更新 / 加载外部代码 / 采集主机标识（型号、主机名、IP、进程） +不能做的 exec / shell / 终端 / 文件读写（配置目录除外）/ 自更新 / 加载外部代码 / 采集主机标识（型号、主机名、IP、进程） 即使 Backend 被攻破 攻击者最多能在本地硬上限内发测量流量，拿不到主机权限，也无法把 Agent 当成扫描器或放大器； - 也推不出恶意更新（更新清单必须由离线密钥签名） + 也推不出恶意更新（更新清单必须由发布密钥签名，节点宿主机上的更新器用本机公钥验签，并且只认本机配置的镜像仓库） ``` - **本地硬上限**写在节点本机的配置文件中，Backend 下发的任务如果超出，节点直接拒绝：允许访问的目标网段（默认为空，即不开放目标任务）、总码率和包速率上限、允许监听的端口。 - **构建期强制**：常驻节点进程使用 `BannedSymbols.Node.txt`，禁用 `System.Diagnostics.Process`、`Assembly.Load*`、`NativeLibrary.Load`、`HttpClient`，以及 `ConfigStore` 以外的文件写入 API，详见 [project-layout.md](project-layout.md) 第 7 节。 -- **三进程权限分离**：注册（`fleet-enroll`，一次性运行）、采集（`monitor-agent` / `monitor-probe`）、更新（`fleet-updater`）是三个独立进程，使用不同的系统用户。采集进程无法改写自己的二进制；更新进程读不到节点身份私钥。 +- **权限分离**：注册（`fleet-enroll`，一次性运行）、采集（`monitor-agent` / `monitor-probe`）、更新是不同的进程。容器节点里，采集进程在容器内以 UID 1654 运行（只读文件系统、不带额外能力），更新由宿主机上 root 运行的 `monitor-update` 完成：它只读取节点放进 `update/` 的普通文件、复制到自己的临时目录后验签，状态写在节点只读的 `update-status/`；采集进程改写不了自己的二进制，更新器也读不到节点身份私钥。纯二进制安装的 `fleet-updater` 还只是设计。 - **最小权限运行**：非 root 用户；只在需要时授予 `CAP_NET_RAW`（ICMP）；默认端口都高于 1024，不需要 `CAP_NET_BIND_SERVICE`，只有在 Agent 本地显式开启 443 时才授予。 -- **身份**：节点使用本地生成的 ECDSA P-256 密钥对签名认证，Backend 只存公钥，数据库泄露也无法冒充节点。 +- **身份**：节点使用本地生成的 ECDSA P-256 密钥对签名认证（Probe 的密钥由面板生成、只返回一次，同一把用来连面板和连 Agent），Backend 只存公钥，数据库泄露也无法冒充节点。 - **防放大**：未认证的包静默丢弃；回复长度与请求相等；每个流按声明速率限速；使用重放窗口。 - **自身状态**：节点上报进程内的计数（会话数、包速率、队列、丢弃数）；Agent 另外每隔几秒用 `monitor.host` 上报一份主机资源占用的汇总数字（可以在 `agent.json` 里用 `reporting.host_stats = false` 整个关掉），最新值实时推给展示页，Backend 每分钟存一个样本（默认保留 7 天，`retention.host_days`）。 @@ -130,10 +130,12 @@ Kind 目录编译在二进制中，节点不接受远程下发代码（安全边 | D18 | 默认测量端口不使用 443：控制 7443/tcp，UDP 数据 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 | 客户的防火墙常常要审计节点的出站连接；访客拿不到敏感信息（有测试保证） | +| D22 | 构建信息（版本、tag、提交、构建时间）由节点自报，访客是否可见由设置 `site.show_build` 控制（默认关）；提交号只在管理端 | 展示页可以选择不暴露版本；管理员能看出哪个节点没升级 | ## 9. 仍待确认 -其余待确认事项： +待确认事项： 1. **告警**：首版不包含，是否需要预留 Webhook？ 2. **与真实服务共用 443**（例如 SNI 分流）：首版不做，默认使用非 443 端口；以后如有需要再评估。