想让笔记本、手机、家里的 NAS 和几台 VPS 像在同一个局域网里互通，原生 WireGuard 很快就会碰到一个现实问题：设备一多，密钥、路由和访问权限会越来越难管。NetBird 把 WireGuard 数据面、设备注册、用户登录、访问策略和内网路由放进了同一套控制台，比较适合家庭实验室、小团队和多云服务器。
这篇教程使用 2026 年 9 月发布的 NetBird v0.78.1，在一台 Ubuntu 24.04 VPS 上部署自托管控制面。我们会使用安装器自带的 Traefik 自动申请 HTTPS，接入 Linux 客户端与无人值守服务器，再配置最小权限策略、Networks、DNS、备份和升级。
先说结论：NetBird 不是把所有业务流量都强制绕到这台 VPS。控制面负责登录、策略和连接协调；两台 Peer 能打洞直连时，数据通过 WireGuard 点对点传输。只有直连失败时，流量才会经过 Relay，所以 VPS 的位置和带宽仍然重要，但不能简单按“所有客户端流量之和”估算。
这四种方案经常被放在一起比较，但维护方式差别很大。
| 方案 | 控制面 | 客户端 | 策略与身份 | 适合场景 |
|---|---|---|---|---|
| 原生 WireGuard | 自己写配置 | WireGuard | 需要自己维护 | 少量固定设备、拓扑简单 |
| Tailscale | 官方托管 | Tailscale | 成熟，开箱即用 | 不想维护控制面 |
| Headscale | 自托管 | Tailscale | 需要更多手工配置 | 想保留 Tailscale 客户端生态 |
| NetBird | 可自托管 | NetBird | 内置用户、组、策略、Networks | 多用户、多设备、需要图形化权限管理 |
如果只有三五台固定服务器互联，原生 WireGuard 教程更直接。已经习惯 Tailscale 客户端、只想替换控制服务器，可以看Headscale 自托管教程。NetBird 更适合想把设备接入、用户身份和访问策略一起管理的人。
它也不是“装上就自动零信任”。新账户会创建一条 Default 策略，允许 All 到 All 的全部通信，方便第一次测试，但生产环境必须先建立替代规则，再删除这条全放行策略。
NetBird 官方 quickstart 给出的最低要求是 1 核 CPU、2GB 内存。这个配置可以跑控制面，但我更建议从 2 核 2GB、30GB SSD 起步，给 Docker、日志、镜像更新和备份留出余量。
| 规模 | 建议配置 | 说明 |
|---|---|---|
| 个人、10 台以内 Peer | 2 核 2GB、30GB SSD | 控制面和少量 Relay 流量 |
| 小团队、10–50 台 Peer | 2–4 核、4GB、50GB SSD | 用户、策略和日志更多 |
| Relay 流量较多 | 4GB 起，并关注月流量 | 直连失败时 VPS 带宽会成为瓶颈 |
| 需要高可用 | 不要只纵向加配置 | 单 VPS 仍是控制面单点 |
公网入口只需要这些端口：
80/TCP：Let's Encrypt 验证和 HTTP 跳转；443/TCP：Dashboard、管理 API、Signal 与 gRPC；3478/UDP：STUN，帮助 Peer 判断公网映射并建立直连；22/TCP：SSH 管理，限制到自己的固定 IP。
不要照搬旧教程开放 33073、10000、33080 等端口。新版 quickstart 使用合并式 netbird-server，外部流量统一由 HTTPS 入口和 STUN 端口处理。
本文使用：
- NetBird 域名：
netbird.example.com； - VPS 公网 IP：
203.0.113.10； - 安装目录：
/opt/netbird。
把示例域名和 IP 换成自己的。域名必须先解析到 VPS；如果使用 Cloudflare DNS，部署阶段把记录设为 DNS only，不要让橙云代理影响 UDP 3478 和证书排查。
在本地电脑检查解析：
dig +short A netbird.example.com
dig +short AAAA netbird.example.com
只有 VPS 真有可用 IPv6 时才保留 AAAA。错误的 AAAA 记录会让一部分客户端访问超时，也可能导致证书验证失败。
登录 VPS，核对系统、资源、时间和端口占用：
cat /etc/os-release
uname -m
free -h
df -h /
timedatectl status
sudo ss -lntup | grep -E ':(22|80|443|3478)\b' || true
已经有 Nginx、Caddy 或其他 Traefik 占用 80/443 时，不要继续硬装。可以选择 NetBird 安装器提供的外部反向代理模式，但反向代理必须正确支持 HTTP/2 和 gRPC。本文为了减少变量，使用内置 Traefik。
安装 Docker、Compose v2、curl 和 jq：
sudo apt update
sudo apt upgrade -y
sudo apt install -y ca-certificates curl jq docker.io docker-compose-v2
sudo systemctl enable --now docker
sudo usermod -aG docker "$USER"
执行完后退出 SSH 并重新登录，让 docker 组生效。然后检查版本和权限：
docker version
docker compose version
docker run --rm hello-world
NetBird 要求 Compose v2，所以正确命令是 docker compose，不是老式的 docker-compose。
先在 VPS 厂商的安全组或云防火墙中放行 80/TCP、443/TCP、3478/UDP，并把 SSH 限制到自己的管理 IP。再配置系统 UFW：
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow from YOUR_ADMIN_IP to any port 22 proto tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 3478/udp
sudo ufw enable
sudo ufw status numbered
YOUR_ADMIN_IP 必须替换成真实公网 IP。开启 UFW 前保持当前 SSH 会话不要断，并准备好厂商网页控制台；如果规则写错，可参考VPS 开启 UFW 后 SSH 进不去的恢复清单。
Docker 会自行管理 iptables/nftables 规则，UFW 不是“隐藏错误端口映射”的保险。部署后仍要用 ss 和云防火墙检查实际公网入口。
官方文档给出的命令是把最新安装器直接交给 Bash。生产机器上我更倾向先下载文件、核对发布页校验值，再执行：
sudo install -d -m 0750 -o "$USER" -g "$USER" /opt/netbird
cd /opt/netbird
curl -fL \
https://github.com/netbirdio/netbird/releases/download/v0.78.1/getting-started.sh \
-o getting-started.sh
echo 'a8d17cdb2229c680514063a6893d117aad55343d8dd2c703d1aa1033577b1570 getting-started.sh' \
| sha256sum -c -
chmod 700 getting-started.sh
export NETBIRD_DOMAIN=netbird.example.com
bash ./getting-started.sh
安装器询问反向代理时选择 [0] Traefik，直接回车就是默认项。它会把 Traefik 写进 Compose，自动处理 Let's Encrypt 证书。
接着会问是否启用 NetBird Proxy service。这不是控制面必需组件，而是把内网资源选择性暴露到公网的功能。本文选择 N，先把私网访问跑通；以后确实需要公开服务，再单独评估通配符 DNS、认证和暴露面。
安装完成后，目录中至少会出现：
/opt/netbird/
├── docker-compose.yml
├── config.yaml
├── dashboard.env
└── getting-started.sh
启用了 NetBird Proxy 才会多出 proxy.env。config.yaml 和环境文件可能包含敏感配置，收紧权限：
cd /opt/netbird
chmod 600 config.yaml dashboard.env
test ! -f proxy.env || chmod 600 proxy.env
docker compose config --quiet
docker compose ps
docker compose config --quiet 没有输出且退出码为 0，说明 Compose 能解析；它不能代替运行状态检查。
先看容器，不要只凭浏览器能打开就判定部署成功：
cd /opt/netbird
docker compose ps
docker compose logs --tail=100 netbird-server dashboard
curl -I https://netbird.example.com
sudo ss -lntup | grep -E ':(80|443|3478)\b'
正常情况下，80/443 由 Traefik 接管，3478/UDP 提供 STUN。curl -I 收到 200、302 或其他正常 HTTP 响应都说明 TLS 和入口基本可用；连接超时通常是 DNS、安全组或端口没放行。
如果不知道 Compose 里的实际服务名，先执行：
docker compose config --services
不要猜 management、signal 或 coturn。从 v0.65 起的新安装已经合并为 netbird-server，旧教程的容器名不适用于这里。
浏览器打开：
https://netbird.example.com
第一次会跳转到 /setup，填写邮箱、姓名和强密码，创建第一个 Owner。这个页面只在系统里没有任何用户时开放；创建完成后，再访问 /setup 会回到普通登录页。
建议立刻做三件事：
- 给 Owner 使用独立密码，不和 VPS root、邮箱或其他系统共用；
- 在 Team 页面创建日常使用的普通账号，Owner 只留给管理操作；
- 如果接入外部 OIDC/SSO，先保留一个经过验证的本地管理员，避免身份提供商故障时把自己锁在外面。
在要加入私网的 Linux 电脑或服务器上下载安装脚本：
curl -fsSLO https://pkgs.netbird.io/install.sh
less install.sh
sh ./install.sh
rm -f install.sh
个人电脑适合交互式登录：
sudo netbird up --management-url https://netbird.example.com
netbird status
ip addr show wt0
命令会打开浏览器，让用户在自托管登录页完成认证。登录后到 Dashboard 的 Peers 页面确认设备名、NetBird IP、系统和最近在线时间。
服务器、云主机或自动化任务更适合一次性 Setup Key。在 Dashboard 打开 Peers → Add Peer → Generate Key，默认会生成一枚 24 小时过期的一次性密钥。不要把密钥写进 shell history：
read -rsp 'NetBird setup key: ' NETBIRD_SETUP_KEY
echo
sudo netbird up \
--management-url https://netbird.example.com \
--setup-key "$NETBIRD_SETUP_KEY"
unset NETBIRD_SETUP_KEY
netbird status
需要批量注册时，可以在 Settings → Setup Keys 创建可复用密钥，并限制到期时间、使用次数和自动分组。临时容器可启用 Ephemeral；它们离线超过 10 分钟后会被自动移除。终端用户设备仍应使用登录方式，便于把访问权限绑定到真实用户，而不是长期共享一枚机器密钥。
两台 Peer 接入后，从一台设备测试另一台的 NetBird IP：
netbird status
netbird status --detail
ping -c 4 PEER_NETBIRD_IP
第一次测试能通，通常是因为自动创建的 Default 策略允许 All → All。这条规则适合排除安装问题，不适合长期保留。
在 Access Control → Groups 建立清晰的组，例如：
admins：管理员的笔记本和手机；servers：允许被管理的 VPS；workstations：普通办公设备；routing-peers：负责转发家庭或办公室网段的节点。
先创建替代规则，例如：
| 策略 | Source | Destination | 协议和端口 | 方向 |
|---|---|---|---|---|
| Admin SSH | admins | servers | TCP 22 | 单向 |
| Admin Web | admins | servers | TCP 80,443 | 单向 |
| Admin Ping | admins | servers | ICMP | 单向 |
把测试设备放进对应组，确认 SSH、HTTPS 和 Ping 都按预期工作，最后再禁用或删除 Default。顺序不能反过来，否则所有 Peer 会立刻失去通信。
NetBird 只处理 ALLOW 规则，没有“后写的 DENY 覆盖前面的 ALLOW”这种优先级。只要还有一条宽泛的 All → All，新增的精细策略就不会真正限制访问。
假设家中有一台 Linux 小主机 192.168.50.2 已安装 NetBird，想让管理员从外面访问不能安装客户端的 NAS 192.168.50.10。
先在这台小主机启用 IPv4 转发：
echo 'net.ipv4.ip_forward=1' \
| sudo tee /etc/sysctl.d/99-netbird-forward.conf
sudo sysctl --system
sysctl net.ipv4.ip_forward
然后在 Dashboard 中：
- 打开
Networks，创建Home LAN； - 添加 Resource，地址填
192.168.50.10/32； - 把 Resource 放入
home-nas资源组； - 选择
192.168.50.2这台设备作为 Routing Peer； - 创建策略：Source 为
admins，Destination 为home-nas，只放行 NAS 实际使用的端口。
能用 /32 就不要直接写整个 192.168.50.0/24。单主机资源更符合最小权限，也能避免误把摄像头、打印机或路由器后台一起开放给远程用户。
2026 年的新配置应该优先使用 Networks。旧的 Network Routes 已被标记为弃用，除 Exit Node 外的常规远程访问都迁移到了 Networks；旧 Routes 如果没设置 ACL Group，还可能绕过预期的访问控制。
还有一个常见坑：资源策略管的是 Routing Peer 转发到后端资源的流量。如果要访问 Routing Peer 自己的 SSH、Web 或 DNS 服务，还要单独建立 Peer-to-Peer 策略，把该节点所在组作为 Destination。
NetBird 会给 Peer 分配私有域名，设备不多时直接使用自动名称最省事。需要解析 nas.home.internal 或企业内部域名时，再到 DNS → Nameservers 添加内部 DNS。
常见配置思路：
- 内部 DNS 地址：例如
192.168.50.53； - Match Domain：
home.internal； - Distribution Group：只选择需要使用这套 DNS 的设备组；
- 确认 DNS 服务器本身已有 Network Resource 和 UDP/TCP 53 访问策略。
如果某台设备同时运行公司 VPN，出现域名解析冲突，可以临时关闭该 Peer 的 NetBird DNS 管理来定位：
sudo netbird down
sudo netbird up \
--management-url https://netbird.example.com \
--disable-dns
关闭 DNS 只影响名称解析，不会关闭 WireGuard 网络连接。如果禁用后恢复正常，应检查 Match Domain、systemd-resolved 和另一套 VPN 的 DNS 优先级，而不是长期依赖 IP 地址。
只备份 docker-compose.yml 不够。用户、Peer、组、策略和密钥等状态保存在 /var/lib/netbird/，必须在停止 netbird-server 后复制，避免拿到不一致的 SQLite 文件。
在 /opt/netbird 执行：
cd /opt/netbird
BACKUP_DATE="$(date -u +%Y%m%dT%H%M%SZ)"
BACKUP_DIR="/var/backups/netbird/$BACKUP_DATE"
sudo install -d -m 0700 -o "$USER" -g "$USER" "$BACKUP_DIR"
cp docker-compose.yml config.yaml dashboard.env "$BACKUP_DIR/"
test ! -f proxy.env || cp proxy.env "$BACKUP_DIR/"
docker compose stop netbird-server
docker compose cp -a netbird-server:/var/lib/netbird/ "$BACKUP_DIR/"
docker compose start netbird-server
tar -C /var/backups/netbird \
-czf "/var/backups/netbird/netbird-$BACKUP_DATE.tar.gz" \
"$BACKUP_DATE"
tar -tzf "/var/backups/netbird/netbird-$BACKUP_DATE.tar.gz" | head
docker compose ps
把压缩包加密后同步到另一台服务器或对象存储。备份和原 VPS 放在同一块系统盘，只能应付误操作，扛不住磁盘损坏或账号被封。
恢复演练至少要确认：配置文件、store.db 和其他数据文件都在归档里；用同版本镜像启动测试实例时，现有用户、策略和 Peer 记录能够读出。不要等到生产 VPS 故障后才第一次测试备份。
升级前先完成上一节备份，再看 NetBird 与 Dashboard 的官方 Release Notes。对当前合并式安装，官方升级步骤是拉取并重建 netbird-server 和 dashboard：
cd /opt/netbird
docker compose pull netbird-server dashboard
docker compose up -d --force-recreate netbird-server dashboard
docker compose ps
docker compose logs --tail=100 netbird-server dashboard
如果之前启用了 NetBird Proxy，再单独同步它：
docker compose pull proxy
docker compose up -d --force-recreate proxy
docker compose exec proxy /go/bin/netbird-proxy --version
NetBird v0.78.1 在 2026 年 9 月 4 日发布，修复了 v0.78.0 中 peer-based router 的网络分发问题。已经使用 Networks 和 Routing Peer 的环境不要停在 v0.78.0；升级后重点验证资源路由、策略和 Peer 重连。
回滚不能只把镜像标签改回去。数据库可能已经迁移，正确做法是保留升级前的配置与数据快照，在隔离环境验证恢复步骤，再决定回退。生产环境也不要用 Watchtower 之类工具无审批自动更新控制面。
先查 DNS、80/443 入口和 Traefik 日志：
dig +short A netbird.example.com
dig +short AAAA netbird.example.com
sudo ss -lntp | grep -E ':(80|443)\b'
docker compose config --services
docker compose logs --tail=200 | grep -iE 'acme|certificate|error'
最常见原因是 A/AAAA 指错、Cloudflare 橙云代理、云安全组没放行 80，或者另一套 Web 服务占用了端口。
在客户端检查状态和日志：
netbird status --detail
sudo systemctl status netbird --no-pager
sudo journalctl -u netbird -n 200 --no-pager
curl -I https://netbird.example.com
控制面 443 不通时，设备无法拿到网络配置；3478/UDP 被拦时，Peer 更容易退回 Relay，但不一定完全离线。还要检查系统时间，时间偏差会影响 TLS 和登录令牌。
先看 Access Control → Policies，确认 Source、Destination、协议和方向。删除 Default 后没有建立替代规则、设备没进预期组，或者只允许 TCP 22 却拿 ICMP 测试，都会表现为“在线但不通”。
依次确认 Routing Peer 在线、能从局域网直接访问目标、IPv4 转发为 1、Resource 地址正确、策略确实从用户组指向资源组。访问 Routing Peer 本机服务时，还要补 Peer-to-Peer 规则。
netbird status --detail 可以观察连接类型。公司网络、运营商 CGNAT、严格 UDP 防火墙或对称 NAT 都可能让直连失败。此时延迟和流量会受 Relay 所在 VPS 影响，应选择更靠近用户的机房，并监控 3478/UDP 是否真正可达。
- 域名 A/AAAA 只指向真实可达地址；
- 云防火墙和 UFW 只开放 80/TCP、443/TCP、3478/UDP及受限 SSH；
docker compose config --quiet通过，容器保持运行；- Dashboard HTTPS 有效，
/setup已关闭； - 终端用户使用身份登录，服务器使用有限期 Setup Key；
- 已建立细分组和替代策略，Default 全放行已移除；
- 新内网访问使用 Networks 和
/32资源，不继续堆旧 Routes； - 已备份配置与
/var/lib/netbird/，并把归档复制到异地； - 升级前阅读 Release Notes，升级后复测 Peer、策略、Networks 和 DNS。
可以，这是官方 quickstart 的最低配置，适合个人或少量 Peer。长期运行建议 2 核 2GB 起步；如果大量连接无法直连、持续经过 Relay，真正需要关注的是带宽、月流量和机房延迟。
不会。控制面负责身份、策略和连接协调，能直连的 Peer 使用 WireGuard 点对点传输。只有打洞失败、使用 Relay，或主动配置 Exit Node 时，相关数据流量才会经过中继或出口节点。
想继续使用 Tailscale 客户端生态，Headscale 更贴近这个需求；想要 NetBird 自己的客户端、内置本地用户、图形化组策略和 Networks，NetBird 更完整。两者都需要自己负责域名、升级、备份和控制面可用性。
这是正常行为。/setup 只在系统中没有用户时开放，第一个 Owner 创建后会转到普通登录页。忘记管理员密码时不要删除数据库，应使用已有管理员或 PAT 按官方恢复流程处理。
不建议。443/TCP 承载控制面和 Dashboard，80/TCP用于证书验证与跳转，3478/UDP用于 STUN 和直连协商。封掉 3478 不一定完全断线，但会降低打洞成功率，增加 Relay 延迟与流量。
不够。Compose 和环境文件只描述服务，用户、Peer、策略与密钥等状态位于 netbird-server 的 /var/lib/netbird/。应短暂停止该容器后一起复制数据目录，并定期在隔离环境做恢复演练。