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）。

组件

术语：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 <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://<instanceId>.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/..."，不支持子路径部署，因此每个实例挂在独立子域 <instanceId>.hub.example.com 根路径下（本地开发用 <instanceId>.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.