jiedian/docs/troubleshooting.md

运维与故障排查

服务检查

# 核心服务
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

# Reality 密钥诊断（推荐首选）
bash /opt/jiedian/scripts/verify-reality.sh

# 端口监听
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:// 访问。

---

管理面板访问

grep PANEL_PATH /opt/jiedian/.env
curl -I "http://66.hyf2.cc/$(grep ^PANEL_PATH= /opt/jiedian/.env | cut -d= -f2)/login"

面板统计：Hy2 来自 sing-box Clash API；VLESS 在线部分来自 Xray access.log。

GitHub 官方 sing-box 预编译包不含 v2ray_api，配置里不要启用 experimental.v2ray_api。

---

常见问题

VLESS Reality 测速 -1 / 无法连接

现象：Hy2 正常，VLESS 延迟 -1；或 Xray / sing-box 日志出现 REALITY: processed invalid connection。

原因（按概率）：

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 生成

处理：

cd /opt/jiedian
git pull

# 新架构：迁移到 Xray（只需执行一次）
bash scripts/migrate-xray-reality.sh

# 或已迁移后仅重载配置
python3 scripts/render-xray.py
python3 scripts/render-server.py
systemctl restart xray sing-box

诊断：

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/

cd /opt/jiedian && git pull
# 重载 nginx 与面板（见 DEPLOY.md）
systemctl restart jiedian-panel

域名建议 关闭 CDN，仅 DNS 解析到 VPS。

---

多节点全部显示离线

sing-box Clash API 不返回用户 UUID；多节点 Hy2 按 inbound 端口 区分。

1. 更新并重载：

   cd /opt/jiedian && git pull
   python3 scripts/render-xray.py
   python3 scripts/render-server.py
   systemctl restart xray sing-box jiedian-panel
   

2. 安全组 放行 8443-8499/UDP
3. 面板 重新复制 各节点 Hy2 链接（第二节点端口为 8444…）
4. VLESS 多用户在线依赖 Xray access.log + sing-box 日志

---

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

创建/删除节点会后台重启 xray + sing-box。等 5–10 秒后刷新；新版前端会自动重试。

---

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

页面初始为「检测中」。若长期 - 且无数据：

cd /opt/jiedian && git pull
systemctl restart jiedian-panel

浏览器 Ctrl+F5；F12 → Network 确认 .../PANEL_PATH/static/app.js 与 .../api/stats 均为 200。

---

面板流量/在线状态显示「不可用」

旧版 /api/stats 会同步读 Clash /traffic（WebSocket）导致 504。更新后已改为只读 /connections：

cd /opt/jiedian && git pull
systemctl restart jiedian-panel

若仍不可用：

ss -tlnp | grep 9090
python3 scripts/render-server.py
systemctl restart sing-box jiedian-panel

---

sing-box 报错 v2ray api is not included

重新生成配置（已移除 v2ray_api）：

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

---

Xray 无法启动

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 /opt/jiedian/scripts/migrate-xray-reality.sh

---

sing-box 无法启动

journalctl -u sing-box -n 50 --no-pager
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）

---

忘记面板密码或路径

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 证书申请失败

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）
• 检查带宽：wget -O /dev/null http://speedtest.tele2.net/100MB.zip

---

IP 被封

1. 向 VPS 商更换 IP，更新 .env 中 VPS_IP
2. 修改 REALITY_SERVER_NAME（如 www.apple.com）
3. generate-keys.sh → render-xray.py → restart xray

---

apt 锁被占用

安装脚本会自动等待。超时后：

fuser /var/lib/dpkg/lock-frontend
bash scripts/install.sh

---

SSH 主机密钥变更

VPS 重装后本地：

ssh-keygen -R YOUR_VPS_IP

---

卸载后重装

cd /opt/jiedian
git pull
bash scripts/uninstall.sh
bash scripts/generate-keys.sh
bash scripts/install.sh

---

从旧版 sing-box Reality 升级到 Xray

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

客户端参数不变，重测 VLESS 即可。

---

防火墙与安全组对照

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

安全建议

• 使用随机 PANEL_PATH，不要公开分享面板地址
• 可选 PANEL_ALLOW_IP=你的公网IP 限制面板访问
• SSH 密钥登录，禁用密码登录
• 不要将 .env 或节点链接上传到公开仓库

相关文档

• 新部署：DEPLOY.md
• 客户端导入：client-import.md
• 架构说明：STACK.md