docs: update deployment and troubleshooting for Xray + sing-box split

Document new install flow, ports, migration script, and v2rayN Reality settings across README and docs/. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-16 12:03:03 +08:00
parent c9895133cb
commit 4b3f6a1de2
5 changed files with 454 additions and 316 deletions
@@ -4,9 +4,9 @@

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

@@ -16,41 +16,139 @@

 ### 1. DNS 解析

+将域名 **A 记录** 指向 VPS 公网 IP（用于 Hy2 证书与面板访问）：
+
 ```
-66.hyf2.cc  →  47.76.87.111
+your.domain.com  →  YOUR_VPS_IP
 ```

 验证：

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

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

-放行：`22`、`80`、`443/TCP`、`8443/UDP`（**无需 8444**）
+| 端口 | 协议 | 用途 | 必须 |
+|------|------|------|------|
+| 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://66.hyf2.cc/jiedian-xxxx/
+管理面板: http://your.domain.com/jiedian-xxxx/
 面板路径: jiedian-xxxx （见 .env 中 PANEL_PATH）
 用户名:   admin
 密码:     xxxxx
 ```

-浏览器打开面板 → 登录 → **添加节点** → 复制 VLESS / Hysteria2 链接到客户端。
+浏览器打开面板 → 登录 → **添加节点**（或使用默认节点）→ 复制 **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)。

 ---

@@ -70,50 +168,44 @@ bash scripts/install.sh

 ---

-## 安装脚本做了什么
+## 从旧版升级（sing-box 跑 Reality → Xray）

-1. 安装 sing-box、nginx、Python 面板依赖
-2. 防火墙放行 22/80/443/8443（不暴露 8444）
-3. acme.sh 申请 `66.hyf2.cc` 证书
-4. 初始化 SQLite 节点库 + 默认管理员
-5. 生成 sing-box 配置并启动服务
-6. Nginx 80 端口子路径反向代理管理面板
-
---
-
-## 管理面板功能
-
-| 功能 | 说明 |
-|------|------|
-| 登录 | `.env` 中 `PANEL_USERNAME` / `PANEL_PASSWORD` |
-| 添加节点 | 自动生成 UUID + Hy2 密码，更新 sing-box |
-| 复制链接 | VLESS Reality + Hysteria2 分享链接 |
-| 删除节点 | 至少保留 1 个节点 |
-| 连接状态 | 在线/离线、当前连接数（Clash API） |
-| 流量统计 | 实时速率 + 累计上下行（Clash API 连接统计） |
-
---
-
-## 部署后验证
+若你之前用 sing-box 监听 443 且 v2rayN Reality 一直 `-1`，拉代码后执行：

 ```bash
-systemctl status sing-box jiedian-panel
-ss -tlnp | grep -E '80|443|5080'
-ss -ulnp | grep 8443
-PANEL_PATH=$(grep ^PANEL_PATH= /opt/jiedian/.env | cut -d= -f2)
-curl -I "http://66.hyf2.cc/${PANEL_PATH}/login"
+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` |
-| apt 锁被占用 | 等待自动更新结束，或 `bash scripts/install.sh` 会自动等待 |
-| sing-box 443 被占用 | `ss -tlnp \| grep 443`，停止占用进程后重装 |
-| 忘记面板密码/路径 | `grep PANEL_ /opt/jiedian/.env` 或重新 `generate-keys.sh` |
-| SSH 主机密钥变更 | 重装系统后本地执行 `ssh-keygen -R 47.76.87.111` |
+| 面板 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)。