人在公司,家里的 homelab 却连不上:Webapp 现在能直接借用桌面保存的网关


周三下午,会议室里只有你和一台借来的笔记本。你打开浏览器,敲进家里那台机器的 Webapp 地址,想看一眼 homelab 上跑着的定时任务——结果页面里只有本地这一个网关,桌面上明明存着三四个。你甚至能背出它们的名字:Homelab、工作笔记本、那台月付的 VPS。

这不是权限问题,也不是你没登录。过去 Webapp 只知道“服务这个页面的那台网关”,其余的保存在桌面应用自己的目录里,浏览器那一侧根本看不见。

11 月 7 日,一批提交把这件事翻了过来:保存的连接从“桌面应用的私有数据”变成“整台机器共用的一份存储”,Webapp 直接读同一份列表,并且能像桌面一样拨通其中任意一个。

一份文件,两个宿主

核心变化很朴素:桌面应用原来把连接登记表和原生 OAuth 登录信息放在 Electron 的 userData 目录里,现在它们搬到了 Hermes home 下、和 ui-preferences.json 并排的两个文件里:

  • gateway-connections.json:连接本身(名字、URL、SSH 主机、以及每条连接自己的 session token 和额外 header)
  • gateway-connection-tokens.json:OAuth 登录凭据,按连接 id 存

两个文件都是 0600、只有属主可读写。桌面主进程和 Webapp 的服务端一起写它们,读也是同一份,所以你在桌面里加一条 Homelab,浏览器那边刷新一下就在;反过来也一样,不用重启任何东西。第一次运行带共享列表的版本时,旧 userData 里的 connections.json、connection.json、native-oauth-tokens.json 会被一次性导入,连接的 id 保持不变,你不会看到重复条目。旧文件原样留着(老版本还能跑),但导入之后不再读取。

写入契约也值得一提,因为它是“两个宿主同时写”能成立的前提:写之前先抢一个 <store>.lock 目录锁,写完用临时文件 + rename 整个替换,解析不了的文件不会覆盖掉而是留成 .corrupt-<毫秒> 备查,只有文件不存在才被当成“没有存储”。

浏览器只跟一台网关说话

这是最容易误解的地方。Webapp 并不会让浏览器直接去连你那台 VPS——它做不到,也不该做。浏览器的所有请求和套接字仍然只发给服务这个页面的那台网关,由那台网关替你把请求转发给保存的目标:

  • token 模式:带上保存的 X-Hermes-Session-Token
  • OAuth 模式:带一枚会刷新的 bearer,WebSocket 握手另外用一次性 ticket
  • 任何连接上保存的额外 header 也一并带上

被连的那台远端不需要任何新配置——它看到的只是一个普通客户端。每条保存的连接会出现在 Webapp 的网关切换器和侧栏的网关分组里,你可以像桌面一样在它们之间切换、按 Gateway & profile 分组、拖动排序(改的只是侧栏标签,不动网关)。

OAuth 那条路也搬到服务端了:服务页面所在的那台机器自己跑 RFC 8252 的原生流程,PKCE verifier 握在它手里,浏览器被送到远端的 /auth/native/authorize,回来落在 /webapp/gateway-connections/oauth/callback。token 用远端的 /auth/native/refresh 轮换,同一条连接同一时刻只飞一个刷新请求;远端回 401 就判定登录失效,远端只是暂时不可达则保留登录。

如果你的浏览器不在服务这页面的那台机器上(这是常态——你在公司,网关在家),回调会落在你自己电脑的 loopback 上,服务端当然收不到。这时连接编辑器会给你一个粘贴框,把地址栏里那一串贴回去即可完成。

SSH 连接同样能在浏览器里用。服务端把桌面那条 SSH 路径整段移植了过来:一条 ControlMaster 到目标主机,在远端更新标记的互斥锁下以 serve --isolated --host 127.0.0.1 --port 0(外加 session token 文件和 owner nonce)拉起服务,再开一个只绑 127.0.0.1 的转发给中继用。所有权按本机这份连接存储划分,所以桌面和网关不会互相把对方的 serve 杀掉。这套只在 Linux/macOS 两端成立,远端或本机是 Windows 会被直接拒绝为不支持的平台。

先说清楚代价:谁能登录,谁就能用

这是文章里我最想让你停一下的地方。

Webapp 的信任边界是“能登录这个页面的人”。一旦有人能进你的 Webapp,他就能用这台机器上保存的每一条网关连接——以那条连接凭据的身份。官方文档写得毫不含糊:只保存你愿意让这些人访问的网关。

把损失控制在“看得见但拿不走”的部分,靠的是这些约束:远程返回的内容跑在沙箱 CSP 下,浏览器不缓存(no-store),不能把页面重定向到那台网关之外;中继不保留 cookie jar;删除一条连接会立刻关掉它已打开的套接字。

五个曾经能把凭据串出去的边角

这批改动里有一半是修 bug,而且修的都是同一类问题:凭据和它该去的地址对不上。这部分比新功能更有教学价值。

一、拨号时读了两次。 以前拨号先读连接的 URL,再按 id 去读 token、header 和 OAuth 登录信息。如果两次读之间有人改了这条连接,就会出现“老地址配新凭据”。现在 store 一次读就交出一份拨号快照(entry、URL、token、header、以及绑定该 URL 的登录信息),token 模式按快照的 URL 拨,OAuth 的 ensure_access_token 会把 token 和签发它的地址一起返回,套接字 ticket 也只由它真正要拨的地址签发。

二、OAuth 登录没绑定签发地址。 token set 以前只按连接 id 存,而 id 是从标签生成的 slug、会被复用。改一次 URL,或者删掉再同名重建,中继就可能把 A 主机的 bearer 发到 B 主机,甚至把 A 的 refresh token POST 到 B 的 /auth/native/refresh。现在每个 set 自带签发它的 baseUrl;地址对不上就读作未登录,刷新也只发往自己的 URL。任何删除连接或改动 url/authMode 的写入,都会在桌面和 Webapp 两侧同时丢掉这份 set。

三、跨站能借你的中继发请求。 Webapp 的会话 cookie 是 SameSite=Lax,所以一次跨站的顶层导航到 /api/relay/<id>/<path> 也会带上它,中继就会用保存的凭据替那个页面发出 GET。响应是沙箱化的、读不到内容,但一个带副作用的 GET 已经执行了。现在只要 Sec-Fetch-Site 存在且不是同源,请求在发出之前就被 403 掉;页面自己的 fetch 和不带 Fetch Metadata 的老客户端照旧。

四、把回调粘给了错误的连接。 粘贴回调那条路径以前先兑换 code、把 token 存上去,之后才比对路径里的连接 id 与这次登录流程的连接。现在先在登录流程的锁下匹配,粘错连接的回调直接 400,一个 token 请求都不会发,那条连接原本的登录流程还留着可用。

五、克隆和导出把明文 token 带走了。 hermes profile create --clone-all 会把这两个机器级 store 一起拷进克隆,随后 hermes profile export 就带着明文 session token 出门——因为导出擦除器不认 {"encoding":"plain","value":…} 这种信封。现在两个 store 都进了 PROFILE_CREDENTIAL_PATHS,克隆会跳过它们和它们的 .lock 目录,导出时按信封逐个打码。

顺便回答一个常见疑问:为什么这些 secret 是明文躺在文件里,而不是进系统钥匙串?因为 Webapp 的服务端必须读得到它们——钥匙串对服务端进程不成立。保护手段就是 0600 的文件权限加上“渲染进程和插件永远看不到 token 字节”这条边界(插件 SDK 的 host.connections() 只返回标签、类型和 primary id)。老版本用 safeStorage 加过密的 secret,会在导入时解一次;解不开的那条不会被丢弃,而是原样保留并记进文件的 importNotices,等桌面的钥匙串下次能应答时再转成明文。

怎么用

桌面端和 Webapp 是同一条路径,因为页面是同一个:Settings → Gateways。往下滚到 Registered gateways,点 Add connection,选类型:

  • Local:这个应用管理的本地运行时(应用托管,删不掉)
  • Remote gateway:一个跑着的 hermes serve,填 URL,认证选 session token 或 OAuth
  • SSH:填 user@host:22 这种复合字段,可选填远端的 hermes 可执行文件全路径
  • Hermes Cloud:走 Portal 登录与发现流程,不手填 URL

存完点 Test。它探的是这条连接自己的 HTTP 和 WebSocket 两条腿——所以“Reachable”意味着真的能聊天,不只是端口通。在 Webapp 里对一行 SSH 连接点 Test,会开出网关自己用的那条受管隧道,顺带把远端的 hermes serve 拉起来(或者复用已在跑的);这条隧道不会被主动清理,它会在你删除连接、停掉网关,或者远端空闲超过 dashboard.ssh_isolated_idle_grace_s(默认 15 分钟)且无客户端、无任务时自己停。

重复项在保存时就被拒:本地条目永远只有一条;remote 与 cloud 按规范化后的 URL 去重(跨类型,所以云条目和远程条目不能指向同一个 URL);SSH 按 user@host:port 加远端 profile 去重。

什么时候能用到

诚实地说:现在还不能,如果你用的是官方 release。这些提交合在 11 月 7 日,而 v0.23.0 是 11 月 5 日发的——它们都在 main 上,不在任何 tag 里。hermes update 拿到的是 release,所以你得等下一个版本,或者跟 main。

更新(2026-11-10):这批改动已随 v0.23.1 发布(2026-11-09),hermes update 升级即可用。上文「不在 v0.23.0 里」仍然成立,v0.23.1 把缺口补上了。

在那之前,桌面版的保存连接一直是好用的(它已经存在一段时间了,相关说明见 多网关桌面指南)。这次改的是“浏览器那一半终于不再是二等公民”。

如果你的远程网关登录一直卡在 loopback 回调和跳板机上,之前那篇 远程服务器上怎么完成 OAuth 讲的三种路子仍然成立;这次的新东西是服务端替你跑完了整套 native flow,还能在回调落错机器时让你把地址贴回来。

一句话总结

保存的网关连接从“桌面应用的私事”变成了“这台机器的公共设施”:一份 0600 的 JSON、两个宿主同时读写、浏览器只跟服务端网关说话、凭据由服务端按地址绑定后转发。新能力本身不复杂,真正值钱的是那五个修复——它们说明“把凭据发给谁”这件事,一旦允许编辑和多宿主并发写,处处都是坑。

相关命令与配置说明见站内的 hermes gateway 命令参考,桌面端的界面模式可以看 Desktop 界面模式指南。