0 Fork 0

Files

T

admin ce8e6ceed9 chore(工作区): 纳入版本控制基线（回收 411 MB 过程产物）

回收 411 MB（470 M → 58.8 M），全部经回收站，可恢复：
- 待清理/（146.2 M，含 relay 分片 128 M 与 42 项过程目录）
- tmp/（32.4 M，按接续棒命名的过程临时区）
- .workbuddy/tmp/（39.5 M）
- 4 份 workbuddy.db 冗余副本（101 M，09-23 事故的坏副本 / 抢救产物）
- tmp/im16/gw/centrifugo 二进制（63.9 M，可重下）+ 缓存残留

入库范围：常驻规则（CODEBUDDY.md / README.md / state.py）、在途接续入口与
接续包、docs/、交付物/、交接单/、归档/、scripts/、.codebuddy/、
.workbuddy/memory/；共 398 件，其中 >60 KB 的 26 件全为文档。

排除（.gitignore）：tmp/、待清理/、运行态日志与缓存、*.db 与 DB 备份整目录、
打包二进制（*.tar.gz / *.tgz）、记忆修复前备份。

2026-09-24 07:51:03 +08:00

22 KiB

Raw Blame History

覆盖网络 · 功能整体完成情况报告

报告日期：2026-09-18 08:2x ｜性质：整体完成度 + 全景说明（背景目标 / 技术路线 / 架构 / 功能特性 / 应用场景 / 性能与安全评估 / 潜在风险） 单一来源：工作区根 接续入口_覆盖网络线_20260916.md（唯一入口）＋ 参数表_覆盖网络_20260917.md（唯一参数表）＋各序交接单 ⚠️ 引用的都是实测值；凡未实测的一律标"未验证"，⛔ 不编数。

0. 完成度判定（先给结论）

维度	判定	证据
功能主体	✅ 全部开发完成并落地生产	序 ①–㉛全收官（含单 A「退出路径不杀实例」、单 B「组密钥加密」）
在册红项	✅ 0	探针 `OBS-01..23` ⇒ 23 PASS / 0 SKIP / 0 FAIL（rc=0）
待测项	✅ 0 项	参数表 §7（与表内 `待测` 单元格一一对应）
待拍板项	✅ 空	入口 §4（2026-09-17 20:2x 三项全拍板；23:3x 又一轮三问全答复）
部署形态	✅ 两机生产运行	47（Manager ＋ `w-47`）／106（`w-106`），relay 各一台（只绑回环 `20080`）

⇒ 一句话：覆盖网络线的功能开发已全部完成并落地生产，线内在册红项为零、无待拍板项，当前处于 ⏸️ 线内可停状态（待真实信号再启）。

⚠️ 三项"不算未完成"的如实说明（避免被误读为缺口）：

C 档「systemd scope 单一真相源」 —— 用户 2026-09-17 23:3x 明令"登记为架构目标、本阶段不进执行" ⇒ 属有意延后，非缺口。
§10-5 Ed25519→X25519 派生预研 —— 服务对象是回头条件 7「规模上来了要自动分发组密钥」⇒ 触发条件 = 规模上来，⛔ 不是当前执行项；本条本轮未测（不在写死主题内）。
档案 112「只做三件事」的第三件「游戏服放 L1」 —— 属部署形态建议，未见落地记录；前两件（presence、块级内容寻址）✅ 均已完成。

⚠️ 取证提示：dsh-server-docs/BRIEF.md 最后人工核对 = 2026-09-16 10:5x，其中「归档编号至 112」「覆盖网络线后续待排期」等行已过期（现核归档号 130）⇒ 涉及覆盖网络线的现行事实以入口文件为准。

1. 背景目标

1.1 要解决的问题

多租户 DSH 平台的用户设备散落在服务器 / 家宽 / 共享 IP / 移动网 / 企业网 / VPN 等异构网络里。需求 = 让同一个人的多台设备、以及被授权的他人设备能够互通，且全球可接入、规模化时不产生流量风暴。

1.2 目标形态（定性）

任何用户在任何网络里的设备，都能与自己的其他设备、以及授权的他人设备互通；
全球可接入；
规模上去后网络不产生风暴（这是本线最核心的非功能目标）。

1.3 已锁定的边界与口径（用户拍板，⛔ 不许再上抛）

#	口径	含义
1	方案只做技术实现	跨境数据合规由使用者自行考虑 ⇒ 选型不为合规让路、跨境不设限、⛔ 不把合规当前置
2	单机自用 ≠ 不需要互联	「单机用也要互联，这正是建立覆盖网络的目的」⇒ 租户维度收窄 ≠ 网络维度收窄
3	按异构设计	中继按 45% 设计 / 55% 留余量（⛔ 不是同构假设的 15%）；必须补 443/TCP 兜底；有公网 IP 者升格为中继候选
4	权威状态单点	归属 / 租约 / 骨干资格只能控制面写；会合 / 中继可多实例
5	形态默认	单机自用为默认；"当服务器给他人用"的多人维度已放弃
6	游戏重点	MMORPG（2D/2.5D）/ MUD / 传奇类 ⇒ 判定上修为"最匹配"，⛔ 非 3D 强实时竞技

2. 技术路线

2.1 总路线：照抄成熟做法，不自创

判定原话：「有完整可循的工程路径 —— 这套东西在 Tailscale / ZeroTier / Nebula / libp2p / BitTorrent 上已被反复验证，关键是照抄它们踩过的坑，而不是自己发明。」

2.2 优先级：先"只做三件事"，再铺开

序	三件事	状态
1	presence（节点在线态）	✅ 已完成（序⑲ 落地，`OBS-13..16` 四判据）
2	块级内容寻址	✅ 已完成（序㉔落地，`OBS-17`）
3	游戏服放 L1	⚠️ 属部署形态建议，未落地

2.3 关键实现取向（已定，非选型题）

自研 relay（⛔ 不走第三方选型）⇒ 两台：47 ＋ 106，只绑回环 20080；
⛔ 不做打洞实现（打洞失败直接降级中继；不反复重试）；
worker 永远只拨出（106 入站 = 0）⇒ 不新增公网监听口；
内容源优先级链：local → peer → edge → region → origin，唯一解密点在链的统一返回点；
块 id 口径 β′：sha256(密文) 前 32 hex（组内稳定、组外不可预测）；
加密档位：C 组密钥加密（同一 (network, group) 共享一把 AES-256-GCM 对称密钥）；
确定性（收敛）加密：iv = HMAC(key,"iv"‖plain) 前 12 B、k = HMAC(key,"k"‖iv)、AAD = "<groupKey>|<epoch>" ⇒ 同组同明文密文逐字节相同 ⇒ 序㉔的"按哈希共享块"不退化。

3. 架构

3.1 五层架构（设计基线）

层	职责	关键要求
控制面	身份、授权、归属/租约、网络地图（netmap）分发	承载几乎零流量；挂了不影响已建立的数据面（节点内存缓存状态）
会合层	交换候选地址、协助打洞、签发骨干目录	多区域、多实例、可缓存
骨干 / 中继层	打洞失败时转发密文；可选做区域汇聚	限额资源（预约制 + TTL + 配额），不可无限使用
数据面	端到端加密的节点间直连/中继传输	直连优先；空闲不建连；扇出设上限
观测层	路径类型（直连/中继）、时延、重连次数、带宽	没有它，容量规划与排障只能靠猜

3.2 本平台的实际落地形态

                    ┌───────────────────────────────┐
                    │  控制面 = 47 的 Manager(dshs)  │  ← 权威状态单点
                    │  PG13 127.0.0.1:15432          │     归属/租约/骨干资格
                    └────────────┬──────────────────┘
                                 │ 拨出式（Manager 拨号通道，周期重解析）
                    ┌────────────▼──────────────────┐
                    │  会合/目录：/dshs-overlay/     │  ← 签名目录（可信签名者 1）
                    │  bootstrap（只绑回环 3080）     │     候选链 3 条
                    └────────────┬──────────────────┘
                                 │
        ┌────────────────────────┼────────────────────────┐
        │                        │                        │
┌───────▼────────┐      ┌────────▼───────┐       ┌────────▼───────┐
│ relay@47       │      │ relay@106      │       │ 443/TCP 兜底   │
│ 只绑回环 20080 │      │ 只绑回环 20080 │       │ （nginx 反代） │
└───────┬────────┘      └────────┬───────┘       └────────────────┘
        │  转发密文（中继不解密）  │
┌───────▼────────────────────────▼───────────────────────────────┐
│ 数据面：w-47(19100) │ w-106(19000) │ 用户实例 20000 / 21000     │
│ 内容面：local → peer → edge → region → origin（唯一解密点）      │
└────────────────────────────────────────────────────────────────┘
                                 │
                    ┌────────────▼──────────────────┐
                    │  观测层 = scripts/overlay-probe.cjs │
                    │  OBS-01..23（唯一取数来源=参数表） │
                    └───────────────────────────────┘

形态要点：47 = Manager（单元 dshs）兼本地 Worker w-47；106 = Worker w-106。⚠️ 47 兼作 Worker 是有意设计。⚠️ 106 入站 = 0（worker 永远只拨出）。⚠️ nginx 归宝塔面板托管 ⇒ is-active nginx = inactive 是正常态，⛔ 别拿它判死活。

3.3 密钥模型（四层）

离线根 ──► 47 在线签名者 ──► 每机节点密钥 ──► 会话
            /etc/dshs/overlay-signer-key.pem
            公钥 bad464dfd53048efe7b8531029b3030eda49bc12930703d3a2a8f60e3a7daddf

组密钥凭据 = 签 (network, group, epoch, keyId) 四元组，⛔ 载荷不含密钥本体。组密钥铺两机 0600 root:root。双 epoch 过渡窗口 CONTENT_EPOCH_GRACE_MS（缺省 24 h）⇒ previous[] 只解不写，超窗 ⇒ epochExpired +1 ＋ decryptRejected +1。

4. 功能特性

4.1 十二项内建特性 × 落地对账

#	特性（设计基线）	落地状态
1	控制面 / 数据面彻底分离	✅ 控制面挂 → 已建连接不断（`LeasedSpawner` 远端实例寿命长于任何单个 Manager 副本）
2	先中继、再升级直连	✅ relay 中继可用；直连升级属"打洞未做"范围（→ 特性 3）
3	直连成功率作为一等指标	⛔ 不做打洞实现（用户拍板范围外 ⇒ 判死直接降级中继）
4	空闲不建连（懒建连）	✅ 空闲会话不建连；`idle-reap` 间隔 60 s / TTL 7 天 / 每 host 上限 4
5	中继是稀缺资源，要准入	✅ 45% 设计 / 55% 余量＋软门 `utilMaxPct=70` ＋ `utilRefused` 计数
6	失败要能"判死"	✅ 终态早退（`waitUpOnStatus`）＋ `RELAY_FAILOVER_DEADLINE_MS` 内侧
7	端到端加密 + 中继不解密	✅ 组密钥 GCM：中继只见元数据（谁连谁、量多大）
8	一机一身份 + 可吊销	✅ `identityRequired=true` / `trustedSigners=1` / `revokedHosts` 清单
9	自报网络画像	🟡 部分（路径类型/在线态/端口已入观测；NAT 类型 / VPN 检测见特性 12 口径）
10	内容寻址 + 分级缓存	✅ `local → peer → edge → region → origin` 五档链＋块级寻址 `β′`
11	统一限流与退避参数表	✅ 参数表 `参数表_覆盖网络_20260917.md` = 唯一取数来源（探针脚本内零魔数）
12	可见性默认最小	✅ 接入 ≠ 可见；⚠️ VPN/代理检测即降级不重试

4.2 已落地的功能清单（按序）

序	功能	关键判据
①–⑥	可行性评估 / 架构复盘 / 瓶颈落地 / 骨干层 / 百台·千台推演 / 游戏专项	10 份规划文档（归档 103–112）
R0–R5	relay 最小闭环 → 韧性选点 → 常驻 + 443 暴露 → Manager 拨号通道	`OBS-01..12`
⑦–⑩	失败切流（候选集不再退化单点）＋冷却语义拆分（一跳豁免 / 终态早退）	演练幕 `--scene 4/4b/4c`；`[relay-switch]` 行数 ≡ `switches`
⑲	presence（节点在线态）：首帧即全量、稳态零帧率、在线态不撒谎	`OBS-13..16`
㉑–㉒	观测口径与在册缺陷（P-1 门翻转 / P-2b 三级候选链）	`OBS-09`
㉔	块级内容寻址：五档源链 + 块级 store + 唯一解密点	`OBS-17`
㉕–㉚	实例逐步拉起（启动认领 + TCP 探活判孤儿）	`OBS-18`
㉖–㉚	骨干稳定选路与 jitter 选路	`OBS-19`、`OBS-20`
㉗	每连接候选数 ≥ 2（E3 路径多样性）	`OBS-21`（两路径 `count=3`）
㉘单 A	退出路径不杀实例（三处 `teardown()` 同改）	`OBS-22`（静态守卫＋认领面自洽）
㉘单 B	组密钥加密（GCM 确定性）	`OBS-23`（确定性 / 共享 / 明文不出现 / 权限=600）

4.3 观测面（23 条判据 = 功能可断言面）

OBS-01..23 覆盖：容量与在册（01/02/20）｜身份与授权（03/04/05/07）｜判别器三件套（06）｜端点表与实例面（08/09）｜门户与暴露面（10/11）｜relay 内存（12）｜presence（13–16）｜内容分发（17）｜逐步拉起（18）｜抖动选路（19）｜候选数（21）｜退出不杀实例（22）｜组密钥加密（23）。

5. 应用场景

场景	匹配度	说明
MMORPG（2D/2.5D）/ MUD / 传奇类	⭐ 最匹配	核心简化：玩家之间不需要互联，中继按"服数"算；带宽每玩家 2–20 KB/s、jitter < 20 ms
群聊 + agent	⭐⭐ 高	扇出按预算定义分档（⛔ 不按人数拍脑袋）
静态资源分发（首屏包）	⭐⭐ 高	块级寻址 + 五档链 ⇒ 同一份资源全网只取一次（实测首屏包 11,363,655 B / 11 块）
备份 / 迁移提速	⭐⭐ 高	主备份用对象存储；跨机搬运走内容面
多机分布式观测 / 远程运维	⭐⭐ 高	presence ＋端点表＋探针 23 判据
跨异构网络接入（家宽 / 移动 / 企业网 / VPN）	⭐⭐ 高	拨出式设计 ⇒ 无需公网入口
⛔ 3D 强实时竞技	低	明确不在本线目标内

6. 性能与安全评估

6.1 性能（全部为本机 / 真机实测，附口径）

项	实测读数	口径 / 备注
加密开销	总墙钟 p50 22.636 → 42.782 ms、p95 23.020 → 43.599 ms（1.890× / 1.894×）；吞吐 502.02 → 265.62 MB/s；密文 +28 B/块	11,363,655 B / 11 块、n=11、单核、页缓存全热、两臂零回源 ⇒ 加密层自身成本，⛔ 非端到端承诺
轮换代价	冷启动回源 21,021,572 B = 4.0001 × 包 = 1 × 包/组；轮换后首轮同值、次轮 0；对照腿 0	4 组 × 4 节点夹具 ⇒ 轮换 = 一次完整冷启动
换址墙钟	总 30.7–34.1 s → 20.9–23.9 s（检测 15.0–16.6 s ＋首试 0.3–5.0 s ＋白等 12.02 → 0.09 s ＋建连 2.7–5.2 s）	真机 n=5＋n=5；`RELAY_FAILOVER_DEADLINE_MS` 30000 内侧 5/5
候选路径数	两条路径各 count=3 / hosts=3（判据 ≥ 2）	`OBS-21`
容量	`max=7515` / `used=2` / `free=7513` / 利用率 0%（软门 70%）	`OBS-02` / `OBS-20`
资源占用	relay RSS 65,432 KB（阈值 ≤ 800,000 KB）；`MEM_PER_HOST_MB = 0.06`（空闲会话斜率）	`OBS-12`；⚠️ 带流量时未测
presence 帧率	稳态 `Δpushed = 0`、在线态陈旧 p95 11,993 ms（阈值 ≤ 15,000）	`OBS-13` / `OBS-15`
零回归三件套	`npm test` 201/200/0/1 ｜演练 12 PASS / 0 FAIL ｜探针 23 PASS / 0 SKIP / 0 FAIL	2026-09-18 08:0x 复核

6.2 安全

项	状态	证据
中继看不到明文载荷	✅ 成立	组密钥 GCM；中继只见元数据（谁连谁、量多大）
内容不可推断	⚠️ 不成立	收敛加密对低熵必然泄露相等性（10,000 块 / 100 值域 ⇒ 仅 100 种密文）；⛔ 不写"很安全"
身份强制	✅	`identityRequired=true` / `trustedSigners=1` / 可吊销清单
密钥不经网络 / 不经 relay	✅	只走 `0600` 落文件＋ `scp`；凭据 274 B、逐字核不含密钥本体
签名固化	✅	`sign-group-key` 已落 47 两处正式路径（⛔ 不靠临时投放脚本）；篡改 epoch ⇒ `signature-mismatch rc=1`
明文不出现	✅	`plainScans=1` / `plainLeaks=0`（`OBS-23`）
暴露面零新增	✅	仅新增回环口；`nft` 多出 0；`OBS-11` 多出 0
权限只收窄	✅	全程零 `nft` / `nginx` 命令；密钥文件权限 `47=600 106=600`（错则失败关闭）
失败关闭	✅	组密钥装载六原因码具名：`no-file` / `bad-perms` / `parse-error` / `group-mismatch` / `bad-key` / `bad-epoch`
跨组隔离	✅	跨组在认证阶段被拒＋ `decryptRejected +1`；`crossGroupDenied` 语义未放松

7. 潜在风险

7.1 技术风险（已登记，附回头条件）

#	风险	影响	当前处置
1	低熵明文的相等性泄露	中继可观测内容重复率（非明文）	已定性量化；⛔ 不声称"很安全"；如需更强，须换非确定性加密（代价 = 放弃块共享）
2	轮换 = 一次全量回源 + 存储翻倍	旧 epoch 密文不自清（`storeBytes` 5,255,393 → 10,510,786）	回头条件 8：轮换必须约在发布窗口；旧块逐出时延未量化
3	relay 无 `MemoryMax`	只有软口径 `--max-hosts`；极端情况无 cgroup 硬顶	有意不动（加 cgroup ⇒ 新失败模式 OOM-kill，命中 R11）；`--max-hosts` 现为 7515、实测非绑定约束
4	孤儿端点条目不幂等自愈	重启 worker 后 `OBS-08`/`OBS-09` 必红，靠"重新登记同端口"覆盖	已留档；⛔ 不是"跑一会儿就好"
5	引导链缓存有 ≤ 300 s 收敛期	切兜底时最长 300 s 延迟	已把 300 s 收进参数表；⛔ 不改缓存结构
6	106 引导链不吃目录（agent 面）	`DSHS_RENDEZVOUS_URL` 被当 relay URL 直接用	只记录、⛔ 不顺手撤（撤掉 = 生产回归）
7	带流量内存开销未测	`MEM_PER_HOST_MB = 0.06` 只是空闲斜率；带流每条流最多 1 MB 缓冲	回头条件：`--max-hosts` 若重新收紧，必须先有本数
8	规模上来要自动分发组密钥	需新增 `x25519` 或 Ed25519→X25519 派生 ⇒ 属新增密钥类型	回头条件 7：停下报告、另立单；§10-5 预研未做

7.2 运维风险

#	风险	说明
1	密钥文件属主被改	本线有"属主被改 ⇒ 实例全崩"先例（R10）；密钥/用户目录权限须严格保持
2	106 nginx 归宝塔托管	若面板重建站点，需复查 `nginx -T
3	bwrap 版本异构	47 = 0.4.0 / 106 = 0.11.0 ⇒ `--perms` 属 0.5+，47 上用了 ⇒ 沙箱起不来 = 所有实例全挂；要权限用 `--tmpfs`
4	`--max-hosts` 的 env 陷阱	CLI 压 env ⇒ 只设 `Environment=` 会被静默忽略 ⇒ 必须 drop-in 重写 `ExecStart`（现 7515）
5	参数表值格必须纯数字	夹注 ⇒ `NaN` ⇒ 假红；探针 `cleanValue()` 会剥 `` ⇒ 白名单值 ⛔ 别写 `:443`
6	"没装"与"没采到"必须可分	`journalctl` 原文字节数 0 = 读取失败，⛔ 不等于"确无该行"
7	持久禁令	⛔ 不调 `RELAY_FAILOVER_DEADLINE_MS`｜⛔ 不动 `HB_SEC` / burst｜🔴 ⛔ 禁用 `COOLDOWN_MS=0`（实测 121–123 s 无切换）

7.3 安全边界（明确的能力上限，⛔ 不得越界声称）

组内成员互信：同一 (network, group) 的成员共享一把密钥 ⇒ 组内互相可见是设计前提；跨组隔离成立；
中继侧只减不增：中继只见元数据、不见明文；但可见性 ≠ 保密性（相等性泄露见 7.1-1）；
打洞未做：所有跨机流量在打洞失败后走中继 ⇒ 中继是可用性单点（已有 443 兜底＋ 3 条候选链缓解）；
跨境不设限：按用户口径，不做地域封禁 / 数据落地约束（合规由使用者自担）。

7.4 规模风险

中继按 45% 设计；百台画像推演：L1 10 / L2 30 / L3 需中继 40–55；对比全互联 4,950 条 vs 星型 100 条；
千台 × 11 场景推演中，瓶颈排序第一 = presence（已由序⑲ 落地验证）；
⚠️ 上述为推演值，⛔ 非实测；真实规模数据待上线后回归。

8. 附：证据与单一来源

项	位置
唯一入口（状态 / 下一步 / 关键决定 / 回滚点）	工作区根 `接续入口_覆盖网络线_20260916.md`
唯一参数表（输入参数 / 常量 / 观测阈值 / 待测 / 权限影响）	工作区根 `参数表_覆盖网络_20260917.md`（§10 指纹 `52e59df229102d5afa8c8bf01a960398`）
十份规划文档（归档 103–112）	`dsh-server-docs/04-调整方案/`
各序交接单（含执行回报 §8 全节）	工作区根 `交接单_.md` ＋ `dsh-server-docs/交接单/覆盖网络-序NN-.md`
观测探针（一条命令）	`scripts/overlay-probe.cjs --table "<参数表路径>"` ⇒ 23 判据 / 退出码 0-1-2
故障演练	`scripts/overlay-failover-drill.cjs --scene all --table "<参数表路径>"`
代码仓	`https://cnb.cool/maogeigei/dsh-shenxian`（镜像原仓 `work.alotbuy.com:maogeigei/dsh_shenxian.git`），HEAD `09ce76f`

⚠️ 报告生成时的核对基线：HEAD 09ce76f ｜探针 23P/0S/0F ｜归档号现核 130 ｜工作区日志 .workbuddy/memory/2026-09-18.md。

22 KiB Raw Blame History Unescape Escape