Lattice Docs

Appearance

Lattice 部署指南（个人/家庭模式） ​

适用: standalone 模式自托管部署（家庭局域网 + 出门访问） 读者: 自部署用户与家庭管理员 关联: docs/latticedns-technical.md（LatticeDNS 原理）、docs/superpowers/specs/2026-09-17-latticedns-design.md 合规摘要见 §七（自托管自用的边界；商业化运营需另行取得法律意见）

〇、一条黄金法则 ​

所有"下发给设备"的地址（信令、二维码、接入指引），必须是设备能访问到的地址——不是服务器自己的回环地址。

服务器上 127.0.0.1:18090 自己能打开，不代表手机能连上。本次真机联调的第一堵墙就是它。

一、端口与地址总表 ​

端口协议用途绑定
listen（默认 :8080）TCP管理 API + Web 控制台 + 入网二维码见 §二
4222TCPNATS 信令（设备注册/拓扑推送）所有接口
6266TCP/UDPLRP 中继（打洞失败时的兜底通道）所有接口
51820/udpUDPWireGuard 数据面（引擎，按需）引擎
3478UDPSTUN（如启用自有 STUN）配置

二、三个必须理解的地址 ​

名称配置键作用常见错误
监听地址listen / LATTICE_LISTENlatticed API 绑定的地址与端口绑定回环后局域网设备访问不了
信令地址signaling-url / LATTICE_SIGNALING_URL下发给设备的 NATS 地址⚠️ 留空时兜底 nats://127.0.0.1:4222——外部设备永远连不上
服务地址dashboard 的访问地址入网二维码编码的服务器地址用 127.0.0.1 打开控制台 → 二维码里也是回环地址

symptom 速查：App 点"连接"一闪回到"未连接" = 十有八九是信令地址问题（详见 §六故障表）。

三、三种典型部署拓扑 ​

拓扑 A：纯家庭内网使用（设备回家才用） ​

最简部署，无需公网、无需 VPS：

yaml
# lattice.yaml 关键项
listen: "192.168.1.8:18090"        # 绑定局域网地址（或 0.0.0.0）
signaling-url: "nats://192.168.1.8:4222"   # ⚠️ 必填：局域网可达的 NATS 地址
  • 设备（手机/电脑）连家庭 Wi-Fi，App 扫码/手动填 http://192.168.1.8:18090 加入；
  • 出门后回到家用 Wi-Fi 自动重连。

拓扑 B：出门随时可用 —— IPv6 直连（推荐，零暴露） ​

国内家宽与蜂窝网络 IPv6 普及率已很高。两端都有 IPv6 = 天然公网地址直连，无需打洞、无需中继。

要求：

  1. 家里宽带开启 IPv6（光猫改桥接/路由器开启 IPv6）；
  2. 家里设备（NAS/Mac）的防火墙放行 WireGuard 端口（51820/udp）给指定来源；
  3. 出门设备（蜂窝/Wi-Fi）同样具备 IPv6。

IPv4 兜底（无 IPv6 环境时）：路由器端口转发 UDP 51820 → 家里设备，或参考拓扑 C。

拓扑 C：出门随时可用 —— IPv4 + 自部署中继兜底 ​

  1. 路由器端口转发 UDP 51820 → 家里设备（IPv4 直连路径）；
  2. 打洞失败时的兜底：自部署 LRP 中继（lrper）到你有公网的 VPS：
bash
# VPS 上（有公网 IP）
./lrper --listen :6266

# 家里 lattice.yaml
relay-url: "你VPS的IP:6266"

合规边界：官方不运营任何中继节点；lrper 是自部署组件，使用者自行确保用途合规（不承载跨境信道、不面向公众提供服务）。商业化组网服务需电信业务牌照。

四、参考配置（带注释的 lattice.yaml） ​

yaml
# 管理/API 监听地址
listen: "127.0.0.1:18090"     # 仅本机访问控制台时用回环；需要局域网访问则绑 LAN IP

# ⚠️ 信令地址：下发给设备的 NATS 地址。必须留空以外的值——
# 留空时兜底 nats://127.0.0.1:4222，外部设备会连向它自己。
signaling-url: "nats://192.168.1.8:4222"

# STUN：留空时使用内置多服务器列表（自有 + 国内公共 + 全球双栈）。
# 如自建 STUN 可在此指定，将作为列表首位优先使用。
stun-url: ""

# LRP 中继（拓扑 C 的自部署中继）：none 时仅打洞直连
relay-url: ""

环境变量等价（viper 自动绑定，LATTICE_ 前缀）：LATTICE_LISTEN、LATTICE_SIGNALING_URL、LATTICE_STUN_URL。

五、入网二维码与服务器地址语义 ​

控制台「令牌页 → 行菜单 → 入网二维码」生成的码，编码内容为：

lattice://join?server=<控制台访问地址>&token=<令牌值>
  • 控制台地址 = 手机将使用的服务器地址。用 http://192.168.1.8:18090 打开控制台，码里就是局域网地址（回家 Wi-Fi 可用）；用 VPS 域名打开，码里就是 VPS 地址（出门可用）；
  • 二维码弹窗中会显示实际编码的服务器地址，出码前请核对其中的地址是手机可达的；
  • 同一令牌默认 7 天有效、最多 5 台设备使用（生成时可在控制台调整）。

六、故障对照表（真实症状 → 原因 → 处理） ​

症状原因处理
App 点连接一闪回到"未连接"信令地址是回环（127.0.0.1）设 signaling-url 为局域网/公网可达的 NATS 地址
扫码后无法连接 / 连接超时二维码里的服务器地址手机不可达用手机可达的地址重新打开控制台再出码
设备列表质量标签一直"连接中"探测对端不可达检查对端是否在线；满 60 秒转"不可达"
面板/列表无质量标签探测数据未就绪（刚连上 15 秒内属正常）等待探测周期；仍无则检查隧道是否已连接
退出网络后首页仍显示"登录后可查看设备"旧版本退出未删除 VPN 配置升级到包含 removeProfile 的版本后重新退出一次

七、合规边界摘要 ​

  • 自托管、自使用：合法（与 WireGuard/ZeroTier 等开源组网工具同类）；
  • 官方不运营任何中继/节点；lrper 为用户自部署组件；
  • 不承载跨境信道；面向公众的组网/通信服务需电信业务牌照；
  • 本文档为工程合规摘要，不构成法律意见；商业化前请咨询专业律师。

Built with Lattice · Console

© 2026 The Lattice Authors