Nebula static_host_map：灯塔无法提供的地址

每座灯塔都能告诉主机其他所有对等节点的信息，唯独无法提供灯塔自己所处的地址。有些信息必须在 overlay 存在之前就已知，Nebula 把这些信息放进一张小地图。地图把 overlay 身份与一个在普通网络中可用的地址配对。此后学到的一切都取决于这个配对是否正确。

两个地址，两种职责

每台 Nebula 主机都拥有一个 overlay 地址，设备在网络之间移动时它保持不变。这个地址是证书、防火墙规则和对等关系所使用的身份，单靠它无法路由到任何地方。可达端点是另一回事：底层网络上的主机名或地址加上一个 UDP 端口，一旦机器换了位置它就会改变。静态地图就是两者之间的接合处。

地图中只应放入必须冷拨的主机，通常就是灯塔，也许再加一个中继。让这份清单保持简短是设计目标，因为每一条手工记录都会变成必须有人维护的事实。混淆两种地址是常见的配置错误：放进灯塔清单里的公网地址并不会启动发现。

身份放在该放身份的地方。可达性放进地图。

static_host_map:
  "10.42.0.1": ["lighthouse-01.example.net:4242"]

lighthouse:
  am_lighthouse: false
  hosts:
    - "10.42.0.1"

地图条目的结构

键是写成带引号字符串的 overlay 地址，值是一个端点列表，因此一个身份可以有多个入口。每个端点都带有主机和端口，端口必须与对端实际监听的端口一致。Nebula 的默认值是 UDP 4242，这只是起点，并不是对你部署的承诺。

当一座灯塔有多条进入路径时，多个端点很有用，例如一个公网地址和一个供同一网段主机使用的私网地址。客户端会按顺序尝试，所以把最可靠的那个放在前面。对 IPv6 来说，要在追加端口之前把地址放进方括号；弄错会产生一个指向错误行的解析错误。

端口错了只会得到沉默而不是错误，因为 UDP 没有可以拒绝的握手。因此值得对照 Nebula 的 static_host_map 参考文档 去检查条目格式，而不是凭记忆。参考文档还涵盖端点列表和 DNS 刷新行为。

引导必须在 overlay 之前生效

地图中的 DNS 名称必须通过主机在任何隧道存在之前就拥有的解析器来解析，也就是普通的系统解析器。在同一台机器上、开机时、停掉 overlay 的情况下测试它。只能通过 overlay 自带 DNS 解析的名称无法引导 overlay。同样的测试也适用于路由：一条允许 overlay 但不允许第一次 UDP 交换的防火墙规则会挡住最初的包。

用 UDP 工具探测端口，而不是假定它是打开的。确认路径上的任何端口转发都指向正确的内部主机，并且存在返回路径。如果主机名解析到多个地址，就逐个测试，因为客户端可能选中一个你从未检查过的地址。

静态条目是直接拨号的，从不询问灯塔。这就是为什么这里的失败看起来像一次没有任何对等节点参与的普通超时。

第一次握手之后会发生什么

主机一旦到达灯塔，就会获知对等节点及其可达地址，而无需更多手工条目。自上次连接以来移动过的主机会通过那条通道变得可被发现。这就是让手工地图保持简短的回报。

主机也可以通告自己额外的可达地址，已知公网地址后面的对等节点正是这样帮助别人找到它的。这些通告是被学到的，而不是写进静态地图的。

对于写成 DNS 名称的端点，刷新行为很重要，因为进程继续运行时已解析的地址可能改变。Nebula 的设置决定这些查询如何进行，包括使用哪个解析器，所以要读它们，而不是假定系统默认。在隧道起来时解析器会改变的主机上，错误的设置会把一次本来可行的引导变成一个在会话中途停止解析的名称。把查询固定到稳定的解析器，往往就是可靠 overlay 与间歇性 overlay 之间的差别。

当发现能工作而某一个对等节点不能时

如果灯塔可达且大多数对等节点能连接，那引导就不是问题。剩下的那一对要么找不到可用的互通路径，要么在可达性之上的层面失败。再加一种灯塔地址写法并不能修复这两种情况。

在修改那张其他一切都已依赖的地图之前，先检查这一对。地图变更会扰动每一台主机，所以它是最后才该动的东西，而不是最先动的。

从同一机构的证书开始，因为被拒绝的握手从远处看可能像不可达的对等节点。然后检查这一对能否建立直接路径，以及是否为拒绝直接流量的网络配置了中继。中继会增加一跳和一个依赖，但它是受支持的答案，而修复对等路径是另一项任务，不同于修复发现。