1. 问题：服务在私网，客户端在局域网#

服务按“最小暴露”原则只绑私有地址。公网请求由 VPS 的 Nginx 经 WireGuard 转发进来，路径是通的；但同一个局域网里的笔记本、平板、手机直连主机的 LAN 地址时，目标端口上没有 listener，连接会被拒绝。

绕公网也不是不行，只是体验差：

• 每个请求都要经过 Cloudflare 边缘、Tunnel、VPS、WireGuard，往返次数多；
• 公网链路受运营商和隧道状态影响，延迟不稳定；
• dsh 的 WebSocket、Paseo 的流式输出会把这种抖动放大成“打字有延迟、滚动卡顿”。

所以需求很明确：在同一局域网内，用稳定的名字和原端口直连服务，不经过公网。

2. 约束：为什么不能直接改绑定#

最直接的做法是让 dsh、Paseo 改绑 LAN 地址，但这条路走不通：

还有一个隐含约束：局域网入口不能成为新的公网入口。它只能监听 LAN 地址，不能监听 0.0.0.0，也不能监听 IPv6。

3. 设计：一层只服务局域网的 TCP 入口#

方案是在业务服务前面加一层只监听 LAN 地址的 TCP 入口：

1
局域网浏览器
2
  http://homebox.local:PORT
3
        │
4
        ▼
5
  lan-bridge（LAN_IP:PORT）
6
        │  TCP 原样转发
7
        ▼
8
  WG_IP:PORT（本机回环，不进隧道）
9
        │
10
        ▼
11
  dsh / Paseo / Immich / ...

实现上是一层 nginx stream：

• 监听 ${LAN_IP}:${PORT}，地址由启动脚本写入环境文件，容器启动时渲染模板；
• 转发到 WG_IP:${PORT}，也就是主机自己的私有地址，端口不变；
• 容器使用 network_mode: host，因为它必须精确绑当前 LAN 地址。Docker 的端口发布默认会绑 0.0.0.0，还可能带 IPv6，这正是要避免的；
• 只监听 IPv4 的 LAN 地址，不监听通配，不监听 IPv6。

公网路径保持不变：

1
浏览器 → Cloudflare → Tunnel → VPS Nginx
2
        → WireGuard → WG_IP:PORT → 服务

两条路径在主机上汇合到同一个服务监听地址。业务服务不需要为两条路径做区分，它只看到发往自己监听地址的连接。

4. 三个关键事实#

这个设计能成立，靠的是三个经常被忽略的细节。

1
ip route get WG_IP
2
# local WG_IP dev lo src WG_IP

5. 两条路径的对比#

两条路径不是互相替代，而是分别覆盖“在家里”和“在外面”。公网入口负责可达性，局域网入口负责体验；安全责任都落回各服务自己。

6. 换网之后：地址对账#

lan-bridge 绑的是“当前 LAN 地址”，不是固定 IP。换网、搬家、路由器重新分配地址之后，需要重新绑。

这个动作交给一个幂等脚本：

1. 从默认路由取源地址：ip -4 route get 1.1.1.1，取输出里的 src；
2. 校验：必须是 IPv4，拒绝 0.0.0.0、127/8 和 WireGuard 网段；
3. 和运行中容器里的 LAN_IP 比较；
4. 相同且容器在运行 → 直接退出，不动 Docker；
5. 不同 → 写 .env（权限 600）→ 只重建 lan-bridge 容器；
6. 等待端口可连接后退出。

再配一个每分钟触发一次的 systemd user timer，网络变化后最迟一分钟自动恢复。只有 lan-bridge 会重建，dsh、Paseo、Immich 这些业务服务不受影响。即使重建失败，影响的也只是局域网入口，公网路径仍然是好的。

UFW 按来源网段放行。换网段后要单独更新一次防火墙规则；这一步需要 sudo，不会由 timer 自动完成。手动指定地址也很简单：

1
# 显式指定时，把地址换成当前 LAN 地址
2
LAN_IP=192.0.2.10 ./scripts/lan-bridge-up.sh

7. 为什么用 stream 而不是 http#

用 nginx 的 stream 而不是 http 反代，是为了“什么都不改”：

• TCP 字节原样转发，浏览器发的 Host 头原样到达后端；
• WebSocket 的 Upgrade 自动透传，不需要额外配置；
• 上传大小、流式输出不受 HTTP 层 client_max_body_size、缓冲和超时的影响；
• 新增服务时只需要加一个 server 块，不需要为每个服务调一遍代理参数。

代价是失去了 HTTP 层的认证、限流和路由能力。这些必须由服务自己负责；日志也只能记录 TCP 级的来源、端口、时长和字节数。对“只服务可信局域网”的定位来说，这个交换是合理的。

8. 安全边界#

lan-bridge 的便利性来自“信任局域网”，所以边界必须说清楚：

• 只监听 LAN IPv4。 不做路由器端口转发，不把入口开到公网；公网仍然走 Cloudflare + Access。
• 传输是明文 HTTP。 Cookie、口令在局域网内可能被嗅探；只用于自己信任的网络。
• Access 不生效。 局域网直连不经过 Cloudflare，认证完全由各服务自己负责。dsh、Paseo 这种能执行 shell 的界面，尤其不能开到不可信网络。
• Host 白名单要同步。 dsh 的 /api 有 Host/Origin 白名单，必须把 mDNS 名字加进去；用 IP 访问 API 可能返回 403。Paseo 的 hostnames 只写主机名，端口会被去掉。
• Cookie 作用域要检查。 同一主机不同端口共享 Cookie 作用域；新增服务时要注意 Set-Cookie 名字是否冲突。
• 日志也是数据。 访问日志包含来源 IP、端口和时长，按敏感数据保护，不要随手贴出去。

如果当前网络不可信（公司 Wi-Fi、公共热点），不要启用这个入口。用 VPN 或公网入口更合适。

9. 不选其他方案的原因#

这些方案不是“不能用”，而是都不满足“不改业务、不重启、不暴露公网”这三个条件。

10. 故障排查与回滚#

验证时看三件事：

1
# 两个地址应该同时存在
2
ss -ltn | grep ':PORT '
3

4
# 从局域网客户端验证，显式绕过代理
5
curl --noproxy '*' -4 http://homebox.local:PORT/
6

7
# 证明局域网请求没有进隧道
8
sudo tcpdump -ni wg0 port PORT

回滚也很简单：停掉 timer 和 lan-bridge 容器，移除 dsh / Paseo 白名单里的 mDNS 名字即可。公网路径和业务容器都不受影响。

11. 小结#

lan-bridge 的核心不是“再加一个 nginx”，而是把**“从哪来”和“到哪去”分开**：

• 业务服务继续只绑私网地址，不为局域网改变自己的暴露面；
• lan-bridge 只服务局域网，按当前 LAN 地址和原端口转发；
• 公网入口保持原样，继续由 Cloudflare、VPS 和 WireGuard 负责。

它的“特化”体现在几个很具体的选择上：只绑一个具体地址、只监听当前 LAN IPv4、保持原端口、用 TCP 透传而不是 HTTP 解析、用幂等脚本和 timer 做地址对账。代价是明文传输和绕过 Access，所以它只适用于可信局域网。

这套设计不追求“一套入口解决所有场景”。相反，它承认公网和局域网是两种不同的访问需求，然后用两层入口分别满足，边界反而更清楚。

相关阅读#

• 浏览器里的开发工作台：dsh 与 Paseo 的部署与日常
• 家庭服务器的服务清单：监控、密码库与密钥管理