前言¶

DeepSeek Harness（DSH）的 Web GUI 默认只监听回环地址（常见为 127.0.0.1:3080），不会在局域网直接暴露管理界面。若想在同一子网里用浏览器打开 GUI，简单做端口转发往往不够：GUI 会校验 Host / Origin，还要求带启动 token 或合法的 HMAC 会话 cookie。下面介绍的 mira_proxy 是社区插件，由 Stella-Mira 维护，分类为 admin-security；它在 DSH 插件进程内起一个带 TLS 与 HTTP Basic 认证的反向代理，改写请求头并向上游注入签名 cookie，使局域网可通过 HTTPS 访问 GUI，WebSocket 隧道也可直通。

这是什么¶

mira_proxy 的定位是：随 DSH 加载时在插件内启动反向代理，把只监听回环的 DSH Web GUI 变成局域网可访问的 HTTPS（或可选明文 HTTP）入口。设计与同仓库生态里的独立进程版 reverse-proxy 一致（同一套 cookie 复刻思路），差别在于落地方式——本插件无额外进程，配置写在 profile 的插件行 config: 里，证书缺失时会自动现签（SAN 覆盖 localhost、机器名与各网卡 IPv4）。默认监听 8543，上游 http://127.0.0.1:3080，与独立进程版默认 8443 错开。

浏览器  https://192.168.x.x:8543 ──TLS + Basic 认证──▶ http://127.0.0.1:3080
                                                              DSH Web GUI（只监听回环）

插件源码与说明见 GitHub，社区目录页：skillhub.cn/plugins/Stella-Mira/mira_proxy。DSH 社区目录是独立站点，与 DeepSeek / 幻方无官方从属关系；安装前请自行查看源码与 MIT 许可证（package.json 标注版本 0.2.0）。插件以当前 DSH 进程权限运行，启用后会在 0.0.0.0:8543（默认）对外监听，部署前应评估本机防火墙与子网暴露范围。

为什么需要 HTTP 反代而不是四层转发¶

DSH GUI 对 /api 有两道关卡：

1. Host/Origin 信任：Host 须为回环或显式 --trusted-host；带 Origin 时必须与 Host 同源；sec-fetch-site: cross-site 会被拒绝。
2. 浏览器会话：入口 URL 常带每次启动的 ?token=，或换用绑定 authority、约 30 天有效期的 HMAC 签名 cookie。

netsh portproxy 一类四层转发无法改写 Host、也无法替浏览器持有合法上游 cookie。mira_proxy 则：

• 将上游请求的 Host 改写成 127.0.0.1:3080，对本站点相关的 Origin 一并改写；外来 Origin 原样透传，跨站请求仍由 GUI 拒绝。
• 从 $DSH_HOME/.credentials.yaml（及插件配置中的 auth.credentialsFile / auth.credentialsKeyId）读取持久化签名密钥，每个上游请求现签合法 dsh-auth-* cookie，无需重启 GUI 或到终端抄启动 token。

认证后的 WebSocket（如 /api/remote.mux）走原生 Upgrade，README 说明实测可得到 101 与隧道内双向数据。

核心功能¶

• TLS + Basic 认证：默认 HTTPS 自签证书；tls.enabled: false 须显式关闭，不会自动降级为明文。
• Host/Origin 改写与每请求注入上游会话 cookie（复刻 Harness 的 HMAC 构造）。
• 代理自有会话 cookie（mira-proxy-auth）：Basic 通过后浏览器凭此访问，可续期、可撤销，与上游 dsh-auth-* 分层处理，代理侧 cookie 不会转发给上游。
• 配置热重载（改 lib/ 下代码需重启 DSH，宿主会缓存模块实例）。
• 只读状态工具 mira_proxy_status：监听情况、证书、账号数（不含口令）、cookie 剩余天数、弃用配置键、启动失败原因等；刻意不提供会改运行状态的 restart/revoke。
• 回环健康检查 /__proxy/health（默认仅回环可访问）。
• 启动失败可诊断：端口占用会尝试给出 ss/lsof 线索；配置非法（明文口令、错误哈希等）直接拒绝启动。

本版只支持单用户语义：多账号共享同一上游 authority 与同一枚代理 cookie；配置多个 auth.users 不会拒绝启动，但会 warn 并在状态中标记 multiUser。

安装与启用¶

在 DSH 会话中安装本地 bundle（等价于 UI 装本地包）。安装命令以 README 为准：

# 在 DSH 会话里让 agent 执行（等价于 UI 里装本地 bundle）：
#   plugin_manager install_bundle  target = <插件源码目录>/mira_proxy

插件通过 cordis.patch.yml 向 profile 插入一行（id mira-proxy，name mira_proxy）。启用或停用直接改 profile 中对应插件行。全默认时可写：

- id: mira-proxy
  name: 'mira_proxy'
  config: {}          # 全默认：https://0.0.0.0:8543 -> http://127.0.0.1:3080

需要改监听或上游时使用嵌套结构，例如：

  config:
    listen:  { host: 0.0.0.0, port: 8543 }
    upstream: { host: 127.0.0.1, port: 3080 }

数据目录（DSH_HOME 缺省为 ~/.dsh）：

$DSH_HOME/mira_config/mira_proxy/
  data/proxy-cert.pem    自签证书（缺失时自动现签）
  data/proxy-key.pem     私钥（600）
  data/webapps.htpasswd  Basic 口令表（可选）
  cookies.json           代理会话记录（600）
  cookie-secret.key      代理 cookie HMAC 密钥（600）
  logs/proxy.log         访问日志

0.1.x 曾使用 <.dsh>/plugin-data/mira_proxy/，本版不会自动搬迁；若旧目录有数据，启动时可能 warn 并给出 mv 建议。

典型用法¶

1. 配置 Basic 账号¶

口令表为 Apache $apr1$ 或 {SHA}；bcrypt 格式只识别不校验。可将现有 htpasswd 放到默认路径：

cp /path/to/webapps.htpasswd ~/.dsh/mira_config/mira_proxy/data/webapps.htpasswd

文件变更无需重启，下次请求按 mtime/size 重读。也可在配置中内联哈希，例如 auth.users: { "dsh-user": "$apr1$xxxx$...." }；明文口令会被拒绝启动。

若没有任何账号，插件会 warn：局域网访问将一律 401（默认安全姿态）。

2. 局域网访问 GUI¶

DSH 与插件正常启动后，在同一子网设备浏览器访问 https://<本机局域网 IP>:8543（或 https://localhost:8543）。首次会遇自签证书告警；通过 Basic 认证后即可使用 GUI，无需手动拼接 ?token=。

仅本机使用时可将 listen.host 设为 127.0.0.1；要对局域网开放保持默认 0.0.0.0，并建议在防火墙上限定本子网入站。

3. 查看状态与日志¶

• 会话中调用工具 mira_proxy_status 查看入口、上游、证书与 cookie 概况。
• 访问日志：$DSH_HOME/mira_config/mira_proxy/logs/proxy.log（超过 log.maxBytes 默认 5MB 轮转为 .1）。
• 本机回环请求 GET /__proxy/health 可查看监听、上游、账号数、证书有效期等（默认不对局域网开放）。

撤销所有代理侧 cookie：改 Basic 口令、删除 cookie-secret.key 后重启，或调用文档中的 generation 机制；插件不提供静默 revoke 工具以免 agent 误关入口。

配置要点¶

config: {} 即可运行。常用字段摘要（完整表见 README）：

旧扁平键（如 listenHost、listenPort）仍兼容但会记日志与 deprecated 状态，建议改为新结构。上游须为 HTTP 回环服务；HTTPS 上游未实现。

适用场景与注意¶

适合：需要在局域网手机或另一台电脑上操作 DSH Web GUI，且希望 TLS 与 Basic 作为第一道门，同时避免手工处理 Host/Origin 与启动 token 的开发者或运维。

注意：

• 能过 Basic 的人经代理注入 cookie 后就能使用 GUI；跨站请求仍受 GUI 的 Origin 检查保护，插件不会伪造 Origin / sec-fetch-site。
• tls.enabled: false 时口令与内容明文在网络上暴露，仅适合完全可信内网。
• $DSH_HOME 在不同工具中语义可能指数据目录本身或其父目录；插件通过 kit.dshHome() 与 credentialsDir() 按文件存在性定位，具体路径以 mira_proxy_status.baseDir 与启动日志为准。
• 修改 lib/ 后必须重启 DSH；停用再启用或重装 bundle 可能仍执行旧模块。
• README 注明正式跨机访问建议用手机或另一台电脑自测一次；换网段或机器名后删除 data/proxy-cert.pem 与 data/proxy-key.pem 可触发重签。

插件仓库提供 smoke 自检：cd mira_proxy && node test/smoke.m（README 自检一节）。

结尾¶

mira_proxy 把「回环 GUI + 严格 Host/会话规则」收敛成一条可配置的 HTTPS 入口：随 DSH 启停、自动补证书、改写头并注入上游 cookie，Basic 与代理自有 HMAC cookie 分层管理。若你在 DSH 生态里做远程或局域网管理界面暴露，可在安装前阅读源码，再从目录页或 GitHub 获取 bundle。

• 目录页：https://www.skillhub.cn/plugins/Stella-Mira/mira_proxy
• GitHub：https://github.com/Stella-Mira/mira_proxy