简介

NetBird 是一个开源的 Zero Trust 网络平台，允许您为您的 组织或家庭。我们将 NetBird 设计为简单快速，几乎不需要任何配置工作，并且只需 在打开端口的麻烦、复杂的防火墙规则、VPN 网关等的背后。

NetBird 是一个**开源**项目，可以自托管。 在此处查看自托管版本和云托管版本之间的比较。

NetBird 没有集中式 VPN 服务器 - 您的计算机、设备、机器和服务器直接通过快速加密隧道相互连接。 它创建了一个高性能的点对点 WireGuard® 覆盖网络，只需单击几下即可连接在任何地方运行的计算机。
使用 NetBird 部署安全的点对点 VPN 实际上只需不到 5 分钟。

官方网站：NetBird - Open-Source Zero Trust Networking 文档：Introduction to NetBird - NetBird Docs

安装前准备

一、环境配置

我们推荐按照 Docker 官方文档安装 Docker 和 Docker Compose，因为部分 Linux 发行版软件仓库中的 Docker 版本可能过旧。

Docker 安装文档
Docker Compose 安装文档

二、要求

基础设施要求：

  • 至少具有 1 个 CPU 和 2 GB 内存的 Linux VM。
  • VM 应在 TCP 端口 80、443、33073、10000 和 33080 上公开访问;和 UDP 端口：3478、49152-65535。
  • 指向 VM 的公共域名。

软件要求：

  • 使用 docker compose 插件（Docker 安装指南）安装在 VM 上的 Docker，或使用版本 2 或更高版本的 docker-compose 安装在 VM 上的 Docker。
  • JQ 已安装。在大多数发行版中 通常位于官方仓库中，根据系统执行sudo apt install jq或sudo yum install jq安装
  • curl 已安装。 通常位于官方仓库中，根据系统执行sudo apt install curl或sudo yum install curl安装

三、创建安装目录

执行以下命令：

cd ~
mkdir netbird && cd netbird

快速安装

适用于本机没有占用80、443端口的服务器，如果自己配置有反向代理服务，请使用自定义安装服务

一、下载并运行脚本

下载并运行安装脚本，只需一行：

export NETBIRD_DOMAIN=netbird.example.com; curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started-with-zitadel.sh | bash

如果您想在运行脚本之前检查脚本，您可以下载它并在本地运行它：

curl -sSLO https://github.com/netbirdio/netbird/releases/latest/download/getting-started-with-zitadel.sh
# check the script
cat getting-started-with-zitadel.sh
# run the script
export NETBIRD_DOMAIN=netbird.example.com
bash getting-started-with-zitadel.sh

替换为您的域名。netbird.example.com

脚本执行完成后，您可以使用终端中显示的凭据通过 URL 访问您的 netbird 实例。https://netbird.example.com

二、添加用户

如果要添加其他用户，您可以使用相同的凭据通过 URL 访问 Zitadel 的管理控制台。按照 Zitadel 的用户指南添加其他本地用户，或按照指南配置身份提供商将 Zitadel 与您现有的身份提供商集成。https://netbird.example.com/ui/console

三、备份

要备份 NetBird 安装，您需要复制配置文件、管理服务数据库和 Zitadel 的数据库。
配置文件位于运行安装脚本的文件夹中。要备份，请将文件复制到备份位置：

mkdir backup
cp docker-compose.yml Caddyfile zitadel.env dashboard.env turnserver.conf management.json relay.env zdb.env backup/

要保存管理服务数据库，您需要停止管理服务并使用 docker compose 命令从存储目录中复制文件，如下所示：

docker compose stop management
docker compose cp -a management:/var/lib/netbird/ backup/
docker compose start management

您可以按照 Cockroach 备份指南备份 Zitadel 的数据库，其中包含用户信息。

四、升级

使用版本 < v0.15.3 的用户应首先将他们的系统升级到 v0.25.9。 运行 Management 以将规则正确迁移到策略，然后升级到 0.26.0+。
要将 NetBird 升级到最新版本，您需要查看发行说明以了解任何重大更改，并按照以下升级步骤作：

  1. 运行 backup 部分中描述的备份步骤。

  2. 拉取最新的 NetBird docker 镜像：

    docker compose pull management dashboard signal relay

  3. 使用新映像重新启动 NetBird 容器：

    docker compose up -d --force-recreate management dashboard signal relay

五、删除

要从服务器中删除 NetBird 安装和所有相关数据，请从安装 NetBird 的文件夹中运行以下命令：

# remove all NetBird-related containers and volumes (data)
docker compose down --volumes
# remove downloaded and generated config files
rm -f docker-compose.yml Caddyfile zitadel.env dashboard.env machinekey/zitadel-admin-sa.token turnserver.conf management.json

自定义安装

一、部署Authentik IDP

NetBird 支持通用 OpenID （OIDC） 协议，允许与遵循规范的任何 IDP 集成。
NetBird 的管理服务与一些最流行的 IDP API 集成，允许该服务缓存和显示用户名和电子邮件地址，而无需存储敏感数据。

1. 新建目录，并下载官方的docker-compose

cd ~ && mkdir authentik && cd authentik && wget https://goauthentik.io/docker-compose.yml

2. 安装一个生成随机密码的小工具

apt -y install pwgen

3. 生成密码和密匙到.env文件

echo "PG_PASS=$(pwgen -s 40 1)" >> .env
echo "AUTHENTIK_SECRET_KEY=$(pwgen -s 50 1)" >> .env

4. 启动服务

docker compose up -d

5. 反向代理服务

(1) 先在域名服务商配置你要代理的域名DNS到你的服务器

(2) 配置反向代理服务

我这里使用的是NPM，NPM的安装参考我另一篇教程 Nginx Proxy Manager反向代理工具安装

由于官方的docker-compose是对外服务的端口是9000(http)和9443(https)我们在代理的时候就是代理这两个端口，如果我们没有给服务配置ssl证书，那就是直接带了9000端口

PixPin_2025-04-02_10-38-15.png
PixPin_2025-04-02_10-39-11.png
PixPin_2025-04-02_10-40-09.png
PixPin_2025-04-02_10-41-21.png

(3) 配置Authentik IDP

👉 先访问：https://你的域名/if/flow/initial-setup/，配置默认的管理员账号和密码。

👉 按照官方文档进行配置：身份提供商 - NetBird Docs，这里我就不重复这些步骤了。务必记下Client ID、Username、Password，后续配置Netbird需要用到。

❗️ 如果你完全按照官方的文档配置，那么Username就是：Netbird（注意大小写）
❗️ Password是服务账户的密码，不是Authentik管理员账户的密码。

第 1 步：创建 OAuth2/OpenID 提供者
PixPin_2025-04-02_10-57-20.png
PixPin_2025-04-02_10-58-00.png
PixPin_2025-04-02_11-01-13.png
PixPin_2025-04-02_11-07-59.png
PixPin_2025-04-02_11-14-59.png
PixPin_2025-04-02_11-09-01.png
PixPin_2025-04-02_11-10-54.png
PixPin_2025-04-02_11-11-35.png
步骤 2：创建外部应用程序
PixPin_2025-04-02_11-18-55.png
PixPin_2025-04-02_11-21-28.png
第 3 步：创建服务帐户
PixPin_2025-04-02_11-26-20.png
PixPin_2025-04-02_11-30-22.png
PixPin_2025-04-02_11-39-40.png
第 4 步：将服务账户添加到管理员组
PixPin_2025-04-02_16-40-41.png
PixPin_2025-04-02_16-41-51.png
PixPin_2025-04-02_16-42-34.png
第 5 步：创建用于设备令牌身份验证的身份验证流程
PixPin_2025-04-02_16-46-37.png
PixPin_2025-04-02_16-50-27.png

然后回到菜单选择

PixPin_2025-04-02_16-51-30.png
PixPin_2025-04-02_16-53-02.png
PixPin_2025-04-02_16-54-24.png

务必做好上述这些配置，否则后续Netbird客户端将无法通过URL的方式鉴权。

二、安装netbird

1.创建拉取脚本，并拉取最新代码

第一步、先创建netbird目录

cd ~ && mkdir netbird && cd netbird

第二步、执行nano start.sh，然后输入以下内容：

#!/bin/bash
REPO="https://github.com/netbirdio/netbird/"
# this command will fetch the latest release e.g. v0.8.7
LATEST_TAG=$(basename $(curl -fs -o/dev/null -w %{redirect_url} ${REPO}releases/latest))
echo $LATEST_TAG

# this command will clone the latest tag
git clone --depth 1 --branch $LATEST_TAG $REPO

按Ctrl+X输入y最后回车保存start.sh文件

执行chmod +x start.sh赋予文件执行权限，之后运行start.sh脚本以获取最新版本并克隆代码

2. 配置netbird

步骤1：进入配置目录

cd netbird/infrastructure_files/

步骤2：准备配置文件

# 复制配置模板
cp setup.env.example setup.env
# 编辑配置
nano setup.env

需要修改的内容如下：

# 这里填写你的netbird域名
NETBIRD_DOMAIN=""


# 这里填写你的authentik认证服务的地址 "https://你的服务域名/application/o/netbird/.well-known/openid-configuration"
NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://你的服务域名/application/o/netbird/.well-known/openid-configuration"

# 这里填写你的authentik得到的客户端ID
NETBIRD_AUTH_AUDIENCE=""
NETBIRD_AUTH_CLIENT_ID=""
NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID=""
NETBIRD_AUTH_DEVICE_AUTH_AUDIENCE=""
NETBIRD_IDP_MGMT_CLIENT_ID=""

# 这一项这样修改
NETBIRD_AUTH_SUPPORTED_SCOPES="openid profile email offline_access api"

# 这里填写authentik
NETBIRD_MGMT_IDP="authentik"

# 修改这里的为true
NETBIRD_DISABLE_LETSENCRYPT=true

# 添加如下内容
# 这个直接填写Netbird
NETBIRD_IDP_MGMT_EXTRA_USERNAME="Netbird"
# 这里填写你之前配置Authentik时得到的服务账户密码
NETBIRD_IDP_MGMT_EXTRA_PASSWORD="Service Account Password"

# 修改默认端口
NETBIRD_MGMT_API_PORT=8012
NETBIRD_SIGNAL_PORT=10000

参考的是如下图这个官方文档：

PixPin_2025-04-03_19-07-38.png

修改完成后记得ctrl+x 然后输入y 最后回车保存

步骤3（可选)：禁用单账户模式

修改docker-compose.yml.tmpl文件

nano docker-compose.yml.tmpl

然后在management中添加--disable-single-account-mode这条启动命令

PixPin_2025-04-03_19-29-33.png

最后保存并退出

步骤4：生成配置文件

执行官方提供的配置脚本来生成相应的配置文件：

./configure.sh

步骤5：运行docker compose

完成后转到artifacts目录

cd artifacts

里面应该有这4个文件：docker-compose.yml、management.json、openid-configuration.json、turnserver.conf

👉由于官方的这个脚本有点问题，我们还需要修改一些配置才能使其正常工作，首先编辑management.json：

nano management.json

默认的信号服务的端口为10000：

"Signal": {
        "Proto": "https",
        "URI": "nb.example.com:10000",
        "Username": "",
        "Password": ""
    },

需要将其改为443端口，因为我们后续会配置使用Nginx反向代理信号服务：

"Signal": {
        "Proto": "https",
        "URI": "nb.example.com:443",
        "Username": "",
        "Password": ""
    },

👉还需要修改compose文件：

nano docker-compose.yml

官方的脚本没有帮我们处理dashboard容器的端口，由于我们后续会配置使用Nginx反向代理，所以将这里的443端口注释掉，容器外的80端口改为8011：

services:
  #UI dashboard
  dashboard:
    image: netbirdio/dashboard:latest
    restart: unless-stopped
    ports:
      - 8011:80
#      - 443:443

👉另外dashboard容器的环境变量也需要做修改，默认情况下会把Endpoints相关的环境变量配置为Domain:8012的形式：

services:
  #UI dashboard
  dashboard:
    image: netbirdio/dashboard:latest
    ...
    environment:
      # Endpoints
      - NETBIRD_MGMT_API_ENDPOINT=https://nb.example.com:8012
      - NETBIRD_MGMT_GRPC_API_ENDPOINT=https://nb.example.com:8012
    ...

需要将其修改为：

services:
  #UI dashboard
  dashboard:
    image: netbirdio/dashboard:latest
    ...
    environment:
      # Endpoints
      - NETBIRD_MGMT_API_ENDPOINT=https://nb.example.com
      - NETBIRD_MGMT_GRPC_API_ENDPOINT=https://nb.example.com

👉启用signal容器的日志，方便后续维护和调试

...
  signal:
    image: netbirdio/signal:latest
    restart: unless-stopped
...
    command: [ "--log-file", "console"]

👉执行如下命令启动容器

docker compose up -d

步骤6：配置Nginx反向代理Netbird

启动Netbird成功后，现在需要反代Netbird的8011、8012、10000端口，Nginx站点配置文件如下：

upstream dashboard {
    server 127.0.0.1:8011;
    keepalive 10;
}
upstream signal {
    server 127.0.0.1:10000;
}
upstream management {
    server 127.0.0.1:8012;
}

server {
    listen 80;
    listen [::]:80;
    server_name nb.example.com;

    client_header_timeout 1d;
    client_body_timeout 1d;

    proxy_set_header        X-Real-IP $remote_addr;
    proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header        X-Scheme $scheme;
    proxy_set_header        X-Forwarded-Proto https;
    proxy_set_header        X-Forwarded-Host $host;
    grpc_set_header         X-Forwarded-For $proxy_add_x_forwarded_for;

    # Proxy dashboard
    location / {
        proxy_pass http://dashboard;
    }
    # Proxy Signal
    location /signalexchange.SignalExchange/ {
        grpc_pass grpc://signal;
        #grpc_ssl_verify off;
        grpc_read_timeout 1d;
        grpc_send_timeout 1d;
        grpc_socket_keepalive on;
    }
    # Proxy Management http endpoint
    location /api {
        proxy_pass http://management;
    }
    # Proxy Management grpc endpoint
    location /management.ManagementService/ {
        grpc_pass grpc://management;
        #grpc_ssl_verify off;
        grpc_read_timeout 1d;
        grpc_send_timeout 1d;
        grpc_socket_keepalive on;
    }
}

按照文件配置反向代理，然后Netbird服务端就全部部署完毕了。