Netbird Relay 部署记录

博主： WithdewHua
发布时间：2026 年 07 月 06 日
20 次浏览
暂无评论
3497字数
分类：笔记•记录

## 前言

最初 netbird 的 management/signal/coturn/relay 等服务是独立的，后来为了方便部署使用，统一成了一个 netbird-server，但也保留了独立部署服务的能力（提高性能和高可用），根据 [官方文档](https://docs.netbird.io/selfhosted/maintenance/scaling/scaling-your-self-hosted-deployment) 所述，relay/signal 均可以独立部署。

我使用 netbird 主要为了国外服务器之间的互联，都有公网 IP，其实对 relay 服务器需求不是那么高，但是折腾的心按捺不住。同 [Netbird Proxy + Nginx 部署记录](/2026/06/24/deploy-netbird-proxy-behind-nginx)</a> 中所述，我需要基于 nginx 进行部署，不过 relay 倒是不像 proxy 有 TLS 透传要求，比较简单，随便记录一下吧。

## 部署

**注意**：当前如果指定了外部 relay 服务器的话，那 netbird-server 内置的 relay 服务器就不会生效了，预计后续会支持共存 (见 [issue #5351](https://github.com/netbirdio/netbird/issues/5351))

### 生成 authSecret

```bash
openssl rand -base64 32
```

**注意**：该密钥生成一次即可，所有的 relay server 需要共享相同的密钥

### 部署 relay 服务

如前言所说，我需要使用 nginx 来处理 TLS，但是呢，官方文档提供的说明中，又是让 relay server 来处理 TLS，要么采用 ACME 申请证书，要么提供证书文件。但是看 relay server 的作用，本身提供的能力有两个：

- STUN 服务（UDP，用于 p2p 发现）
- Netbird Relay (quic/ws，http 服务，用于流量中转)
  就服务而言，没有必要非得要在 relay server 上进行  tls 终结。实际操作了下，确实如我所想。

#### 准备环境变量

准备环境变量文件 `relay.env`，文件内容示例如下：

```shell
NB_LOG_LEVEL=info
# relay server 监听的地址，容器部署，该端口为容器内监听端口，保持 443 无所谓
NB_LISTEN_ADDRESS=:443
# 实际 client 需要连接的 relay 地址
NB_EXPOSED_ADDRESS=rels://relay.netbird.10101.io:443
# 生成的 authSecret
NB_AUTH_SECRET=XprUtOMCVMdVYFdjLJqNl5mW+RUWyXjyJDgpoZhX0c8=
# Embedded STUN (comma-separated for multiple ports, e.g., 3478,3479)
NB_ENABLE_STUN=true
NB_STUN_PORTS=3478
```

这里去掉了官方示例中的证书相关环境变量，即不让 relay server 来处理 tls，仅对外提供 http 服务和 stun 服务。保证 `NB_EXPOSED_ADDRESS` 为实际 client 需要连接的地址即可。

#### docker-compose

依旧采用 docker-compose 进行部署，relay docker-compose.yaml 内容如下：

```yaml
services:
  relay:
    image: netbirdio/relay:latest
    container_name: netbird-relay
    restart: unless-stopped
    networks: [netbird]
    ports:
      # 监听在 127.0.0.1:33080，不占用 443 端口
      - '127.0.0.1:33080:443'
      # 暴露所有的 NB_STUN_PORTS，具体定义在环境变量文件 relay.env 中
      - '3478:3478/udp'
    env_file:
      # 使用环境变量文件
      - relay.env
    volumes:
      - ./relay_data:/data
    logging:
      driver: "json-file"
      options:
        max-size: "500m"
        max-file: "2"

networks:
  netbird:
    ipam:
      config:
        - subnet: 172.30.0.0/16
          gateway: 172.30.0.1
```

启动服务：

```bash
docker compose up -d

# 查看日志，确保正常启动并监听
docker compose logs relay
```

服务正常启动后，就可以使用 nginx 反代服务了，这里就不赘述了。

#### 配置 netbird-server

relay server 启动后，还需要在 netbird-server 的配置文件中增加 relay 的配置，才能正确下发给 client。

编辑 `config.yaml`文件，增加 relay 和 stun 配置，示例如下：

```yaml
  # External STUN servers
  stuns:
    # stun 地址
    - uri: "stun:relay.netbird.10101.io:3478"
      proto: "udp"

# External relay servers
  relays:
    addresses:
      # relay 地址
      - "rels://relay.netbird.10101.io:443"

# 生成的 authSecret
    secret: "XprUtOMCVMdVYFdjLJqNl5mW+RUWyXjyJDgpoZhX0c8="
    credentialsTTL: "24h"
```

然后重启 netbird-server: `docker compose restart netbird-server`

正常的话，client 端就会接收到新的 relay 服务器了，可以通过 `netbird status -d`，如下：

```bash
Relays: 
  [stun:relay.netbird.10101.io:3478] is Available
  [rels://relay.netbird.10101.io:443] is Available via ws
```

如果需要更多的 relay server 的话，重复上述步骤（注意使用同一 authSecret）即可。

## 参考资料

- [官方文档 set up external relays](https://docs.netbird.io/selfhosted/maintenance/scaling/set-up-external-relays)
- [官方文档 scaling your self-hosted deployment](https://docs.netbird.io/selfhosted/maintenance/scaling/scaling-your-self-hosted-deployment)

最后修改：2026 年 07 月 06 日