# Ubuntu 部署指南

仓库：[https://git.bz121.com/dekun/jiedian.git](https://git.bz121.com/dekun/jiedian.git)

| 项目 | 值 |
|------|-----|
| VPS IP | 你的 VPS 公网 IP |
| 域名 | 已解析到 VPS 的域名 |
| 管理面板 | `http://域名/<PANEL_PATH>/`（**必须 http，不要用 https**） |
| 部署目录 | `/opt/jiedian` |
| 系统 | Ubuntu 22.04 / 24.04 |

---

## 部署前准备

### 1. DNS 解析

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

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

验证：

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

### 2. 阿里云 / 云厂商安全组

| 端口 | 协议 | 用途 | 必须 |
|------|------|------|------|
| 22 | TCP | SSH | 是 |
| 80 | TCP | ACME + 管理面板 | 是 |
| 443 | TCP | VLESS Reality（Xray） | 是 |
| 8443–8499 | UDP | Hysteria2（sing-box，多节点递增） | 是 |

> **注意**：多节点时 Hy2 端口为 8443、8444、8445…，安全组需放行 **8443–8499/UDP**，不能只开 8443。

### 3. 填写 `.env`（首次部署）

```bash
cd /opt/jiedian
cp .env.example .env
nano .env
```

至少填写：

| 变量 | 说明 |
|------|------|
| `VPS_IP` | VPS 公网 IP |
| `DOMAIN` | 域名（Hy2 与证书用） |
| `ACME_EMAIL` | Let's Encrypt 邮箱 |
| `REALITY_SERVER_NAME` | Reality 伪装 SNI，默认 `www.microsoft.com` |

`REALITY_*` 密钥、`PANEL_PASSWORD`、`PANEL_PATH` 可在安装时由 `generate-keys.sh` / `install.sh` 自动生成。

---

## 一键部署（新机器）

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

安装结束会输出类似：

```
管理面板: http://your.domain.com/jiedian-xxxx/
面板路径: jiedian-xxxx （见 .env 中 PANEL_PATH）
用户名:   admin
密码:     xxxxx
```

浏览器打开面板 → 登录 → **添加节点**（或使用默认节点）→ 复制 **VLESS** / **Hysteria2** 链接到客户端。

---

## 安装脚本做了什么

1. 安装 **sing-box**（Hysteria2）、**Xray**（VLESS Reality）、nginx、Python 面板依赖
2. UFW 放行 22/80/443 TCP 与 8443–8499 UDP
3. acme.sh 为 `DOMAIN` 申请 TLS 证书（供 Hy2 使用）
4. 初始化 SQLite 节点库 + 默认管理员
5. `render-server.py` → `/etc/sing-box/config.json`（仅 Hy2 inbound）
6. `render-xray.py` → `/usr/local/etc/xray/config.json`（VLESS Reality 443）
7. 启动 **xray**、**sing-box**、**jiedian-panel**
8. Nginx 80 端口子路径反向代理管理面板

---

## 服务与端口对照

| 服务 | 端口 | 协议 | 说明 |
|------|------|------|------|
| **xray** | 443 | TCP | VLESS + Reality，所有节点 UUID 共用 |
| **sing-box** | 8443+ | UDP | Hysteria2，每节点独立端口（按 ID 排序） |
| **jiedian-panel** | 5080 | TCP | 仅本机，经 Nginx 80 对外 |
| **nginx** | 80 | TCP | ACME + 面板 |

查看监听：

```bash
ss -tlnp | grep -E ':443|:80|:5080'
ss -ulnp | grep 8443
systemctl status xray sing-box jiedian-panel
```

---

## 管理面板功能

| 功能 | 说明 |
|------|------|
| 登录 | `.env` 中 `PANEL_USERNAME` / `PANEL_PASSWORD` |
| 添加节点 | 自动生成 UUID + Hy2 密码，后台更新 Xray + sing-box 配置 |
| 复制链接 | VLESS Reality + Hysteria2（Hy2 端口随节点自动变化） |
| 删除节点 | 至少保留 1 个节点 |
| 连接状态 | 在线/离线、连接数 |
| 流量统计 | 实时速率 + 累计上下行 |

---

## 部署后验证

```bash
# 服务
systemctl is-active xray sing-box jiedian-panel

# 配置语法
xray run -test -c /usr/local/etc/xray/config.json
sing-box check -c /etc/sing-box/config.json

# Reality 密钥是否一致
bash /opt/jiedian/scripts/verify-reality.sh

# 面板可访问
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"
```

客户端：导入面板复制的 **VLESS** 链接，v2rayN 测速应显示延迟（非 `-1`）。详见 [client-import.md](client-import.md)。

---

## 卸载后重装（推荐流程）

若之前部署混乱，先卸载再装：

```bash
cd /opt/jiedian
git pull
bash scripts/uninstall.sh
bash scripts/generate-keys.sh    # 重新生成 Reality 密钥与面板密码
bash scripts/install.sh
```

`uninstall.sh` 会停止服务并清理配置，**保留** `/opt/jiedian` 代码与 `.env` 基础字段。

---

## 从旧版升级（sing-box 跑 Reality → Xray）

若你之前用 sing-box 监听 443 且 v2rayN Reality 一直 `-1`，拉代码后执行：

```bash
cd /opt/jiedian && git pull
bash scripts/migrate-xray-reality.sh
```

客户端 **无需改参数**，直接重测 VLESS 节点即可。

---

## 增删节点后的配置

面板会自动后台执行 `render-xray.py`、`render-server.py` 并重启服务。若需手动：

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

修改 Reality 密钥后（`generate-keys.sh`）也必须执行上述命令。

---

## 故障排查速查

| 问题 | 处理 |
|------|------|
| 面板 404 | URL 须含完整 `PANEL_PATH`，见 `grep PANEL_PATH .env` |
| 面板 Invalid URL / [No Host] | 用 **http://** 访问，不要用 https |
| VLESS 测速 `-1` | `bash scripts/verify-reality.sh`；确认未用 https 访问面板 |
| Hy2 不通 | 安全组放行 **8443–8499/UDP**；重新复制面板 Hy2 链接 |
| apt 锁被占用 | 等待自动更新结束，`install.sh` 会自动等待 |
| 443 被占用 | `ss -tlnp \| grep 443`，应为 **xray** |
| 忘记面板密码/路径 | `grep PANEL_ /opt/jiedian/.env` 或 `generate-keys.sh` |

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