From 874f5846a4c4d190e726481018741e4dbd51ba06 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=87=8C?= <i@ioioi.cn>
Date: Wed, 18 Mar 2026 20:37:40 +0800
Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=20README.md?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 148 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 148 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..6ccdfaa
--- /dev/null
+++ b/README.md
@@ -0,0 +1,148 @@
+# NetBird External Relay Setup
+
+交互式脚本，为一台或多台 [NetBird](https://netbird.io) 外部 Relay 服务器生成 `relay.env` 和 `docker-compose.yml`，并在最后输出主服务器所需的配置片段。
+
+## 前置要求
+
+每台 Relay 服务器需满足：
+
+- Linux，≥ 1 CPU / 1 GB RAM
+- 公网 IP，且有域名解析指向该 IP
+- 已安装 Docker（含 `docker compose`）
+- 防火墙放行（具体端口由脚本根据配置动态列出）：
+  - `80/tcp` — Let's Encrypt HTTP challenge（仅使用自动证书时需要）
+  - `443/tcp` — Relay（可自定义端口）
+  - `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
+
+# 指定输出到 /opt/netbird-configs
+./setup-relay.sh --output=/opt/netbird-configs
+
+# 组合使用
+./setup-relay.sh --dry-run --output=/tmp/preview
+```
+
+## 向导流程
+
+```
+Step 1 · Authentication Secret
+  → 自动生成或粘贴已有的共享密钥
+
+Step 2 · How many relay servers?
+  → 输入要配置的 Relay 数量
+
+Step 3.N · Relay Server #N（每台重复）
+  → 域名、监听端口、日志级别
+  → 是否启用内置 STUN，STUN 端口
+  → TLS 方式：
+      1) Let's Encrypt（自动签发，需开放 80 端口）
+      2) 已有证书（输入宿主机证书目录及容器内路径）
+  → 文件输出目录（默认 /opt/netbird-relay）
+
+Step 4 · Main Server Configuration Snippet
+  → 打印主服务器所需的 Relay URL、STUN URL 及共享密钥
+
+Step 5 · Next Steps
+  → 逐台列出部署命令及需要放行的防火墙端口
+```
+
+## 生成文件说明
+
+### `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=admin@example.com
+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`）。目录会以只读方式挂载进容器。
+
+## 多台 Relay 部署
+
+多台 Relay 使用**相同**的 `NB_AUTH_SECRET`，域名和输出目录各自独立。向导在 Step 2 输入数量后会逐台引导配置。
+
+## 许可
+
+MIT
\ No newline at end of file