dsh-loopback-bridge

Readme

<div align="center">

# dsh-loopback-bridge

用局域网 IP 或公网域名打开 DSH，设置页也能改模型和 API Key

装完重启即可 · 不改官方源码 · 入口必须有鉴权

**[English](README.en.md)** · 中文

</div>

---

> [!WARNING]
> 这个插件把「仅本机」的设置和凭据写入能力，开放给所有能打开这个 DSH 页面的人。家庭局域网自己看着办；挂公网就必须在前面加 authentik / oauth2-proxy 这类鉴权。接入前先备份，数据丢了概不负责。

## 这是什么

DSH 设置页只认地址栏是不是本机（`127.0.0.1` / `localhost`）。用 `192.168.x.x` 或自己的域名打开时，页面会报 *"settings are unavailable in this browser"*，模型 tab 改不了。

服务端从 0.1.2 起已经认 `--trusted-host`，RPC 本身能通。卡住的是浏览器里那一刀：设置页看见 hostname 不是回环，直接进只读，请求都不发。这个插件在页面加载时把连接标成本机，设置页就会正常工作。

## ✨ 特性

- **远程能改设置** —— 局域网 IP、NAS 域名、公网域名打开，模型和凭据都能写
- **不改官方包** —— DSH 随便升级；官方哪天认 trusted-host 了，卸掉就行
- **装完即生效** —— `dsh plugin add` 之后重启 web，不用手改 nginx
- **0.1.2 友好** —— 不要再把 Host 改写成 `127.0.0.1`，cookie 会对不上然后 401

## 🚀 快速开始

### 1. 确认服务端已经信任你的访问地址

`dsh web` 启动参数里要带上实际用来打开页面的 Host，例如：

```bash
dsh web --host 127.0.0.1 --port 3080 \
  --trusted-host 192.168.31.229 \
  --trusted-host dsh.example.com
```

### 2. 安装插件

```bash
dsh plugin --profile web add github:johnhom1024/dsh-loopback-bridge
```

本地开发：

```bash
dsh plugin --profile web add link:/path/to/dsh-loopback-bridge
```

### 3. 重启 `dsh web`

Docker 共享 netns 的栈不要只 `restart` 单个容器，整栈重建。装完刷新页面，远程打开设置 → 模型，应该能改了。

## ⚙️ 要求

| 项 | 说明 |
| --- | --- |
| DSH | 按 `0.1.2-rc.1` 验证，`0.1.5+` 必用 1.0.1（旧版会把官方 `__ModuleLoader__` 盖掉，浏览器报 bootstrap facade is missing）。更早版本服务端还要改 Host，不推荐 |
| `--trusted-host` | 必须覆盖你实际访问用的 hostname / IP |
| 反代 | **不要**把特权 API 的 Host 改写成 `127.0.0.1`（0.1.2 的 cookie 绑 Host，改了会 401） |
| 鉴权 | LAN 信任模型可以裸奔；公网必须有反代鉴权 |

## 验证

打开远程地址的设置页，模型 tab 不再报 *unavailable*，能保存 API Key 就算成功。

<details>
<summary>命令行核对（可选）</summary>

```bash
# 脚本可达
curl -s -o /dev/null -w "%{http_code} %{size_download}B\n" http://<host>/loopback-bridge.js

# HTML 首包已注入
curl -s http://<host>/ | grep loopback-bridge

# 设置 RPC（0.1.2 路径是斜杠；要带着你的会话 cookie）
curl -s -o /dev/null -w "%{http_code}\n" -X POST \
  -H "Content-Type: application/json" \
  -d '{"type":"client-request","rpcId":"t","method":"settings/describe","payload":{"args":{}}}' \
  http://<host>/api/settings/describe
```

</details>

## 🔒 安全

插件只动客户端。谁能打开 DSH 页面，谁就能改设置、写 `credentials.set`。这在自家反代后面是正确语义，裸奔公网则不是。

上游如果改成由服务端下发 `isLoopback`，这个插件会一起失效，卸掉即可。

## 📄 License

[MIT](LICENSE)