@iasiv5/dsh-obmc-web

在 DSH GUI 里使用 BMC Web UI（OpenBMC / bmcweb，AST2700 EVB 实测； 插件本体于 DSH Web 0.1.7-rc.2 实测）。 host 半身在 DSH web 服务器的 GUI origin 上注册一组同源代理路由，经 obmc-web-relay.service（SSH 本地转发，仅绑 127.0.0.1，端口默认 18443、被占自动顺延）抵达 BMC；client 半身仿照 dsh-surf，在「设置」 菜单位注册一个 BMC 控制台 启动面板：显示隧道状态芯片与当前 BMC 地址，一键在顶层标签页打开控制台，并支持 BMC IP 变化后的 SSH 自动 探测与隧道重定向。

控制台不放进侧边栏 iframe：公网入口的 dsh-auth-caddy 给所有响应盖了 X-Frame-Options: DENY，因此面板用 window.open 做顶层导航（XFO 不约束顶层页面）。登录仍在 BMC 自己的页面里完成，本插件不经手凭据。

浏览器 ── GUI origin (/bmc, /js, /css, /redfish, /login, /logout, /kvm·/console WS)
   └─ dsh web server (127.0.0.1:3080) ── @iasiv5/dsh-obmc-web host 路由
        │                                （剥 XFO/HSTS/WWW-Authenticate/frame-ancestors）
        └─ obmc-web-relay.service (ssh -N -L 127.0.0.1:<relay端口> → $BMC_TARGET)
             └─ BMC (bmcweb, hash 路由 SPA)

面板一览

「设置 → BMC 控制台」从上到下：

• 状态芯片：整个面板共享一次轮询，每 15s 打一次 /bmc-status?probe=1 （探测轮进行中改为 2s），实测隧道后显示：隧道在线 / 正在 SSH 探测 / DSH 会话已过期 / 可达但响应异常 / BMC 不可达；保存配置、探测 IP、 安装 relay 这类影响隧道的动作完成后会立即重新探测，芯片在 1~2s 内 跟上动作结果，不必等下一个轮询周期；
• 当前 BMC IP 与最近一次探测结果（找到的地址、时间、是否已切换并验证）；
• 部署配置表单：五个等宽输入框（SSH 跳板机、SSH 端口、BMC 地址、 网段、relay 本地端口），加 保存配置 / 探测 BMC IP / 安装并启动 relay 服务 三个动作与 relay 运行状态一行；
• 打开 BMC Web 控制台：顶层标签页打开；尚未配置 BMC 地址时置灰。

为什么是这些路由

bmcweb 的 SPA 以根绝对路径引用资源与 API（/js/…、/css/…、/redfish/…、 /login、/logout；KVM/串口走 /kvm、/console WebSocket），且路由为 hash 模式，因此挂在 /bmc 前缀下不会与 SPA 内部导航冲突。DSH web 服务器 按「精确表优先、前缀最长者胜」分发，GUI 自身的路由永远优先；重复注册只 跳过、不会让插件失败。

安装

# 任意目录执行即可（dsh plugin 把参数转发给 profile 目录里的 pnpm）
dsh plugin --profile web add @iasiv5/dsh-obmc-web

然后重启 dsh web。「设置」菜单里会出现 BMC 控制台 面板。

本地开发可用 link 方式直装源码：

dsh plugin --profile web add link:/path/to/dsh-obmc-web

配置

推荐方式：全部在网页里完成。 首次安装后打开「设置 → BMC 控制台」， 展开「部署配置」表单：

1. 填 SSH 跳板机（user@host；与 BMC 链路网段相通、已配好对本机 BatchMode 免密登录的机器）与 SSH 端口；BMC 地址可以留空； 链路网段、relay 本地端口（默认 18443）均可留空用默认；
2. 点 「探测 BMC IP」——先保存表单，再 SSH 登录跳板机自动发现 bmcweb 地址并回填；BMC IP 被 DHCP 改变后，也用同一个按钮（此时显示 「重新探测 IP」）重新找回并切换隧道；同一时刻只有一轮探测在跑；
3. 点 「安装并启动 relay 服务」——插件按当前配置生成 ~/.config/systemd/user/obmc-web-relay.service，daemon-reload 并启动， 隧道验证通过后报告；若配置的 relay 端口被其他程序占用，会自动顺延到 空闲端口并提示。之后升级配置也用同一个按钮。

保存配置单独说明：表单立即写入 env 文件并生效；若 BMC 地址或 relay 端口发生变化且 relay 正在运行，会自动重启 relay 并验证隧道，结果随保存 响应返回（首次保存、只改跳板机等不影响隧道的编辑不会重启 relay）。

手动方式（高级）：配置实际存储在插件与 relay unit 共用的 KEY=VALUE 文件 ~/.config/systemd/user/obmc-relay.env（可用环境变量 OBMC_WEB_ENV 改位置）。首次启动若文件不存在，插件自动生成一份全注释 的模板（含说明与文档示例地址）；手改后重启 dsh web 生效。模板见 deploy/relay.env.example；手工安装用的 unit 示例在 deploy/obmc-web-relay.service.example（一般用不着——面板按钮会生成）：

| 键 | 必填 | 说明 | |---|---|---| | BMC_TARGET | 是* | 当前 BMC 地址 ip:port，relay unit 的 ExecStart 消费；自动探测会原地改写此行（保留其他键）。表单保存与探测都会补全成 ip:443——手写时请务必带端口，ssh -L 的转发目标需要 host:port 形式。*可用「探测 BMC IP」自动发现 | | OBMC_SSH_TARGET | 探测必填 | 跳板机 SSH 目标 user@host（BatchMode 免密）；不配则探测关闭，代理不受影响 | | OBMC_SSH_PORT | 否 | 跳板机 SSH 端口，默认 22 | | OBMC_SUBNET | 否 | 探测网段 a.b.c；缺省先取 BMC_TARGET IP 的 /24，连 BMC IP 都没有时，探测会在跳板机上自动枚举直连 IPv4 网段逐个扫 | | OBMC_RELAY_PORT | 否 | relay 本地监听端口，默认 18443，需与 relay unit 的 -L 参数一致（面板的安装按钮会保持两者同步） |

代码本身不含任何站点相关默认值——你的网络拓扑只活在这份配置里（表单 和 env 文件是同一份数据的两个入口）。真正必须由人类提供的只有跳板机 这一项；DSH 自身的 3080、公网反代端口等属于 DSH/网关层，与本插件无关， 无需在此配置。

BMC IP 自动探测

BMC 地址常由跳板侧 DHCP 动态分配，可能变化。当隧道目标失联（代理上游 报错，或 /bmc-status?probe=1 实测失败）时，插件自动 SSH 到跳板机定位 bmcweb 实际地址：先查 dnsmasq 租约表 + ARP 表（单纯换址时亚秒级返回）， 不通再对候选网段做 TCP-443 扫描；候选地址以 /redfish/v1 应答做指纹 校验（200 需带 "RedfishVersion" 服务签名；401 保留原判；当选后的 TLS 证书另经 TOFU 钉扎，见「安全说明」）。探测网段的确定顺序：配置的 OBMC_SUBNET → BMC_TARGET IP 的 /24 → 跳板机自身枚举的直连 IPv4 网段。找到后写回 env 文件的 BMC_TARGET 行、经 user manager 重启 relay，并通过隧道验证后才报告成功；若 relay unit 尚未安装（首次 bootstrap），地址仍会写入配置并提示下一步去点「安装并启动 relay 服务」。SSH 层失败（地址/端口/免密）会透出真实原因，不会伪装成 「未发现 bmcweb」。触发方式：

• 手动：部署配置里的「探测 BMC IP / 重新探测 IP」按钮（POST /bmc-status），不设冷却，但同一时刻仅一轮；
• 自动：代理上游报错时触发，自带 60s 冷却。

安全说明

• 上游仅 127.0.0.1（SSH 隧道，端口默认 18443），不新增任何公网监听。
• 剥掉的响应头：X-Frame-Options、Strict-Transport-Security、 WWW-Authenticate（防止 bmcweb 的 401 Basic challenge 弹浏览器原生 凭据框；BMC SPA 走 POST /login JSON + cookie）、Clear-Site-Data （bmcweb 登出会发 Clear-Site-Data: "cache","cookies","storage"，语义 是清空整个源的 Cookie 与存储——在同源代理下会连带清掉 GUI 自身的会话 Cookie，把 DSH 一起登出；BMC 侧登出不受影响：显式的 SESSION= 过期 Set-Cookie 照常透传，服务端会话照常销毁），CSP 仅移除 frame-ancestors 指令；其余响应头原样透传。
• 上行 Cookie 白名单（0.1.3 起）：GUI 源的 Cookie 不再整串透传给 BMC——只有 bmcweb 自己的 SESSION / XSRF-TOKEN 允许跨隧道，其余 （尤其 DSH 会话 Cookie __Host-dsh_auth_session）在上行前剥离， BMC 这个信任域永远收不到 DSH 会话。
• BMC TLS 证书 TOFU 钉扎（0.1.3 起）：隧道对端的自签证书按 BMC_TARGET 记录 SHA-256 指纹（~/.config/systemd/user/obmc-relay-trust.json， OBMC_WEB_TRUST 可改址），首次见到即钉扎；此后指纹不符的交换会被 502 拒绝、旧指纹作废、下一次请求重新钉扎——静默中间人最多拿到一次 被拒的交换，且拿不到 Cookie。BMC 侧重生成证书同样自动重钉扎；如需 彻底重置删除上述文件即可。WS（KVM/控制台）路径同受保护——顺带修复 了该路径调用不存在的 https.connect 导致首个升级请求即崩的问题。
• 非 /login 的上游 401 统一降级为 403：BMC SPA 的 axios 拦截器对其他 401 会执行 window.location = "/login"——根绝对路径的顶层导航，在 同源代理下会逃出 /bmc 前缀，落到 GUI 自己的 /login 并被认证门 重定向进 DSH 应用，把用户从 BMC 控制台拽走（首次打开最常见）。403 走 SPA 的原地「未授权」提示，不发生导航；/login 的真实 401 保留 （登录表单错误处理与 CSRF 探测依赖它）。
• 不在任何地方存储 BMC 凭据；登录在 BMC 自身页面完成。
• 信任围栏仿照 dsh-better-sidebar 的 trust-fence（Host 必须是 loopback 或部署信任的 authority、Sec-Fetch-Site 不得为 cross-site、Origin 若有 必须与 Host 同 hostname）——这是 DNS-rebinding 防御，不是认证；真正的 访问控制由部署在 GUI 前面的既有网关承担。
• 已知取舍：代理内容与 GUI 同源（bmcweb 需要 Cookie 登录，无法用 opaque-origin sandbox）。信任级别等同于在浏览器同站打开 BMC 页面。

License

MIT