故障排查
读者：部署或运行中遇到异常的运维人员。
按现象索引到对应专题；多数问题可归因于网络、授权、同步、SSH 四类。
1. 控制台无法访问
Section titled “1. 控制台无法访问”| 现象 | 排查 |
|---|---|
| 502 / 连接拒绝 | systemctl status xctl-master；journalctl -u xctl-master -n 50 |
| 数据库错误 | 检查 master.yaml DSN；MariaDB 是否运行 |
| 证书错误 | 反代 TLS 配置；浏览器是否用正确域名 |
凭据：sudo xctl master creds
2. 授权异常
Section titled “2. 授权异常”| 现象 | 排查 |
|---|---|
| 提示 License 无效 | /etc/xctl/master.env 中 XCTL_LICENSE_KEY；是否续费 续费与升级 |
| 无法新建租户/Host | 套餐 配额是否用尽 |
3. 节点离线
Section titled “3. 节点离线”| 现象 | 排查 |
|---|---|
| Host 显示离线 | 节点：systemctl status xctl-client；能否 curl Master /dl/ |
| 间歇离线 | 反代 WebSocket idle timeout；节点出网不稳 |
| SSH 通但 Client 离线 | Master URL 是否与浏览器 origin 一致；防火墙出站 |
4. 配置不同步
Section titled “4. 配置不同步”| 现象 | 排查 |
|---|---|
pending 长期不变 | Client 离线；见上 |
failed | 配置同步队列 错误信息；XUI API 是否可达 |
drift | 是否手工改过 3x-ui；触发重新同步或删除本机 inbound 重建 |
| 订阅无线路 | 逻辑节点 准入、group_id、用户 |
5. SSH 装机失败
Section titled “5. SSH 装机失败”见 SSH 一键装机 FAQ：安全组、密钥、出网下载、磁盘满。
6. 面板 / WHMCS 对接
Section titled “6. 面板 / WHMCS 对接”| 现象 | 排查 |
|---|---|
| 开通失败 | Adapter Token Scope；biz_ref 冲突；租户 是否正确 |
| 订阅空 | group_id 与逻辑节点 group_ids |
| 流量不回 | Webhook URL；GET /api/v1/events 兜底 |
| 全继承多节点同步乱/报错 | 多个面板 node_id 对接同一 XCTL Node Group 时，面板后台服务器端口（server_port）是否一致；控制台是否显示端口冲突 |
面板全继承：服务器端口不一致
Section titled “面板全继承：服务器端口不一致”现象：drift、config 来回变；控制台标端口冲突，Telegram 有提醒。
处理：把映射到同一 Node Group 的面板节点 server_port 改齐，或拆成不同逻辑节点。Master 只告警、不拦同步。详见 面板节点服务器端口须一致。
证书续签或下发失败
Section titled “证书续签或下发失败”现象：Telegram 报证书临期/续签失败；逻辑节点 TLS 仍显示旧过期时间。
处理：控制台 → 证书中心 查看状态与失败原因（常见：DNS Token 权限、传播慢）；修复后手动 续签 或等待自动重试。续签失败时 Host 上旧证书不会被删。
7. 升级后异常
Section titled “7. 升级后异常”- Master：migration 失败 → 查日志，必要时从 DB 备份回滚
- Client：版本过旧 → 升级 并重启
8. 收集信息联系支持
Section titled “8. 收集信息联系支持”提供（勿含明文 Token / 密钥）：
- Master 版本、License 套餐档位
request_id（API 错误响应中）- 主机 ID、逻辑节点 ID、失败任务截图
- 相关时间段 审计 摘要