前言¶

DeepSeek Harness（DSH）的 dsh web 默認面向本機瀏覽器：工作區選擇會彈出宿主機原生目錄框，若干特權 API（host.pickDirectory、settings.*、credentials.* 等）被官方硬編碼限制在 loopback，文檔裏也寫明「直到真正的認證層出現」。若要把 DSH 經 nginx、SSH 隧道、Tailscale 或 Frp 暴露到局域網或外網，遠程用戶既看不到原生選擇框，也無法在未認證情況下安全使用這些接口。

@xgone/dsh-remote（GitHub：xgone/dsh-remote）正是針對這一缺口：在 dsh web 前增加賬號密碼登錄、MFA（TOTP）門禁、簽名會話 Cookie 與角色權限，並把目錄選擇改爲瀏覽器內對話框。認證通過後自動放行 DSH 原本僅限本機的特權路徑，全程不在宿主機彈出原生窗口。

這是什麼¶

@xgone/dsh-remote 由維護者 xgone 發佈，分類爲 admin-security，MIT 許可證。npm 當前版本爲 0.2.8。GitHub 倉庫約 42 stars、2 forks。

一句話定位：讓 DeepSeek Harness 可以被安全地遠程訪問——外網或局域網瀏覽器登錄後即可使用完整 Web 功能，包括工作區選擇與賬號管理。

核心功能¶

遠程訪問與 DSH 特權放行¶

經反向代理或隧道暴露後，外部瀏覽器登錄即可使用全部功能。插件作爲認證層，認證通過後自動放行 DSH /api 中原本釘死在 loopback 的特權方法。

WebSocket 事件流（events.mux / events.host）在會話有效時正常建立。

瀏覽器內目錄選擇¶

DSH 默認目錄選擇器在 loopback 部署下會調用宿主機 OS 選擇框，遠程用戶無法操作。本插件用 browse 後端替換：選擇或新建工作區變爲瀏覽器內雙欄目錄視圖，帶麪包屑與新建文件夾，不彈宿主窗口。

賬號密碼與登錄門禁¶

未登錄訪問任意路徑均返回自包含登錄頁；/api 與 WebSocket 全部要求有效會話 Cookie。

會話採用 HMAC-SHA256 簽名的 HttpOnly Cookie，可配置過期時間、Secure、SameSite；簽名密鑰隨機生成並持久化，重啓後會話仍有效。

密碼以 scrypt 哈希存儲（N=16384,r=8,p=1），配合常量時間比較，不落盤明文。登錄失敗按「IP + 用戶名」限速，默認 15 分鐘窗口內 5 次。

首次無賬號時，登錄頁提供「創建首個管理員」，僅本機 loopback 可提交，防止遠程搶先註冊。根賬號不可刪除、不可改角色，只能重置密碼。默認 adminOnly 模式禁止新建賬號、強制 admin 角色；關閉後可啓用 admin / user / guest 三層方法級權限。

MFA 兩步驗證（TOTP）¶

兼容 Google Authenticator、1Password、Authy 等標準認證器（RFC 6238，6 位 / 30 秒）。開啓時展示二維碼（SVG）、手動密鑰、otpauth 鏈接與 10 個一次性備用碼（備用碼僅存 SHA-256 哈希）。登錄頁顯示動態碼剩餘秒數倒計時，輸入滿 6 位自動驗證；備用碼含字母時需手動確認。管理員可用自己的密碼爲任意賬號禁用 MFA。

設置頁與體驗細節¶

設置 → 登錄與賬號：MFA 自服務、賬號列表、重置密碼、退出登錄。會話過期時 SPA 內出現全屏重登浮層。

界面通過 DSH 官方設計令牌（--dsw-alias-*）取色，自動跟隨淺色 / 深色 / 跟隨系統。登錄頁、MFA 引導、重登浮層、設置頁均提供中英雙語，跟隨 DSH 應用語言設置；遠程瀏覽器下插件還接管語言偏好的讀寫通道，經標準 settings.describe / settings.mutate RPC 與 settings.yaml 同步。

較新版本還修復了遠程場景下插件配置頁空白、歡迎彈窗反覆出現、模型頁「settings are unavailable」等問題（README 中分別標註 v0.1.5+、v0.1.6+、v0.2.6+）。

安裝與啓用¶

前置條件¶

1. 已安裝 DeepSeek Harness，可運行 dsh web（默認端口 3080）；
2. 已初始化 web profile（首次運行 dsh web 會自動初始化）；
3. 系統 PATH 中有 pnpm（dsh plugin 管理 profile 插件時需要）。

安裝插件¶

NPM 安裝（推薦）：

dsh plugin --profile web add @xgone/dsh-remote

固定版本示例：

dsh plugin --profile web add @xgone/dsh-remote@0.1.0

也可從 Git 或本地目錄安裝：

dsh plugin --profile web add git@github.com:xgone/dsh-remote.git
dsh plugin --profile web add ~/path/to/dsh-remote

dsh plugin 會在 ~/.dsh/profiles/web/ 下用 pnpm 安裝包，並自動把 @xgone/dsh-remote 追加到 profile 的 dsh.profile.bundles，無需手動改 bundles 列表。

確認安裝並重啓¶

python3 -c "import json; print(json.load(open('$HOME/.dsh/profiles/web/package.json'))['dsh']['profile']['bundles'])"

期望輸出類似：['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app', '@xgone/dsh-remote']。

Web 表面禁用 HMR，必須重啓 dsh web 才生效：

dsh web

首次創建管理員¶

重啓後瀏覽器打開 http://127.0.0.1:3080：

1. 未登錄會看到登錄頁；
2. 無賬號時進入引導模式，標題爲「創建首個管理員賬號」；
3. 輸入用戶名與至少 6 位密碼，點擊創建——僅限本機 loopback 提交；
4. 創建成功即登錄並簽發會話 Cookie。

驗證：

curl http://127.0.0.1:3080/auth/me

應返回含 authEnabled、authenticated 等字段的 JSON。

無瀏覽器服務器（headless）¶

無法在本機瀏覽器完成引導時，可在 ~/.dsh/profiles/web/cordis.patch.yml 中預置首個管理員（賬號庫爲空時生效，冪等）：

- id: remote
  config:
    enabled: true
    bootstrap:
      username: admin
      password: '換成一個強密碼'

首次登錄後建議從配置中移除 bootstrap 節；反向代理部署通常還需 trustProxy: true（默認已開啓）。

卸載¶

dsh plugin --profile web remove @xgone/dsh-remote

重啓 dsh web 後門禁消失。$DSH_HOME/auth/store.json 會保留，需徹底清除可手動刪除。

典型用法¶

綁定 MFA¶

登錄後進入設置 → 登錄與賬號 → 雙重驗證 (MFA) → 啓用雙重驗證：

1. 掃碼或手動輸入密鑰，保存 10 個一次性備用碼；
2. 在認證器中輸入當前 6 位動態碼，自動驗證並啓用；
3. 之後每次登錄需密碼 + 動態碼（或備用碼）。

也可在登錄頁密碼驗證通過後，按引導就地綁定 MFA。

遠程暴露¶

將 dsh web 經 nginx、SSH 隧道（ssh -L）、Tailscale 或 Frp 暴露後，遠程瀏覽器訪問同一入口 URL，先過登錄門禁，再正常使用工作區選擇與 API。HTTPS 部署時建議在 cordis.patch.yml 將 session.secure 設爲 true。

主要配置項¶

編輯 ~/.dsh/profiles/web/cordis.patch.yml 中 remote 行的 config：

- id: remote
  config:
    enabled: true
    session:
      cookieName: dsh_session
      ttlSeconds: 604800
      secure: false
      sameSite: lax
    enforceRoles: true
    adminOnly: true
    trustProxy: true
    mfa:
      enabled: true
      issuer: DeepSeek Harness
      window: 1
      backupCodes: 10
    rateLimit:
      maxAttempts: 5
      windowMs: 900000

緊急旁路：設 enabled: false 重啓，或刪除 $DSH_HOME/auth/store.json 重新引導。忘記 MFA 時由管理員在設置頁爲該賬號禁用 MFA（需管理員密碼）。

適用場景與注意¶

適合需要把 DSH Web 安全暴露到非本機瀏覽器的開發者：遠程辦公、內網穿透、無圖形界面服務器上的 headless 部署等。

插件以當前 dsh 進程權限運行，安裝前應閱讀 GitHub 源碼 與 MIT 許可證，確認符合你的安全策略。創建首個管理員僅限 loopback，是爲防止公網搶先註冊；公網暴露前務必完成賬號創建並建議啓用 MFA。

DSH 生態理念是「一切皆插件」；SkillHub 等社區目錄爲獨立站點，與 DeepSeek / 幻方無官方從屬關係。@xgone/dsh-remote 是社區維護的 admin-security 類插件，不是 DSH 內置組件。

鏈接¶

• 目錄頁：https://www.skillhub.cn/plugins/xgone/dsh-remote
• GitHub：https://github.com/xgone/dsh-remote
• npm：https://www.npmjs.com/package/@xgone/dsh-remote