# 运维与故障排查

## 服务检查

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

```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`，相当于隐藏入口。

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

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

---

## 常见问题

### 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 统计）并重启：

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

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

sing-box 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
```

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

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

- 有流量时面板会按速率推断在线；若仍显示离线，执行 `curl -s -H "Authorization: Bearer $(grep CLASH_API_SECRET /opt/jiedian/.env | cut -d= -f2)" http://127.0.0.1:9090/connections | head` 查看连接 metadata 是否含 user 字段
- 修改节点或升级后需重新渲染配置：`python3 /opt/jiedian/scripts/render-server.py && systemctl restart sing-box`

### 面板打不开 / 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 配置：

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

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

```bash
grep -E 'PANEL_(USERNAME|PASSWORD|PATH)' /opt/jiedian/.env
# 重置密码与 Reality 密钥
bash scripts/generate-keys.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
```

### 客户端能连但速度慢

- 换 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 分钟。若超时：

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

### SSH 主机密钥变更

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

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

### 卸载后重装

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

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

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` 或节点分享链接上传到公开仓库