Files

T

dekun 1f36a76ce0 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

8.6 KiB

Raw Blame History

部署指南

本文档说明如何在 Ubuntu VPS 上部署 jiedian（Hysteria2 + Web 管理面板）。

项目	说明
仓库	https://git.bz121.com/dekun/jiedian.git
部署目录	`/opt/jiedian`
系统要求	Ubuntu 22.04 / 24.04（root 或 sudo）
协议	Hysteria2（UDP 8443+）
管理面板	`https://域名/<PANEL_PATH>/`（安装完成后输出；HTTP 80 自动跳转）

一、部署前准备（必读）

部署前请逐项完成以下准备。端口未放行或 DNS 未解析会导致安装失败或客户端连不上。

准备清单

#	项目	要求
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：

your.domain.com  →  YOUR_VPS_IP

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

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

DNS 未生效时，证书申请会失败。一键部署脚本会检测并提示。

3. 云厂商安全组配置示例

阿里云 / 腾讯云 / AWS 等：进入 VPS 实例 → 安全组 → 入站规则，添加上表中的端口。

常见错误：

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

4. 部署时需要的信息

一键部署时会交互询问（或命令行传入）：

项目	必填	说明
域名	是	已解析到 VPS 的域名
证书邮箱	是	Let's Encrypt 申请用
面板用户名	否	默认 `admin`
面板密码	否	留空则自动生成

以下由脚本自动处理，无需手动填写：

项目	说明
`VPS_IP`	自动检测公网 IP
`PANEL_PATH`	自动生成随机路径（如 `jiedian-a1b2c3d4`）
`CLASH_API_SECRET`	自动生成，供面板读取连接统计

5. 手动配置（可选）

若不用一键部署、需自定义 .env，见手动安装。

二、一键安装（新机器）

SSH 登录 VPS 后执行（无需先 clone，脚本会自动 clone 到 /opt/jiedian）：

curl -fsSL https://git.bz121.com/dekun/jiedian/raw/main/scripts/bootstrap.sh | bash

按提示输入域名、证书邮箱、面板用户名和密码即可。

脚本会自动：

检测公网 IP，校验 DNS
clone 仓库到 /opt/jiedian
写入 .env，调用 install.sh
安装 sing-box、nginx、Python 面板
配置 UFW（22/80/443 TCP + 8443–8499 UDP）
申请 TLS 证书，启动服务
输出面板地址、用户名、密码

非交互模式（适合脚本化）：

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

手动安装（备选）

ssh root@YOUR_VPS_IP

apt update && apt install -y git
git clone https://git.bz121.com/dekun/jiedian.git /opt/jiedian
cd /opt/jiedian
cp .env.example .env
# 编辑 .env 填写 VPS_IP、DOMAIN、ACME_EMAIL
bash scripts/install.sh

变量	必填	说明
`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/
║  用户名:   admin
║  密码:     xxxxxxxxx
╠══════════════════════════════════════════════════════╣
║  凭证已保存: /root/jiedian-credentials.txt
╚══════════════════════════════════════════════════════╝

浏览器打开面板地址 → 登录 → 添加节点 → 复制 Hysteria2 链接到客户端。

客户端导入详见 client-import.md。

三、部署后验证

# 服务状态
systemctl is-active sing-box jiedian-panel nginx

# sing-box 配置语法
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"

客户端导入 Hy2 链接后测速，应显示正常延迟（非 -1）。

四、已有 VPS 更新代码

cd /opt/jiedian
git pull
python3 scripts/render-server.py
systemctl restart sing-box jiedian-panel

仅更新面板前端/代码、未改 sing-box 配置时：

cd /opt/jiedian && git pull && systemctl restart jiedian-panel

从旧版（含 VLESS/Xray）升级到仅 Hy2

cd /opt/jiedian
git pull
sudo bash scripts/remove-vless.sh

已有 VPS 仅升级 HTTPS 面板

cd /opt/jiedian && git pull
sudo bash scripts/enable-panel-https.sh
systemctl restart jiedian-panel

五、增删节点后的配置重载

面板添加/删除节点时会 后台自动 重载 sing-box。若需手动执行：

cd /opt/jiedian
python3 scripts/render-server.py
systemctl restart sing-box

六、卸载与重装

cd /opt/jiedian
bash scripts/uninstall.sh
bash scripts/bootstrap.sh   # 或 bash scripts/install.sh

七、架构说明

浏览器 ──► Nginx:443 HTTPS/<PANEL_PATH>/ ──► Flask 管理面板
         └─► Nginx:80（ACME + 跳转 HTTPS）
                              │
                              ▼
                    render-server.py
                              │
                              ▼
                    sing-box :8443+
                    Hysteria2（每节点独立端口 + 密码）

客户端 ── UDP 8443+ ──► sing-box

更多技术细节见 STACK.md。

八、常见问题

见 troubleshooting.md。

日常使用见 GUIDE.md。

8.6 KiB Raw Blame History Unescape Escape