feat: add bootstrap one-click deploy and update deployment docs

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-11 13:49:20 +08:00
parent 46728e12f7
commit 1f36a76ce0
11 changed files with 525 additions and 223 deletions
@@ -12,68 +12,143 @@

 ---

-## 一、部署前准备
+## 一、部署前准备（必读）

-### 1. 购买 VPS 并获取 root 登录
+部署前请逐项完成以下准备。**端口未放行或 DNS 未解析会导致安装失败或客户端连不上。**

-建议使用境外 VPS，带宽 ≥ 30Mbps。记录：
+### 准备清单

- 公网 IP（写入 `.env` 的 `VPS_IP`）
+| # | 项目 | 要求 |
+|---|------|------|
+| 1 | VPS | Ubuntu 22.04 / 24.04，root 或 sudo，建议带宽 ≥ 30Mbps |
+| 2 | 域名 | 已注册，可添加 DNS 记录 |
+| 3 | DNS | 域名 **A 记录** 指向 VPS 公网 IP |
+| 4 | 安全组 | 云厂商控制台放行下方端口（见下表） |
+| 5 | 系统防火墙 | 安装脚本会自动配置 UFW，无需手动操作 |
+
+### 需要开放的端口
+
+**云厂商安全组**与 **VPS 防火墙**均需放行（安装脚本会配置 UFW，但安全组必须在控制台手动开）。
+
+| 端口 | 协议 | 方向 | 用途 | 必须 |
+|------|------|------|------|------|
+| **22** | TCP | 入站 | SSH 远程登录 | 是 |
+| **80** | TCP | 入站 | ACME 证书验证（Let's Encrypt） | 是 |
+| **443** | TCP | 入站 | **HTTPS 管理面板** | 是 |
+| **8443–8499** | **UDP** | 入站 | **Hysteria2 代理**（多节点递增） | 是 |
+
+> **重要**
+>
+> - Hy2 使用 **UDP**，不是 TCP。安全组必须放行 **8443–8499/UDP 整段**，不能只开 8443。
+> - 每增加一个节点，Hy2 端口 +1（8443、8444、8445…）。预留 8443–8499 可支持约 57 个节点。
+> - 面板走 **443/TCP**，客户端代理走 **8443+/UDP**，两者都需要。
+
+### 各组件端口对照
+
+| 组件 | 端口 | 协议 | 说明 |
+|------|------|------|------|
+| SSH | 22 | TCP | 部署与运维 |
+| Nginx | 80 | TCP | 证书申请 + HTTP 跳转 HTTPS |
+| Nginx | 443 | TCP | 管理面板 HTTPS |
+| sing-box | 8443 | UDP | 第 1 个节点 Hy2 |
+| sing-box | 8444 | UDP | 第 2 个节点 Hy2 |
+| sing-box | 8445… | UDP | 后续节点依次 +1 |
+
+### 1. 购买 VPS
+
+记录：
+
+- 公网 IP（一键部署会自动检测并写入 `.env`）
 - SSH 登录方式（密码或密钥）

 ### 2. 域名与 DNS

-将域名 **A 记录** 解析到 VPS 公网 IP（用于 Hy2 TLS 证书与面板访问）：
+将域名 **A 记录** 解析到 VPS 公网 IP：

 ```
 your.domain.com  →  YOUR_VPS_IP
 ```

-验证：
+验证（在本地或 VPS 上执行）：

 ```bash
 dig +short A your.domain.com
-# 应返回 VPS IP
+# 应返回 VPS 公网 IP
 ```

-### 3. 云厂商安全组
+DNS 未生效时，证书申请会失败。一键部署脚本会检测并提示。

-在阿里云 / 腾讯云等控制台放行：
+### 3. 云厂商安全组配置示例

-| 端口 | 协议 | 用途 | 必须 |
-|------|------|------|------|
-| 22 | TCP | SSH | 是 |
-| 80 | TCP | ACME 证书验证 | 是 |
-| 443 | TCP | **HTTPS 管理面板** | 是 |
-| 8443–8499 | UDP | Hysteria2（多节点递增） | 是 |
+**阿里云 / 腾讯云 / AWS 等**：进入 VPS 实例 → 安全组 → 入站规则，添加上表中的端口。

-> **重要**：每增加一个节点，Hy2 端口 +1（8443、8444、8445…）。安全组必须放行 **8443–8499/UDP** 整段，不能只开 8443。
+常见错误：

-### 4. 填写 `.env`
+| 错误 | 后果 |
+|------|------|
+| 只开 8443/UDP，未开 8444–8499 | 第 2 个节点起客户端连不上 |
+| Hy2 端口写成 TCP | 客户端延迟 `-1` 或无法连接 |
+| 未开 80/TCP | Let's Encrypt 证书申请失败 |
+| 未开 443/TCP | 管理面板无法 HTTPS 访问 |

-```bash
-git clone https://git.bz121.com/dekun/jiedian.git /opt/jiedian
-cd /opt/jiedian
-cp .env.example .env
-nano .env
-```
+### 4. 部署时需要的信息

-| 变量 | 必填 | 说明 |
+一键部署时会交互询问（或命令行传入）：
+
+| 项目 | 必填 | 说明 |
 |------|------|------|
-| `VPS_IP` | 是 | VPS 公网 IP |
-| `DOMAIN` | 是 | 已解析到 VPS 的域名 |
-| `ACME_EMAIL` | 是 | Let's Encrypt 申请证书邮箱 |
-| `PANEL_USERNAME` | 否 | 面板登录用户名，默认 `admin` |
-| `PANEL_PASSWORD` | 否 | 面板密码；留空则安装时自动生成 |
-| `PANEL_PATH` | 否 | 面板 URL 路径；留空则自动生成如 `jiedian-a1b2c3d4` |
-| `PANEL_ALLOW_IP` | 否 | 仅允许指定 IP 访问面板（可选） |
+| 域名 | 是 | 已解析到 VPS 的域名 |
+| 证书邮箱 | 是 | Let's Encrypt 申请用 |
+| 面板用户名 | 否 | 默认 `admin` |
+| 面板密码 | 否 | 留空则自动生成 |

-`CLASH_API_SECRET` 由 `install.sh` 自动生成，供面板读取连接统计，无需手动填写。
+以下由脚本自动处理，**无需手动填写**：
+
+| 项目 | 说明 |
+|------|------|
+| `VPS_IP` | 自动检测公网 IP |
+| `PANEL_PATH` | 自动生成随机路径（如 `jiedian-a1b2c3d4`） |
+| `CLASH_API_SECRET` | 自动生成，供面板读取连接统计 |
+
+### 5. 手动配置（可选）
+
+若不用一键部署、需自定义 `.env`，见 [手动安装](#手动安装备选)。

 ---

 ## 二、一键安装（新机器）

+SSH 登录 VPS 后执行（**无需先 clone**，脚本会自动 clone 到 `/opt/jiedian`）：
+
+```bash
+curl -fsSL https://git.bz121.com/dekun/jiedian/raw/main/scripts/bootstrap.sh | bash
+```
+
+按提示输入域名、证书邮箱、面板用户名和密码即可。
+
+脚本会自动：
+
+1. 检测公网 IP，校验 DNS
+2. clone 仓库到 `/opt/jiedian`
+3. 写入 `.env`，调用 `install.sh`
+4. 安装 sing-box、nginx、Python 面板
+5. 配置 UFW（22/80/443 TCP + 8443–8499 UDP）
+6. 申请 TLS 证书，启动服务
+7. 输出面板地址、用户名、密码
+
+**非交互模式**（适合脚本化）：
+
+```bash
+curl -fsSL https://git.bz121.com/dekun/jiedian/raw/main/scripts/bootstrap.sh | bash -s -- \
+  --domain your.domain.com \
+  --email you@example.com \
+  --username admin \
+  --password 'your-password' \
+  --yes
+```
+
+### 手动安装（备选）
+
 ```bash
 ssh root@YOUR_VPS_IP

@@ -85,24 +160,28 @@ cp .env.example .env
 bash scripts/install.sh
 ```

-安装脚本会自动完成：
-
-1. 安装 sing-box、nginx、Python 面板依赖
-2. 配置 UFW 防火墙（22/80/443 TCP，8443–8499 UDP）
-3. 通过 acme.sh 为 `DOMAIN` 申请 TLS 证书
-4. 初始化 SQLite 节点库与默认管理员
-5. 生成 sing-box 配置、启用 **HTTPS 面板**并启动服务
+| 变量 | 必填 | 说明 |
+|------|------|------|
+| `VPS_IP` | 是 | VPS 公网 IP |
+| `DOMAIN` | 是 | 已解析到 VPS 的域名 |
+| `ACME_EMAIL` | 是 | Let's Encrypt 申请证书邮箱 |
+| `PANEL_USERNAME` | 否 | 面板登录用户名，默认 `admin` |
+| `PANEL_PASSWORD` | 否 | 面板密码；留空则安装时自动生成 |
+| `PANEL_PATH` | 否 | 面板 URL 路径；留空则自动生成 |
+| `PANEL_ALLOW_IP` | 否 | 仅允许指定 IP 访问面板（可选） |

 安装结束输出示例：

 ```
-==========================================
-  管理面板: https://66.hyf2.cc/jiedian-xxxx/
-  （HTTP 会自动跳转到 HTTPS）
-  面板路径: jiedian-xxxx
-  用户名:   dekun
-  密码:     xxxxx
-==========================================
+╔══════════════════════════════════════════════════════╗
+║                  部署完成                             ║
+╠══════════════════════════════════════════════════════╣
+║  面板地址: https://66.hyf2.cc/jiedian-xxxx/
+║  用户名:   admin
+║  密码:     xxxxxxxxx
+╠══════════════════════════════════════════════════════╣
+║  凭证已保存: /root/jiedian-credentials.txt
+╚══════════════════════════════════════════════════════╝
 ```

 浏览器打开面板地址 → 登录 → **添加节点** → 复制 **Hysteria2** 链接到客户端。
@@ -123,6 +202,9 @@ sing-box check -c /etc/sing-box/config.json
 # Hy2 端口监听（默认 8443，多节点还有 8444…）
 ss -ulnp | grep 8443

+# UFW 规则（确认 UDP 8443-8499 已放行）
+ufw status
+
 # 面板 HTTPS 可访问（应返回 200/302）
 PANEL_PATH=$(grep ^PANEL_PATH= /opt/jiedian/.env | cut -d= -f2)
 curl -Ik "https://$(grep ^DOMAIN= /opt/jiedian/.env | cut -d= -f2)/${PANEL_PATH}/login"
@@ -141,9 +223,13 @@ python3 scripts/render-server.py
 systemctl restart sing-box jiedian-panel
 ```

-### 从旧版（含 VLESS/Xray）升级到仅 Hy2
+仅更新面板前端/代码、未改 sing-box 配置时：

-若你之前部署过带 VLESS Reality 的版本：
+```bash
+cd /opt/jiedian && git pull && systemctl restart jiedian-panel
+```
+
+### 从旧版（含 VLESS/Xray）升级到仅 Hy2

 ```bash
 cd /opt/jiedian
@@ -151,15 +237,6 @@ git pull
 sudo bash scripts/remove-vless.sh
 ```

-该脚本会：
-
- 停止并禁用 Xray
- 重载 sing-box 配置
- **启用 HTTPS 管理面板（443）**
- 重启面板
-
-完成后客户端 **删除所有 VLESS 节点**，从面板复制 `hy2://` 链接，并用 **HTTPS** 登录面板。
-
 ### 已有 VPS 仅升级 HTTPS 面板

 ```bash
@@ -187,8 +264,7 @@ systemctl restart sing-box
 ```bash
 cd /opt/jiedian
 bash scripts/uninstall.sh
-# 保留 .env 与代码，清理 data/ 与 venv
-bash scripts/install.sh
+bash scripts/bootstrap.sh   # 或 bash scripts/install.sh
 ```

 ---
@@ -2,7 +2,7 @@

 | 文档 | 适用对象 | 内容 |
 |------|----------|------|
-| **[DEPLOY.md](DEPLOY.md)** | 运维 / 首次部署 | VPS 安装、安全组、`.env`、升级、验证 |
+| **[DEPLOY.md](DEPLOY.md)** | 运维 / 首次部署 | **前期准备、端口放行、一键安装**、升级、验证 |
 | **[GUIDE.md](GUIDE.md)** | 日常使用 | 面板操作、节点管理、Hy2 说明、安全建议 |
 | **[client-import.md](client-import.md)** | 客户端用户 | Windows / Android / iOS 导入 Hy2 链接 |
 | **[troubleshooting.md](troubleshooting.md)** | 排错 | 连不上、面板打不开、迁移 |
@@ -12,6 +12,12 @@

 - 仓库：https://git.bz121.com/dekun/jiedian.git
 - 部署目录：`/opt/jiedian`
- 一键安装：`bash scripts/install.sh`（自动 HTTPS 面板）
+- **一键部署**：`curl -fsSL https://git.bz121.com/dekun/jiedian/raw/main/scripts/bootstrap.sh | bash`
 - 旧版去 VLESS：`bash scripts/remove-vless.sh`
- 单独启用 HTTPS：`bash scripts/enable-panel-https.sh`
+
+## 部署前必做
+
+1. 域名 A 记录 → VPS 公网 IP
+2. 安全组放行：**22/TCP、80/TCP、443/TCP、8443–8499/UDP**
+
+详见 **[DEPLOY.md](DEPLOY.md)**。
@@ -5,16 +5,21 @@
 | 组件 | 用途 |
 |------|------|
 | **sing-box** | Hysteria2 服务端、Clash API 统计、多 inbound 按节点分端口 |
-| **Nginx** | ACME 验证、管理面板反代（HTTP 80） |
+| **Nginx** | ACME 验证、HTTPS 管理面板反代 |
 | **Flask 面板** | 添加/删除节点、复制 Hy2 链接、在线与流量统计 |

 ## 端口

-| 端口 | 协议 | 进程 | 说明 |
-|------|------|------|------|
-| 80 | TCP | Nginx | ACME 验证 + 跳转 HTTPS |
-| 443 | TCP | Nginx | **HTTPS 管理面板** |
-| 8443–8499 | UDP | sing-box | Hy2，每节点 +1 |
+部署前需在云厂商安全组放行以下端口（安装脚本会同步配置 UFW）：
+
+| 端口 | 协议 | 进程 | 方向 | 说明 |
+|------|------|------|------|------|
+| 22 | TCP | sshd | 入站 | SSH 运维 |
+| 80 | TCP | Nginx | 入站 | ACME 证书验证 + 跳转 HTTPS |
+| 443 | TCP | Nginx | 入站 | **HTTPS 管理面板** |
+| 8443–8499 | **UDP** | sing-box | 入站 | **Hy2 代理**，每节点端口 +1 |
+
+> Hy2 使用 UDP。安全组必须放行 **8443–8499/UDP 整段**，不能只开 8443。

 ## 配置生成

@@ -23,3 +28,10 @@
 | `render-server.py` | `/etc/sing-box/config.json` |

 增删节点后运行 `render-server.py` 并 `systemctl restart sing-box`。
+
+## 部署入口
+
+| 脚本 | 用途 |
+|------|------|
+| `bootstrap.sh` | 一键部署（自动 clone、交互配置、调用 install.sh） |
+| `install.sh` | 核心安装（sing-box / nginx / 证书 / 面板） |