From 1fa633b36d05324796213f535901836ab7184b3a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=87=8C?= <i@ioioi.cn>
Date: Wed, 18 Mar 2026 21:03:04 +0800
Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0=20README.md?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 109 ++++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 89 insertions(+), 20 deletions(-)

diff --git a/README.md b/README.md
index 6ccdfaa..78898c5 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,8 @@
 # NetBird External Relay Setup
 
-交互式脚本，为一台或多台 [NetBird](https://netbird.io) 外部 Relay 服务器生成 `relay.env` 和 `docker-compose.yml`，并在最后输出主服务器所需的配置片段。
+交互式脚本，为一台或多台 [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)
 
 ## 前置要求
 
@@ -9,10 +11,10 @@
 - Linux，≥ 1 CPU / 1 GB RAM
 - 公网 IP，且有域名解析指向该 IP
 - 已安装 Docker（含 `docker compose`）
-- 防火墙放行（具体端口由脚本根据配置动态列出）：
-  - `80/tcp` — Let's Encrypt HTTP challenge（仅使用自动证书时需要）
-  - `443/tcp` — Relay（可自定义端口）
-  - `3478/udp` — STUN（可自定义端口，可多个）
+- 以下端口按实际配置放行（脚本会在最后动态列出）：
+  - `80/tcp` — Let's Encrypt HTTP challenge（仅自动证书模式需要）
+  - `443/tcp` — Relay HTTPS（可自定义端口）
+  - `3478/udp` — STUN（可自定义端口，支持多个）
 
 ## 快速开始
 
@@ -37,14 +39,14 @@ bash <(curl -fsSL https://mybugs.work/i/netbird-relay/raw/branch/main/setup-rela
 
 | 参数 | 说明 |
 |------|------|
-| `--dry-run` | 预览模式，只打印生成内容，不写入文件 |
-| `--output=<dir>` | 指定输出目录（默认为当前目录） |
+| `--dry-run` | 预览模式，只打印生成内容，不写入文件，跳过防火墙步骤 |
+| `--output=<dir>` | 指定默认输出根目录 |
 
 ```bash
 # 预览，不写文件
 ./setup-relay.sh --dry-run
 
-# 指定输出到 /opt/netbird-configs
+# 指定输出根目录
 ./setup-relay.sh --output=/opt/netbird-configs
 
 # 组合使用
@@ -55,26 +57,42 @@ bash <(curl -fsSL https://mybugs.work/i/netbird-relay/raw/branch/main/setup-rela
 
 ```
 Step 1 · Authentication Secret
-  → 自动生成或粘贴已有的共享密钥
+  → 若 /opt/netbird-relay/relay.env 已存在，自动读取密钥作为默认值，回车确认
+  → 或自动生成新密钥，或手动粘贴已有密钥
 
 Step 2 · How many relay servers?
-  → 输入要配置的 Relay 数量
+  → 输入要配置的 Relay 数量（支持批量）
 
 Step 3.N · Relay Server #N（每台重复）
+  → 先询问输出目录，若目录下已有 relay.env 则自动读取作为所有字段的默认值
   → 域名、监听端口、日志级别
-  → 是否启用内置 STUN，STUN 端口
+  → 是否启用内置 STUN，STUN 端口（支持多个，逗号分隔）
   → TLS 方式：
-      1) Let's Encrypt（自动签发，需开放 80 端口）
-      2) 已有证书（输入宿主机证书目录及容器内路径）
-  → 文件输出目录（默认 /opt/netbird-relay）
+      1) Let's Encrypt — 自动签发，需开放 80/tcp
+      2) 已有证书 — 输入宿主机目录及容器内路径（均可自定义）
+      3) 自签证书 — 脚本调用 openssl 生成，支持完整 Subject 字段、
+                    额外 SAN（DNS/IP）、有效期、RSA/ECC 及密钥长度选择
 
-Step 4 · Main Server Configuration Snippet
-  → 打印主服务器所需的 Relay URL、STUN URL 及共享密钥
+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`，脚本会自动解析并将以下字段作为默认值填入后续输入框，直接回车即保留原值，输入新值则覆盖：
+
+- 域名、监听端口、日志级别
+- STUN 开关及端口
+- TLS 模式、LE 邮箱、证书路径
+
 ## 生成文件说明
 
 ### `relay.env`
@@ -107,7 +125,7 @@ services:
     restart: unless-stopped
     ports:
       - '443:443'
-      - '80:80'        # 仅 Let's Encrypt 模式
+      - '80:80'          # 仅 Let's Encrypt 模式
       - '3478:3478/udp'
     env_file:
       - relay.env
@@ -127,7 +145,7 @@ volumes:
 
 **Let's Encrypt（推荐）**
 
-证书在第一次请求时懒加载，运行后执行以下命令触发签发并验证：
+证书在第一次请求时懒加载，部署后执行以下命令触发签发并验证：
 
 ```bash
 curl -v https://relay.example.com/
@@ -137,11 +155,62 @@ curl -v https://relay.example.com/
 
 **已有证书**
 
-向导会询问宿主机证书目录（默认建议 `/opt/1panel/www/sites/<域名>/ssl`），以及证书和私钥在容器内的路径（默认 `/certs/fullchain.pem` / `/certs/privkey.pem`）。目录会以只读方式挂载进容器。
+向导询问宿主机证书目录（默认建议路径含当前输入的域名，如 `/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`，脚本会打印等效命令供手动执行。
+
+## 主服务器 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 输入数量后会逐台引导配置。
+多台 Relay 使用**相同**的 `NB_AUTH_SECRET`，域名和输出目录各自独立。向导在 Step 2 输入数量后逐台引导配置。
 
 ## 许可