怎么设置 NetBird 网络的 DNS

背景 链接到标题

自建 NetBird 控制平面后，节点间可以通过 *.netbird.selfhosted 域名互相访问。但实际部署中发现 DNS 表现因节点环境而异，部分节点需要额外配置才能正常工作。

NetBird DNS 的三层结构 链接到标题

NetBird 的 DNS 由三层组成：

应用 → 系统解析器 → NetBird magic DNS (100.121.255.254)
                         ├── peer 域名 (peer-a.netbird.selfhosted → 100.121.*)
                         ├── Nameserver Group (*.lan → 100.121.*.*:53 dnsmasq)
                         └── 普通域名 → 上游 DNS

其中 100.121.255.254 是 NetBird 的 magic DNS 地址（类似 Tailscale 的 100.100.100.100），负责按域名规则路由查询。

场景一：macOS 链接到标题

在 macOS 上 NetBird 通过系统框架（scutil）自动注册 DNS。

# 查看当前 DNS 配置
scutil --dns

输出中可以看到 NetBird 注册了：

domain   : netbird.selfhosted
nameserver : 100.121.255.254
domain   : lan
nameserver : 100.121.255.254

配合搜索域，短名也能自动补全：

# FQDN
dscacheutil -q host -a name peer-a.netbird.selfhosted
→ 100.121.*.*

# 短名（自动补全 peer-a.netbird.selfhosted）
dscacheutil -q host -a name peer-a
→ 100.121.*.*

# .lan 域（经 peer-a dnsmasq 解析）
dscacheutil -q host -a name peer-a.lan
→ 192.168.*.*

macOS 上不需要改 /etc/hosts，也无需任何额外配置。

场景二：Linux + systemd-resolved（推荐） 链接到标题

Ubuntu/Debian 默认启用 systemd-resolved，NetBird 能自动注册 DNS。

# 验证 systemd-resolved
systemctl is-active systemd-resolved

正常时应输出 active。resolvectl status 应显示 wt0 接口已注册 DNS：

Link 4 (wt0)
    Current DNS Server: 100.121.*.*
    DNS Domain: ~lan netbird.selfhosted ~*.in-addr.arpa

如果 systemd-resolved 未运行，启动它并将 /etc/resolv.conf 改为指向 systemd-resolved：

sudo systemctl enable --now systemd-resolved
sudo ln -sf /run/systemd/resolve/stub-resolv.conf /etc/resolv.conf

然后重启 NetBird。

场景三：Linux + 本机 DNS 查询超时（WireGuard 回环问题） 链接到标题

在一台树莓派（ARM64）上发现：从本机查询 NetBird DNS 代理总是超时，但从其他节点远程查询却正常。

# 其他节点 OK
dig peer-a.netbird.selfhosted @100.121.*.*  →  100.121.*.* ✅

# 本机超时
dig peer-a.netbird.selfhosted @100.121.*.*  →  超时 ❌

tcpdump 显示 DNS 查询包已到达 loopback 接口，但 NetBird 进程未回应。原因是 WireGuard 内核接口对自身 IP 的回环流量处理存在限制。

修复：用 --dns-resolver-address 让 NetBird DNS 监听在 127.0.0.1，绕过 WireGuard 接口。

sudo netbird down
sudo netbird up \
  --management-url https://your-management-url \
  --setup-key YOUR_KEY \
  --dns-resolver-address 127.0.0.1

验证：

dig peer-a.netbird.selfhosted @127.0.0.1
→ 100.121.*.* ✅

该配置已持久化到 default.json。

场景四：Linux + 同时运行 dnsmasq 链接到标题

如果节点同时运行 dnsmasq（占用 53 端口），NetBird DNS 会被禁用（disable_dns: true）。

对于 dnsmasq 节点本身，在 /etc/hosts 中添加 NetBird 节点的 IP：

100.121.*.*  peer-a peer-a.netbird.selfhosted
100.121.*.*  peer-b peer-b.netbird.selfhosted

对于局域网中走该 dnsmasq 的其他设备，修改 dnsmasq 的 hosts 配置文件，将跨网络节点的 IP 改为 NetBird IP：

# 原配置（家庭/云节点使用办公室 LAN IP，不通）
192.168.*.*  peer-b peer-b.lan

# 改为 NetBird IP（所有环境都能通）
100.121.*.*  peer-b peer-b.lan

这样办公室设备通过 dnsmasq 查询 peer-b 时，自动返回 NetBird IP，无需逐个配置。

总结 链接到标题