dsh-auth

dsh plugin --profile web add dsh-auth

dsh-auth

[English](README.md) | 简体中文




DeepSeek Harness 的非官方社区插件。为 DeepSeek Harness Web 应用增加安全的管理员登录。dsh-auth 让 Harness 只监听回环地址，并安装由本项目维护的 Caddy forward_auth 边缘，覆盖页面、API、下载、SSE 和 WebSocket。

0.2.0 相对旧版 v1 部署是破坏性升级。旧安装器参数、由 Nginx 管理的安装，以及旧会话都不会迁移。请先卸载旧安装，再重新执行 setup。

快速开始

交互式安装

安装已发布的 CLI，然后从一个现有的 DSH Web systemd 服务开始；该服务的上游必须只监听回环地址：

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

npm install -g dsh-auth 安装当前稳定版 CLI，安装器会把同一版本钉死到所选 DSH profile。若需按供应链策略做受控生产发布，请安装已批准的精确版本：

sudo npm install -g dsh-auth@0.2.3

交互式安装器会询问精确的 DSH 服务、管理员初始化方式、HTTPS 主机名和 TLS 模式；展示一份不含密钥的计划；只有在你输入精确确认词后才会改动系统。它会把钉死的包安装进所选 DSH profile，复制同包内经过校验和验证的 Caddy 二进制，写入权限受限的认证状态，并启用独立的 dsh-auth-caddy.service。它从不存储明文密码，安装时也从不下载 Caddy。

常规部署需要 Linux x64 或 ARM64、systemd、Node.js 24.7 或更新版本，以及 DSH Web 0.1.0-rc.7。自动 TLS 是 HTTPS 默认值。手动 TLS 需要已有的证书和私钥。

$ 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
Password:
Confirm password:
dsh-auth setup completed successfully.

重复执行同一命令是幂等的。若已有受管安装且非密钥配置完全相同，会报告未发生变化；配置不同，或文件没有所有权记录时，会拒绝覆盖而不是改写。

在正式安装前可用 plan 查看同一份类型化计划，不会读取密码，也不会改动文件系统：

sudo dsh-auth plan

命令行安装（非交互）

非交互模式需要稳定的参数，以及明确的管理员初始化方式。密码初始化时，请把明文密码挂载为平台提供的临时 0600 密钥文件；dsh-auth 只读取一次以生成 Argon2id 哈希，不会复制明文。

这些命令名、参数名、--name value 或 --name=value 语法、JSON schema 第 2 版，以及退出码，构成公开自动化契约。全局参数可以放在命令之前。允许新增参数和诊断码。重命名、删除或改变已有参数、JSON 字段或退出码的含义属于破坏性变更。

打印冻结的用法文本：

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

-h 是 --help 的别名。dsh-auth setup --help 打印相同的用法文本。下面的示例是一次完整的 HTTPS 系统安装：密码初始化，并使用自动 TLS。

只有在 stdin 和 stdout 都是 TTY，且未设置 --non-interactive 时才会出现提示。--json 只影响输出格式，不会关闭提示。

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

令牌初始化不需要密码和用户名。第一位获授权用户在浏览器中设置它们，也可以选择稍后设置：

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

参数 · 是否必需 · 默认值 · 说明

--help、-h · 否 · · 打印用法并退出。

--version · 否 · · 打印 CLI 版本并退出。

--non-interactive · 在 TTY 上 · · 关闭提示。

--json · 否 · · 输出一份 JSON 文档。不会关闭提示。

--mode · 否 · https · https 或 http。

--admin-bootstrap · 非提示模式时 · · password 或 login-token。

--admin-username · 密码安装时 · · 初始管理员登录名。

--login-token · 非提示模式时 · · enabled 或 disabled。令牌初始化必须为 enabled。

--login-token-error-message-zh · 否 · 内置中文文案 · 可选的 1–500 字符中文令牌失败页文本。需要 --login-token enabled。

--login-token-error-message-en · 否 · 内置英文文案 · 可选的 1–500 字符英文令牌失败页文本。需要 --login-token enabled。

--listen-address · HTTP · HTTPS 为 0.0.0.0 · 字面量 IP 绑定地址。HTTP 仍必须显式指定私网或回环地址。

--dsh-service · 系统安装 · · 精确的现有 DSH Web systemd 单元。仅在使用 --output-dir 时可省略。

--password-file 或 --password-stdin · 就绪密码的 setup · · 密码来源。plan 和令牌初始化不使用。未变化的重复执行会跳过。

--server-name · --mode https · · 公开 HTTPS 主机名。

--tls · HTTPS · automatic · automatic 或 manual。

--certificate · --tls manual · · TLS 证书的绝对路径。

--certificate-key · --tls manual · · TLS 私钥的绝对路径。

--dry-run · 否 · · 在 setup 上等价于 plan。在 uninstall 上列出将删除的自有文件，但不改动主机。

--dsh-home · 否 · 自动发现 · 单元无法推断时的 Harness 主目录。

--dsh-executable · 否 · 自动发现 · 单元无法推断时的 DSH 可执行文件。必须是文件，不能是目录。

--profile · 否 · web · DSH profile 名称。

--upstream · 否 · 127.0.0.1:3080 · 回环 DSH 监听地址（127.0.0.1 或 [::1]）。

--package · 否 · dsh-auth@<CLI version> · 钉死的 registry 规格或绝对路径 .tgz。

--http-port · 否 · 80（HTTP 为 8080） · HTTP 或 HTTPS 重定向端口。

--https-port · 否 · 443 · HTTPS 监听端口。

--output-dir · 否 · · 离线或容器渲染目录。跳过 systemd。

已删除且无别名：--nginx、--authorize-nginx-install、--user-id、--username、--roles 和 --dsh-bin。

其他命令接受更小的冻结参数集：

命令 · 非提示模式时的必需项 · 可选项

plan · 与 setup 相同的参数，但不需要密码来源 · --json、--non-interactive

doctor · · --json

reset-password · --password-file 或 --password-stdin；--authorize-password-reset · --json、--non-interactive

uninstall · --authorize-uninstall · --json、--non-interactive、--dry-run

issue-login-token · 非提示模式时需要 --authorize-login-token-issue · --ttl-seconds、与 --public-origin 一起使用的 --auth-state-file、--json

hash · · --password-stdin

secret · ·

密码只能通过隐藏的交互输入、--password-stdin 或 --password-file 提供。没有内联密码参数。命令输出、JSON、计划、子进程 argv 和安装器错误从不包含密码或会话密钥。issue-login-token 是唯一允许在成功的 stdout 或 JSON 中包含持有者登录令牌的命令。

签发一次性登录链接

安装时若启用了登录令牌，云控制面或运维人员可以签发一次性 URL。原始令牌只出现在成功的人类可读 URL 行，或 JSON 成功文档中：

sudo dsh-auth issue-login-token --non-interactive --authorize-login-token-issue

URL 使用 fragment（/auth/token#token=…）。打开后会建立与密码登录相同的 72 小时滚动会话。若尚未设置管理员密码，浏览器会先提供设置页；选择稍后只会跳过那一次登录。

容器和镜像布局需要显式传入路径，而不是读取 systemd 所有权记录：

dsh-auth issue-login-token \
  --non-interactive \
  --authorize-login-token-issue \
  --json \
  --auth-stat

…(truncated)