前言¶

DeepSeek Harness 的扩展思路是「一切皆插件」；插件目录是独立站点，不等同于 DeepSeek 或幻方官方应用商店。

一个常见场景是：DSH Web 本应在本机 loopback 上运行，运维人员希望通过 HTTPS 从浏览器访问，但不希望页面、API、下载、SSE、WebSocket 在未登录状态下直接暴露。dsh-auth 是针对 DeepSeek Harness 的非官方社区插件，用于给 DSH Web 增加管理员登录。它由 hxy91819 维护，核心做法是让 Harness 保持在 loopback，再安装一个项目持有的 Caddy forward_auth edge 来统一做登录校验。

这是什么¶

dsh-auth 是 DeepSeek Harness 的社区插件，用于给 DSH Web app 增加 secure administrator login。

• GitHub 仓库：https://github.com/hxy91819/dsh-auth
• package.json 中版本：0.2.3
• README 提供精确版本安装：dsh-auth@0.2.3
• 许可证类型在本次资料中未确认；资料中只出现 LICENSE 文件和 license badge。

核心能力¶

下面介绍已核实的 dsh-auth 能力：

• 让 Harness 保持在 loopback，并安装项目持有的 Caddy forward_auth edge，覆盖 pages、APIs、downloads、SSE、WebSockets。
• 提供 interactive setup、plan preview 和 non-interactive JSON setup。
• 支持通过 password 或 login-token 进行管理员初始化。
• Password source 会经过 Argon2id hash，不以 plaintext 存储。
• 支持 HTTPS，并支持 automatic 或 manual TLS；automatic TLS 是 HTTPS default。
• 复制 checksum-verified 的 bundled Caddy binary，并启用独立的 dsh-auth-caddy.service。
• 支持可选的中文和英文 token-failure 页面文案。
• 支持 --behind-tls-proxy，用于保持 managed HTTP edge 在 loopback、要求可信 HTTPS forwarding headers，并 issue Secure cookies。

安装与启用¶

插件预安装不等于启用认证¶

先执行下面的命令，将 dsh-auth bundle 添加到 DSH Web profile：

dsh plugin --profile web add dsh-auth

这一步只增加 bundle，不等于已经启用认证。插件命令不会创建 secrets、不会安装 Caddy、也不会保护任何内容。启用认证仍需全局安装 CLI 并运行 sudo dsh-auth setup。

安装 CLI¶

安装当前稳定版 CLI：

sudo npm install -g dsh-auth

如果你需要按供应链策略锁定版本，可以安装 README 中给出的精确版本：

sudo npm install -g dsh-auth@0.2.3

运行 setup¶

正常部署需要 Linux x64 或 ARM64、systemd、Node.js 24.7 或更高版本，以及 DSH Web 0.1.0-rc.7。

运行交互式 setup：

sudo dsh-auth setup

交互式安装会要求确认 DSH service、管理员初始化方式、HTTPS hostname 和 TLS mode；它会先展示 secret-free plan，并在你输入确认值后才修改系统。setup 会安装 pinned bundle、复制 checksum-verified Caddy binary、写入权限受限的 authentication state，并启用 dsh-auth-caddy.service。它不会存储 plaintext password，也不会在 setup 时下载 Caddy。

先查看 plan¶

在执行 setup 前，可以用 plan 查看同样的 typed plan。它不会读取密码，也不会改变文件系统：

sudo dsh-auth plan

查看帮助与版本¶

可以打印 usage 和 CLI 版本：

dsh-auth --help
dsh-auth --version

典型用法¶

交互式 password 初始化¶

安装 CLI 后，从已有 DSH Web systemd service 开始 setup。示例如下：

sudo npm install -g dsh-auth
sudo dsh-auth setup

下面是 README 中的交互示例，省略了实际密码输入：

$ sudo dsh-auth setup
Existing DSH Web systemd unit: dsh-web.service
Administrator initialization (password/login-token): password
Login tokens (enabled/disabled) [disabled]: enabled
Administrator username: operator
Edge mode (https/http) [https]:
TLS (automatic/manual) [automatic]:
Public HTTPS hostname: harness.example.com
...
Type install to apply this exact plan: install
dsh-auth setup completed successfully.

非交互 JSON + password 初始化¶

非交互模式要求显式给出 administrator initialization method。使用 password 初始化时，需要把 plaintext password 作为平台提供的 temporary 0600 secret file 挂载；dsh-auth 只读取一次，用于创建 Argon2id hash，不会复制 plaintext。

下面的示例是完整的 HTTPS system install，使用 password initialization 和 automatic TLS：

sudo dsh-auth setup \
  --non-interactive \
  --json \
  --dsh-service dsh-web.service \
  --dsh-home /var/lib/dsh \
  --dsh-executable /usr/local/bin/dsh \
  --profile web \
  --admin-bootstrap password \
  --admin-username operator \
  --login-token enabled \
  --password-file /run/secrets/dsh-auth-password \
  --mode https \
  --tls automatic \
  --upstream 127.0.0.1:3080 \
  --listen-address 0.0.0.0 \
  --server-name harness.example.com

非交互 JSON + login-token 初始化¶

使用 login-token 初始化时，不传 password 和 username；第一个授权用户可以在浏览器中设置，或选择 Later：

sudo dsh-auth setup \
  --non-interactive \
  --json \
  --dsh-service dsh-web.service \
  --admin-bootstrap login-token \
  --login-token enabled \
  --mode https \
  --tls automatic \
  --server-name harness.example.com

常用参数¶

以下参数来自 README 示例与说明，完整参数仍以仓库文档为准。

• --mode：选择 https 或 http，默认 https。
• --tls：选择 automatic 或 manual，默认 automatic。
• --server-name：Public HTTPS hostname，--mode https 时需要。
• --admin-bootstrap：非交互时选择 password 或 login-token。
• --admin-username：password setup 时的初始管理员登录名。
• --login-token：非交互时选择 enabled 或 disabled；token initialization 需要 enabled。
• --listen-address：Literal IP bind address；HTTP 仍需显式 private 或 loopback address。
• --behind-tls-proxy：保持 managed HTTP edge 在 loopback，要求 trusted HTTPS forwarding headers，并 issue Secure cookies。
• --login-token-error-message-zh / --login-token-error-message-en：可选的 token-failure 页面文案，需要 --login-token enabled。
• --certificate / --certificate-key：manual TLS 时使用的 certificate 和 private key 绝对路径。

升级、幂等与限制¶

• Version 0.2.0 是从 legacy v1 deployments 的 breaking upgrade；previous installer flags、Nginx-managed installations、old sessions 不会被迁移。
• 按 README 描述的 breaking upgrade path，需要先卸载 previous installation，再运行 setup。
• 重复执行相同命令是幂等的；已有 managed installation 如果非密配置相同，会报告 unchanged。
• 不同 settings，或没有 ownership record 的文件，会被拒绝而不是覆盖。
• 部分配置缺失时，系统会 fail loudly，而不是带着不完整配置 boot。
• HTTP 模式仍然要求 explicit private 或 loopback address。

适用场景与注意¶

dsh-auth 适合这类部署：

• 已有 DSH Web systemd service，例如 dsh-web.service。
• DSH Web upstream 只在 loopback 监听。
• 需要通过 HTTPS 暴露 Web，并增加管理员登录。
• 需要 Caddy forward_auth edge 同时覆盖 pages、APIs、downloads、SSE、WebSockets。
• 希望通过 password 或 login-token 初始化管理员，并希望避免 plaintext password 长期存储。

启用前需要注意：

• dsh plugin --profile web add dsh-auth 只是预安装 bundle，不等于启用认证。
• sudo dsh-auth setup 会修改主机系统，包括安装 pinned bundle、复制 Caddy binary、写入 authentication state、启用 dsh-auth-caddy.service。
• 插件内容以当前 dsh 进程权限运行；安装前应检查源码与许可证。
• 许可证类型在本次资料中未确认，只看到 LICENSE 文件和 license badge；请自行确认后再部署。
• 本文不采用未确认的信息，例如目录页 URL、分类、星标数、fork 数、revocable sessions、bilingual UI 等。

链接¶

• GitHub：https://github.com/hxy91819/dsh-auth
• 目录页：本文已核实资料未给出可确认的目录页 URL；请以插件目录站点实际发布地址为准。