kirbylynx/dsh-hub

dsh-hub

语言：English | 简体中文

为多台机器上的 DSH（DeepSeek Harness） 实例提供多租户远程接入/控制中心。

DSH 默认只监听本机回环端口（127.0.0.1:3080），并有意拒绝 --host 0.0.0.0（防止把 agent 的 shell/文件能力暴露到网络）。dsh-hub 通过 注册 + 出站隧道 把这些实例接入一个公网中心，用户在中心经 Authelia 认证后，在一个门户里切换 namespace / 实例，并以整页实例入口作为可靠路径复用 DSH 原版 Web GUI；iframe 当前只保留为受限/实验入口。

┌──────────────────────────────────────────┐
用户浏览器             │  dsh-hub-service（公网，中心）            │
┌──────────┐  https     │                                          │
│  Portal   │ ────────▶ │  Authelia（边缘认证）                    │
└──────────┘            │     │                                    │
│ 整页入口 / iframe │     ▼                                    │
│ instA.hub...     │  HTTP+WS 反代 + 隧道中继                 │
└─────────────────▶│     │                                    │
│     ▼                                    │
│  注册表（namespace/instance/token）       │
└──────────────┬───────────────────────────┘
│ 出站 wss 隧道（实例→中心）
┌─────────────┴───────────────┐
│                             │
┌────────▼──────────┐         ┌────────▼──────────┐
│ dsh-hub-plugin    │         │ dsh-hub-client    │
│（DSH 进程内插件）  │         │（独立进程，npm）  │
│  ┌─ DSH web ──┐   │         │  ┌─ DSH web ──┐   │
│  │127.0.0.1:P │   │         │  │127.0.0.1:3080│  │
│  └────────────┘   │         │  └─────────────┘   │
└───────────────────┘         └────────────────────┘

- 星型拓扑：每台实例各自出站连接中心，无需公网端口、无需 P2P。
- 中心只做「注册 + 中继 + 门户 + 认证」，不理解 DSH 业务协议（字节透传）。
- 实例侧两种交付方式（plugin / client）共享同一份中继协议（见 docs/protocol.md）。

组件

| 组件 | 说明 | 状态 |
|---|---|---|
| dsh-hub-service | 中心服务：注册 / 隧道中继 / 门户 / 数据持久化（SQLite），直接运行（node）或 docker-compose（Caddy + Authelia + LLDAP / existing Caddy 后端模式）；v0.1.x 基线包含内部 loopback Prometheus /metrics、tunnel 级未确认字节总账、高/低水位发送门控、公平 sender 调度、本地背压检查、release 运行手册、history relay 保护、deploymentMode 元数据、基于 LLDAP 的邀请注册、namespace 角色、管理员用户控制、namespace/user/admin-console 管理、成员管理、邀请管理、registry key 展示/更新、实例 ACL、基于 LLDAP 的自助修改密码、system-admin 重置他人密码和审计 API | v0.1.7 release 基线，可受信自托管试用 |
| dsh-hub-plugin | 实例侧交付 A：DSH 进程内插件；已具备默认关闭的 host 插件骨架、显式 remote-capabilities.patch.yml、DSH browse picker overlay、hosted /workspace 限制 picker overlay、dsh.client browser card、plugin tunnel adapter、registry/replacement 入伙、instance credentials 存储、自动建连、token rotate/leave、host/browser 状态视图、本地 DSH session/workspace 诊断摘要、同源 live status bridge、remote-origin-gated history autoload、host.describe.canOpenPath=false UI gating、面向 DeepSeek 官方与 OpenAI-compatible/custom Base URL provider 的 hosted 模型设置、dsh-hub-web 一行启动、只读安装检查、默认 dry-run profile 安装器和 plugin 入伙 CLI | v0.1.7 推荐主路径 |
| dsh-hub-client | 实例侧交付 B：独立进程，join / run / status，可跨 DSH 重启保隧道；新增 plugin-install-check / plugin-install / plugin-join / dsh-hub-web 用于检查、安装、入伙和启动 DSH plugin，并包含 deployment mode 元数据、实例侧 history 请求下压、响应瘦身、raw/final byte cap 与脱敏诊断；定位为试用、链路诊断、应急 fallback 和 plugin 启动辅助 | v0.1.7 fallback/辅助路径 |

术语：namespace 是用户用于组织实例的逻辑分组，可通过 membership 共享访问；registry key 是 namespace 级入伙凭据，具备权限的 namespace 管理者可以展示、复制或更新；instance token 是实例级连接凭据，可轮换/吊销。

快速开始（M1：service + client 直接运行）

前置：Node.js ≥ 22（本项目在 Node 24 上开发验证）。

1. 安装依赖
npm install

2. 启动中心服务（默认 127.0.0.1:8081，数据落在 ./data/hub.db）
DEV_AUTH_USER=dev 仅用于本地开发：模拟 Authelia 认证通过的用户；
生产环境必须在前面挂 Authelia（见 docs/plans/...-design.md §7）。
DEV_AUTH_USER=dev node packages/dsh-hub-service/bin/dsh-hub-service.js --port 8081

3. 另开终端：实例侧 agent 入伙（交互式录入 endpoint 与 registry key，
凭据写入本机 Keychain / 0600 文件）
node packages/dsh-hub-client/bin/dsh-hub-client.js join \
--endpoint http://127.0.0.1:8081 --registry-key

4. 运行隧道（把本地 127.0.0.1:3080 的 DSH Web 转发到中心）
node packages/dsh-hub-client/bin/dsh-hub-client.js run

5. 可选：采集 M2 只读兼容诊断（session/workspace/events/目录选择器推断）
node packages/dsh-hub-client/bin/dsh-hub-client.js diagnose --json

6. 浏览器打开门户 http://127.0.0.1:8081/ ，进入实例子域
http://.localhost:8081/   （本地开发用 .localhost 解析回环）

Plugin 远程模式安装、入伙和一行启动（M4D-7B）

dsh-hub-web 是 dsh web 的安全包装：不保存 registry key / replacement grant / instance token；它只在启动时应用 plugin enabled patch 与显式 remote-capabilities.patch.yml，用于远程 browse picker 与 canOpenPath=false UI gating。plugin-install 默认只做 dry-run，必须显式 --apply 才会写 DSH profile；如使用 --enabled-patch 自定义文件名，路径也必须留在所选 profile 目录内。

只读检查本机 DSH web profile 是否已装 plugin/overlay/凭据
dsh-hub-client plugin-install-check

预览安装：不写 ~/.dsh
dsh-hub-client plugin-install \
--endpoint https://control.hub.example.com --namespace my-team

确认安装：写入 profile package、本地 plugin symlink 和非秘密 enabled patch
dsh-hub-client plugin-install \
--endpoint https://control.hub.example.com --namespace my-team --apply

推荐从 stdin 或交互提示输入 registry key，避免进入 shell history
printf '%s' "$DSH_HUB_REGISTRY_KEY" | dsh-hub-client plugin-join \
--endpoint https://control.hub.example.com --registry-key-stdin

启动远程 plugin 模式
dsh-hub-web

v0.1.7 release 基线保留 v0.1.2 已验证的大会话历史加载路径、v0.1.3 hosted 模型/provider 设置面板和 v0.1.4 生产发布卫生文档，建立在 v0.1.5 LLDAP 多用户基线与 v0.1.6 G3 namespace/admin console 之上，并新增 G15 LLDAP 密码管理：用户输入当前密码后可自助修改自己的密码，system admin 可在填写审计原因后重置其他 Hub 用户密码。用户仍可以创建和编辑自己的 namespace，system admin 可以为 active user 创建 namespace，具备权限的 namespace 管理者可以展示/复制或更新当前 registry key，实例生命周期/诊断操作进入审计。实例侧 registry key / replacement grant 仍建议通过 stdin 或交互输入。

首次使用：创建 namespace 与 registry key

中心侧（需要 DEV_AUTH_USER 或 Authelia 认证上下文）创建 namespace
curl -H 'x-authenticated-user: dev' http://127.0.0.1:8081/api/namespaces \
-d '{"name":"my-team"}'
→ 返回 { "namespace": {...}, "registryKey": "dhk_..." }

安全模型（重要，v1 的唯一安全边界）

中心认证 = 唯一安全边界。 经中心转发后，请求对 DSH 而言与「本机浏览器」无异（实例侧会把 Host 改写为 127.0.0.1、剥离 Origin / sec-fetch- 头以通过 DSH 的 Host 围栏，包括特权方法）。因此：

- 任何「绕过中心认证直接触达实例」的路径都必须被堵死：实例只从出站隧道接收转发，无其它入站。
- 用户 → namespace → 实例的 ACL 由中心强制执行。
- 部署模板中 Authelia 使用 LLDAP 作为身份后端；Hub 保存授权元数据，并把邀请注册用户写入 LLDAP。
- Authelia 的域规则必须覆盖所有实例子域（.hub.example.com），防止用户绕过门户直连实例。
- instance token 支持吊销，吊销即断隧道；registry key 支持轮换。
- 全链路 TLS（https + wss），实例侧校验中心证书（防中间人）。

一实例一子域是硬约束：DSH 前端把 API 基址硬编码为 location.origin + "/api/..."，不支持子路径部署，因此每个实例挂在独立子域 .hub.example.com 根路径下（本地开发用 .localhost）。

里程碑

- M1A/M1B：安全/凭据/协议/有界中继已完成并复审通过。
- M1C：DSH 核心 HTTP/WS 和整页实例入口兼容基线已通过；iframe、停启恢复、聊天/工具/附件长链路和 npm latest/next 仍待补测。
- M2：部署模板基线；支持全栈 compose 和 existing-Caddy 后端模式。新增 dsh-hub-client diagnose 与 npm run test:m2:compat，可重复采集 session/workspace/events/目录选择器推断、stale workspace session 和 SQLite 备份恢复证据。公开仓库只保留通用模板；实际域名、服务器地址和部署证据应放在使用者自己的私有运维 overlay。
- M3A：最小远程兼容诊断已落地；Portal 提供按实例“诊断”按钮，GET /api/instances/:id/diagnostics 通过在线 tunnel 只读探测 DSH API/WS，解释 relay、session.list、workspace.list、未挂接/stale session、events 和 host capability 问题；返回值不含 workspace 本机路径/请求体/凭据，最多包含有界 session ID 样本用于定位映射问题，为 M4 plugin 提供输入。
- M4：plugin-first 远程体验主路径已达到 v0.1.0 MVP 收口口径；远程 DSH Web UI、plugin tunnel、browse picker、状态卡片、session/workspace 诊断和 canOpenPath=false UI gating 已完成基础验证。remote openPath 替代 UI 不在 v0.1.0。
- M3B：可运维性基线已达到 v0.1.0 MVP 收口口径，包括内部 metrics、告警规则示例、运行手册、本地恢复/回滚演练、日志轮转和脱敏。长时压测、真实部署恢复/升级/回滚实战演练、Alertmanager 接收人配置和故障演练进入后续生产化阶段。
- v0.1.0：MVP 已收口，详见 docs/releases/v0.1.0.zh.md。
- v0.1.1：新增实验性的手工托管 DSH 容器基线，详见 docs/releases/v0.1.1.zh.md。
- v0.1.2：新增大会话历史加载基线；实例侧 history 请求会被下压，已结算 chunk 在离开实例前瘦身，浏览器自动加载只在远程 origin 启用，错误分类不记录 payload 内容，详见 docs/releases/v0.1.2.zh.md。
- v0.1.3：hosted DSH 实例可上报 deploymentMode=hosted，plugin browser card 提供窄面的同源模型/provider 设置面板，支持 DeepSeek 官方和 OpenAI-compatible/custom Base URL provider。API key 只写入 hosted DSH 的本地 credential store，不写入 Hub service 数据库，详见 docs/releases/v0.1.3.zh.md。
- v0.1.4：补齐自托管生产发布卫生，包括生产检查清单、release/tag/deploy 指南、SQLite 备份验证和 existing-Caddy 共存指南，详见 docs/releases/v0.1.4.zh.md。
- v0.1.5：新增第一版基于 LLDAP 的多用户基线，包括邀请注册、namespace 角色、轻量管理员 Portal、实例 ACL 和审计 API，详见 docs/releases/v0.1.5.zh.md。
- v0.1.6：新增第一版 G3 namespace/admin console 基线，包括 namespace 创建/编辑/列表、用户归属 namespace 语义、registry key 展示/复制/更新、replacement grant、实例吊销/恢复、诊断、通用分页和可审计管理写操作，详见 docs/releases/v0.1.6.zh.md。
- v0.1.7：G15 基于 LLDAP 新增密码管理，包括用户自助修改密码、system admin 重置其他用户密码、统一 Hub 密码策略、密码变更元数据、可审计密码写操作和稳定的 password idempotency fingerprint key，详见 docs/releases/v0.1.7.zh.md。
- 后续：公开路线见 docs/ROADMAP.zh.md；继续推进多用户权限、管理员界面和 Portal 侧 hosted 模型管理。当前限制见 docs/KNOWN-LIMITATIONS.zh.md。

v0.1.7 仍不包含：敌对租户 SaaS 级隔离、邮件找回密码、Portal 侧模型管理、托管实例池自动分配、team-owned namespace、namespace 归属转移/删除、批量管理操作、无头控制 API、用户级会话隔离、P2P、多实例聚合、remote openPath 替代 UI、生产长时压测报告、真实告警接收人配置或真实回滚演练。

文档

每个 Markdown 文档都有同名 *.zh.md 简体中文版，并在文档头部提供语言切换链接。

- docs/ROADMAP.zh.md — v0.1.7 后公开路线图
- docs/KNOWN-LIMITATIONS.zh.md — v0.1.x 已知限制
- docs/releases/v0.1.0.zh.md — v0.1.0 MVP 收口文档
- docs/releases/v0.1.1.zh.md — v0.1.1 托管 DSH 收口文档
- docs/releases/v0.1.2.zh.md — v0.1.2 大会话历史加载收口文档
- docs/releases/v0.1.3.zh.md — v0.1.3 hosted 模型/provider 设置收口文档
- docs/releases/v0.1.4.zh.md — v0.1.4 生产发布卫生说明
- docs/releases/v0.1.5.zh.md — v0.1.5 多用户权限和 LLDAP 邀请基线
- docs/releases/v0.1.6.zh.md — v0.1.6 namespace/admin console 基线
- docs/plans/20260821-v0.1.0-requirements.zh.md — v0.1.0 MVP 需求文档
- docs/plans/20260821-v0.1.0-design.zh.md — v0.1.0 MVP 设计文档
- docs/plans/20260821-v0.1.0-implementation-plan.zh.md — v0.1.0 MVP 实施计划
- docs/protocol.zh.md — 中继协议
- deploy/m3-observability/README.zh.md — M3 告警规则与本地校验说明
- deploy/m3-recovery/README.zh.md — M3 本地恢复/回滚演练校验说明
- deploy/hosted-dsh/README.zh.md — 实验性的手工托管 DSH 容器模板，包含 /workspace 限制目录选择器

运维与自托管指南

如果你准备自托管 dsh-hub，建议先读这三份公开指南；它们是模板和安全边界说明，不包含任何真实环境部署证据：

- docs/ops/m3-runbook.zh.md — 告警响应与运行手册，说明 /metrics 内部采集、告警含义和排查顺序。
- docs/ops/m3-recovery-runbook.zh.md — SQLite 备份、恢复、升级和回滚指南，强调一致性备份和覆盖恢复前置条件。
- docs/ops/m3-log-retention.zh.md — Docker 日志轮转与脱敏指南，说明哪些内容不能进入日志、issue 或工单。
- docs/ops/production-checklist.zh.md — 自托管生产就绪检查清单。
- docs/ops/release-runbook.zh.md — release、deploy、verify、closeout 和 tag 流程。
- docs/ops/sqlite-backup-restore.zh.md — SQLite 备份和非破坏性恢复验证指南。
- docs/ops/existing-caddy-coexistence.zh.md — existing-Caddy 共存和校验指南。
- deploy/hosted-dsh/README.zh.md — 实验性的手工托管 DSH 容器模板，包含 /workspace 限制目录选择器；真实 VPS 证据和私有配置应保存在 private overlay。

License

MIT License. See LICENSE.