管理员登录网关hxy91819/dsh-auth

dsh-auth

npm version
CI
license

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 需要已有的证书和私钥。--server-name 同时接受 DNS 名称和公网字面量 IP 地址。

$ 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。 |
| --behind-tls-proxy | 否 | 关闭 | 让受管 HTTP 鉴权边缘只监听回环地址，要求可信的 HTTPS 转发头，并签发 Secure Cookie。 |
| --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@ | 钉死的 registry 规格或绝对路径 .tgz。 |
| --http-port | 否 | 80（HTTP 为 8080） | HTTP 或 HTTPS 重定向端口。 |
| --https-port | 否 | 443 | HTTPS 监听端口。 |
| --output-dir | 否 | | 离线或容器渲染目录。跳过 systemd。 |

为公网 IP 申请免费证书

当 --server-name 是可从公网路由的 IPv4 或 IPv6 地址，且选择 --tls automatic 时，受管 Caddy 会使用 Let’s Encrypt 的 shortlived profile 申请免费的 IP 地址证书，并自动续期。Let’s Encrypt 要求这类证书有效期约六天，因此主机必须保留 Caddy 的持久化状态，并能访问 ACME 服务。HTTP challenge 端口必须能从公网访问（通常是 TCP 80）；证书认证的是 IP 而不是端口，所以签发后 HTTPS 可以监听其他端口。

当前公网地址 9.135.102.192 使用标准 HTTPS 端口时，可以这样安装：

sudo dsh-auth setup \
--non-interactive \
--dsh-service dsh-web.service \
--admin-bootstrap login-token \
--login-token enabled \
--mode https \
--tls automatic \
--server-name 9.135.102.192 \
--http-port 80 \
--https-port 443

如果 ACME 校验无法访问这台机器，安装器不会把它伪装成受信任证书：请恢复 challenge 端口的公网访问、改用 DNS 名称，或用 --tls manual 提供已有证书。tls internal 仍然只是显式的本地/评估回退，不是浏览器默认信任的公网证书。

已删除且无别名：--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-state-file /export/dsh-auth/state/auth-state.json \
--public-origin https://harness.example.com

安装时可以替换内置失败页文案。中文和英文可分别配置；省略某种语言则保留其内置文案。每个值是 1–500 个 Unicode 字符的纯文本。控制字符会被拒绝，HTML 按文本显示而不是按标记渲染。当 --login-token 为 disabled 时，安装器会拒绝这些参数。

格式错误、已过期、已使用和未知令牌都会返回同一份带该文案的 HTTP 401 页面。页面不会区分具体是哪一种情况。令牌 POST 因 Origin 或 CSRF 校验失败时返回另一份 HTTP 403 页面：提示从控制台重新打开最新链接或检查公网访问地址，不使用上述 401 文案，也不会消费令牌。

sudo dsh-auth setup \
--login-token enabled \
--login-token-error-message-zh '登录链接不可用，请向管理员重新申请。' \
--login-token-error-message-en 'This sign-in link is unavailable. Request a new one from your administrator.'

外部身份提供商

dsh-auth 提供与具体身份系统无关的授权码接口。内置的 ioa provider
适配腾讯 IOA/太湖的签名 AccessToken 换取流程；Session、CSRF、state 和授权
策略仍由通用核心负责。

通过 Cordis bundle 配置启用（默认关闭）：

externalIdentity:
enabled: true
paasId: ${TAIHU_PAAS_ID}
tokenFile: /run/secrets/taihu-token
baseUrl: https://api.woa.com
callbackUrl: https://lightpilot.woa.com/auth/callback
allowedUsers: [masonxhuang, yuehuali]
allowedDepartmentIds: []
allowedDepartmentPrefixes: []

用户访问 /auth/login/ioa 发起登录。回调会校验短期 state，在服务端
使用一次性 code 换取身份信息，应用用户/部门白名单，然后创建与密码登录相同的
可吊销不透明 Session。太湖 Token 只从权限受限的 tokenFile 读取，不会出现在
URL 或持久化认证状态中。

已验证身份 Header

已认证的 GET/HEAD /auth/verify 仍返回 204 及旧版
X-Dsh-Auth-User-Id: admin、用户名和边缘角色 Header。IOA Session 还会返回
经过 URI 编码和校验的 X-Dsh-Auth-Subject、X-Dsh-Auth-Username、
X-Dsh-Auth-Display-Name，以及可选的 X-Dsh-Auth-Picture。Subject 是稳定的
外部账号键；X-Dsh-Auth-Roles 只表示 dsh-auth 边缘角色，消费方不得将其直接当作
应用角色。受管 Caddy 会在 forward_auth 前删除客户端同名 Header，只把验证结果复制
给上游。资料字段限制为 512 个 UTF-8 字节并拒绝控制字符，头像地址必须是无凭据、无片段
的 HTTPS URL。

重置密码

已登录管理员可以打开 设置 → 通用 → 重置密码，输入当前密码并设置新密码。这会更新存储的哈希，并让其他浏览器会话退出；不会轮换会话密钥。

如果当前密码不可用，对由 setup 创建的安装拥有 root 权限的运维人员可以运行交互式重置：

sudo dsh-auth reset-password

在精确确认后，命令会无回显地读取并确认新密码。它会原子替换受管 Argon2id 哈希、轮换会话密钥、吊销全部现有会话，并仅在已记录的 DSH 服务处于活动状态时重启它。重启失败会同时恢复两份先前的凭据文件。

自动化必须通过 stdin 或临时 0600 文件提供密码，并显式授权该操作：

sudo dsh-auth reset-password \
--non-interactive \
--json \
--authorize-password-reset \
--password-file /run/secrets/dsh-auth-new-password

该命令从不在 argv 中接受密码值，也不会打印密码、哈希或会话密钥。

隔离可信网络上的明文 HTTP

明文 HTTP 仍然需要认证，但会把凭据和会话暴露给网络窃听。只有显式指定 --mode http，并给出字面量回环、RFC1918 或 ULA 监听地址时才会接受：

sudo dsh-auth setup \
--admin-bootstrap password \
--admin-username operator \
--login-token disabled \
--mode http \
--listen-address 10.0.0.20 \
--http-port 8080
不要在不受信任的网络上使用此模式。HTTPS 是生产默认值。

由外层反向代理终止 TLS

运维人员可以让同一主机或同一网络命名空间内的 ingress、负载均衡器或反向代理继续管理证书和公网 TLS，同时保留 dsh-auth 受管 Caddy，作为唯一能够访问 DSH 的鉴权边缘：

sudo dsh-auth setup \
--admin-bootstrap login-token \
--login-token enabled \
--mode http \
--listen-address 127.0.0.1 \
--http-port 8080 \
--behind-tls-proxy

此模式只接受回环监听。外层代理必须从回环地址连接，并覆盖而不是追加 X-Forwarded-Host、X-Forwarded-Proto 和 X-Real-IP；转发协议必须是 https。转发信息缺失时请求会被拒绝。虽然内层链路是 HTTP，dsh-auth 仍会保留用于精确 Origin 校验的公网 authority、使用相对登录跳转，并签发 Secure、__Host- Cookie。

外层代理及其证书、公网地址和端口仍由运维人员负责。setup 不探测、重载或修改它们，变化的公网 origin 也不属于 setup 指纹。签发一次性登录链接时，应把当前公网 HTTPS origin 传给 issue-login-token --public-origin。不要暴露内层监听地址、把路径前缀当作认证秘密，或让外层代理保留客户端伪造的转发头。

在这种拓扑里，TLS 终止和鉴权执行是两条不同的所有权边界。外层代理不需要理解 Harness 路由或 dsh-auth 会话语义，也绝不能把任何路径直接转发给 Harness。dsh-auth 刻意保留受管 Caddy，避免运维人员在现有网关中自行复刻页面、API、下载、SSE 和 WebSocket 的完整 forward_auth 覆盖。使用运维人员管理的 Caddy、Nginx、ingress 或负载均衡器直接承担鉴权边缘，不属于当前支持的部署模式。

诊断、卸载与 v1 重装

doctor 会检查所有权记录、文件权限、精确的 DSH 服务、root 可执行安全性、Caddy 版本与校验和、caddy validate，以及服务状态：

sudo dsh-auth doctor
sudo dsh-auth doctor --json

uninstall --dry-run 只列出所有权记录能证明的文件和 profile 变更。交互式卸载需要输入 uninstall；自动化需要精确的 --authorize-uninstall 参数。会移除独立的 Caddy 单元；从不触碰用户自行安装的 Caddy 或 Nginx。

sudo dsh-auth uninstall --dry-run
sudo dsh-auth uninstall

schema v1 所有权记录、旧 Nginx 参数和旧插件身份字段会被拒绝，并给出重装诊断。没有自动迁移。卸载并重新 setup 后，旧会话会失效。

体验环境部署

手动触发的体验环境部署工作流会通过已固定主机密钥的 SSH，把所选开发 ref 部署到一个受保护的 GitHub Environment。它生成只在体验服务器使用的 -experience.. 预发布 tarball，首次执行非交互 setup，之后使用事务性 upgrade。它不会发布 npm，也不会创建 GitHub Release。请按 docs/experience-deploy.md 配置 Environment Variables 和 Secrets；SSH 账户应专用并能以 sudo -n 执行安装操作，同时保留所有权记录引用的服务器端 tarball，以便离线回滚。

退出码

| 码 | 含义 |
|---:|---|
| 0 | 成功、健康，或未发生变化 |
| 2 | CLI 输入无效或不完整 |
| 3 | 缺少或不支持的前置条件 |
| 4 | 所有权或现有配置冲突 |
| 5 | 权限不足或不安全 |
| 6 | 执行或回滚失败 |
| 7 | 改动前的交互式取消 |
| 8 | doctor 发现安装不健康 |

JSON 输出使用 schema 第 2 版，包含命令、状态、退出码、已脱敏的操作，以及结构化诊断。

Docker 与离线镜像

构建并钉死精确的 npm tarball，然后在没有 registry 访问的情况下安装进 DSH profile：

将 X.Y.Z 替换为打包产物文件名中的版本。

corepack pnpm pack --pack-destination packed
dsh plugin --profile web add --offline --config.auto-install-peers=false /artifacts/dsh-auth-X.Y.Z.tgz

生成确定性运行时文件，不调用 systemd、包管理器或主机上的 Caddy 二进制：

dsh-auth setup \
--non-interactive \
--output-dir /image/dsh-auth \
--package /artifacts/dsh-auth-X.Y.Z.tgz \
--admin-bootstrap password \
--admin-username operator \
--login-token enabled \
--password-file /run/secrets/dsh-auth-password \
--server-name harness.example.com \
--tls manual \
--certificate /run/tls/fullchain.pem \
--certificate-key /run/tls/privkey.pem

输出目录包含 dsh-auth.env、基于文件的凭据、认证状态、登录令牌目录和 Caddyfile。将它们复制或挂载到固定镜像路径，并显式接入环境文件和 Caddy 配置。同一份 tarball 已包含 linux-x64 和 linux-arm64 的 Caddy 二进制；setup 会在校验和验证后复制当前架构，从不下载二进制。deploy/docker/Dockerfile.install 展示了离线 profile 层。

安全行为与边界

- 生产 Cookie 为 HttpOnly、Secure、SameSite=Lax、Path=/，并带 __Host- 前缀。明文 HTTP 使用显式兼容 Cookie 模式。
- Argon2id 哈希和随机会话密钥分别存放在权限受限的文件中。持久不透明会话使用 0600 的认证状态文档。
- 登录、退出、令牌兑换和首次管理员设置会在受信代理解析后强制 CSRF 以及精确的 Origin/Referer 检查。认证响应为 no-store。
- 第 2 版每个受管安装只支持一个管理员身份（admin）。密码初始化和令牌初始化是明确选项。注册、自助账户恢复、MFA、数据库、多账户策略和多租户不在本版本范围内。
- dsh-auth 受管 Caddy 是唯一允许访问 Harness 的鉴权边缘。通常它也是公网监听器；使用 --behind-tls-proxy 时，运维人员的代理对公网监听，但只能访问受管鉴权边缘。标准反向代理无法立即吊销已经打开的 WebSocket。需要立即终止流的部署必须使用连接感知边缘。

安全报告请遵循 SECURITY.md。

开发

corepack pnpm install --frozen-lockfile
corepack pnpm run check
corepack pnpm run check:caddy
corepack pnpm run test:e2e
corepack pnpm pack --pack-destination packed
node scripts/installer-e2e.mjs packed/dsh-auth-X.Y.Z.tgz

将 X.Y.Z 替换为 package.json 中的版本。

test:e2e 会打包当前检出、安装进一次性 DSH profile，并驱动真实 TLS Caddy 边缘加无头浏览器。它验证未认证拒绝、登录令牌签发与兑换、首次管理员设置、密码登录、受保护的 SPA/API/下载/WebSocket 路径、会话续期与重启持久化，以及侧栏退出登录的吊销。需要 OpenSSL、ss 和 Chrome 或 Chromium；浏览器不在标准 Linux 路径时设置 DSH_E2E_CHROME_BIN。未设置 DSH_E2E_CADDY_BIN 时，测试会准备一份仅用于隔离、经过校验和验证的官方 Caddy v2.11.4 二进制。

贡献者应阅读 AGENTS.md。安装器架构与维护检查见 docs/installer.md。

稳定的 npm 和 GitHub 发布由 Release 工作流 调度；维护者应先更新 changelog 并遵循 docs/releasing.md。