企业官网建设流程全解析

1. 为什么“一键部署自定义端口的NetBird”不是噱头，而是真实存在的效率跃迁

NetBird 这个名字在最近半年的技术圈里出现频率陡增，尤其在中小团队和独立开发者之间。它不像 WireGuard 那样需要手写配置、调试内核模块，也不像 Tailscale 那样强绑定中心化控制平面——它用一套轻量级的 Go 二进制 + 内存中 mesh 路由表，把“零配置组网”这件事真正落到了实处。但问题来了：官方 Docker 镜像默认监听53/udp（DNS）、443/tcp（HTTPS 控制面）、51820/udp（WireGuard 数据面），这三个端口在很多生产环境里根本不可用。比如你租了一台阿里云轻量应用服务器，安全组默认只开放22、80、443；又比如你在公司内网部署，防火墙策略严禁51820这类“非标”UDP 端口通行；再比如你正跑着 Nginx，443已被占用，根本没法让 NetBird 的管理 API 启动。

这时候，“一键部署自定义端口”就不再是锦上添花的功能，而是决定项目能否落地的生死线。我去年帮一家做边缘 AI 推理的客户做远程设备纳管，他们现场有 37 台 NVIDIA Jetson Orin，全部部署在工厂车间的隔离子网里，出口只允许走443和8080。我们试过强行改 NetBird Agent 的--port参数，结果发现控制面通信直接中断——因为 Server 端没同步改，Agent 发起的 TLS 握手始终连不到443。后来翻了三天源码才搞明白：NetBird 的端口不是单点配置，而是一套三层映射关系：Docker 容器内部监听端口 → 宿主机端口映射 → 控制面服务注册地址中的端口声明。三者必须严格对齐，否则整个 mesh 就会“失联”。所谓“一键”，本质是把这三重映射的校验、生成、注入逻辑全部封装进一个可复用的脚本里，而不是简单地docker run -p 8080:443就完事。

关键词里虽然没填，但实际场景中，“Docker”是绕不开的载体。NetBird 官方推荐的部署方式就是容器化，原因很实在：它的 Server 组件依赖 PostgreSQL、Redis、gRPC Gateway、OIDC Provider 等多个服务，手动编译安装光依赖版本对齐就能耗掉一整天。而 Docker Compose 能把整个依赖栈打包成一个声明式文件，配合.env文件做变量注入，天然适配“自定义端口”这个需求。我测试过，在 Ubuntu 22.04 上，从git clone到docker-compose up -d成功，全程 6 分钟 23 秒，其中 4 分钟 17 秒花在拉镜像上——这才是“一键”的真实含义：不是省去所有步骤，而是把重复性高、容错率低、极易出错的配置环节，压缩成一次确定性极高的执行。

所以，这篇文章不讲“NetBird 是什么”，也不堆砌概念图。我要带你亲手拆开那个deploy.sh脚本，看它怎么把PORT_HTTP=8080、PORT_GRPC=9001、PORT_WG=51821这三个变量，精准地塞进docker-compose.yml的ports字段、netbird-server的启动参数、以及netbird-admin前端的 API 地址配置里。你会看到，真正的“一键”，背后是至少 7 处硬编码检查、3 次端口冲突探测、2 次 YAML 结构校验——这些细节，官方文档一页都没提，但它们决定了你的组网是 5 分钟跑通，还是卡在connection refused里查到凌晨三点。

2. 端口自定义不是改个数字那么简单：NetBird 的三层端口映射机制

很多人第一次尝试改端口，是在docker-compose.yml里把- "443:443"改成- "8080:443"，然后兴冲冲docker-compose up，结果浏览器打不开https://your-domain:8080，日志里全是failed to dial grpc server。这不是你的操作错了，而是你没理解 NetBird 的端口不是“单点暴露”，而是一个贯穿 Client-Server-Admin 的完整链路。我把这个链路拆成三层，每层都必须显式声明、且彼此一致，否则整个 mesh 就会断成碎片。

2.1 第一层：Server 容器内部监听端口（底层事实）

这是最基础的一层，也是所有后续配置的源头。NetBird Server 的核心组件netbird-server是一个 Go 二进制，它启动时通过命令行参数指定监听地址。关键参数有两个：

• --http-port：控制面 HTTP API 和 Web UI 的监听端口，默认443
• --grpc-port：gRPC 服务端口（Agent 用来注册、同步路由表），默认33073

注意，这里没有--wg-port，因为 WireGuard 数据面是通过netbird-server内部的wgctrl库直接操作内核模块，不走 TCP/UDP socket，所以它不参与“端口映射”，但它的 UDP 端口（默认51820）必须由netbird-server在启动时显式传给wgctrl初始化，这个值会写入数据库并下发给所有 Agent。

所以，如果你只想改 Web UI 端口，只改--http-port是不够的——netbird-admin前端在构建时，会把API_BASE_URL硬编码进 JS bundle 里。如果 Server 监听8080，但前端还往443发请求，那页面永远是白屏。这就是第二层要解决的问题。

2.2 第二层：Admin 前端的 API 地址硬编码（构建时锁定）

netbird-admin是一个 React 应用，它的src/config.js里有这样一段：

export const API_BASE_URL = process.env.REACT_APP_API_BASE_URL || 'https://localhost:443';

这个REACT_APP_API_BASE_URL是在docker build阶段通过--build-arg注入的。也就是说，当你docker-compose build admin时，Dockerfile 会读取.env文件里的ADMIN_API_URL变量，并把它作为构建参数传进去。最终生成的index.html里，所有 fetch 请求都会发往这个地址。

我做过实验：如果ADMIN_API_URL=https://my-server:8080，但netbird-server实际监听的是443，那么前端能加载，但所有 API 调用 100% 404；反之，如果ADMIN_API_URL指向443，但netbird-server监听8080，则前端直接报net::ERR_CONNECTION_REFUSED。两者必须严丝合缝。

2.3 第三层：Docker 端口映射与外部可达性（运行时桥梁）

这是最外层，也是用户唯一能直接感知的一层。docker-compose.yml里的ports字段，本质是告诉 Docker Daemon：“把宿主机的8080端口，转发到容器内部的443端口”。但它不改变容器内部进程的监听行为，也不影响前端构建时的 URL。它只是网络层面的“管道”。

但这里有个致命陷阱：Docker 的ports映射只对bridge网络模式生效，而 NetBird Server 默认使用host网络模式。为什么？因为netbird-server需要直接操作wg0接口，而bridge模式下容器没有权限访问宿主机的网络命名空间。所以，官方docker-compose.yml里netbird-server的network_mode: host是强制要求。

这意味着：ports字段对netbird-server容器完全无效！你写- "8080:443"，它根本不会起作用。netbird-server只会监听宿主机的443，而netbird-admin容器（它用的是bridge模式）要访问 Server，只能通过http://host.docker.internal:443这个特殊 DNS 名。所以，netbird-admin的API_BASE_URL必须指向host.docker.internal，而不是localhost或域名。

我把这三层的关系画成一张表，方便你对照检查：

提示：host.docker.internal这个 DNS 名在 Linux 上默认不存在，需要在docker-compose.yml的netbird-admin服务下显式添加extra_hosts：

extra_hosts: - "host.docker.internal:host-gateway"

否则admin容器根本解析不了这个域名，日志里全是getaddrinfo ENOTFOUND host.docker.internal。

3. “一键部署脚本”的真实面目：7 个校验点与 3 次端口探测

现在你知道了，所谓“一键”，绝不是curl | bash那种黑盒操作。它必须是一个透明、可审计、可调试的 Bash 脚本，里面藏着至少 7 个关键校验点和 3 次主动探测。我把它拆解给你看，每一行代码都有明确目的，没有一行是凑数的。

3.1 校验点 1：端口可用性探测（避免启动即失败）

脚本第一件事，不是生成配置，而是检查你要用的端口在宿主机上是否空闲。很多人忽略这点，直接docker-compose up，结果netbird-server启动失败，日志里只有一句listen tcp :443: bind: address already in use，然后开始疯狂 Google。脚本里用ss -tuln做静默探测：

check_port_available() { local port=$1 if ss -tuln | grep -q ":$port "; then echo "❌ 端口 $port 已被占用，请更换" exit 1 fi } check_port_available "$HTTP_PORT" check_port_available "$GRPC_PORT" check_port_available "$WG_PORT"

注意，这里探测的是WG_PORT（即 WireGuard UDP 端口），虽然它不走docker ports，但netbird-server启动时会尝试bind()这个 UDP socket，如果被占，直接 panic。我见过最离谱的案例：客户在51820上跑了另一个 WireGuard 实例，netbird-server日志里没有任何提示，只是 Agent 死活连不上，最后用strace才抓到bind(51820) = -1 EADDRINUSE。

3.2 校验点 2：端口范围合法性（防低级错误）

HTTP_PORT设成65536？WG_PORT设成-1？这种输入必须在脚本里拦截。脚本里有严格的数值范围检查：

validate_port() { local port=$1 if [[ ! $port =~ ^[0-9]+$ ]] || [ "$port" -lt 1 ] || [ "$port" -gt 65535 ]; then echo "❌ 端口 $port 不合法：必须是 1-65535 的整数" exit 1 fi } validate_port "$HTTP_PORT" validate_port "$GRPC_PORT" validate_port "$WG_PORT"

这个检查救了我两次：一次是同事手抖把8080打成80800，一次是测试环境误设HTTP_PORT=0，结果netbird-server启动后监听0.0.0.0:0，所有 Agent 都连到一个随机端口，整个 mesh 彻底混乱。

3.3 校验点 3：Docker 与 Compose 版本兼容性（避坑关键）

NetBird Server v0.24.0 要求 Docker Engine >= 20.10，Compose v2.15+。老版本的docker-compose（v1.x）根本不支持profiles和x-networks这些高级特性，会导致docker-compose up报yaml: unmarshal errors。脚本里用docker version --format '{{.Server.Version}}'和docker compose version --short提取版本号，做字符串比较：

DOCKER_VERSION=$(docker version --format '{{.Server.Version}}' | cut -d. -f1,2) COMPOSE_VERSION=$(docker compose version --short | cut -d. -f1,2) if [[ "$(printf '%s\n' "$DOCKER_VERSION" "20.10" | sort -V | tail -n1)" != "20.10" ]]; then echo "❌ Docker 版本过低，需 >= 20.10，当前 $DOCKER_VERSION" exit 1 fi

注意：sort -V是语义化版本排序，比sort -n更可靠。我曾经在一台 CentOS 7 机器上，docker --version显示20.10.12，但docker version --format输出却是20.10，导致脚本误判。所以最终采用cut -d. -f1,2截取主次版本号，再用sort -V比较，这才是生产环境该用的方式。

3.4 校验点 4：.env 文件变量完整性（防漏配）

.env文件里必须有HTTP_PORT、GRPC_PORT、WG_PORT、DOMAIN_NAME四个变量。脚本用grep -q '^HTTP_PORT=' .env逐个检查，缺一个就报错退出。为什么DOMAIN_NAME也必须？因为netbird-server的 TLS 证书是用certbot自动生成的，它需要域名来申请 Let's Encrypt 证书。如果你填localhost，certbot会直接失败，因为 LE 不签localhost。所以脚本里还加了一行：

if [[ "$DOMAIN_NAME" == "localhost" ]]; then echo "❌ DOMAIN_NAME 不能为 localhost，请配置真实域名或内网 DNS 可解析的名称" exit 1 fi

3.5 校验点 5：YAML 结构校验（防手误破坏格式）

docker-compose.yml是 YAML 格式，缩进错一个空格就会yaml: unmarshal errors。脚本在生成最终文件前，用yamllint做语法检查（需提前pip install yamllint）：

if ! yamllint docker-compose.yml >/dev/null 2>&1; then echo "❌ docker-compose.yml 格式错误，请检查缩进和冒号" exit 1 fi

这个检查在我自己身上发生过：有一次复制粘贴ports配置，多了一个空格，docker-compose up报错信息极其晦涩，花了 40 分钟才定位到是 YAML 语法问题。加了yamllint后，脚本直接告诉你第 12 行缩进错误，秒级定位。

3.6 校验点 6：PostgreSQL 连接预检（防数据库启动失败）

netbird-server启动前必须确保 PostgreSQL 可连接。脚本里用pg_isready做连接测试：

if ! pg_isready -h postgres -p 5432 -U netbird; then echo "❌ PostgreSQL 无法连接，请检查 postgres 服务状态" exit 1 fi

这个检查非常必要。因为docker-compose up是并行启动所有服务，postgres容器可能还没初始化完，netbird-server就开始连，结果连不上就 crash loop。有了这个预检，脚本会等postgresready 后再继续，避免无谓的重启。

3.7 校验点 7：TLS 证书存在性检查（防 HTTPS 白屏）

netbird-admin前端通过 HTTPS 访问netbird-server的 API，如果证书不存在或过期，浏览器会直接拦截，页面白屏。脚本在启动前检查/etc/letsencrypt/live/$DOMAIN_NAME/fullchain.pem是否存在且可读：

CERT_PATH="/etc/letsencrypt/live/$DOMAIN_NAME/fullchain.pem" if [[ ! -f "$CERT_PATH" ]] || [[ ! -r "$CERT_PATH" ]]; then echo "❌ TLS 证书不存在或不可读：$CERT_PATH" echo "💡 运行 'sudo certbot certonly --standalone -d $DOMAIN_NAME' 获取证书" exit 1 fi

这个检查让我少踩了三次坑。有一次证书过期没注意，netbird-server日志里只有http: TLS handshake error，前端白屏，查了两个小时才发现是证书问题。

4. 从零生成可运行的 docker-compose.yml：变量注入的 5 种手法

docker-compose.yml是整个部署的蓝图，而它的灵魂在于变量注入。NetBird 官方模板里用的是env_file，但这种方式在“自定义端口”场景下有严重缺陷：env_file只能注入环境变量到容器内部，无法修改ports字段、command参数、build.args这些顶层配置。所以，我们必须用更灵活的方式——模板渲染。我用envsubst作为核心工具，配合 5 种不同粒度的注入手法，确保每个端口都在正确的位置被替换。

4.1 手法 1：全局变量注入（.env 文件驱动）

这是最基础的手法。创建一个docker-compose.template.yml，里面用${HTTP_PORT}这样的占位符：

version: '3.8' services: netbird-server: image: netbirdio/netbird-server:v0.24.0 command: > --http-port ${HTTP_PORT} --grpc-port ${GRPC_PORT} --wg-port ${WG_PORT} --domain ${DOMAIN_NAME} ports: - "${HTTP_PORT}:${HTTP_PORT}" - "${GRPC_PORT}:${GRPC_PORT}" # ... 其他配置

然后用envsubst < docker-compose.template.yml > docker-compose.yml渲染。但注意：envsubst默认只替换$VAR和${VAR}，不支持${VAR:-default}这种 bash 扩展语法。所以.env文件里必须提供所有变量，不能留空。

4.2 手法 2：构建时参数注入（Admin 前端 URL 的命门）

netbird-admin的API_BASE_URL必须在docker build阶段注入，不能等到运行时。所以在docker-compose.yml的admin服务里，这样写：

admin: build: context: ./admin dockerfile: Dockerfile args: - REACT_APP_API_BASE_URL=https://${DOMAIN_NAME}:${HTTP_PORT} # ... 其他配置

args字段会把REACT_APP_API_BASE_URL作为构建参数传给Dockerfile，而Dockerfile里必须有对应的ARG声明：

FROM node:18-alpine AS builder ARG REACT_APP_API_BASE_URL ENV REACT_APP_API_BASE_URL=$REACT_APP_API_BASE_URL # ... 构建逻辑

这个ARG是关键。我曾经漏写了ARG，只写了ENV，结果构建出来的镜像里REACT_APP_API_BASE_URL是空的，前端默认连localhost:443，在容器里当然连不通。

4.3 手法 3：运行时覆盖（Server 启动参数的动态拼接）

netbird-server的command参数很长，包含--http-port、--grpc-port、--wg-port、--domain、--log-level等十几个选项。如果全写在docker-compose.yml里，模板会变得极其臃肿。我的做法是：在.env文件里定义一个SERVER_COMMAND_ARGS变量，脚本里用printf动态拼接：

SERVER_COMMAND_ARGS="--http-port ${HTTP_PORT} --grpc-port ${GRPC_PORT} --wg-port ${WG_PORT} --domain ${DOMAIN_NAME}" echo "SERVER_COMMAND_ARGS=$SERVER_COMMAND_ARGS" >> .env

然后在docker-compose.template.yml里直接引用：

command: ${SERVER_COMMAND_ARGS}

这样，.env文件保持简洁，复杂逻辑交给脚本处理，符合 Unix 哲学——“让脚本做计算，让配置做声明”。

4.4 手法 4：条件化端口映射（应对 host 模式限制）

前面说过，netbird-server用host模式，ports字段无效。但netbird-admin和nginx（反向代理）用的是bridge模式，它们的ports必须映射。所以，我在模板里用两个不同的变量：

# netbird-server 用 host 模式，不映射端口 netbird-server: network_mode: host # ... 无 ports 字段 # nginx 用 bridge 模式，必须映射 nginx: image: nginx:alpine ports: - "${HTTP_PORT}:443" - "${HTTP_PORT}:80" # ... 其他配置

这里nginx的ports是"${HTTP_PORT}:443"，意思是把宿主机的HTTP_PORT（比如8080）映射到容器内部的443。而netbird-server容器内部依然监听443，但因为它用host模式，所以它直接监听宿主机的443端口——等等，这不就冲突了吗？

不冲突。因为nginx是反向代理，它监听宿主机的8080，然后把流量转发给http://localhost:443（即netbird-server的host模式监听地址）。所以netbird-server实际监听的是localhost:443，而nginx监听的是0.0.0.0:8080，两者端口不重叠。这个设计是 NetBird 官方推荐的生产部署模式，既解决了host模式的权限问题，又实现了端口自定义。

4.5 手法 5：敏感信息分离（证书路径的绝对化处理）

netbird-server需要读取 TLS 证书，路径是/etc/letsencrypt/live/${DOMAIN_NAME}/fullchain.pem。这个路径不能硬编码在docker-compose.yml里，因为DOMAIN_NAME是变量，而且证书路径在不同系统上可能不同（比如 macOS 上用mkcert生成的证书在/Users/xxx/cert.pem）。所以，我在脚本里动态生成一个certs卷：

CERT_DIR="/etc/letsencrypt/live/$DOMAIN_NAME" if [[ ! -d "$CERT_DIR" ]]; then CERT_DIR="/opt/certs" # fallback for dev fi echo "CERT_DIR=$CERT_DIR" >> .env

然后在docker-compose.template.yml里：

volumes: - "${CERT_DIR}:/etc/ssl/certs:ro"

这样，无论证书在哪儿，脚本都能找到并挂载。我测试过三种环境：Ubuntu（Let's Encrypt）、macOS（mkcert）、CentOS（自签名），这个方案全部兼容。

5. 实战排错：5 个高频问题与 100% 可复现的修复路径

即使脚本做了 7 个校验，部署过程中依然会遇到各种诡异问题。下面这 5 个，是我过去一年在 17 个不同客户环境里，100% 遇到过的高频问题。每个问题我都给出了完整的排查链路和修复命令，你可以直接复制粘贴执行。

5.1 问题 1：Web UI 加载成功，但所有 API 请求返回 404

现象：浏览器打开https://your-domain:8080，UI 正常显示登录页，输入账号密码后，Network 面板里所有/api/v1/*请求都是 404。

根因定位：这是典型的第二层（Admin 前端 URL）与第一层（Server 监听端口）不一致。前端构建时REACT_APP_API_BASE_URL指向了错误的端口。

排查链路：

1. 进入netbird-admin容器：docker exec -it netbird_admin sh
2. 查看构建时注入的环境变量：cat /app/.env.local（React 应用会在构建时生成这个文件）
3. 检查输出是否为REACT_APP_API_BASE_URL=https://your-domain:443（错误）或https://your-domain:8080（正确）

修复命令：

# 重新构建 admin 镜像，注入正确的 URL docker build \ --build-arg REACT_APP_API_BASE_URL="https://your-domain:$HTTP_PORT" \ -t netbirdio/netbird-admin:custom \ ./admin # 修改 docker-compose.yml，让 admin 服务使用新镜像 # 然后重启 docker-compose down && docker-compose up -d

5.2 问题 2：Agent 无法注册，日志显示rpc error: code = Unavailable desc = connection closed before server preface received

现象：netbird service start启动 Agent，日志里反复出现connection closed before server preface received，netbird status显示offline。

根因定位：这是 gRPC 连接失败，99% 的原因是netbird-server的--grpc-port和netbird-admin的API_BASE_URL不匹配，或者nginx反向代理没配置 gRPC 支持。

排查链路：

1. 检查netbird-server容器日志：docker logs netbird_server | grep "gRPC server listening"
2. 确认输出是否为gRPC server listening on :9001（假设GRPC_PORT=9001）
3. 检查nginx配置是否启用了http2和grpc_pass：

   location / { grpc_pass grpc://localhost:9001; grpc_set_header X-Real-IP $remote_addr; }

修复命令：

# 进入 nginx 容器，检查配置 docker exec -it netbird_nginx cat /etc/nginx/conf.d/default.conf # 如果没有 grpc_pass，编辑 docker-compose.yml，挂载自定义 nginx 配置 volumes: - "./nginx.conf:/etc/nginx/conf.d/default.conf:ro"

5.3 问题 3：docker-compose up启动后，netbird-server容器立即退出，日志为空

现象：docker-compose up -d后，docker ps -a显示netbird_server状态是Exited (1)，docker logs netbird_server输出为空。

根因定位：这是host模式下的经典陷阱——netbird-server需要CAP_NET_ADMIN权限来创建wg0接口，但 Docker 默认不赋予。docker-compose.yml里必须显式声明cap_add。

排查链路：

1. 检查docker-compose.yml中netbird-server服务是否有cap_add：

   cap_add: - NET_ADMIN - SYS_MODULE

2. 检查宿主机是否已加载wireguard内核模块：lsmod | grep wireguard

修复命令：

# 加载内核模块（Ubuntu/Debian） sudo apt update && sudo apt install -y wireguard sudo modprobe wireguard # 确保 docker-compose.yml 包含 cap_add # 然后重启 docker-compose down && docker-compose up -d

5.4 问题 4：Agent 能注册，但无法 ping 通其他节点，netbird routes显示路由表为空

现象：所有 Agent 都显示online，但ping 100.64.0.2（其他节点 IP）超时，netbird routes输出只有本地路由。

根因定位：这是 WireGuard 数据面端口（WG_PORT）没打通。netbird-server会把WG_PORT下发给所有 Agent，Agent 会尝试连接这个端口。如果防火墙阻断了这个 UDP 端口，mesh 就无法建立。

排查链路：

1. 在 Server 宿主机上，检查WG_PORT是否监听：sudo ss -tuln | grep :$WG_PORT
2. 从一台 Agent 机器上，测试 UDP 连通性：nc -zuv your-server-ip $WG_PORT
3. 如果nc显示Connection refused，说明 Server 没监听；如果超时，说明防火墙阻断。

修复命令：

# 开放防火墙（Ubuntu ufw） sudo ufw allow $WG_PORT/udp # 或者阿里云/腾讯云，去安全组里添加入方向规则 # 协议：UDP，端口：$WG_PORT，源：0.0.0.0/0（或最小化授权）

5.5 问题 5：netbird login失败，提示error: failed to get auth url: Get "https://.../api/v1/auth/url": x509: certificate signed by unknown authority

现象：在 Agent 机器上执行netbird login，报x509: certificate signed by unknown authority。

根因定位：Agent 客户端默认只信任公共 CA（如 Let's Encrypt），如果你用的是自签名证书或mkcert生成的证书，Agent 就会拒绝连接。

排查链路：

1. 检查netbird-server的证书是否为自签名：openssl x509 -in /path/to/cert.pem -text -noout | grep "CA:TRUE"
2. 如果是自签名，Agent 需要手动信任。

修复命令：

# 将证书复制到 Agent 机器 scp /etc/letsencrypt/live/your-domain/fullchain.pem user@agent:/tmp/ # 在 Agent 上，将证书加入系统信任库（Ubuntu/Debian） sudo cp /tmp/fullchain.pem /usr/local/share/ca-certificates/your-domain.crt sudo update-ca-certificates # 或者，临时跳过证书验证（仅测试用） netbird login --insecure-skip-tls-verify

注意：--insecure-skip-tls-verify是危险操作，生产环境务必用update-ca-certificates方式。

6. 部署完成后的 3 个必做验证与 1 个隐藏技巧

部署脚本跑完，docker-compose ps显示所有服务Up，不代表万事大吉。我总结了 3 个必须手动验证的步骤，以及 1 个官方文档里从没提过、但能极大提升稳定性的隐藏技巧。

6.1 验证 1：检查 Server 的 gRPC 服务是否真正可连通

docker-compose ps显示netbird_server是Up，但它的 gRPC 端口可能被防火墙挡住，或者nginx没配置好grpc_pass。最直接的验证方式，是用grpcurl工具直连：

# 在 Server 宿主机上安装 grpcurl curl -L https://github.com/fullstorydev/grpcurl/releases/download/v1.8.7/grpcurl_1.8.7_linux_x86_64.tar.gz | tar -xz # 测试 gRPC 连通性（假设 GRPC_PORT=9001） ./grpcurl -plaintext -import-path ./proto -proto api.proto localhost:9001 list # 正常输出应该包含： # netbird.api.ManagementService # netbird.api.SignalService

如果报Failed to dial target host "localhost:9001": dial tcp 127.0.0.1:9001: connect: connection refused，说明netbird-server根本没监听9001，回去检查command参数；如果报 `Failed to list services: rpc error: code = Unavailable desc = transport