跳到主要内容

NetBird

1. 概述​

NetBird 由管理服务器和加密私有网络组成。Linux、macOS、Windows 和 PicoKVM 可作为节点接入同一个 NetBird 管理服务器，PLC 接入功能尚在规划中。节点上线且访问策略允许通信后，远程电脑可通过目标节点的 NetBird IP 地址打开其 Web 管理界面。

这些节点不需要位于同一个物理局域网。本文所说的“同一私有网络”，是指所有节点接入同一个 NetBird 管理服务器，并且 NetBird 访问策略允许节点之间通信。

本文使用以下占位符：

项目示例
NetBird 服务端域名<NETBIRD_SERVER_DOMAIN>
NetBird Setup Key<NETBIRD_SETUP_KEY>
目标节点名称<TARGET_PEER_NAME>
目标节点 NetBird IP<TARGET_NETBIRD_IP>
妥善保管 Setup Key

Setup Key 可授权设备加入私有网络。不要在截图、日志或共享文档中公开该密钥；不再使用或已经泄露的密钥应及时在 NetBird 控制台中撤销。

2. 部署 NetBird 管理服务器​

2.1 准备服务器和域名​

  1. 准备一台具有公网 IP 的服务器和一个域名，添加 A 记录，将 <NETBIRD_SERVER_DOMAIN> 解析到服务器公网 IP。

    DNS 记录说明
    1. A 记录用于将域名解析到一个 IPv4 地址。
    2. 主机记录 @ 表示根域名。例如，域名为 picokvm.com 时，@ 表示 picokvm.com；服务配置完成后，可通过 https://picokvm.com 访问。
    3. 记录值应填写部署 NetBird 管理服务的服务器公网 IPv4 地址。

  2. 在云服务器安全组和系统防火墙中放行 NetBird 所需端口。

自建服务端域名备案

如果 NetBird 管理服务部署在国内云服务器，并通过域名提供 HTTP 或 HTTPS 访问，需要按要求完成 ICP 备案。域名实名认证不等同于 ICP 备案。

如果服务部署在腾讯云，即使域名已经在其他云服务商完成备案，也需要先在腾讯云完成接入备案。域名未备案或未完成腾讯云接入备案时，HTTP 和 HTTPS 访问都会被阻断，并可能显示“未备案”或“未接入备案”提示。

2.2 安装自建服务端​

  1. 域名解析生效后，在服务器上执行：

    sudo apt update
    sudo apt install -y jq
    export NETBIRD_DOMAIN=<NETBIRD_SERVER_DOMAIN>

    curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh | bash

  2. 等待安装程序提示 NetBird 服务已经启动。

2.3 初始化并登录管理后台​

  1. 打开 https://<NETBIRD_SERVER_DOMAIN>，创建第一个管理员账号。

  2. 使用管理员账号登录。

  3. 首次登录后，NetBird 会进入初始化向导。根据需要访问的资源选择类型，本文以 Domain 为例。

  4. 输入需要通过 NetBird 访问的域名和资源名称，然后创建资源。

  5. 创建资源后，向导会生成用于 Routing Peer 接入的 Setup Key。请复制该密钥并妥善保存。

  6. 点击 Install Routing Peer 进入安装说明页面。该页面会分别提供 Linux、macOS、Windows 和 Docker 等平台的 NetBird 安装及接入步骤，可根据实际使用的平台查看并保存对应说明。

  7. 如果跳过了初始化向导，或者需要为其他设备创建新密钥，可在 NetBird 管理后台进入 Setup Keys 创建并复制 Setup Key。下面各平台的接入命令使用该密钥替换 <NETBIRD_SETUP_KEY>。

  8. 完成或跳过初始化向导后，打开 Peers，确认管理后台可以正常使用。

3. 接入不同平台​

本节中的所有平台都需要使用同一个 https://<NETBIRD_SERVER_DOMAIN>。每个平台完成连接后，打开 NetBird 管理后台的 Peers，确认对应节点已经上线。

3.1 Linux​

  1. 安装 NetBird：

    curl -fsSL https://pkgs.netbird.io/install.sh | sh

  2. 将 Linux 设备连接到自建管理服务器：

    sudo netbird up \
      --management-url https://<NETBIRD_SERVER_DOMAIN> \
      --setup-key <NETBIRD_SETUP_KEY>

  3. 检查连接状态：

    netbird status

3.2 macOS​

  1. 根据 NetBird 安装说明 下载并安装 macOS 客户端。

  2. 将 macOS 设备连接到自建管理服务器：

    netbird up \
      --management-url https://<NETBIRD_SERVER_DOMAIN> \
      --setup-key <NETBIRD_SETUP_KEY>

  3. 执行 netbird status，确认客户端已经连接。

3.3 Windows​

  1. 根据 NetBird 安装说明 下载并安装 Windows 客户端。

  2. 如需使用 Setup Key 接入，以管理员身份打开 PowerShell 并执行：

    netbird up --management-url https://<NETBIRD_SERVER_DOMAIN> --setup-key <NETBIRD_SETUP_KEY>

  3. 如需交互式登录，打开 Settings -> General，选择自建管理服务器并输入 https://<NETBIRD_SERVER_DOMAIN>。

  4. 点击 Connect，然后在浏览器中完成登录。

3.4 PicoKVM​

  1. 打开 PicoKVM Web 管理界面，进入 Settings -> Access -> NetBird。
  2. 在 Management URL 中输入 https://<NETBIRD_SERVER_DOMAIN>，然后启动 NetBird 服务。
  3. 复制并打开生成的 Binding Link，登录同一个 NetBird 管理后台并绑定 PicoKVM。
  4. 返回 PicoKVM，确认 NetBird 状态已经上线。

3.5 Luckfox Lyra PLC​

Luckfox Lyra PLC 的 NetBird 接入功能尚在规划中，功能可用后将补充客户端接入步骤和截图。

4. 验证私有网络访问​

  1. 打开 NetBird 管理后台的 Peers，确认远程电脑和目标节点都处于在线状态。

  2. 复制目标节点的 NetBird IP 地址，并将其作为 <TARGET_NETBIRD_IP>。

  3. 在远程电脑上检查连接：

    netbird status
    ping <TARGET_NETBIRD_IP>

  4. 打开目标设备的 Web 管理界面：

    http://<TARGET_NETBIRD_IP>

    如果目标设备使用 HTTPS 或非默认端口，请填写实际协议和端口。

5. 常见问题​

  • 管理后台中没有显示节点：检查管理服务器地址、Setup Key 是否有效、系统时间以及 NetBird 服务状态。
  • 节点在线但无法访问目标设备：检查 NetBird 访问策略是否允许远程电脑与目标节点通信。
  • 无法 Ping 通但 Web 页面可打开：可能是 ICMP 被拦截，可直接测试 Web 服务。
  • Web 页面无法打开：确认目标设备上的服务已经启动，并且防火墙允许来自 NetBird 接口的流量。
  • Setup Key 已泄露或过期：在管理后台撤销原密钥并创建新密钥。

6. 参考资料​