---
title: 故障排查
description: 解决 3x-ui 常见问题——面板无法启动、502 错误、证书问题，以及客户端无法连接。
icon: Wrench
---

最常见问题的排查清单。如有疑问，请调高日志级别
（`XUI_LOG_LEVEL=debug`），并检查面板和 Xray 日志。

## 面板无法启动

- 检查服务状态和日志（`x-ui` 菜单 → 状态/日志）。
- 确认**面板端口未被**其他服务占用。
- 验证数据库路径可写（默认为 `/etc/x-ui/x-ui.db`）。

## 502 / 通过代理时面板无法访问

- 确认面板确实在监听上游端口（例如 `2053`）。
- 确保你的[反向代理](/docs/operations/reverse-proxy)传递了 WebSocket
  升级头，并指向正确的端口和**网站根路径（web base path）**。
- 检查防火墙没有阻断代理 → 面板的连接。

## 证书问题

- 在签发证书之前，域名的 DNS 必须已指向服务器。
- 80/443 端口必须可访问，以便进行 HTTP/TLS 验证（或改用 DNS 验证）。
- 对于 REALITY，请记住它**无需证书**——问题通常出在错误的
  `dest`/SNI 上（参见 [REALITY 常见陷阱](/docs/config/reality)）。

## 客户端无法连接

- 使用[分享链接检查器](/docs/config/share-links)解码客户端的链接，
  并确认每一个参数。
- 检查两端的**传输方式和安全设置是否匹配**。
- 确认客户端未触及其**流量、到期时间或 IP 限制**。
- 确认入站端口已在防火墙中开放。

<Callout type="info">
  仍然无法解决？搜索
  [GitHub issues](https://github.com/MHSanaei/3x-ui/issues)——你遇到的现象
  很可能此前已有人遇到过。
</Callout>
