dsh-passwords（npm 包dsh-passwords，仓库slywalker2006/dsh-passwords，npm latest2.7.8）给 DSH 加一层登录门，把它变成多人共用的多租户平台：主用户创建子账号，再按工作区、会话和配额逐个授权。它的部署面比一般插件宽——要占端口、要签证书、要有稳定的.env与数据库路径，每个环节都能独立翻车，所以现场排查最忌讳一上来就重装。想先横向对照同类插件的中文清单，可以先看 完整插件清单与汉化避坑指南。
两条口径先分开。站内信任档位「已验证」，记录的是在dsh 0.2.0-rc.2下真实安装成功（L4 · 真实安装）；本插件自己的版本门禁则要求>=0.2.1-alpha.1 <0.2.2-0——这是两件事，不要合并成一个版本号。站内安全扫描把它标记为「含敏感能力」、尚无人工评估；许可为GPL-3.0-only；README 原文写明「本项目是 dsh 的独立扩展，与 DeepSeek 无隶属关系」。
分诊顺序：从启动日志一路看到用户表
- 先看启动日志。加载期报错只有这里最全，
duplicate loader entry id就在这一层，它意味着注册方式错了，不是某个值写错了。
- 再看版本门禁。门禁
>=0.2.1-alpha.1 <0.2.2-0会拒绝0.1.x、0.2.0、0.2.1-alpha.0与0.2.2+；宿主不在范围内，后面的自检都没有意义。
- 再看证书。自动 HTTPS签发失败会拒绝启动，这一层会伪装成「服务起不来」。
- 最后看用户表。服务起来了、页面能开却停在首次配置页，那既不是 TLS 问题也不是注册问题。
坑一 · 启动日志里直接打出 duplicate loader entry id
现象。启动 dsh 时报duplicate loader entry id，登录页打不开，网关也没接管端口。
原因。多半是之前额外执行过一次目录网站或旧帖子给的dsh plugin add。它会把所有声明 bundle 的依赖一并加入 bundles 层，和本插件要求的精确注册撞车，同一个 loader entry 被登记两遍。README 的原话是：「不要另外执行目录网站可能提供的dsh plugin add，本项目需要安装器或手动注册脚本精确注册。」
解决。先卸载，再用注册脚本重来。package.json里dsh.bundle.patch指向./cordis.yml，注册脚本会按这个声明处理：
跑完重启dsh web；找不到 dsh 目录时用MCP_DSH_ROOT指定。手动安装五步里的第 4、5 步正是这两步，漏掉网关就不会真正生效。
坑二 · 非 root 执行安装，要么当场失败要么绑不上 443
现象。普通账号跑一键安装直接失败；或装完了进程起不来，日志里是绑定443被拒。
原因。Linux 下1024 以下的端口需要 root。非 root 首次安装若仍走自动 HTTPS，安装器还会反过来要 root，因为自动签发必须占用 80 端口做 http-01 验证。
解决。换高位端口，端口转发交给你自己那一层：
同时记住三点：非 root 首次安装必须显式关闭自动 HTTPS（MCP_GATEWAY_AUTO_TLS=0）或提供自管证书（MCP_GATEWAY_TLS_CERT/MCP_GATEWAY_TLS_KEY）；下载式安装默认目录会从/opt改到$HOME/dsh-passwords，也可用DSH_PASSWORDS_DIR指定；本地或受信内网走 HTTP 模式更省事（node scripts/start-http.mjs默认127.0.0.1:8080，但 HTTP 不加密，公网入口仍应由反代提供 HTTPS）。
坑三 · 自动 HTTPS 起不来，只留下一个两位数的错误码
现象。宿主机自动 HTTPS 启动失败，日志里只有一个两位数错误码，不知道从哪查。
原因。三个码是三件事：30证书签发失败；31拿不到公网 IP 或域名；32端口被占用。自动签发走http-01，签发与续期期间 80 端口都要从外部可达，DNS 也要正确解析，任一条不满足都落在 30。
解决。按码分流：
错误码 | 含义 | 处理 |
30 | 证书签发失败 | 检查 80/443 放行与占用情况，确认能连通 Let's Encrypt |
31 | 拿不到公网 IP 或域名 | 设置 |
32 | 端口被占用 | 更换 |
已有自有证书可直接在.env填MCP_GATEWAY_TLS_CERT/MCP_GATEWAY_TLS_KEY，绕开自动签发，也就不需要 80 端口。
坑四 · 登录页一直停在「首次配置」
现象。服务在跑、端口通、页面打得开，但访问网关始终停在首次配置页。
原因。用户表为空——首次配置没走完，或者数据库被换成空的、做过破坏性清理后没重建账号。
解决。先用就绪检查确认这一层是好的（readyz含数据库检查）：
两者都返回ok:true，就按提示输入SETUP_KEY重建主用户。宿主机安装的SETUP_KEY打印在安装目录的setup-key.txt；如果这个文件已经不在了，不要指望重装能把它找回来，需要先从备份里取回密钥，再完成首次配置（处置边界见同批次的卸载与回滚篇）。
总结
四类现场问题对应四个分层：注册方式、端口与权限、证书、账号数据。把它和 完整插件清单与汉化避坑指南 里的同类插件放在一起看，dsh-passwords 更像「部署」而不是「装插件」：先确认启动日志干净，再确认宿主落在>=0.2.1-alpha.1 <0.2.2-0，然后才是证书与用户表；跳过任何一层就重装，基本等于把同一段错误再演一遍。还要记住，/gateway/healthz与/gateway/readyz只证明进程活着，健康检查不能代替权限验收。
适合与不适合
适合：要把一台机器上的 DSH 开放给小团队、需要独立账号与配额的人；已遇上注册冲突或端口绑定失败、想按分层顺序定位的运维；用 nginx / Caddy 反代或 Cloudflare Tunnel、需要明确 HTTPS 由谁提供的人。
不适合：宿主机 DSH 仍是0.1.x或0.2.0的人——版本门禁直接拒绝，现在就用不了；只服务自己一个人的场景，为个人使用引入登录门、证书与密钥备份只是白白增加运维面；把「密码够安全」当整体结论的人——这里是字段加密，不是整库加密，留言正文、部分权限配置和工作区路径不在保护范围，bcrypt 哈希也仍可能被离线猜测。
标签：dsh-passwords、DeepSeek Harness、多租户网关、安装排错、HTTPS 部署
本文由 DeepSeek Harness Hub 自动整理，数据来源于插件详情页。
