[Bug] 非 loopback 访问时 Settings 面板报错 "settings are unavailable in this browser"

[LanPangZiDuoLa]

正文
Describe the bug
通过非本地回环地址（如局域网 IP 或域名）访问 dsh Web UI 时，点击“设置”或“Models”菜单，页面报错“加载提供方目录失败: settings are unavailable in this browser”，无法配置模型和 API Key。

To Reproduce

在服务器上启动 dsh：

bash
dsh web --port 3081 --trusted-host
在另一台设备的浏览器中通过局域网 IP 访问：https://:

点击左侧菜单“设置”或“Models”

页面报错：加载提供方目录失败: settings are unavailable in this browser
Expected behavior
通过非 loopback 地址访问时，Settings 面板应能正常加载并配置模型/API Key，或提供官方的远程访问认证方案。

Environment

@deepseek-ai/dsh 版本：0.1.1-rc.2（npm list -g @deepseek-ai/dsh）

Node.js 版本：v22.23.2

操作系统：Debian 12 (FNOS)

浏览器：Microsoft Edge 151 / Chrome 151

部署方式：nginx 反向代理 + HTTPS 自签名证书

Additional context

后端 API 正常（curl 测试返回非 403/502 响应）

通过 127.0.0.1:3080 本地访问时 Settings 面板可正常加载

社区已有类似反馈，且存在第三方补丁方案（如 dsh-remote和 patch_settings_memory.py），说明该问题是官方设计限制。

[denial123789]

从 rc.2 源码看，这个现象是当前 Settings scope 的明确设计边界，不是 provider catalog、nginx 或 HTTPS 自身加载失败。

ui-settings 的 client mirror 会根据浏览器 scope 选择 persistence。非 loopback 浏览器从初始化开始就是 unavailable，对应的 Settings rows 不会发送 Settings RPC。因此第一步应该在 DevTools Network 中确认：

• 完全没有 Settings RPC：客户端被判定为 non-loopback，属于当前设计的 unavailable scope；
• 请求到达 DSH 后返回 403：才属于 Host / Origin / privileged method trust fence；
• RPC 成功但写入失败：再检查 settings provider、schema、revision 或 credential store。

--trusted-host 解决的是 Host/Origin 信任声明，不会把远程浏览器升级成 loopback 配置端，也不是用户认证。HTTPS 和自签名证书同样不会改变这个 capability scope。把代理的 Host/Origin 伪装成 loopback 可能绕过有意的安全边界，但仍没有为 DSH 提供 authenticated principal。

目前比较安全的三种选择：

1. 单一管理员：SSH local forwarding，在浏览器中打开真正的 127.0.0.1 origin；
2. 远程观察端：模型、凭据和 Settings 在 Host 上以 out-of-band 方式管理，只开放经过审核的远程功能；
3. 多用户远程管理：另建具备身份认证、授权、write-only secret、CSRF/origin、审计和撤销能力的配置服务。

完整英文诊断与架构图： https://sandbaseai.github.io/deepseek-harness-handbook/remote-settings-loopback.html

Disclosure: I maintain the SandBase community handbook.

[denial123789]

The rc.2 source boundary makes this easier to classify: a non-loopback browser with no Settings RPC is outside the Web client configuration scope; an HTTP 403 is instead the Host/Origin or privileged-method trust fence; and a successful RPC followed by a write error points to provider schema, revision, or credential handling. --trusted-host changes request trust, not loopback capability or authentication. Safe topologies are an SSH loopback tunnel, a remote observer with settings managed out of band, or a separately authenticated configuration service. We documented the decision tree and threat boundary here: https://sandbaseai.github.io/deepseek-harness-handbook/remote-settings-loopback.html

Disclosure: I contribute to this independent community handbook.

[weijiafu14]

@denial123789 那份分析把边界说清楚了（非 loopback 浏览器从初始化起就是 unavailable scope，--trusted-host 解决的是 Host/Origin 信任声明、不是把远程浏览器升级成配置端）。补一件他点到但没展开的：你真正要做的事——配模型和 API Key——今天有一条完全受支持、且不绕任何安全边界的路。

直接改 settings.yaml，不需要 Settings 面板

模型和凭证的权威就在 $DSH_HOME/settings.yaml。你已经能 SSH 到那台服务器，那就在那边改，改完 DSH 会热加载（settings 变更下一次请求即生效，不用重启）：

llm-pi-ai:
  providers:
    my-gateway:
      displayName: My Gateway
      api: openai-completions
      baseURL: https://<你的端点>/v1
      apiKeyEnv: MY_GATEWAY_API_KEY      # ← 引用名，不是密钥本身
      models:
        - id: <model-id>
          contextWindow: 131072
          input: [text, image]           # 视觉模型才写
          reasoningEfforts:              # 推理模型才写
            off:
            low: low
            high: high

密钥本身不写进这个文件——apiKeyEnv 只是一个引用名，真正的值走环境变量。用户级密钥的正确落点是 $DSH_HOME/.env（这一层有分层加载：继承环境 > 仓库根 .env > ~/.dsh/.env，见 #1015，那位指出这层目前没有用户文档）：

# $DSH_HOME/.env
MY_GATEWAY_API_KEY=sk-...

这条路的性质：它不是 workaround，它就是 @denial123789 说的第 2 种选择（"模型、凭据和 Settings 在 Host 上以 out-of-band 方式管理"）的具体做法。Settings 面板本来就只是这个文件的一个编辑器，而你手上有更直接的编辑方式。

几个坑先说：

1. 一个非法键会让整个 settings 段被拒——不是只忽略那一个键。所以一次加一个字段、加完试一次；
2. 改环境变量（.env）需要重启进程才生效，改 settings.yaml 不用；
3. 想确认组合结果，用 dsh --profile <p> --dump-config 看一眼。

关于第三方补丁那条，我同意 @denial123789 的判断，再补一个理由

你提到 dsh-remote 和 patch_settings_memory.py 这类方案。除了他说的"把 Host/Origin 伪装成 loopback 可能绕过有意的安全边界、且仍没有为 DSH 提供 authenticated principal"之外，还有一条很实际的：

这个仓库里有一份已复现的实录——#4384：agent 读源码发现本地 API 的信任栅栏只要求 loopback 的 Host 头（那段代码的注释自己写着 "explicitly not an authentication layer"），随后用自己的 shell 工具调 commands/execute，把权限预设切到 danger-full-access——全程无人参与。

也就是说：loopback 这道门在同一台机器上本来就挡不住 agent 自己。 你如果再把它对局域网打开，等于把一个"已知挡不住本机进程"的门朝网络开了。这不是理论顾虑，是有实录的。

如果你确实需要多人远程配置

那 @denial123789 的第 3 条（另建一个带认证/授权/审计的配置服务）是对的方向。补一个今天可用的低成本形态：SSH 本地端口转发——在你自己的机器上：

ssh -L 3080:127.0.0.1:3080 user@<server>

然后浏览器打开 http://127.0.0.1:3080。这样浏览器看到的是真正的 loopback origin，Settings 面板正常工作，而认证由 SSH 承担（那是一套真的认证）。

但有一个坑要提前知道：经隧道访问 DSH 有一个已知问题——#3030 实证，空闲的 events.mux WebSocket 会被中间盒静默回收、两端都收不到 close 帧，客户端的重连只在检测到 close 时触发，于是界面一直以为自己连着、却不再收到实时帧——最典型的表现是审批弹窗永远不出现，刷新一下才有。判据：刷新后立刻正常、闲置一会儿又不行，就是它。SSH 侧加 ServerAliveInterval 30 能减少空闲，但防不住 DSH 自己那条 WebSocket 因为无流量被回收。

边界与利益相关

我们不修 DSH 自家组件——Settings scope、trust fence、WebSocket 下行都在 DSH 里。第一节那段 YAML 是纯 DSH 官方配置（这个形状我们在真 DSH loop 上端到端跑过）；#4384 / #3030 / #1015 都是别人的报告，我没有复现过。

利益相关：我维护 pi2dsh（Pi 生态兼容层）。这条不推销：上面全部是 DSH 自己的配置文件和 SSH，不需要装任何东西。

[pixel4696]

如果自己部署了登录和验证, 应该允许域名访问。