# 运维与故障排查

## 服务检查

```bash
# 核心服务
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://` 访问。

---

## 管理面板访问

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

**处理**：

```bash
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
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
```

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

---

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

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

1. 更新并重载：
   ```bash
   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 秒后刷新；新版前端会自动重试。

---

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

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

```bash
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`：

```bash
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 报错 v2ray api is not included

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

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

---

### Xray 无法启动

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

---

### sing-box 无法启动

```bash
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）

---

### 忘记面板密码或路径

```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）
- 检查带宽：`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 锁被占用

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

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

---

### SSH 主机密钥变更

VPS 重装后本地：

```bash
ssh-keygen -R YOUR_VPS_IP
```

---

### 卸载后重装

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

---

### 从旧版 sing-box Reality 升级到 Xray

```bash
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](DEPLOY.md)
- 客户端导入：[client-import.md](client-import.md)
- 架构说明：[STACK.md](STACK.md)