dsh-totp

为什么使用它

你想解决的问题	dsh-totp 提供的能力
不希望别人知道地址就能进入 DSH	开启保护后，本机、内网和公网访问同一入口都需要动态码
不想维护另一套账号或登录站点	在 DSH 的「设置 → 访问验证」中扫码绑定
希望自己决定什么时候启用验证	首次安装默认关闭，绑定成功后开启，之后可随时切换
暂时离开时希望立即收回访问权限	一键锁定所有已授权页面和设备，无需再输入动态码
担心换手机后无法访问	提供一次性恢复码和验证器更换流程
不希望绑定完成后再等一轮验证码	当前绑定页保持可用，保存恢复码后直接继续使用

日常使用

操作	如何操作	结果
进入 DSH	保护开启时，打开或刷新页面并输入动态码	获得当前页面的临时访问授权
开启 / 关闭保护	在设置页点击开关，输入一组新的动态码确认	立即生效，旧页面授权撤销；关闭后可直接访问
锁定所有设备	点击对话页右下角的「锁定」，或设置页的「锁定所有设备」	当前页和其他已授权页面立即锁定，无需动态码
更新恢复码	在设置页点击「更新恢复码」，输入新的动态码	生成 10 个新恢复码，旧恢复码失效
更换验证器	验证当前动态码，再扫描新二维码并确认新动态码	新验证器生效；当前页面可继续使用，其他页面重新验证

锁定按钮的状态：

• 未绑定验证器：置灰，提示先到设置页绑定。
• 已绑定但保护关闭：置灰，提示先到设置页开启保护。
• 已绑定且保护开启：可直接锁定，无需再次验证。

锁定会关闭访问连接，插件不会主动取消 DSH 后台任务。具体任务在连接中断后的行为仍由 DSH 和所用插件决定。

手机不可用时

在登录页点击 无法使用验证器，输入一个未使用过的恢复码，然后重新绑定验证器。

恢复码验证成功后，旧验证器和旧页面授权立即失效。在新验证器确认前，恢复授权仅允许绑定，不能访问 DSH 数据。确认新动态码并保存新恢复码后，可以直接进入 DSH，无需再登录一次。

每个恢复码只能使用一次。更新恢复码或成功换绑后，请用新的恢复码替换旧备份。

配置与本机管理

展开查看配置、数据目录和本机命令

可选配置

可在对应 profile 的 cordis.patch.yml 中配置：

- id: dsh-totp
  config:
    host: '0.0.0.0'
    port: 3080
    allowedHosts:
      - 'dsh.example.com:3080'
    idleMs: 900000
    maxMs: 28800000

修改监听地址、端口或数据目录需要重启；页面内的保护启停和锁定立即生效。

DSH 会通过插件导出的 Config 校验配置。host 支持 127.0.0.1 和 0.0.0.0；port 为 0–65535 的整数（0 表示动态端口）；idleMs 不得大于 maxMs，两者为正整数且最长不超过 24 小时。allowedHosts 填写 host[:port]，不带协议或路径。

数据目录

默认依次使用 DSH_TOTP_DATA_DIR、$DSH_HOME/dsh-totp、~/.dsh/dsh-totp。插件配置的 dataDir 可覆盖默认路径。

每个数据目录只允许一个运行中的插件实例。多个 DSH 实例应使用不同目录。普通重启保留绑定和保护状态，但不保留页面授权。

本机命令

在本仓库目录执行：

node src/cli.js status
node src/cli.js doctor
node src/cli.js enable
node src/cli.js disable
node src/cli.js lock

这些是持有本机管理权限的恢复与运维入口，不要求手机动态码。lock 命令会开启保护并锁定所有页面，因此与保护关闭时置灰的网页按钮不同；未绑定时不能开启保护。

可附加 --data-dir /path/to/data。本机命令必须与插件使用同一数据目录。它们不支持扫码绑定或换绑。

可选配置

可在对应 profile 的 cordis.patch.yml 中配置：

- id: dsh-totp
  config:
    host: '0.0.0.0'
    port: 3080
    allowedHosts:
      - 'dsh.example.com:3080'
    idleMs: 900000
    maxMs: 28800000

修改监听地址、端口或数据目录需要重启；页面内的保护启停和锁定立即生效。

DSH 会通过插件导出的 Config 校验配置。host 支持 127.0.0.1 和 0.0.0.0；port 为 0–65535 的整数（0 表示动态端口）；idleMs 不得大于 maxMs，两者为正整数且最长不超过 24 小时。allowedHosts 填写 host[:port]，不带协议或路径。