自托管服务装多了以后，最麻烦的地方不是找不到服务，而是每次打开都要重复做几件事。
先打开 Homepage，找到 UPS、DDNS 或证书管理，再打开终端，建立 SSH 隧道，回到浏览器输入本机地址。用完以后还要记得关掉终端。服务虽然有网页，访问方式却还停留在命令行阶段。
所以我做了 HomeTunnel · 家庭隧道，把 Homepage 的服务卡片、OpenSSH 的本地端口转发和 Bitwarden SSH Agent 接到了一起。现在从主页点卡片，客户端会建立隧道，网页随后在浏览器里打开。
Homepage 负责找到服务
我在 Homepage 里放了几类服务：Mac 上的 UPS Guard、DDNS 管理，云服务器上的证书服务，还有 NAS 管理页面。它们都显示成卡片，但访问方式并不一样。
已经有 HTTPS 和认证的网站可以直接打开；只在服务器本机监听的管理页面，则通过 SSH 隧道访问。这样不用为每个服务再开一个公网端口，也不用再维护一层反向代理。
Homepage 的服务卡片本身支持自定义链接。我在需要隧道的卡片上使用 hometunnel:// 协议，所以这件事不需要改 Homepage 的源码，其他能放链接的页面也可以这样接。
官方配置说明见Homepage Services。
从卡片到网页
以打开一个远端私有 Web 服务为例，实际过程就是：
- 在 Homepage 点击卡片。
- 浏览器把
hometunnel://connect?...交给 HomeTunnel。 - HomeTunnel 调用系统 OpenSSH，向 Bitwarden SSH Agent 请求签名。
- 在 Bitwarden 中批准这次密钥使用。
- 隧道建立后打开本机地址。
Homepage → HomeTunnel → OpenSSH → Bitwarden SSH Agent
↓
本机回环端口 ← SSH 隧道 ← 远端回环 Web 服务
Bitwarden 批准的是 SSH 认证时的签名请求。隧道建立后，网页里的操作仍按服务器账号和 Web 服务本身的权限执行。
如果是第一次连接，还需要先核对服务器主机指纹。登录公钥是“我是谁”，主机密钥是“我连到谁”，这两个东西不是一回事。HomeTunnel 不会自动接受未知主机，也不会因为主机密钥变化就直接放行。
密钥继续放在 Bitwarden
我之前已经把人工 SSH 私钥放进 Bitwarden，具体的密钥保管、Agent 接入和迁移过程，已经在《把 SSH 私钥交给 Bitwarden：为人工与智能体连接建立授权边界》中写过。HomeTunnel 只是沿用这套方式：客户端可以请求连接，但不读取私钥正文。
Bitwarden SSH Agent 给 OpenSSH 提供公钥和签名接口。私钥由 Agent 使用，SSH 客户端把签名交给服务器验证。我的设置是每次签名都提示授权，Agent 没解锁、没有对应身份或拒绝签名时，连接就失败。
HomeTunnel 关闭了密码和键盘交互回退，也关闭 Agent 转发。这样连接失败时不会悄悄换成另一种认证方式。
Bitwarden 的接入方法和授权选项以官方 SSH Agent 文档为准。
连接列表比终端窗口清楚
把隧道做成一个按钮，只解决了“怎么打开”。我还需要知道当前连着什么、什么时候到期，以及怎么断开。
HomeTunnel 的连接列表会显示服务名称、目标、端口映射、剩余时间和连接状态。每条连接可以打开网页、续期或断开，也可以一次断开全部连接。
我把默认有效期设为 30 分钟。需要继续使用时手动续期，到期后客户端关闭自己建立的隧道。重复点击同一个目标时，会复用已有连接，不会不停创建 SSH 进程。
Windows 版常驻托盘，macOS 版使用菜单栏。关闭窗口后，后台连接仍然可以继续管理；登录自启可以在设置中打开。
如果目标就是当前电脑上的服务，客户端会直接打开本机地址；如果已经有相同隧道，也会复用现有连接。这两种情况不一定再次弹出 Bitwarden，新的远端连接才会请求签名。
在 Homepage 加一张卡片
接入前，服务器需要已经安装对应公钥，SSH 允许本地端口转发，目标 Web 服务也要能从远端回环地址访问。
下面是一张实际使用方式的简化示例，域名和账号是虚构的：
- 私有管理:
- 示例管理页:
icon: mdi-shield-lock
href: "hometunnel://connect?host=server.example.com&user=alice&sshPort=22&port=18080&remotePort=8080&name=Private%20service&path=%2F&browser=default"
description: 通过本机 SSH 隧道访问
它表示：使用 alice 登录 server.example.com:22，把本机 18080 端口转发到远端回环地址的 8080 端口，然后打开根路径。
| 参数 | 用途 |
|---|---|
| host / user / sshPort | SSH 主机、账号和端口 |
| port | 本机监听端口，只绑定回环地址 |
| remotePort | 远端回环 Web 服务端口 |
| name / path | 连接名称和打开路径 |
| browser | 使用默认浏览器或受支持的指定浏览器 |
| fingerprint | 可选的 SSH 主机 SHA256 指纹 |
参数值需要进行 URL 编码。页面路径里如果还有查询参数，建议用 URLSearchParams 生成链接，避免和协议参数混在一起。真实的入口链接只放在受保护的 Homepage 里，不放到公开仓库或 Issue。
出问题时先看诊断
开发过程中遇到过几次“点了卡片却没有反应”。后来发现这条链路其实由几个独立部分组成：浏览器协议注册、桌面应用、OpenSSH、Agent、主机指纹和远端服务，任何一环都可能出问题。
运行诊断页会分别检查协议是否指向当前安装、登录启动是否登记、OpenSSH 是否存在，以及 Agent 能不能返回公钥。
我的排查顺序是：先看浏览器有没有调用 HomeTunnel，再看协议注册和 Agent 授权，之后检查主机指纹、端口冲突，最后确认远端 Web 服务是否响应。这样比反复点击同一张卡片快很多。
目前的使用边界
这套方式适合管理页面只在服务器本机监听的场景。SSH 服务器仍然是入口，服务器更新、账号权限和备份照常需要维护；隧道只是把访问路径收回到 SSH 连接里。
Homepage 登录、SSH 登录、Web 服务登录是三套权限。批准 SSH 签名不会代替 Web 服务自己的登录，主页账号也不会自动变成服务器账号。
HomeTunnel 做的是 SSH 本地端口转发，不是 VPN，也不负责 NAT 打洞。它需要一个本来就能访问的 SSH 服务。某些依赖固定域名、远端 HTTPS 或复杂跨域配置的 Web 应用，还需要单独处理。
目前 HomeTunnel v0.1.8 已提供 Windows x64 安装包和 macOS Apple Silicon DMG，项目使用 Rust、Tauri 2 和 Vite 构建。安装包和 SHA256SUMS 可在最新发行页获取。
项目地址：DongLiStudio/HomeTunnel。
对我来说，它解决的是一个很具体的问题：从 Homepage 打开自己的管理页面时，不再需要先找终端、敲命令、记端口，再回到浏览器。入口还是原来的入口，密钥也还是由 Bitwarden 管，日常使用少了几步。
