dekun/jiedian
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
Document new install flow, ports, migration script, and v2rayN Reality settings across README and docs/.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
dekun
2026-06-16 12:03:03 +08:00
parent c9895133cb
commit 4b3f6a1de2
5 changed files with 454 additions and 316 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/troubleshooting.md
+192 -189
View File
@@ -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)