# 部署指南

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

| 项目 | 说明 |
|------|------|
| 仓库 | https://git.bz121.com/dekun/jiedian.git |
| 部署目录 | `/opt/jiedian` |
| 系统要求 | Ubuntu 22.04 / 24.04（root 或 sudo） |
| 协议 | Hysteria2（UDP 8443+） |
| 管理面板 | `http://域名/<PANEL_PATH>/`（**HTTP 80，不要用 HTTPS 访问面板**） |

---

## 一、部署前准备

### 1. 购买 VPS 并获取 root 登录

建议使用境外 VPS，带宽 ≥ 30Mbps。记录：

- 公网 IP（写入 `.env` 的 `VPS_IP`）
- SSH 登录方式（密码或密钥）

### 2. 域名与 DNS

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

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

验证：

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

### 3. 云厂商安全组

在阿里云 / 腾讯云等控制台放行：

| 端口 | 协议 | 用途 | 必须 |
|------|------|------|------|
| 22 | TCP | SSH | 是 |
| 80 | TCP | ACME 证书验证 + 管理面板 | 是 |
| 8443–8499 | UDP | Hysteria2（多节点递增） | 是 |

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

### 4. 填写 `.env`

```bash
git clone https://git.bz121.com/dekun/jiedian.git /opt/jiedian
cd /opt/jiedian
cp .env.example .env
nano .env
```

| 变量 | 必填 | 说明 |
|------|------|------|
| `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 访问面板（可选） |

`CLASH_API_SECRET` 由 `install.sh` 自动生成，供面板读取连接统计，无需手动填写。

---

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

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

安装脚本会自动完成：

1. 安装 sing-box、nginx、Python 面板依赖
2. 配置 UFW 防火墙（22/80 TCP，8443–8499 UDP）
3. 通过 acme.sh 为 `DOMAIN` 申请 TLS 证书
4. 初始化 SQLite 节点库与默认管理员
5. 生成 sing-box 配置并启动服务

安装结束输出示例：

```
==========================================
  管理面板: http://66.hyf2.cc/jiedian-xxxx/
  面板路径: jiedian-xxxx
  用户名:   dekun
  密码:     xxxxx
==========================================
```

浏览器打开面板地址 → 登录 → **添加节点** → 复制 **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

# 面板可访问
PANEL_PATH=$(grep ^PANEL_PATH= /opt/jiedian/.env | cut -d= -f2)
curl -I "http://$(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
```

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

若你之前部署过带 VLESS Reality 的版本：

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

该脚本会：

- 停止并禁用 Xray
- 重载 sing-box 配置
- 重启面板
- 删除防火墙 443 规则（可选）

完成后客户端 **删除所有 VLESS 节点**，仅从面板复制 `hy2://` 链接。

---

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

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

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

---

## 六、卸载与重装

```bash
cd /opt/jiedian
bash scripts/uninstall.sh
# 保留 .env 与代码，清理 data/ 与 venv
bash scripts/install.sh
```

---

## 七、架构说明

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

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

更多技术细节见 [STACK.md](STACK.md)。

---

## 八、常见问题

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

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