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)。
@@ -5,18 +5,33 @@
 | 项目 | 选择 | 理由 |
 |------|------|------|
 | 协议栈 | **VLESS + Reality + Hysteria2 双栈** | Reality 抗主动探测；Hysteria2 作 UDP 备用与流媒体 |
-| 服务端 | **sing-box** | 单进程同时跑 Reality 与 Hysteria2，配置统一 |
-| 系统 | **Ubuntu 22.04/24.04 或 Debian 12** | 脚本基于 apt，其他发行版需手动适配 |
-| 面板 | **无** | 个人 1–5 人，手改 `.env` + 模板即可 |
+| Reality 服务端 | **Xray** | 与 v2rayN / v2rayNG（Xray 核心）兼容性最好；sing-box Reality 易出现 `processed invalid connection` |
+| Hy2 服务端 | **sing-box** | 原生 Hysteria2、Clash API 统计、多 inbound 按节点分端口 |
+| 系统 | **Ubuntu 22.04/24.04** | 脚本基于 apt，其他发行版需手动适配 |
+| 面板 | **Flask Web 面板** | 添加/删除节点、复制链接、在线与流量统计 |

 ## 端口规划

- `443/TCP` — VLESS + Reality（主力）
- `8443/UDP` — Hysteria2（备用）
- `80/TCP` — ACME 验证 + 管理面板 Nginx 反向代理
- `127.0.0.1:8080` — Nginx 伪装静态页（Reality fallback 场景）
- `127.0.0.1:5080` — Flask 面板后端（不对外暴露）
+| 端口 | 协议 | 服务 | 用途 |
+|------|------|------|------|
+| 443 | TCP | **Xray** | VLESS + Reality（主力） |
+| 8443–8499 | UDP | **sing-box** | Hysteria2（每节点递增：8443、8444…） |
+| 80 | TCP | nginx | ACME 验证 + 管理面板反向代理 |
+| 127.0.0.1:5080 | TCP | Flask | 面板后端（不对外暴露） |
+| 127.0.0.1:9090 | TCP | sing-box | Clash API（面板统计 Hy2） |
+
+## 配置生成
+
+| 脚本 | 输出 | 内容 |
+|------|------|------|
+| `render-xray.py` | `/usr/local/etc/xray/config.json` | 所有启用节点的 VLESS UUID + Reality |
+| `render-server.py` | `/etc/sing-box/config.json` | 每节点独立 Hy2 inbound + Clash API |
+
+增删节点或轮换 Reality 密钥后，两个脚本都需重新运行并 `systemctl restart xray sing-box`。

 ## 单协议简化

-若只想维护一种协议，删除 `server/sing-box.json.template` 中的 `hysteria2-in` inbound，并跳过证书申请步骤即可，仅保留 Reality。
+- **仅 Reality**：删除 `render-server.py` 中 Hy2 inbound 逻辑，跳过 acme 证书步骤（需改代码）。
+- **仅 Hy2**：不安装 Xray，删除 443 inbound（不推荐，失去 TCP 主力）。
+
+当前默认 **双栈**，与 README / DEPLOY 一致。
@@ -1,68 +1,77 @@
 # 客户端导入与测试指南

-部署完成后，在 VPS 上查看 `client/generated/share-links.txt`，或本地运行 `bash scripts/render-client.sh` 生成链接。
+部署完成后，在 **管理面板** 复制各节点的 VLESS / Hy2 链接；或本地运行 `bash scripts/render-client.sh` 生成 `client/generated/share-links.txt`。

 ---

 ## 一、连通性测试（推荐顺序）

-### 1. Reality（TCP 443）
+### 1. Reality（TCP 443，Xray）

 在**国内网络**下测试（不要在 VPS 本机 curl 自己）：

-```bash
+```powershell
 # Windows PowerShell — 仅测端口是否可达
 Test-NetConnection -ComputerName YOUR_VPS_IP -Port 443
 ```

-客户端连上后访问 https://www.google.com 或 https://ip.sb 确认出口 IP 为 VPS。
+v2rayN 中对 VLESS 节点 **右键 → 测试真链接延迟**，应显示毫秒数（不是 `-1`）。

-### 2. Hysteria2（UDP 8443）
+连上后访问 https://www.google.com 或 https://ip.sb 确认出口 IP 为 VPS。

-UDP 无法用普通 TCP 工具测。直接导入客户端测试；若 Reality 可用但 Hysteria2 不通，可能是运营商 QoS/封锁 UDP，可继续只用 Reality。
+### 2. Hysteria2（UDP 8443+）
+
+- **第一个节点**：UDP **8443**
+- **第二个节点**：UDP **8444**（依此类推）
+
+UDP 无法用普通 TCP 工具测。从面板 **重新复制** Hy2 链接（多节点升级后端口可能已变），导入客户端测试。
+
+若 Reality 可用但 Hysteria2 不通，可能是运营商 QoS/封锁 UDP，可继续只用 Reality。

 ### 3. 故障判断

 | 现象 | 可能原因 |
 |------|----------|
-| ping 通 IP，客户端 timeout | 协议层问题，检查 UUID/密钥/SNI |
+| ping 通 IP，VLESS 测速 `-1` | Reality 参数或密钥不同步 → `bash scripts/verify-reality.sh` |
+| Hy2 不通，VLESS 正常 | UDP 未放行或端口错误（需 8443–8499/UDP） |
 | ping 不通 | IP 可能被封，考虑换 IP |
-| 连接成功但无网 | 检查 VPS 防火墙、sing-box 日志 `journalctl -u sing-box -f` |
-| Hysteria2 不通，Reality 正常 | UDP 被干扰，备用节点可忽略 |
+| 连接成功但无网 | 检查防火墙、`journalctl -u xray -f` |

 ---

 ## 二、Windows

-### 方案 A：v2rayN（推荐，上手快）
+### 方案 A：v2rayN（推荐）

-1. 下载 [v2rayN](https://github.com/2dust/v2rayN/releases)（选 `v2rayN-With-Core.zip`）
-2. 解压运行，托盘图标 → **服务器** → **从剪贴板导入批量 URL**
-3. 复制 `share-links.txt` 中的 `vless://...` 行到剪贴板，导入
-4. 再导入 `hy2://...` 行作为备用
-5. 右键节点 → **设为活动服务器**，路由选 **绕过大陆**
-6. 系统代理 → **自动配置系统代理**
+1. 下载 [v2rayN](https://github.com/2dust/v2rayN/releases)（选 `v2rayN-With-Core.zip` 或自带 Xray 的版本）
+2. **设置 → 核心类型**：VLESS 使用 **Xray** 核心（不要用 sing-box 核心跑 Reality）
+3. 托盘 → **服务器** → **从剪贴板导入批量 URL**
+4. 从面板复制 `vless://...` 与 `hy2://...` 分别导入
+5. 设为活动服务器，路由选 **绕过大陆**

 **手动核对 Reality 参数：**

 | 字段 | 值 |
 |------|-----|
-| 地址 | VPS IP |
+| 地址 | VPS IP（或域名，SNI 仍用 microsoft） |
 | 端口 | 443 |
-| 用户 ID | `.env` 中的 UUID |
+| 用户 ID | 面板节点 UUID |
 | 流控 | xtls-rprx-vision |
-| 传输 | tcp |
+| 传输 | tcp / raw（Xray 26+ 显示 raw 正常） |
 | 安全 | reality |
-| SNI | www.microsoft.com（或你设的 REALITY_SERVER_NAME） |
+| SNI | `www.microsoft.com`（**不要用 Hy2 域名**） |
 | Fingerprint | chrome |
-| Public Key | REALITY_PUBLIC_KEY |
-| Short ID | REALITY_SHORT_ID |
+| Public Key | `.env` 的 `REALITY_PUBLIC_KEY` |
+| Short ID | `.env` 的 `REALITY_SHORT_ID` |
+| **SpiderX** | **`/`**（空着可能连不上） |
+
+> **常见错误**：Hy2 的 SNI 是 `66.hyf2.cc`，Reality 的 SNI 必须是 `www.microsoft.com`，两者不要混用。

 ### 方案 B：sing-box 客户端

 1. 下载 [sing-box for Windows](https://github.com/SagerNet/sing-box/releases)
 2. 将 `client/generated/sing-box-client.json` 放入配置目录
-3. 以管理员运行（TUN 模式需要），启动后选择 `reality` 出站
+3. 以管理员运行（TUN 模式需要），选择 `reality` 出站

 ### 方案 C：Nekoray

@@ -76,18 +85,12 @@ UDP 无法用普通 TCP 工具测。直接导入客户端测试；若 Reality

 ### v2rayNG（推荐）

-1. [Google Play](https://play.google.com/store/apps/details?id=com.v2ray.ang) 或 [GitHub Releases](https://github.com/2dust/v2rayNG/releases) 安装
-2. 右上角 **+** → **从剪贴板导入**（先复制 `vless://` 链接）
+1. [GitHub Releases](https://github.com/2dust/v2rayNG/releases) 安装 **arm64-v8a** APK（多数新机）
+2. 右上角 **+** → **从剪贴板导入**（先复制面板 `vless://` 链接）
 3. 再导入 `hy2://` 备用节点
 4. 点击右下角 **V** 连接
 5. 设置 → **路由设置** → **绕过局域网及大陆地址**

-### sing-box for Android
-
-1. [GitHub Releases](https://github.com/SagerNet/sing-box/releases) 安装 APK
-2. **Profiles** → **+** → 导入 `sing-box-client.json`
-3. 开启 **Service**
-
 ---

 ## 四、iOS
@@ -96,57 +99,56 @@ UDP 无法用普通 TCP 工具测。直接导入客户端测试；若 Reality

 ### Shadowrocket（小火箭）

-1. App Store 购买安装 Shadowrocket
-2. 首页右上角 **+** → **类型选 NONE** → 右上角 **扫描或从剪贴板导入**
-3. 粘贴 `vless://` 链接，自动填充 Reality 参数
-4. 再添加 `hy2://` 备用
-5. 连接后 **连通性测试** 应显示延迟
+1. App Store 安装 Shadowrocket
+2. **+** → 从剪贴板导入 `vless://` 链接
+3. 再添加 `hy2://` 备用
+4. 连接后 **连通性测试** 应显示延迟

 **手动添加 Reality：**

 - 类型：VLESS
 - 地址：VPS IP
 - 端口：443
- UUID：你的 UUID
- 传输方式：none
- TLS：开启 → 类型 **REALITY**
- SNI：REALITY_SERVER_NAME
- Public Key / Short ID：从 `.env` 复制
+- UUID：面板中的 UUID
+- TLS：REALITY
+- SNI：`REALITY_SERVER_NAME`（默认 `www.microsoft.com`）
+- Public Key / Short ID：从 `.env` 或面板链接复制
 - uTLS：chrome
 - Flow：xtls-rprx-vision

 ### Streisand

-1. App Store 安装 Streisand
-2. **+** → **Import from Clipboard**，粘贴链接
-3. 连接
+**+** → **Import from Clipboard**，粘贴链接后连接。

 ---

 ## 五、macOS

-与 Windows 类似：
-
- **V2rayU** / **Nekoray** / **sing-box for Apple platforms**
- 从剪贴板导入 `vless://` 和 `hy2://` 链接
+与 Windows 类似：V2rayU / Nekoray / sing-box，从剪贴板导入面板链接。

 ---

 ## 六、日常使用建议

 1. **默认节点**：Reality（`vless://`）
-2. **备用节点**：Hysteria2（看视频卡顿时可切换）
-3. **不要分享**节点链接；每设备保存一份即可
-4. **每月检查**：`systemctl status sing-box`、证书是否续期（acme.sh 自动）
+2. **备用节点**：Hysteria2（UDP 卡顿时切换）
+3. **不要分享**节点链接
+4. **每月检查**：`systemctl status xray sing-box`、证书续期（acme.sh 自动）

 ---

 ## 七、分享链接格式参考

-```
-vless://UUID@IP:443?encryption=none&flow=xtls-rprx-vision&security=reality&sni=SNI&fp=chrome&pbk=PUBLIC_KEY&sid=SHORT_ID&type=tcp#名称
+面板生成的 VLESS 链接示例：

-hy2://PASSWORD@DOMAIN:8443?sni=DOMAIN#名称
+```
+vless://UUID@IP:443?encryption=none&flow=xtls-rprx-vision&security=reality&sni=SNI&fp=chrome&pbk=PUBLIC_KEY&sid=SHORT_ID&spx=%2F&type=tcp#名称
 ```

-完整链接见部署后生成的 `client/generated/share-links.txt`。
+Hy2（端口随节点变化，以面板为准）：
+
+```
+hy2://PASSWORD@DOMAIN:8443?sni=DOMAIN#名称-Hy2
+```
+
+完整链接见面板或 `client/generated/share-links.txt`。
@@ -3,320 +3,323 @@
 ## 服务检查

 ```bash
-# sing-box 是否运行
-systemctl is-active sing-box
-
-# 管理面板是否运行
+# 核心服务
+systemctl is-active xray          # VLESS Reality 443
+systemctl is-active sing-box      # Hysteria2 8443+
 systemctl is-active jiedian-panel

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

-# 端口监听
-ss -tlnp | grep 443      # Reality TCP
-ss -tlnp | grep 5080     # 面板后端（仅本机）
-ss -tlnp | grep :80       # Nginx（ACME + 面板反向代理）
-ss -ulnp | grep 8443     # Hysteria2 UDP
+# Reality 密钥诊断（推荐首选）
+bash /opt/jiedian/scripts/verify-reality.sh

-# Nginx fallback
-curl -s http://127.0.0.1:8080
+# 端口监听
+ss -tlnp | grep 443      # 应为 xray（VLESS Reality）
+ss -tlnp | grep 5080     # 面板后端（仅本机）
+ss -tlnp | grep :80      # Nginx（ACME + 面板）
+ss -ulnp | grep 8443     # sing-box Hy2（多节点还有 8444…）
 ```

+## 架构速查
+
+| 组件 | 端口 | 说明 |
+|------|------|------|
+| **Xray** | 443/TCP | VLESS + Reality |
+| **sing-box** | 8443+/UDP | Hysteria2，每节点独立端口 |
+| **面板** | 80/TCP（Nginx 反代） | `http://域名/PANEL_PATH/` |
+
+> **443 由 Xray 占用**（不是 Web 面板）。面板走 **80** 端口子路径，必须用 `http://` 访问。
+
+---
+
 ## 管理面板访问

-面板通过 **Nginx 80 端口反向代理**，不再单独暴露 8444。
-
 ```bash
-# 查看面板路径（安装时自动生成或 .env 中配置）
 grep PANEL_PATH /opt/jiedian/.env
-
-# 示例：PANEL_PATH=jiedian-a1b2c3d4
-# 访问地址：http://66.hyf2.cc/jiedian-a1b2c3d4/
 curl -I "http://66.hyf2.cc/$(grep ^PANEL_PATH= /opt/jiedian/.env | cut -d= -f2)/login"
 ```

-> 443 端口已被 sing-box Reality 占用，面板走 80 端口子路径。请妥善保管 `PANEL_PATH`，相当于隐藏入口。
->
-> **必须用 `http://` 访问，不要用 `https://`。** 443 不是 Web 面板，用 HTTPS 会报错或出现 `Invalid URL / [No Host]`。
+面板统计：Hy2 来自 sing-box Clash API；VLESS 在线部分来自 Xray `access.log`。

-面板可查看每个节点的 **在线状态、连接数、实时速率、累计流量**（数据来自 sing-box Clash API，仅监听 127.0.0.1）。
-
-> **注意**：GitHub 官方 sing-box 预编译包**不含** `v2ray_api`，配置里不要启用 `experimental.v2ray_api`，否则 sing-box 无法启动。
+> GitHub 官方 sing-box 预编译包**不含** `v2ray_api`，配置里不要启用 `experimental.v2ray_api`。

 ---

 ## 常见问题

-### 面板报 Invalid URL / [No Host]
+### VLESS Reality 测速 `-1` / 无法连接

-**原因**：用了 `https://域名/面板路径/` 访问，或域名开了 CDN 加速但回源 Host 未配置。
+**现象**：Hy2 正常，VLESS 延迟 `-1`；或 Xray / sing-box 日志出现 `REALITY: processed invalid connection`。

- 443 端口是 **sing-box Reality**，不是 Web 面板
- 面板地址必须是：**`http://66.hyf2.cc/jiedian-xxxx/`**（注意是 **http**）
+**原因（按概率）**：
+
+1. **旧版仍用 sing-box 跑 443** → 与 v2rayN（Xray 核心）不兼容
+2. **`.env` 私钥与 `/usr/local/etc/xray/config.json` 不一致**（改过密钥未 render）
+3. **SNI 填错**：Reality 必须 `www.microsoft.com`，不能填 Hy2 域名
+4. **SpiderX 为空**：v2rayN 中填 **`/`**
+5. **公钥私钥不配对**：`.env` 中 PUBLIC/PRIVATE 不是同一批 `generate-keys.sh` 生成

 **处理**：

 ```bash
-# 1. 用 HTTP 打开（把 jiedian-xxxx 换成你的 PANEL_PATH）
-http://66.hyf2.cc/jiedian-xxxx/
-
-# 2. VPS 上更新 nginx 与面板（修复 Host 头）
 cd /opt/jiedian
 git pull
-sed -e "s|__DOMAIN__|$(grep ^DOMAIN= .env | cut -d= -f2)|g" \
-    -e "s|__PANEL_LOCATION__|/$(grep ^PANEL_PATH= .env | cut -d= -f2)/|g" \
-    -e "s|__PANEL_PREFIX__|/$(grep ^PANEL_PATH= .env | cut -d= -f2)|g" \
-    -e "s|__PANEL_ALLOW__||g" \
-    server/nginx/acme.conf.template > /etc/nginx/sites-available/acme
-nginx -t && systemctl reload nginx
+
+# 新架构：迁移到 Xray（只需执行一次）
+bash scripts/migrate-xray-reality.sh
+
+# 或已迁移后仅重载配置
+python3 scripts/render-xray.py
+python3 scripts/render-server.py
+systemctl restart xray sing-box
+```
+
+**诊断**：
+
+```bash
+bash scripts/verify-reality.sh
+journalctl -u xray -n 30 --no-pager
+```
+
+**客户端核对**（v2rayN）：
+
+| 项 | 值 |
+|----|-----|
+| 地址 | VPS IP |
+| 端口 | 443 |
+| SNI | `www.microsoft.com` |
+| 流控 | xtls-rprx-vision |
+| SpiderX | `/` |
+| 核心 | Xray（非 sing-box） |
+
+从面板 **重新复制** VLESS 链接导入，不要手改旧节点。
+
+---
+
+### 面板报 Invalid URL / [No Host]
+
+**原因**：用了 `https://域名/面板路径/` 访问，或 CDN 回源 Host 异常。
+
+- 443 是 **Xray Reality**，不是 Web
+- 面板必须是：**`http://域名/jiedian-xxxx/`**
+
+```bash
+cd /opt/jiedian && git pull
+# 重载 nginx 与面板（见 DEPLOY.md）
 systemctl restart jiedian-panel
 ```

-若域名在阿里云/Cloudflare 开了 **CDN 代理**，建议对管理域名 **关闭 CDN**（仅 DNS 解析到 VPS），否则 80 端口回源也可能异常。
+域名建议 **关闭 CDN**，仅 DNS 解析到 VPS。
+
+---

 ### 多节点全部显示离线

-sing-box 的 Clash API **不会在连接详情里返回用户 UUID**（单节点时面板用兜底逻辑，多节点必须按 inbound 区分）。
+sing-box Clash API **不返回用户 UUID**；多节点 Hy2 按 **inbound 端口** 区分。

-升级后每个节点有 **独立 Hysteria2 端口**（按节点 ID 排序：8443、8444、8445…）。请：
-
-1. 更新代码并重新生成配置：
+1. 更新并重载：
   ```bash
   cd /opt/jiedian && git pull
+   python3 scripts/render-xray.py
   python3 scripts/render-server.py
-   systemctl restart sing-box jiedian-panel
+   systemctl restart xray sing-box jiedian-panel
   ```
-2. **阿里云安全组** 放行 `8443-8499/UDP`（不只 8443）
-3. 在面板 **重新复制** 各节点的 Hysteria2 链接（端口可能已变）
-4. VLESS 多用户在线状态依赖 sing-box 日志，需保持 `log.level` 为 `info`（render-server 已默认）
+2. **安全组** 放行 `8443-8499/UDP`
+3. 面板 **重新复制** 各节点 Hy2 链接（第二节点端口为 8444…）
+4. VLESS 多用户在线依赖 Xray access.log + sing-box 日志
+
+---

 ### 添加/删除节点后白屏或 503

-创建节点会触发 sing-box 重启，页面刷新时可能短暂不可用。新版前端会自动重试；若仍白屏，等 10 秒后手动刷新 `http://域名/面板路径/`。
+创建/删除节点会后台重启 xray + sing-box。等 5–10 秒后刷新；新版前端会自动重试。
+
+---

 ### 在线节点 / 统计一直显示「检测中」

-页面初始状态是「检测中」。若长期不变且数字一直是 `-`，说明 **前端 JS 或 `/api/stats` 请求失败**（常见：静态资源路径缺少 `PANEL_PATH` 前缀）。
-
-**处理**：
+页面初始为「检测中」。若长期 `-` 且无数据：

 ```bash
-cd /opt/jiedian
-git pull
-grep PANEL_PATH /opt/jiedian/.env
-grep PANEL /etc/systemd/system/jiedian-panel.service
+cd /opt/jiedian && git pull
 systemctl restart jiedian-panel
 ```

-浏览器 **Ctrl+F5** 强制刷新。按 F12 → Network，确认：
+浏览器 **Ctrl+F5**；F12 → Network 确认 `.../PANEL_PATH/static/app.js` 与 `.../api/stats` 均为 200。

- `.../jiedian-xxxx/static/app.js` 返回 200（不是 `/static/app.js`）
- `.../jiedian-xxxx/api/stats` 返回 200 JSON
+---

-若 `app.js` 404 或 `api/stats` 返回纯文本 `ok`，说明路径前缀仍未生效，需确认 `.env` 中 `PANEL_PATH` 与 systemd 里 `Environment=PANEL_PATH=...` 一致。
+### 面板流量/在线状态显示「不可用」

-### sing-box 报错 v2ray api is not included in this build
-
-GitHub 下载的官方 sing-box **默认不带** `v2ray_api` 模块。若配置里写了 `experimental.v2ray_api`，启动时会直接失败：
-
-```
-FATAL create v2ray-server: v2ray api is not included in this build, rebuild with -tags with_v2ray_api
-```
-
-**处理**：重新生成配置（已移除 v2ray_api，改用 Clash API 统计）并重启：
+旧版 `/api/stats` 会同步读 Clash `/traffic`（WebSocket）导致 504。更新后已改为只读 `/connections`：

 ```bash
-cd /opt/jiedian
-git pull
+cd /opt/jiedian && git pull
+systemctl restart jiedian-panel
+```
+
+若仍不可用：
+
+```bash
+ss -tlnp | grep 9090
 python3 scripts/render-server.py
 systemctl restart sing-box jiedian-panel
 ```

-### 面板流量/在线状态显示「不可用」或一直「检测中」后超时
+---

-常见原因是面板请求 sing-box **Clash API 的 `/traffic`**。该接口是 **WebSocket 实时流**，用普通 HTTP GET 会一直占用连接，直到 Nginx 60s 超时返回 **504**，前端 `/api/stats` 失败即显示「不可用」。
+### sing-box 报错 v2ray api is not included

-**处理**：更新代码并重启面板（已改为只读 `/connections`，不再阻塞请求）：
+重新生成配置（已移除 v2ray_api）：

 ```bash
-cd /opt/jiedian
-git pull
-systemctl restart jiedian-panel
-```
-
-若仍显示「不可用」，再检查 Clash API 是否启用：
-
-```bash
-systemctl is-active sing-box
-ss -tlnp | grep 9090    # Clash API
-grep CLASH_API_SECRET /opt/jiedian/.env
 python3 /opt/jiedian/scripts/render-server.py
-systemctl restart sing-box jiedian-panel
+systemctl restart sing-box
 ```

-升级后若未重装，需重新生成 sing-box 配置并重启服务，才会启用 `experimental.clash_api`。
+---

-### 在线状态始终离线但客户端能连
-
-面板通过 sing-box **Clash API** 判断在线。统计服务显示「正常」只代表 API 能访问，不代表能识别到连接。
-
-常见原因：
-
-1. **Clash API 未带 user 字段**（Hysteria2 旧配置未设置 `name`）→ 重新生成配置：
-   ```bash
-   python3 /opt/jiedian/scripts/render-server.py && systemctl restart sing-box
-   ```
-2. **仅有一个节点时**：新版面板会把所有活跃连接归到该节点；多节点需确保 hy2 用户 `name` 与 VLESS 的 UUID 一致。
-3. **客户端测速有延迟但面板仍离线**：在 VPS 上查看 Clash 连接列表：
-   ```bash
-   curl -s -H "Authorization: Bearer $(grep ^CLASH_API_SECRET= /opt/jiedian/.env | cut -d= -f2)" \
-     http://127.0.0.1:9090/connections | python3 -m json.tool | head -80
-   ```
-   若 `connections` 为空但客户端确实在传流量，单节点场景面板会用连接汇总速率推断在线。
-
-### 面板打不开 / 404
-
-1. **路径不对**：必须用完整路径，末尾带 `/`，例如 `http://域名/jiedian-xxxx/login`
-2. **Nginx 未加载配置**：
-   ```bash
-   nginx -t && systemctl reload nginx
-   cat /etc/nginx/sites-available/acme | grep -A5 jiedian
-   ```
-3. **面板进程未运行**：
-   ```bash
-   systemctl status jiedian-panel
-   journalctl -u jiedian-panel -n 30 --no-pager
-   curl -I http://127.0.0.1:5080/login
-   ```
-4. **阿里云安全组**：只需放行 `80/TCP`，**无需**再放行 8444
-
-### 面板登录后跳回登录页 / 样式丢失
-
-通常是子路径反向代理头未生效，检查 Nginx 是否包含：
-
-```nginx
-proxy_set_header X-Forwarded-Prefix /你的PANEL_PATH;
-```
-
-修改后 `systemctl reload nginx`，并确认 `.env` 中 `PANEL_PATH` 与 Nginx 一致。
-
-### 设置了 PANEL_ALLOW_IP 后无法访问
-
-`.env` 中 `PANEL_ALLOW_IP` 会限制仅该 IP 可访问面板。本机公网 IP 变更后需更新并重装 Nginx 配置：
+### Xray 无法启动

 ```bash
-# 编辑 .env 后重新渲染 nginx
-cd /opt/jiedian
-bash scripts/install.sh   # 或手动 sed acme 配置后 reload nginx
+journalctl -u xray -n 50 --no-pager
+xray run -test -c /usr/local/etc/xray/config.json
+ss -tlnp | grep :443
 ```

-### 忘记面板密码或路径
+常见原因：443 被其他进程占用、JSON 错误、私钥格式错误。
+
+若 sing-box 仍监听 443，说明未迁移：

 ```bash
-grep -E 'PANEL_(USERNAME|PASSWORD|PATH)' /opt/jiedian/.env
-# 重置密码与 Reality 密钥
-bash scripts/generate-keys.sh
+bash /opt/jiedian/scripts/migrate-xray-reality.sh
 ```

-### acme.sh 证书申请失败
-
-```bash
-# 确认 DNS 已生效
-dig +short A your.domain.com
-
-# 确认 80 端口未被占用（nginx 需先启动）
-ss -tlnp | grep :80
-
-# 手动重试
-/root/.acme.sh/acme.sh --issue -d your.domain.com -w /var/www/acme --force
-```
+---

 ### sing-box 无法启动

 ```bash
 journalctl -u sing-box -n 50 --no-pager
-```
-
-常见原因：证书路径错误、JSON 语法错误、443 被占用。
-
-```bash
-ss -tlnp | grep :443
 sing-box check -c /etc/sing-box/config.json
 ```

+常见原因：Hy2 证书路径错误、8443+ UDP 配置错误。443 不应再被 sing-box 占用。
+
+---
+
+### 面板打不开 / 404
+
+1. URL 含完整 `PANEL_PATH`，末尾 `/`
+2. `systemctl status jiedian-panel`
+3. 安全组放行 **80/TCP**（无需 8444）
+
+---
+
+### 忘记面板密码或路径
+
+```bash
+grep -E 'PANEL_(USERNAME|PASSWORD|PATH)' /opt/jiedian/.env
+bash scripts/generate-keys.sh   # 会轮换 Reality 密钥，之后必须 render + restart
+python3 scripts/render-xray.py
+python3 scripts/render-server.py
+systemctl restart xray sing-box
+```
+
+---
+
+### acme.sh 证书申请失败
+
+```bash
+dig +short A your.domain.com
+ss -tlnp | grep :80
+/root/.acme.sh/acme.sh --issue -d your.domain.com -w /var/www/acme --force
+```
+
+证书仅用于 **Hy2**；Reality 不使用域名证书。
+
+---
+
 ### 客户端能连但速度慢

- 换 Hysteria2 节点（UDP/QUIC 抗丢包）
- 检查 VPS 带宽：`wget -O /dev/null http://speedtest.tele2.net/100MB.zip`
- 避免高峰时段长时间 4K 流媒体
+- 换 Hysteria2（UDP）
+- 检查带宽：`wget -O /dev/null http://speedtest.tele2.net/100MB.zip`
+
+---

 ### IP 被封

-1. 向 VPS 商申请更换 IP
-2. 修改 `.env` 中 `REALITY_SERVER_NAME` 为其他大站（如 `www.apple.com`）
-3. 重新运行 `install.sh` 或手动更新 `/etc/sing-box/config.json` 并 restart
+1. 向 VPS 商更换 IP，更新 `.env` 中 `VPS_IP`
+2. 修改 `REALITY_SERVER_NAME`（如 `www.apple.com`）
+3. `generate-keys.sh` → `render-xray.py` → `restart xray`
+
+---

 ### apt 锁被占用

-安装脚本会自动等待最多 10 分钟。若超时：
+安装脚本会自动等待。超时后：

 ```bash
-# 查看占用进程
 fuser /var/lib/dpkg/lock-frontend
-# 等待 cloud-init / unattended-upgrades 结束后再执行
 bash scripts/install.sh
 ```

+---
+
 ### SSH 主机密钥变更

-VPS 重装系统后，本地执行：
+VPS 重装后本地：

 ```bash
-ssh-keygen -R 你的VPS_IP
+ssh-keygen -R YOUR_VPS_IP
 ```

+---
+
 ### 卸载后重装

 ```bash
 cd /opt/jiedian
 git pull
 bash scripts/uninstall.sh
-bash scripts/generate-keys.sh    # 可选：重置密钥与面板密码
+bash scripts/generate-keys.sh
 bash scripts/install.sh
 ```

-### 改用 Xray 替代 sing-box（可选）
+---

-若更熟悉 Xray，可使用 `server/xray-server.json.template`：
+### 从旧版 sing-box Reality 升级到 Xray

 ```bash
-# 安装 Xray
-bash -c "$(curl -L https://github.com/XTLS/Xray-install/raw/main/install-release.sh)" @ install
-
-# 渲染配置
-sed -e "s|\${UUID}|...|g" ... server/xray-server.json.template > /usr/local/etc/xray/config.json
-
-systemctl restart xray
+cd /opt/jiedian && git pull
+bash scripts/migrate-xray-reality.sh
 ```

-Hysteria2 仍需单独部署（或使用 sing-box 仅跑 Hy2 inbound）。
+客户端参数不变，重测 VLESS 即可。

 ---

 ## 防火墙与安全组对照

-| 端口 | 协议 | 用途 | 是否必须放行 |
-|------|------|------|-------------|
+| 端口 | 协议 | 用途 | 必须放行 |
+|------|------|------|----------|
 | 22 | TCP | SSH | 是 |
-| 80 | TCP | ACME 验证 + **管理面板** | 是 |
-| 443 | TCP | VLESS + Reality | 是 |
-| 8443-8499 | UDP | Hysteria2（每节点递增端口） | 是 |
-| ~~8444~~ | ~~TCP~~ | ~~旧版面板的独立 HTTPS~~ | **已废弃，无需放行** |
+| 80 | TCP | ACME + **管理面板** | 是 |
+| 443 | TCP | VLESS + Reality（**Xray**） | 是 |
+| 8443–8499 | UDP | Hysteria2（**sing-box**，每节点递增） | 是 |
+| ~~8444~~ | ~~TCP~~ | ~~旧版面板 HTTPS~~ | **已废弃** |

 ## 安全建议

 - 使用随机 `PANEL_PATH`，不要公开分享面板地址
- 可选在 `.env` 设置 `PANEL_ALLOW_IP=你的公网IP` 限制访问来源
- SSH 改用密钥登录，禁用密码：`PermitRootLogin prohibit-password`
- 可选修改 SSH 端口，ufw 放行新端口后再删 22
- 不要将 `.env` 或节点分享链接上传到公开仓库
+- 可选 `PANEL_ALLOW_IP=你的公网IP` 限制面板访问
+- SSH 密钥登录，禁用密码登录
+- 不要将 `.env` 或节点链接上传到公开仓库
+
+## 相关文档
+
+- 新部署：[DEPLOY.md](DEPLOY.md)
+- 客户端导入：[client-import.md](client-import.md)
+- 架构说明：[STACK.md](STACK.md)