dekun/jiedian
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
db251c39bf68b67501b02522622d3fbb5ca2d05f
jiedian/docs/troubleshooting.md
T
dekun db251c39bf fix: stop panel stats from hanging on Clash /traffic WebSocket 
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-16 10:59:45 +08:00

9.7 KiB
Raw Blame History

运维与故障排查

服务检查

# sing-box 是否运行
systemctl is-active sing-box

# 管理面板是否运行
systemctl is-active jiedian-panel

# 配置语法
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

# Nginx fallback
curl -s http://127.0.0.1:8080

管理面板访问

面板通过 Nginx 80 端口反向代理，不再单独暴露 8444。

# 查看面板路径（安装时自动生成或 .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]。

面板可查看每个节点的 在线状态、连接数、实时速率、累计流量（数据来自 sing-box Clash API，仅监听 127.0.0.1）。

注意：GitHub 官方 sing-box 预编译包不含 v2ray_api，配置里不要启用 experimental.v2ray_api，否则 sing-box 无法启动。

常见问题

面板报 Invalid URL / [No Host]

原因：用了 https://域名/面板路径/ 访问，或域名开了 CDN 加速但回源 Host 未配置。

  • 443 端口是 sing-box Reality，不是 Web 面板
  • 面板地址必须是：http://66.hyf2.cc/jiedian-xxxx/（注意是 http）

处理：

# 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
systemctl restart jiedian-panel

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

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

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

处理：

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

浏览器 Ctrl+F5 强制刷新。按 F12 → Network，确认：

  • .../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 统计）并重启：

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

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

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

处理：更新代码并重启面板（已改为只读 /connections，不再阻塞请求）：

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

若仍显示「不可用」，再检查 Clash API 是否启用：

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

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

在线状态始终离线但客户端能连

面板通过 sing-box Clash API 判断在线。统计服务显示「正常」只代表 API 能访问，不代表能识别到连接。

常见原因：

  1. Clash API 未带 user 字段（Hysteria2 旧配置未设置 name）→ 重新生成配置： 
    python3 /opt/jiedian/scripts/render-server.py && systemctl restart sing-box
  2. 仅有一个节点时：新版面板会把所有活跃连接归到该节点；多节点需确保 hy2 用户 name 与 VLESS 的 UUID 一致。
  3. 客户端测速有延迟但面板仍离线：在 VPS 上查看 Clash 连接列表： 
    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 未加载配置： 
    nginx -t && systemctl reload nginx
cat /etc/nginx/sites-available/acme | grep -A5 jiedian
  3. 面板进程未运行： 
    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 是否包含：

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 配置：

# 编辑 .env 后重新渲染 nginx
cd /opt/jiedian
bash scripts/install.sh   # 或手动 sed acme 配置后 reload nginx

忘记面板密码或路径

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

acme.sh 证书申请失败

# 确认 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 无法启动

journalctl -u sing-box -n 50 --no-pager

常见原因：证书路径错误、JSON 语法错误、443 被占用。

ss -tlnp | grep :443
sing-box check -c /etc/sing-box/config.json

客户端能连但速度慢

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

IP 被封

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

apt 锁被占用

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

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

SSH 主机密钥变更

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

ssh-keygen -R 你的VPS_IP

卸载后重装

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

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

若更熟悉 Xray，可使用 server/xray-server.json.template：

# 安装 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

Hysteria2 仍需单独部署（或使用 sing-box 仅跑 Hy2 inbound）。

防火墙与安全组对照

端口 协议 用途 是否必须放行
22 TCP SSH 是
80 TCP ACME 验证 + 管理面板 是
443 TCP VLESS + Reality 是
8443 UDP Hysteria2 是
8444 TCP 旧版面板的独立 HTTPS 已废弃，无需放行

安全建议

  • 使用随机 PANEL_PATH，不要公开分享面板地址
  • 可选在 .env 设置 PANEL_ALLOW_IP=你的公网IP 限制访问来源
  • SSH 改用密钥登录，禁用密码：PermitRootLogin prohibit-password
  • 可选修改 SSH 端口，ufw 放行新端口后再删 22
  • 不要将 .env 或节点分享链接上传到公开仓库
Reference in New Issue View Git Blame Copy Permalink