jiedian/docs/DEPLOY.md

# 部署指南

本文档说明如何在 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 上执行）：

```bash
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`）：

```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

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](client-import.md)。

---

## 三、部署后验证

```bash
# 服务状态
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 更新代码

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

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

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

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

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

### 已有 VPS 仅升级 HTTPS 面板

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

---

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

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

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

---

## 六、卸载与重装

```bash
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](STACK.md)。

---

## 八、常见问题

见 [troubleshooting.md](troubleshooting.md)。

日常使用见 [GUIDE.md](GUIDE.md)。