222 lines
6.9 KiB
Markdown
222 lines
6.9 KiB
Markdown
# NetBird External Relay Setup
|
||
|
||
交互式脚本，为一台或多台 [NetBird](https://netbird.io) 外部 Relay 服务器生成 `relay.env` 和 `docker-compose.yml`，在最后输出主服务器 `config.yaml` 的配置片段，并可选择自动配置防火墙规则。
|
||
|
||
参考文档：[Set Up External Relay Servers — NetBird Docs](https://docs.netbird.io/selfhosted/splitting-self-hosted-deployment/set-up-external-relay-servers)
|
||
|
||
## 前置要求
|
||
|
||
每台 Relay 服务器需满足：
|
||
|
||
- Linux，≥ 1 CPU / 1 GB RAM
|
||
- 公网 IP，且有域名解析指向该 IP；脚本里的 Relay 地址也可以直接填写 IP
|
||
- 已安装 Docker（含 `docker compose`）
|
||
- 以下端口按实际配置放行（脚本会在最后动态列出）：
|
||
- `80/tcp` — Let's Encrypt HTTP challenge（仅自动证书模式需要）
|
||
- `443/tcp` — Relay HTTPS（可自定义端口）
|
||
- `3478/udp` — STUN（可自定义端口，支持多个）
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
# 下载脚本
|
||
curl -O https://mybugs.work/i/netbird-relay/raw/branch/main/setup-relay.sh
|
||
|
||
# 添加执行权限
|
||
chmod +x setup-relay.sh
|
||
|
||
# 运行（交互式向导）
|
||
./setup-relay.sh
|
||
```
|
||
|
||
一键下载并运行：
|
||
|
||
```bash
|
||
bash <(curl -fsSL https://mybugs.work/i/netbird-relay/raw/branch/main/setup-relay.sh)
|
||
```
|
||
|
||
## 可选参数
|
||
|
||
| 参数 | 说明 |
|
||
|------|------|
|
||
| `--dry-run` | 预览模式，只打印生成内容，不写入文件，跳过防火墙步骤 |
|
||
| `--output=<dir>` | 指定默认输出根目录 |
|
||
|
||
```bash
|
||
# 预览，不写文件
|
||
./setup-relay.sh --dry-run
|
||
|
||
# 指定输出根目录
|
||
./setup-relay.sh --output=/opt/netbird-configs
|
||
|
||
# 组合使用
|
||
./setup-relay.sh --dry-run --output=/tmp/preview
|
||
```
|
||
|
||
## 向导流程
|
||
|
||
```
|
||
Step 1 · Authentication Secret
|
||
→ 若 /opt/netbird-relay/relay.env 已存在，自动读取密钥作为默认值，回车确认
|
||
→ 或自动生成新密钥，或手动粘贴已有密钥
|
||
|
||
Step 2 · How many relay servers?
|
||
→ 输入要配置的 Relay 数量（支持批量）
|
||
|
||
Step 3.N · Relay Server #N（每台重复）
|
||
→ 先询问输出目录，若目录下已有 relay.env 则自动读取作为所有字段的默认值
|
||
→ 域名、监听端口、日志级别
|
||
→ 是否启用内置 STUN，STUN 端口（支持多个，逗号分隔）
|
||
→ TLS 方式：
|
||
1) Let's Encrypt — 自动签发，需开放 80/tcp
|
||
2) 已有证书 — 输入宿主机目录及容器内路径（均可自定义）
|
||
3) 自签证书 — 脚本调用 openssl 生成，支持完整 Subject 字段、
|
||
额外 SAN（DNS/IP）、有效期、RSA/ECC 及密钥长度选择
|
||
4) 粘贴证书 — 直接粘贴 PEM 证书和私钥内容，由脚本写入 certs 目录
|
||
|
||
Step 4 · Main Server config.yaml Snippet
|
||
→ 打印带占位符的 config.yaml 片段（不输出真实域名和密钥）
|
||
→ 附 NetBird 官方文档链接
|
||
|
||
Step 5 · Next Steps
|
||
→ 逐台列出部署命令及需要放行的防火墙端口
|
||
|
||
Step 6 · Firewall Configuration（可选，可跳过）
|
||
→ 自动检测防火墙类型（firewalld / ufw / nftables / iptables）
|
||
→ 汇总所有 relay 需要开放的端口，确认后自动添加规则并持久化
|
||
```
|
||
|
||
## 已有配置读取（重新运行）
|
||
|
||
脚本支持在已有部署上重新运行以修改配置。Step 3 中先询问输出目录，若该目录下存在 `relay.env`，脚本会自动解析并将以下字段作为默认值填入后续输入框，直接回车即保留原值，输入新值则覆盖：
|
||
|
||
- 域名或 IP、监听端口、日志级别
|
||
- STUN 开关及端口
|
||
- TLS 模式、LE 邮箱、证书路径
|
||
|
||
## 生成文件说明
|
||
|
||
### `relay.env`
|
||
|
||
```env
|
||
NB_LOG_LEVEL=info
|
||
NB_LISTEN_ADDRESS=:443
|
||
NB_EXPOSED_ADDRESS=rels://relay.example.com:443
|
||
NB_AUTH_SECRET=<shared-secret>
|
||
|
||
# TLS — Let's Encrypt
|
||
NB_LETSENCRYPT_DOMAINS=relay.example.com
|
||
NB_LETSENCRYPT_EMAIL=[email protected]
|
||
NB_LETSENCRYPT_DATA_DIR=/data/letsencrypt
|
||
|
||
# 内置 STUN
|
||
NB_ENABLE_STUN=true
|
||
NB_STUN_PORTS=3478
|
||
```
|
||
|
||
> `relay.env` 权限自动设为 `600` 以保护密钥。
|
||
|
||
### `docker-compose.yml`
|
||
|
||
```yaml
|
||
services:
|
||
relay:
|
||
image: netbirdio/relay:latest
|
||
container_name: netbird-relay
|
||
restart: unless-stopped
|
||
ports:
|
||
- '443:443'
|
||
- '80:80' # 仅 Let's Encrypt 模式
|
||
- '3478:3478/udp'
|
||
env_file:
|
||
- relay.env
|
||
volumes:
|
||
- relay_data:/data
|
||
logging:
|
||
driver: "json-file"
|
||
options:
|
||
max-size: "500m"
|
||
max-file: "2"
|
||
|
||
volumes:
|
||
relay_data:
|
||
```
|
||
|
||
## TLS 证书说明
|
||
|
||
**Let's Encrypt（推荐）**
|
||
|
||
证书在第一次请求时懒加载，部署后执行以下命令触发签发并验证：
|
||
|
||
```bash
|
||
curl -v https://relay.example.com/
|
||
```
|
||
|
||
期望结果：`404 page not found` + TLS 握手成功，证书 issuer 为 Let's Encrypt。
|
||
|
||
**已有证书**
|
||
|
||
向导询问宿主机证书目录（默认建议路径含当前输入的域名，如 `/opt/1panel/www/sites/<域名>/ssl`）以及容器内证书和私钥路径（默认 `/certs/fullchain.pem` / `/certs/privkey.pem`，均可自定义）。目录以只读方式挂载进容器。
|
||
|
||
**自签证书**
|
||
|
||
脚本调用本机 `openssl` 生成，可配置：
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| CN / O / OU / C / ST / L | 完整 Subject 字段，非必填项可留空 |
|
||
| SAN | 自动包含域名，可循环追加 `DNS:xxx` 或 `IP:x.x.x.x` |
|
||
| 有效期 | 默认 3650 天 |
|
||
| 密钥类型 | RSA 2048 / RSA 4096 / ECC P-256 / ECC P-384 / ECC P-521 |
|
||
|
||
证书输出到 `<输出目录>/certs/`，私钥权限自动设为 `600`。若系统未安装 `openssl`，脚本会打印等效命令供手动执行。
|
||
|
||
**粘贴证书**
|
||
|
||
选择该模式后，脚本会提示分别粘贴证书 PEM 和私钥 PEM，保存到 `<输出目录>/certs/fullchain.pem` 与 `<输出目录>/certs/privkey.pem`，并自动挂载到容器中。
|
||
|
||
## 主服务器 config.yaml 配置
|
||
|
||
Step 4 输出带占位符的配置片段，需在主服务器上手动填入真实域名和密钥：
|
||
|
||
```yaml
|
||
server:
|
||
# 移除嵌入式 relay 密钥：
|
||
# authSecret: ...
|
||
# 移除嵌入式 STUN 端口：
|
||
# stunPorts:
|
||
# - 3478
|
||
|
||
stuns:
|
||
- uri: "stun:<relay-1-domain>:3478"
|
||
proto: "udp"
|
||
|
||
relays:
|
||
addresses:
|
||
- "rels://<relay-1-domain>:443"
|
||
secret: "<your-shared-secret>"
|
||
credentialsTTL: "24h"
|
||
```
|
||
|
||
> `relays.secret` 必须与所有 relay 服务器的 `NB_AUTH_SECRET` 完全一致，不匹配会导致连接静默失败。
|
||
|
||
## 防火墙自动配置
|
||
|
||
Step 6 检测当前系统防火墙并自动开放所需端口：
|
||
|
||
| 防火墙 | 持久化方式 |
|
||
|--------|-----------|
|
||
| firewalld | `--permanent` + `--reload` |
|
||
| ufw | 自动持久 |
|
||
| nftables | 写入 `/etc/nftables.d/netbird-relay.nft` 或 `/etc/nftables.conf` |
|
||
| iptables | `netfilter-persistent save` 或写入 `/etc/iptables/rules.v4` |
|
||
|
||
脚本会跨所有 relay 汇总端口并去重后再应用，iptables 会先检查规则是否已存在避免重复添加。非 root 运行时会给出警告。
|
||
|
||
## 多台 Relay 部署
|
||
|
||
多台 Relay 使用**相同**的 `NB_AUTH_SECRET`，域名和输出目录各自独立。向导在 Step 2 输入数量后逐台引导配置。
|
||
|
||
## 许可
|
||
|
||
MIT |