dsh-plugin-lan-proxy

Readme

# dsh-lan-proxy

<p align="center">
  把 dsh 只监听回环地址的 Web UI 通过 <code>0.0.0.0</code> 反代暴露到局域网；
  开关、状态与启动日志直接嵌入 dsh 设置页，随 dsh 启停，无需单独进程。
</p>

## 界面预览

设置页「局域网反代」一级菜单面板（监听已开启时）：

![局域网反代设置面板](docs/preview/settings-tab.png)

## 安装

```bash
dsh plugin --profile web add "github:liveqte/dsh-lan-proxy#main"
```

bundle 层栈在启动时组合，装完**重启 dsh web** 生效。验证：设置页导航「局域网反代」一级菜单出现，启动日志无 `plugin tree failed to load`。

## 功能

| 能力 | 说明 |
| --- | --- |
| 局域网反代 | 将 dsh Web UI 同时监听 `0.0.0.0:<port>`，局域网内任何设备经 `http://<局域网IP>:<port>/` 访问 |
| 网页端目录选择 | 禁用原生 OS 文件夹对话框，固定为网页内嵌「选择工作区目录」浏览（可在远程机器上选宿主目录） |
| 免配置开关 | 设置页「局域网反代」tab 一键开关，即时热启停，无需重启 dsh |
| 端口配置 | tab 内直接修改监听端口与上游端口，保存即生效 |
| 协议适配 | 自动改写 Host/Origin 为回环、桥接 WebSocket（RFC6455 帧编解码）、注入 `crypto.randomUUID` polyfill（局域网 HTTP 非安全上下文缺失） |
| 状态与日志 | 2 秒轮询的运行状态、上游可达性探测、局域网地址列表与启动日志，内置「重启反代」按钮 |

## 使用

- **开关**：设置页 →「局域网反代」tab，切换「监听局域网访问」。
  页面开关的即时状态写入运行时文件（`$DSH_HOME/profiles/web/lan-proxy.runtime.json`，
  优先级高于配置默认值），立即生效。
- **局域网访问**：`http://<局域网IP>:<监听端口>/`。
- **端口**：tab 内可直接修改监听端口（所有网卡）与上游端口
  （`127.0.0.1`，`0` 表示自动取 dsh 实际监听端口）。
- 开关与端口修改接口仅限本机回环地址调用；局域网访问只读状态与日志。
- **选择工作区**：装上本插件后，侧边栏 / 会话区的「添加工作区」改为网页内嵌目录浏览器
  （宿主文件系统列举 + 新建文件夹），不再在 dsh 进程所在机器上弹出 OS 对话框。
  这样局域网/远程浏览器也能选目录；本机 `127.0.0.1` 访问同样走内嵌对话框。
  实现方式：bundle 层禁用 `directory-picker`（auto），并挂载官方
  `directory-picker-browse` 双面（host 列举/创建 + client 对话框）。

## 配置项

| 键 | 默认值 | 说明 |
| --- | --- | --- |
| `enabled` | `false` | 监听局域网访问（配置默认值；页面开关优先级更高并持久化到运行时文件） |
| `port` | `3080` | 反代监听端口（所有网卡） |
| `upstreamPort` | `0` | 上游端口，`0` = 自动取 dsh 实际监听端口 |
| `maxLogLines` | `500` | 页面日志缓冲行数 |
| `bypassRules` | 见下 | 前端 JS 改写规则表（屏蔽 dsh 对非回环来源的设置页封锁） |

配置覆盖写在 profile 层的 `cordis.patch.yml`（`id: lan-proxy` 行的 `config`），
不需要修改仓库内文件。

### 设置页非回环封锁的绕过（bypass 规则）

dsh 0.1.x 的浏览器端只为回环地址加载设置面（`connection.isLoopback`），从局域网
访问「设置 → 模型」会得到：`加载提供方目录失败: settings are unavailable in
this browser`。反代在转发 `/plugins/<id>/client.js` 字节流时，按规则表改写其
JS，把封锁判定固定为回环；服务端 `/api` 信任栅栏按 Host 头判定，反代已把 Host
改回 `127.0.0.1`，因此服务端天然放行。这是改动浏览器实际执行字节的补丁，与插件
加载顺序无关。

内置规则（dsh 0.1.x）：

| id | 改写目标 | 动作 |
| --- | --- | --- |
| `dsh-client-connection:isLoopback-mirror` | 把 `dsh-client-connection` client 里的 `isLoopback: pageLocation…` 改为 `isLoopback: true` | 设置/模型/凭据面视为回环，正常读写 |

官方换一种封锁方式时，在配置里加一条 `find`/`replace` 规则即可（或覆盖
`bypassRules` 表），旧规则 `find` 不中会自动跳过并在日志面板提示。规则状态
（命中次数/最后错误）出现在「局域网反代」设置页的运行状态里。

## 插件管理

已装插件用 plugin-registry 的浏览器管理面板（轻量控制台）统一管理：查看、
安装、卸载插件，调整 bundle 层栈与 insert 行，启停插件，全程无需手改配置文件。
安装：
`dsh plugin --profile web add <plugin-registry>/packages/plugin/console`