Netbird on OHTLY Blog

iPhone 远程访问内网：NetBird 受阻，回归 WireGuard

Fri, 26 Jun 2026 19:07:25 +0800

背景链接到标题

已有 NetBird 自建网络覆盖办公室、家里、云服务器等多个节点，日常用 macOS/Linux 客户端体验很好。现在想让 iPhone 也能访问办公室内网资源（如内部服务、开发环境）。

第一选择：NetBird 链接到标题

NetBird 有官方 iOS App，支持自建服务器（Private Setup），配置很简单：

在管理面板生成 Setup Key
iPhone App 输入服务器 URL 和 Key
授权 VPN 权限即可

遇到的问题链接到标题

问题一：iOS DNS 限制

办公室内网域名走 *.lan 后缀，由内网 dnsmasq 解析。NetBird 的 Nameserver Group 虽然配置了 lan 域指向内网 DNS，但 iOS 客户端对自定义 DNS 解析器支持有限——蜂窝网络下根本无法配置 DNS，WiFi 下手动改 DNS 为内网地址后，流量走隧道出去 DNS 查询却不一定走隧道。

问题二：网络封锁

在办公室集团 WiFi 下，NetBird 一开始能连通，也能通过 IP 访问内网服务。但几分钟后连接中断，反复重连都失败。切换到 5G 则一切正常。判断是企业 WiFi 的 DPI 检测到 VPN 特征后进行了限流或阻断。

NetBird 子网路由主备配置

Wed, 24 Jun 2026 10:28:11 +0800

背景链接到标题

自建 NetBird 网络最初只有一个路由 peer（称节点 A），负责将办公子网 192.168.*.* 暴露给其他 NetBird 节点。单一故障点意味着节点 A 下线后，家庭等远程节点无法访问办公内网。

增加第二个路由 peer，实现主备冗余。

新增节点到 NetBird 链接到标题

办公室有另一台 Mac Mini（称为节点 B），加入 NetBird 网络：

netbird up --management-url https://netbird-api.域名 --setup-key <setup-key>

加入后获取 NetBird IP（100.x.x.x/16），所有 peer 自动连通。

开启 IP 转发链接到标题

NetBird 路由 peer 需要转发子网流量。macOS 默认关闭 IP 转发：

sudo sysctl -w net.inet.ip.forwarding=1
echo "net.inet.ip.forwarding=1" | sudo tee -a /etc/sysctl.conf

即时生效并持久化。

创建备份路由链接到标题

通过 NetBird Route API 添加第二条路由，关键参数是 metric：

NetBird 客户端自动重连的 systemd 实现

Tue, 23 Jun 2026 22:29:46 +0800

NetBird 客户端运行中偶遇 management server 不稳定时会断开连接，且不会自动恢复。需要手动 netbird down && netbird up 才能重连。

问题特征链接到标题

日志如下：

WARN management/client/grpc.go: job stream disconnected, will retry silently.
  Reason: unexpected HTTP status code received from server: 504 (Gateway Timeout)
ERRO management/client/grpc.go: stream receive error
INFO engine.go: stopped Netbird Engine
INFO server.go: service is down

daemon 进程存活，但内部引擎已永久退出。只有手动重连才能恢复。

原因链接到标题

NetBird 客户端内部有一个 backoff 重试循环：

// 简化示意
backoff.Retry(func() error {
    return s.connect(ctx, ...)
}, backOff)

重试耗尽后 giveUpChan 关闭，引擎永久退出。此后即使网络恢复，客户端也不会再次尝试连接。

NetBird 子网路由与 Access Policy 配置

Tue, 23 Jun 2026 18:25:39 +0800

场景链接到标题

办公室有大量 VM（host-a、host-b、host-c 等），它们无法或不适合安装 NetBird agent。家里的笔记本需要能直接通过这些机器的 LAN IP 访问（RustDesk、SSH 等），而不能逐个安装 agent。

方案：路由 peer 链接到标题

NetBird 的 Network Route 功能允许将整个子网通过一个路由 peer 暴露给 VPN 网络。

家里笔记本 ── NetBird 隧道 ── gateway(路由 peer) ── 办公室 LAN 192.168.0.0/24
                                                    ├── host-a      (192.168.0.*)
                                                    ├── host-c      (192.168.0.*)
                                                    └── 其他无 agent 节点

路由 peer（gateway）对流量做 Masquerade（NAT），将来自 NetBird 的包源 IP 替换为自己的 LAN IP，这样目标机器的回包就能正确路由回来。

前置条件链接到标题

路由 peer 需要开启 IP 转发：

echo "net.ipv4.ip_forward=1" | sudo tee /etc/sysctl.d/99-netbird-forward.conf
sudo sysctl -p /etc/sysctl.d/99-netbird-forward.conf

第一步：创建 Network Route 链接到标题

source .env

curl -X POST "https://your-management/api/routes" \
  -H "Authorization: Token $NETBIRD_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Office LAN",
    "network_id": "office-lan",
    "enabled": true,
    "peer": "<gateway_peer_id>",
    "network": "192.168.0.0/24",
    "metric": 100,
    "masquerade": true,
    "groups": ["<all_group_id>"]
  }'

关键参数：

怎么设置 NetBird 网络的 DNS

Tue, 23 Jun 2026 15:31:05 +0800

背景链接到标题

自建 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。

自定义别名查看 NetBird 所有节点信息

Tue, 23 Jun 2026 11:46:20 +0800

对比链接到标题

NetBird 和 Tailscale 都是 mesh VPN，但 CLI 体验有个明显差距：

操作	Tailscale	NetBird
查看节点列表	`tailscale status` — 简洁表格	`netbird status` — 只显示本机状态
查看详情	`tailscale status --json`	`netbird status --detail` — 散文体

tailscale status 输出是这样的：

100.121.*.*  peer-a     linux   -
100.121.*.*  server     linux   -
100.121.*.*  laptop     macOS   -

而 netbird status --detail 的节点信息散布在两处：

Peers detail 区块：每个对端分多行（FQDN、IP、Status）
Summary 区块：本地节点的 FQDN 和 IP 在底部

解析思路链接到标题

以 Peers detail 中的一段为例：

NetBird 自托管 IDP 密码重置

Tue, 23 Jun 2026 11:27:19 +0800

背景链接到标题

NetBird 自托管控制平面使用内置 Dex 作为 OIDC Provider。管理员账号在首次部署时通过 config.yaml 的 owner 字段创建，密码以 bcrypt 哈希存储。

长时间没有登录 Dashboard，密码遗忘了。Dashboard 没有提供密码重置功能，需要直接操作数据库恢复。

架构链接到标题

NetBird 的认证数据分两处存放：

位置	文件	作用
配置	`config.yaml`	server 启动时读取 `owner.password`，同步到数据库
数据库	Docker volume `idp.db`	Dex 运行时读写的 `password` 表

Dex 的 password 表结构：

email         - 登录邮箱
hash          - bcrypt(password)
username      - 用户名
user_id       - UUID

直接改数据库？不行链接到标题

第一个尝试是直接用 Python 更新 idp.db 的 password 表：

自建 NetBird 控制平面记录

Thu, 18 Jun 2026 21:41:45 +0800

概述链接到标题

用 NetBird 自建控制平面，替换现有的 WireGuard VPN 手动组网。控制平面部署在云服务器上，所有节点通过 P2P WireGuard 隧道互联。

步骤链接到标题

1. Traefik v2 → v3 升级链接到标题

现有 Traefik 版本是 v2.10.7，先升级到 v3.7.5 为后续路由做准备。

兼容性分析：

文件配置文件（File provider）的 YAML 语法完全兼容，无需改动
--serversTransport.insecureSkipVerify CLI 参数名不变
ipwhitelist 中间件重命名为 ipAllowList，在 v3 中需要手动迁移
升级时需要加 --core.defaultrulesyntax=v2 保持路由语法兼容，确认稳定后移除

升级步骤：只需改 Docker Compose 的 image tag，重启即可。

2. NetBird 控制平面部署链接到标题

控制平面用 Docker Compose 部署，使用 NetBird v0.65+ 的合并容器架构，不再需要分开的 management/signal/relay/coturn 四个容器。

Netbird on OHTLY Blog

iPhone 远程访问内网：NetBird 受阻，回归 WireGuard

背景 链接到标题

第一选择：NetBird 链接到标题

遇到的问题 链接到标题

NetBird 子网路由主备配置

背景 链接到标题

新增节点到 NetBird 链接到标题

开启 IP 转发 链接到标题

创建备份路由 链接到标题

NetBird 客户端自动重连的 systemd 实现

问题特征 链接到标题

原因 链接到标题

NetBird 子网路由与 Access Policy 配置

场景 链接到标题

方案：路由 peer 链接到标题

前置条件 链接到标题

第一步：创建 Network Route 链接到标题

怎么设置 NetBird 网络的 DNS

背景 链接到标题

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

场景一：macOS 链接到标题

自定义别名查看 NetBird 所有节点信息

对比 链接到标题

解析思路 链接到标题

NetBird 自托管 IDP 密码重置

背景 链接到标题

架构 链接到标题

直接改数据库？不行 链接到标题

自建 NetBird 控制平面记录

概述 链接到标题

步骤 链接到标题

1. Traefik v2 → v3 升级 链接到标题

2. NetBird 控制平面部署 链接到标题

背景链接到标题

遇到的问题链接到标题

背景链接到标题

开启 IP 转发链接到标题

创建备份路由链接到标题

问题特征链接到标题

原因链接到标题

场景链接到标题

前置条件链接到标题

背景链接到标题

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

对比链接到标题

解析思路链接到标题

背景链接到标题

架构链接到标题

直接改数据库？不行链接到标题

概述链接到标题

步骤链接到标题

1. Traefik v2 → v3 升级链接到标题

2. NetBird 控制平面部署链接到标题