0 Fork 0

Files

T

build / build-and-scan (push) Canceled after 0s

Details

文档库：目录改为编号制（01-规范/02-架构设计/03-数据库/04-调整方案/
05-交接单/06-ops/07-scripts/08-skills/09-archive），顶层散文件归入 01-规范/；
INDEX.md 与 docs-manifest.json 重刷（档案 146 篇）；旧目录名引用全量对齐。

IM 线：src/im/**（SDK / hub / store / presence / ws / gateway-token）、
src/web/routes/im.ts、src/db/plugin-data/**、src/supervisor/plugin-assembly.ts
及对应 test/**。

插件线：poc/{im-agent-bridge,im-connection-gateway,im-conversation-tabs,
business-plugins-im,carbon-mcp-probe}、src/web/routes/{sessions,overlay-device}.ts、
src/net/relay/{device-grant,instance-credential}.ts。

仓库卫生：清出 40 个历史误入库 / 已改名文件（34 个交接单归档 + 6 个旧结构，
本地均有副本）；dsh-server-docs/.gitignore 补 tmp/；交接单不入库（政策）。

2026-09-24 07:25:16 +08:00

24 KiB

Raw Blame History

147 · 多节点形态下的插件投放与数据面（把「插件规模化」放回整张网里）

日期：2026-09-21
触发（用户原话）：「什么就 2-3 天做 A 档哪有这么复杂，方案还没做完整呢，其他节点上线后如何组成网（比如现在本机 ubuntu 就部署了一个服务）节点之间如何分工，其他节点的用户（服务器用户、windows 用户、移动用户）如何分发插件和连接数据库。看看这些都想到了吗」
上游：144（插件规模化投放 · §八可行性复核）｜119（集群化 Manager/Worker · 角色与数据分层）｜120（跨节点迁移与节点自举）｜103（客户端安装与覆盖网络互联 · 缺口 1–4）｜145（序47 会话并存与设备来源维度）｜覆盖网络线入口《接续入口_覆盖网络线_20260916.md》
状态：📋 方案（规划态 · 未实施）。本档零代码/零服务器改动；只做「把 144 的范围补成整张网」＋「逐条核对已想到 / 没想到」。
与前档的关系：不取代 144，而是修正 144 的范围口径并补它缺失的三问（组网 / 分工 / 分发与数据面）。

TL;DR

上一棒的错不在结论，在范围：144 §八判「A 档可行、2~3 天」时，默认了"所有用户都在 47 本机"。把整张网摊开看，A 档要落地还有一条今天完全不存在的承重墙：「控制面 → 某一台节点上的某一个用户」的投放通路。

🔴 本档最硬的一条实测结论（可复现）：今天的插件投放只能裝到"与 Manager 同机"的用户。 mine/apply 的 profileDir() / uidOf() / healOwnership() / runPnpmAs() 全是本机路径与本机 uid；跨机唯一那条腿 userFs.writeHandoff 是空转（DSHS_ENABLE_PATCH 默认 false ⇒ watchdog 不启动 ⇒ handoff.json 无人消费）。 ⇒ 「其他节点上的用户如何分发插件」这一问，今天的答案是没有通路，不是"慢"或"绕"。

✅ 组网与身份其实已经做完了，只是没进 144：节点一条命令接入（overlay-node-join.cjs）、准入邀请与网注册表（overlay-node-admit.cjs）、一机一钥（序③）、443/TCP 兜底（序④）、presence 在线态（序⑲）、设备台账与凭据（序47 · overlay_devices）。缺的是"接进网"与"被平台当节点托管实例"这两条路的衔接。

🔴 「连接数据库」这一问的正确答案不是"开 PG 端口"：控制面 PG 物理上只监听 127.0.0.1:15432、语义上只有 Manager 能写归属（119 §1.3）⇒ ⛔ 不给任何节点/设备发 PG 凭据。真正的缺口是 「实例/设备 → 控制面」的身份与数据 API = 0（145 §一已取证）—— 插件跨用户数据今天无路可走。

移动端：dsh 实例需要 Node 运行时 ⇒ 移动端只能做「壳」（远程访问某节点上的实例），插件分发实际发生在实例所在的那台节点上，移动端零分发动作。这条必须写死，否则会被反复重启讨论。

一、范围修正：上一棒的结论对，但尺子量错了

项	144 §八的口径	整张网下的口径
目标用户	默认"用户都在 47 本机"（`install-plugin-for-user.cjs` 的入参是 `--home` ＋ `--uid`，机器无关，但没有"怎么把动作送到那台机"这一层）	用户可能锚在 w-47 / w-106 / 未来节点 / 用户自己的 Windows 机上
成本	「2~3 天（含 PoC）」	这个数只覆盖"47 单机把共享层立起来"那一段；不是这条需求的总量
§8.7 建议	「范围压到最小：1 个插件 × 47 单机」	单机 PoC 仍值得做（验证 `resolveBundleDir` 与 ro 语义），但不能拿它当"这条需求快做完了"的证据

判据：方案不全时给总工期 = 用错误的尺子量。⇒ 本档不给总工期，只给按依赖排序的推进段（§六），并把每一段的前置是什么写清。

二、逐条回答用户的三问

2.1 「其他节点上线后如何组成网」

组网这件事，覆盖网络线已经做完了机制层，而且做的正是用户当初要的形态（原话：「b 要实现开启一台结点服务器，就能连上覆盖网络」）：

步	做什么	载体（已存在）
1	控制面签一张准入邀请（网络绑定＋有效期＋一次性 nonce，载荷无密钥）	`scripts/overlay-node-admit.cjs issue-invite`
2	节点一条命令接入（四步各打 `✓`/`✗`，失败具名、⛔ 零空 catch）	`scripts/overlay-node-join.cjs --network <网> --invite <json> --portal <控制面>/dshs-overlay/join`
3	控制面收单（验签＋原子占位 nonce）→ 批准 → 派生白名单	`overlay-node-admit.cjs apply / approve / derive`（`derive` 缺省只打印，`--apply` 才落盘）
4	节点拨出接入（无公网 IP 要求）＋目录候选链＋ 443/TCP 兜底＋打洞（`--direct` 可关）	主入口 `wss://ai1net.com/dshs-relay`（候选 3 条，序㊿）｜序④
5	一机一钥身份（`/etc/dshs/node.key` 0600，永不出机）＋信任根＋ relay 准入（`REQUIRE_IDENTITY` ＋ grant ＋ revocations）	序③ 已完成（交接单 `T16-一机一钥与信任根`）
6	在线态（订阅式推送＋ TTL 安全网，替代 5 s 轮询）	序⑲ 已上线（档案/单 `presence在线态`）

🔴 但这里有一条今天没接上的缝：

"接进网"（设备/节点身份） 与 "被平台当节点托管实例"（worker 角色） 是两条不同的路：
- 路 A（进网）：overlay-node-join ＋邀请＋一机一钥＋拨出 —— 面向设备/节点身份；
- 路 B（当 worker）：scripts/bootstrap-worker.sh（幂等：装 dsh 主程序 / dsh-runtime / 目录权限 711 / provisioner 单元 / 清旧角色残留）＋自检 doctor ＋ 注册进 dsh_hosts（capacity_mb / endpoint / via / network_id）；
- 两路之间没有"衔接件"：跑完路 A 的机器不会自动变成可被调度的 worker，跑完路 B 的机器也不会自动拿到设备身份。
⇒ 用户举的例子（本机 Ubuntu 起了个服务）恰好卡在这条缝上：它能进网、能有身份、能持续在线，但平台不会把它当"可以放实例的节点"，也不会知道往它那儿投插件。

"节点上线后如何组成网"的完整答案 = 三步（第 3 步是本档新提出的）： ① 进网（已有）→ ② 升格为执行体（已有 bootstrap-worker.sh ＋ dsh_hosts 注册，但需与 ① 串起来，且要补 120 §4 的 D1 自检缺口）→ ③ 🔴 被分配角色与配额（dsh_hosts.capacity_mb 由谁写、写多少；新用户按什么规则落过去）——今天是人工 scp ＋人工登库，属 144 §一硬伤①的同一个病根。

2.2 「节点之间如何分工」

现有的角色划分（119 §1.1/§1.2）已经清楚，问题是 144 没引用它：

角色	今天是谁	提供	⛔ 不提供
Manager（控制面）	47（单元 `dshs`，`127.0.0.1:3080`）	门户/认证/候选池/归属与租约（唯一写者）/代理出入口/控制面 PG	不 spawn 非本机实例；⛔ 不直写用户 home（必须走 `UserFs`）
Worker（执行体）	w-47(19100) / w-106(19000) / 未来节点	实例进程（bwrap ＋独立 uid ＋ systemd scope）、代理口、熔断/配额/探活（本地自管）、用户卷	不写归属；⛔ 不直连控制面 PG
中继（relay）	47 / 106（`dshs-relay` 独立单元，可独立部署）	双向可达性（wss / 443 / 打洞）、准入、per-port 并发额度	不碰业务数据
设备/客户端	浏览器 · 桌面壳 · 服务器实例（`.overlay-device.json` 凭据）	显示面 / 本地算力（客户端形态下跑 `soft` 档）	⛔ 不写归属；⛔ 不拿平台级凭据（103 缺口 3）

三条分工铁律（都是既有判据，144 需要在投放方案里遵守）：

归属/租约只有 Manager 能写（否则双写 = 脑裂）—— dsh_hosts / dsh_instances / overlay_devices / 插件开关台账全归 Manager。
跟着用户走的数据在实例 home；本机运维用的在 Worker 本地库（119 §1.3，⛔ 别再用"碰不碰 DB"判）。
🔴 插件内容源只有一个 = 控制面（候选池 tgz 在 Manager 的 dataRoot/business-plugins/）；其他节点上的只能是每机一份缓存。⇒ 谁也别想"各节点自己存一份插件池当第二真相源"。

本档要补的那一格分工（今天空白）："节点侧装配"这件事该谁做。

现状（mine/apply）：Manager 亲自在本机 pnpm（见 §三 · G1）⇒ 对非本机用户不成立。
建议：Manager 只发"该装什么"（清单＋版本＋内容热备），节点自己装配。理由：装配天然是"本机操作"（要写 node_modules、要 setpriv 降权、要停该 uid 的 scope），而这正是 install-plugin-for-user.cjs 已经做成机器无关原子动作的那一步 —— 把它搬到正确的那台机上执行即可。

2.3 「其他节点的用户（服务器用户 / Windows 用户 / 移动用户）如何分发插件和连接数据库」

(a) 插件分发 —— 统一模型：内容源（控制面唯一）→ 节点缓存（每机一份只读层）→ 每用户启用位（PG 台账）

用户形态	实例跑在哪	插件分发怎么落	今天的状态
服务器用户（实例锚 47/106）	平台自己的 Worker	控制面 → 该节点一份 `bundled-plugins/<pkg>/<ver>/`（缓存）＋每用户装配	🔴 不通（G1/G2：`mine/apply` 只能装本机用户；候选池 tgz 不出 Manager）
Windows 用户（客户端形态 B · 自带实例 · `soft` 档）	用户自己的机器	同一个模型：内容拉到该机 → 该机本地缓存 → 该机唯一那个用户装配	🔴 未设计。⚠️ 硬约束：一台客户端的实例只能属于该客户端主人（103 缺口 3）；⛔ 平台级共享密钥不得下发客户端
移动用户	不承载实例	零分发动作 —— 移动端只是"壳"（远程访问某节点上的实例），插件始终装在实例所在那台节点上	⚪ 形态未定义（全部档案里 `移动端` 只出现在覆盖网络的弱网讨论里，从未作为承载形态被定义过）

🔴 移动端这条要写死：dsh 实例需要 Node 运行时＋可写工作区＋（服务器侧）bwrap/uid/scope。手机（iOS/Android）不满足，也不该为它造一套隔离层。⇒ 移动用户 = 壳（浏览器或轻壳访问实例）， 它的"插件分发"退化成"实例所在节点的分发"，不要把它当成第三种分发目标。

(b) 连接数据库 —— 三档，且直连控制面 PG 一律不做

档	数据	落在哪	谁连	跨节点可达性
①	控制面数据（用户/会话/凭据/候选池/归属与租约/插件开关台账）	Manager 的 PG13（`127.0.0.1:15432`，只监听回环）	只有 Manager	🔴 物理上也不可达（只绑回环）＋语义上只有 Manager 能写 ⇒ ⛔ 不给任何节点/设备发 PG 凭据
②	插件 per-user 数据（`<home>/.dsh/<plugin>.db`）	实例 home（跟用户走，迁移时随 home 搬）	该实例自己	不需要网络：本地文件 ✓。⚠️ 平台侧要写必须走 `UserFs`（138 §五：直写 = 静默空操作）
③	插件跨用户 / 平台级数据（房间、榜单、聚合看板）	平台库 PG（插件前缀表＋内核 ACL），⛔ 插件不直连 DB（144 §6.3 / 142 §九）	经控制面 API 中转	🔴 今天没有这条通路：145 §一已取证本版平台不存在「实例 → 平台」的身份通道（`src/web/middleware/authn.ts:16-28` 只认 `sid` cookie；spawn 只投 `DSHS_*` ＋ `DEEPSEEK_API_KEY`）

⇒ 「其他节点的用户如何连接数据库」的正确答案：

不开放 PG。谁也不需要"连数据库"这个动作；
②类数据本来就不需要连（本地 SQLite，跟 home 走）；
🔴 ③类数据缺的是一条「实例/设备 → 控制面」的身份＋数据 API —— 这条同时服务服务器用户 / Windows 用户 / 移动用户的实例，是"数据库"这一问的真正承重墙，也是 序47 步 6–9 未做的那一半（平台侧代签实例凭据）。 ⇒ 建议：与序47 步 6–9 合批（同一套身份基建，别造两处判据）。

三、五条硬缺口（带可复现证据）

判据：每一条都能被第三方按 file:line 复现；⛔ 不写"我猜没有"。

G1 🔴 「控制面 → 某节点上的某用户」的投放通路 = 不存在（本档最硬一条）

mine/apply 全程本机：
- business-plugins.ts:436 profileDir() = join(userRoot(config.dataRoot, userId), 'home', 'profiles', 'web') ⇒ Manager 本机路径；
- :444 uidOf() = lstatSync(join(userRoot(...), 'home')).uid ⇒ Manager 本机 uid（用户不在本机 ⇒ ENOENT）；
- :454/:473 runPnpmAs() / healOwnership() 同样依赖上述两者；
- :635 安装 = runPnpmAs(user.id, ['add', 'file:' + plugin.tgzPath, …], dir) ⇒ 在 Manager 的 shell 里对 Manager 的盘跑 pnpm。
跨机唯一那条腿是空转：:649 await app.userFs.writeHandoff(user.id, …) 写的是 handoff.json，而它由 watchdog 消费，watchdog 需要 ENABLE_PATCH=true —— config.ts:405 DEFAULT_ENABLE_PATCH = false、 :666 线上取默认值 ⇒ 永不启动；routes/dsh.ts:149-157 原文即写「线上为 false → 永不启动，且 handoff.json 无人消费」。
⇒ 结论：这条通路不是"慢"或"绕"，是没有。144 §三 A 写的「跨机 = 每机一份（可由节点自举通道分发）」是没有实现的设想。

G2 🔴 插件内容（tgz）出不了 Manager

候选池 = <dataRoot>/business-plugins/*.tgz（business-plugins.ts:13、:305）；池记录里存的是 本机绝对路径 business_plugins.tgz_path（schema.ts:234-260，线上实测形如 /var/lib/dshs/business-plugins/_dsh-local_storyforge.tgz）。
bootstrap-worker.sh 装的是 dsh 主程序 / dsh-runtime / 目录权限 / provisioner 单元 —— ⛔ 不含业务插件内容。
⇒ "节点侧每机一份缓存"前置是：先有一条控制面 → 节点的内容分发通道（谁拉、按什么身份、如何对账完整性）。

G3 🔴 「实例/设备 → 控制面」的身份通道 = 0

取证在 145 §一（硬前置，规划棒已完成）：本版平台不存在该通道。
影响：③类数据（跨用户/平台级）无路可走；这条与"要不要做插件共享层"完全正交，但和"用户问的连数据库"是同一件事。

G4 🔴 A 档也逃不掉「跨机写用户 profile」

144 §8.4-① 把"写不到 <profile>/package.json"记成 B 档（用户自助开关）的限制 —— 这判断只对了一半：
- UserFs home 面白名单只有 3 个裸文件名（settings.yaml、.credentials.yaml、.overlay-device.json，src/fs/user-fs.ts:126）；
- A 档（共享只读层）同样要在用户所在那台机的 profile 里建软链 / 写 file: 清单（A1/A2 两种装配方案都如此，144 §8.5） ⇒ A 档一样受这条约束，只是它可以由节点自己在 spawn 前做（见 §四建议），而 B 档需要用户触发的写操作。
⇒ 修正：这条约束不是"A 档可以绕开"，而是"A 档必须换执行方"（谁在正确的那台机上动手）。

G5 ⚪ 形态差异从未进过投放方案

103 的缺口 2/3/4（节点身份=共享令牌要升级为每节点独立凭据｜ 信任模型反转：宿主机归用户 ⇒ 平台不得下发别人的实例/数据/平台级凭据｜分发与版本矩阵）在 144 里零出现；Windows 相关文档（127/128）与 144 无引用关系。
⇒ 只要"插件投放"这件事要覆盖 Windows 客户端，缺口 3 的两条硬约束必须先落码（实例只能属于机器主人＋共享密钥不下发客户端）。

四、节点侧装配：我选了什么（可推翻）

问题：G1/G4 说"要有人在那台机上动手"，但 ⛔ 不能给每个节点开一个入站管理口（R5：可见面只收窄）。

我选 A（可推翻）：复用既有的 POST /launch 投递面，把"该用户的插件清单"作为启动参数下发；装配由 Worker 在 spawn 前自己完成。

依据：agent 的 /launch 今天已经在投递 uid ＋ apiKey（119 §1.3 末段）——这条面是现成的、单向拨入的、最小接口白名单内的，再加一份"开关清单＋版本"不新增任何可见面。
客户端节点（Windows/桌面壳）同样成立：它也是"被 Manager 拨入的执行体"，走同一套。
A1/A2 装配都落在节点侧：Worker 在 spawn 前按清单在本机 node_modules 建软链（A1）或写 file: 依赖后跑一次轻量 pnpm（A2）。
排除的候选及理由：
- 给节点开入站管理口（新增可见面、NAT 后的客户端节点不可达）⇒ 违 R5 与 R11；
- 让节点直读控制面 PG 拿清单（119 §1.3：Worker ⛔ 不连控制面 PG）⇒ 职责越界。

五、与 144 的关系：哪些保留、哪些修正

144 的条目	本档判定
§一四处硬伤（本机枚举用户 / 无台账 / 每用户一份拷贝 / 契约静默失效）	✅ 全部保留，且 §一硬伤① 与本档 G1 是同一病根的两面
§二 `install-plugin-for-user.cjs`（机器无关原子动作）	✅ 保留，且升级为核心：它正是"节点侧装配"该复用的原子动作（缺的是"怎么被送到正确的那台机"）
§三 A（共享只读插件层）	✅ 方向成立；🔴 修正两处：① 「跨机由节点自举通道分发」= 未实现的设想（G2）② A 档也需要跨机通路（G4）
§三 B（用户自助开关）	⏸️ 仍不能开工（144 §8.4-① 成立），且要先解决"用户触发的写操作怎么落到那台机"
§三 C（PG 台账＋按 Worker 分组编排＋三态输出）	✅ 保留，且应最先做 —— 但必须带节点维度（台账里的 `worker_id` 方向正确，要落实）
§三 D（契约失效治理）	✅ 与节点数无关，保留
§六运行期数据落点（五问判据）	✅ 保留；本档 §2.3(b) 是它的可达性补充（落点对 ≠ 连得上）
§8.7「先做 1 插件 × 47 单机的最小 PoC」	🟡 仍值得做但降级为"技术验证"，⛔ 不能当"这条需求快做完了"的证据；单机 PoC 只回答"共享层能不能立住"，不回答"别的节点怎么用上"

六、推进顺序（按依赖，不承诺总工期）

段	内容	为什么在这一位	前置
S1	C1＋C2＋C3：PG 台账（带 `worker_id`）＋按节点分组编排＋三态输出（成功/失败/未达预期，⛔ 不把"跳过"混进成功）	与形态无关、当天见效；且它是后面每一步的"看得见"基础	无
S2	G1 ＋ G4 的通路：Manager 只发"该装什么"，装配由该用户所在节点在 spawn 前完成（§四选 A）	承重墙：A/B 两档都要它	S1（要知道"该装什么"）
S3	G2 内容分发：控制面 → 节点（节点带设备身份拉取，产物哈希清单对账）	共享层的"每机一份"要有内容才成立	S2（或并行，但 S2 先验证有收益）
S4	A 档共享层（每机一份只读层＋沙箱 `--ro-bind-try`）	形态根治	S2 ＋ S3
S5	G3 平台数据身份＋数据 API（实例/设备 → 控制面）	回答"连数据库"那一问；建议与序47 步 6–9 合批	与 S2–S4 正交
S6	B 档（用户自助开关）＋管理面版本分布＋契约版本协商	依赖 S4 立住	S4

🔴 S2 有一条"必须先验证"（照 144 §八的规矩，不许跳过）： /launch 面加一份清单参数后，**客户端形态（soft 档）与服务器形态（account 档）**是否都能在同一处装配逻辑下工作 —— 两档的 spawn 前钩子不同（account 要 setpriv 降权＋停 scope），别写成一个分支套另一个。

七、待拍板（每条都是真取舍；候选竖排成段）

1. 节点侧插件内容的分发通道形态

A · 节点主动拉取（控制面出只读端点＋节点带设备身份拉）优点：不新增任何入站口（符合 R5 只收窄）；复用既有的拨出通道与一机一钥设备身份；对 NAT 后的客户端节点也成立（唯一对三种节点类型都成立的方案）；产物哈希清单可对账。缺点：要给节点一份"能读产物"的凭据（需限定到"只能读它该装的那些包"），且要配额与审计。

B · 控制面推送（Manager 直接打到节点 agent）优点：与 agent 现成的最小接口一致；控制面掌握时序，实施最直接。缺点：客户端节点不可达（在用户家里、NAT 后）⇒ 对 Windows/移动形态不成立；需要节点有入站口。

C · 两路并存（服务器节点推送、客户端节点拉取）优点：各取所长。缺点：两套代码路径、两处判据（与仓库一贯的"单一判据"倾向相冲）；验证面翻倍。

▶ 倾向 A。

2. 插件跨用户 / 平台级数据的承载方式

A · 控制面 API（实例/设备身份＋表端点白名单）优点：与"插件不直连 DB"一致；可审计、可按插件前缀做 ACL；客户端形态也成立；不需要下发任何数据库凭据。缺点：要新建身份通道与 API 面（本档 S5），工作量最大；要定清楚"哪些表允许插件经它读写"。

B · 每节点本地 DB（数据不出机）优点：零新通道、最省。缺点：跨用户聚合（房间、榜单、运营看板）做不到；数据锁死在节点上，与"跟着用户迁移"冲突；各节点 schema 漂移无人对账。

C · 把 PG 开放给节点（凭据下发／只读副本）优点：插件可直接 SQL，开发最省。缺点：扩大暴露面且要下发数据库凭据；客户端形态绝对不可行（103 缺口 3：不得把平台级凭据发到用户掌控的机器）；与"归属只有 Manager 能写"的边界打架。