NetBird 服务端部署教程（官方脚本生成配置文件 + Docker Compose + Caddy）

1. 方案概览

最终结构：

• 宿主机 Caddy 负责 80/tcp、443/tcp 和 HTTPS 证书
• dashboard 容器提供控制台前端
• netbird-server 容器提供 management / signal / API / embedded IdP
• 3478/udp 直接暴露到公网，供 STUN 使用

也就是说：

• 官方脚本只负责帮你生成配置文件
• 真正运行仍然靠 docker compose
• 反代依然由你现有的 Caddy 负责

2. 域名是不是必须

建议视为必须。

因为这条路线默认会使用：

• https://你的域名
• embedded IdP 的回调地址
• Caddy 的自动 TLS 证书申请

示例域名：

netbird.example.com

并且需要提前解析到服务器公网 IP。

3. 前提条件

至少满足以下条件：

• 一台公网 Linux 服务器
• 已安装 Docker
• 已安装 docker compose
• 已安装 curl
• 已安装 jq
• 已安装宿主机版 Caddy
• 已放行：
  • 80/tcp
  • 443/tcp
  • 3478/udp

如果你在云服务器上，还要确认安全组也放通了上述端口。

4. 创建工作目录

示例目录：

sudo mkdir -p /opt/netbird
sudo chown "$USER":"$USER" /opt/netbird
cd /opt/netbird

5. 执行官方脚本

在工作目录里运行：

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

脚本执行过程中，会询问你一些问题。

6. 脚本交互时怎么选

建议按下面思路选择：

1）管理域名

填你的实际域名，例如：

netbird.example.com

2）反向代理类型

如果你想继续使用宿主机现有的 Caddy，选择：

External Caddy

不要选 Traefik，除非你准备把反向代理也交给脚本生成的 Traefik 容器。

3）是否启用 NetBird Proxy

如果脚本询问是否启用 NetBird Proxy，建议先选：

N

原因：

• 你当前目标只是先把管理面部署起来
• NetBird Proxy 官方更推荐配合 Traefik
• 如果你选了 Caddy 路线，再启用 Proxy 会让整体复杂度明显上升

7. 脚本通常会生成哪些文件

成功后，目录下通常会出现这些文件：

• docker-compose.yml
• config.yaml
• dashboard.env
• caddyfile-netbird.txt

有时还会包含其他辅助文件，但上面这几个是最关键的。

可以先查看：

ls -lah

8. 每个文件是干什么的

1）docker-compose.yml

作用：

• 定义要启动哪些容器
• 定义端口映射
• 定义数据卷和配置挂载

你后续日常维护主要就是靠它：

docker compose up -d
docker compose ps
docker compose logs -f
docker compose pull

2）config.yaml

作用：

• 定义 NetBird 服务端核心配置
• 包括外部访问地址、认证、embedded IdP、存储方式等

你可以重点检查：

• 域名是否正确
• issuer 是否正确
• redirect URI 是否正确
• 是否使用了 sqlite

3）dashboard.env

作用：

• 提供 Dashboard 前端运行时环境变量
• 告诉前端该访问哪个管理地址和认证地址

你可以重点检查：

• NETBIRD_MGMT_API_ENDPOINT
• AUTH_AUTHORITY
• AUTH_CLIENT_ID

4）caddyfile-netbird.txt

作用：

• 这是脚本给你生成的 Caddy 站点配置示例
• 一般是给“宿主机已有 Caddy”的场景准备的

你通常不需要单独让它生效，而是把其中 NetBird 相关站点块合并到你自己的：

/etc/caddy/Caddyfile

9. 先不要急着启动，先检查生成内容

建议先看这三个文件：

sed -n '1,220p' docker-compose.yml
sed -n '1,260p' config.yaml
sed -n '1,220p' dashboard.env

你至少要确认下面几件事。

10. 重点检查项

1）检查 Compose 端口映射

对于 “External Caddy” 路线，常见思路是：

• dashboard 只监听本机回环地址，例如 127.0.0.1:8080
• netbird-server 只监听本机回环地址，例如 127.0.0.1:8081
• 3478/udp 对公网开放

你可以重点找类似内容：

ports:
  - "127.0.0.1:8080:80"

和：

ports:
  - "127.0.0.1:8081:80"
  - "3478:3478/udp"

如果脚本生成的本地端口不是 8080/8081，也没关系，但你后面的 Caddy 配置必须同步对应。

2）检查 config.yaml 中的域名

重点确认这些值里的域名是否正确：

• server.exposedAddress
• server.auth.issuer
• server.auth.dashboardRedirectURIs
• server.auth.cliRedirectURIs

3）检查 dashboard.env 中的认证地址

重点确认：

• NETBIRD_MGMT_API_ENDPOINT
• NETBIRD_MGMT_GRPC_API_ENDPOINT
• AUTH_AUTHORITY

这些值是否都指向你的实际域名。

4）检查是否为 Caddy 外部反代模式

通常你会看到类似思路：

• Dashboard 不自己申请公开证书
• 认证地址和管理地址都指向你的外部域名

如果 dashboard.env 中出现类似：

LETSENCRYPT_DOMAIN=none

这通常意味着证书交给外部反向代理处理，是符合预期的。

11. 把脚本生成的 Caddy 配置合并到宿主机 Caddyfile

先查看脚本生成的模板：

sed -n '1,220p' caddyfile-netbird.txt

然后把其中和 NetBird 相关的站点配置，合并进你的：

/etc/caddy/Caddyfile

典型结构一般类似：

netbird.example.com {
    encode zstd gzip

    @grpc header Content-Type application/grpc*
    reverse_proxy @grpc h2c://127.0.0.1:8081

    @backend path /relay* /ws-proxy/* /api/* /oauth2/*
    reverse_proxy @backend 127.0.0.1:8081

    reverse_proxy 127.0.0.1:8080
}

如果脚本输出和这里略有差异，以脚本生成结果为准，再结合你自己的现网 Caddy 风格调整。

12. 校验并重载 Caddy

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy

如果你的 Caddy 不是通过 systemd 启动，请改用自己的重载方式。

13. 用生成好的 Compose 文件启动服务

确认配置无误后启动：

cd /opt/netbird
docker compose up -d
docker compose ps

查看日志：

docker compose logs -f

14. 首次初始化

浏览器访问：

https://netbird.example.com/setup

首次访问时：

1. 创建管理员账号
2. 设置邮箱、名称、密码
3. 完成初始化

初始化完成后，后续再访问通常会进入普通登录页。

15. 推荐的“生成后备份”做法

虽然配置是脚本生成的，但建议你马上备份一份：

cd /opt/netbird
tar czf netbird-config-backup.tgz docker-compose.yml config.yaml dashboard.env caddyfile-netbird.txt

这样后续升级或回滚会更方便。

16. 后续如何维护

这条路线下，脚本不是每天都要跑。

通常只在下面两种情况下才考虑重新运行：

• 你第一次初始化部署
• 你要重建整套配置

平时的运维主要还是：

docker compose ps
docker compose logs -f
docker compose pull
docker compose up -d

也就是说：

• 生成配置靠脚本
• 日常维护靠 docker compose
• HTTPS 和域名还是由宿主机 Caddy 管

17. 常见问题

1）脚本跑完了，但网页打不开

优先检查：

• 域名是否已经解析到公网 IP
• 80/tcp 和 443/tcp 是否可从公网访问
• Caddy 是否已经 reload 成功
• docker compose ps 里容器是否正常

2）网页能开，但登录或接口异常

优先检查：

• Caddyfile 是否正确拆分了 gRPC 和普通后端请求
• config.yaml 和 dashboard.env 中的域名是否一致
• AUTH_AUTHORITY 是否和 issuer 对应

3）客户端注册失败

优先检查：

• 3478/udp 是否开放
• 云安全组是否放行 3478/udp
• docker-compose.yml 是否真的映射了 3478:3478/udp

4）我能不能先用脚本生成，再手动修改

可以，而且这其实是比较稳妥的方式。

推荐顺序：

1. 先用脚本生成
2. 审核 docker-compose.yml
3. 审核 config.yaml
4. 审核 dashboard.env
5. 再根据自己的环境微调
6. 最后启动

18. 和手工版教程怎么选

你可以这样理解：

• 如果你想完全掌控每个字段怎么来，用手工版
• 如果你想先得到一套官方当前版本可用的基线配置，再自己审阅和修改，用这份脚本生成版

对大多数人来说，脚本生成版更适合作为第一套基线。

19. 最小核对清单

部署完成后，至少确认这几项：

• 域名已经正确解析
• 80/tcp、443/tcp、3478/udp 已开放
• 已生成 docker-compose.yml
• 已生成 config.yaml
• 已生成 dashboard.env
• 已生成 caddyfile-netbird.txt
• 宿主机 Caddy 已合并 NetBird 站点配置
• docker compose ps 状态正常
• https://netbird.example.com/setup 可访问

20. 参考文档

• NetBird 官方 Quickstart：
  • https://docs.netbird.io/selfhosted/selfhosted-quickstart
• NetBird 官方 External Reverse Proxy：
  • https://docs.netbird.io/selfhosted/external-reverse-proxy
• NetBird 官方脚本：
  • https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh