3x-ui 面板正常但节点不可用的排查方法
3x-ui 装好了，后台能登录，入站也建了，客户端却一直超时。或者客户端已经显示连接，浏览器仍然打不开网页。
这种时候，重新运行安装脚本未必能解决问题。后台页面、Xray 核心、入站端口和客户端配置，分别处在访问过程的不同位置。面板正常，只能先确认管理入口可用；真正的代理请求还要经过下面这条路径：
1 | 客户端应用 → 本地代理 → 服务器入站端口 → Xray 处理请求 → 出站 → 目标网站 |
下面按服务状态、端口、握手、DNS 与出站的顺序定位故障，最后复测原来的请求。尚未安装或创建入站时，先完成3x-ui 安装与首次连接。
示例环境和检查范围
本文沿用 Debian 12、systemd 与官方脚本安装的命令示例，入站以 VLESS/TCP/REALITY 为例。资料核对日期为 2026 年 10 月 18 日，3x-ui 参考版本为 v3.10.2，发布页列出的 Xray-core 为 v26.10.10。排错时记录自己的实际版本，不要以这组示例替代现场信息。版本记录
假设面板使用 2053、节点使用 443：浏览器能访问前者，无法证明后者正常。203.0.113.10 是文档保留地址，端口也只是示例，请替换为实际值。127.0.0.1 指执行命令那台机器的回环地址。
Docker 安装需要按容器部署方式查看服务与日志；下文的 systemctl、journalctl -u x-ui 用于 systemd 管理的脚本安装。
先按现象确定检查顺序
先记下故障发生的时间、面板版本、服务端 Xray 版本、客户端版本，以及客户端内置核心版本。然后用同一个节点发起一次真实请求，同时观察客户端和服务器日志。
“连不上”还需要进一步分清：
| 现象 | 优先进入的检查 |
|---|---|
| 入站没有对应的监听 | Xray 启动与配置应用 |
| 节点端口超时或被拒绝 | 监听地址、网络路径、防火墙和安全组 |
| 端口可达但握手失败 | 协议、身份参数、REALITY 与客户端兼容 |
| 显示连接但网页打不开 | 本地代理、DNS、路由、出站与用户限制 |
| 部分网站或资源失败 | 具体域名的请求路径与失败日志 |
| 更换导入方式或更新后才出问题 | 实际配置差异和版本变更 |
下面每一步都可以留下一个明确结果，方便决定下一步查哪里。
先确认 Xray 和实际入站
在服务器查看面板服务及近期日志：
1 | sudo x-ui status |
x-ui 服务处于 active，不足以单独证明 Xray 入站正常。继续在面板检查 Xray 状态和错误日志，尤其留意保存入站后出现的配置解析、端口占用、文件读取等错误。官方管理入口也提供查看日志和单独重启 Xray 的功能。管理命令
再检查节点端口是否真的由预期进程监听：
1 | sudo ss -lntp 'sport = :443' |
对于 TCP 入站，关注监听地址、端口和所属进程：
- 没有输出：当前网络命名空间没有这个 TCP 监听，先检查入站是否启用、配置是否应用，以及 Xray 是否启动成功。
- 只有
127.0.0.1:443：只能通过当前机器的回环地址访问；如果准备让客户端直接连接，需要核对监听配置。 - 出现
0.0.0.0:443：表示 IPv4 通配监听，外网连通性还需要继续验证。 - 进程是 Nginx 或其他程序：确认这个端口的用途，不能把它当作 Xray 入站已成功启动的证据。
IPv6 监听还需要结合系统的双栈行为和实际连接测试。UDP 入站则应查看 UDP socket，例如 sudo ss -lnup，TCP 的检查结果不能代替 UDP 验证。
若日志明确提示地址被占用，先决定哪个服务使用该端口，再调整冲突的一方。若提示配置无法解析，回看最近修改的字段，而不是继续添加防火墙放行规则。官方启动排查
Docker 安装还要确认使用的是 host 还是 bridge 网络。bridge 模式需要核对容器内监听与发布到宿主机的端口；host 模式则直接使用宿主机网络。容器里的 127.0.0.1 与宿主机的回环地址不能混为一谈。
从客户端所在网络检查节点端口
在自己的 Windows 电脑上，可以用 PowerShell 做 TCP 探测：
1 | Test-NetConnection -ComputerName 203.0.113.10 -Port 443 |
把示例 IP 和端口换成节点实际使用的值。
TcpTestSucceeded: True 说明这次 TCP 建连成功，下一步继续验证协议握手和真实请求。失败时，也不能只凭这一项就判断为防火墙拦截；还需要排除地址、监听、地址族和网络路径问题。
服务器侧先查看现有规则：
1 | sudo nft list ruleset |
使用 UFW 管理规则的机器，再查看：
1 | sudo ufw status verbose |
ufw: command not found 只说明没有这个命令。Debian 使用 nftables 框架，机器上还可能有其他组件维护规则；具体云镜像是否启用过滤，要看实际规则和策略。Debian nftables 说明
如果确认 UFW 正在管理规则，并且该节点确实需要开放 TCP 443，可以按实际范围添加规则：
1 | sudo ufw allow 443/tcp |
随后还要检查云平台安全组或网络防火墙是否允许相应协议、端口和来源。面板端口已经放行，不代表节点端口也被允许；TCP 规则也不会自动放行 UDP。
Docker bridge 的发布端口与 UFW 还存在处理顺序上的差异，不能仅根据 ufw status 推断容器端口是否受限。先确认 Docker 网络模式和端口映射，再检查对应规则。Docker 防火墙说明
需要进一步确认请求有没有到达服务器时，可以在安装了 tcpdump 的服务器短时观察连接头：
1 | sudo tcpdump -ni any -c 20 'tcp port 443' |
同时从客户端发起一次连接。观察到入站 SYN、返回 SYN-ACK 或 RST，有助于缩小范围；看不到包时，先核对目标地址、地址族、过滤条件和请求是否经过本机。看到包也不等于应用握手成功。抓包结果里的真实地址在对外分享前要脱敏。
端口可达后对照握手参数
TCP 能连通，但客户端提示握手失败、认证失败或连接被关闭时，把导入后的配置与面板中的当前记录逐项对照：
- 地址和端口是否属于正在排查的那个入站。
- UUID 是否对应实际启用、未到期的客户端。
- 传输方式和安全模式是否一致。
- REALITY 公钥是否来自当前服务端密钥对，Short ID 是否匹配。
- SNI、目标配置与客户端 flow 是否对应。
- 客户端指纹和握手能力是否受当前核心支持。
链接导入成功，只能说明客户端读懂了这个链接，不保证所有字段都按预期生效。修改过入站或客户端信息后，重新获取配置，并检查客户端里实际保存的值；复制一条旧链接，可能仍然带着旧端口、公钥或其他参数。官方连接排查
REALITY 客户端出现认证失败，或收到目标站真实证书的提示时，应结合两端日志核对握手条件。这些提示不能单独用来证明发生了攻击，也不能单独证明服务器已经无法访问。
还要分开看两项版本因素：最低客户端版本限制与客户端实际提供的握手能力。3x-ui 的版本文档说明，部分 Xray 核心对空的最低版本字段处理不同；较新核心涉及的 ML-KEM 要求又是另一项兼容条件。只调整最低版本字段，未必能补齐客户端缺少的握手能力。版本相关说明
因此，遇到更新后全部失效，先记录双方核心版本和错误，再查对应变更。不要只比较客户端 App 的版本号，也不要把网上某次降级有效的反馈直接套到自己的环境。
显示已连接但网页打不开
客户端界面的“连接成功”可能表示本地核心已启动、选中了节点，或某种探测通过。判断代理功能是否可用，还需要让真实请求明确经过这个节点。
先在客户端所在电脑测试本地 SOCKS 入口。以下假设本地 SOCKS 端口为 10808，请换成客户端实际端口：
1 | curl --noproxy "" --proxy socks5h://127.0.0.1:10808 --connect-timeout 5 --max-time 20 -sS -o proxy-probe.html -w "HTTP %{http_code}\n" https://example.com/ |
Windows 可将命令中的 curl 写为 curl.exe。proxy-probe.html 保存在当前目录，用于确认实际返回的内容；这是一次真实请求，不只是端口探测。
这里显式指定本地 SOCKS 代理，并清除 NO_PROXY 对这次请求的绕过影响。socks5h 会把目标域名交给代理处理，不过客户端内部仍可能通过规则选择直连，所以测试前也要确认这个目标确实经过正在排查的节点。curl 代理选项
根据结果继续判断：
- 本地
127.0.0.1:10808就连接失败：先检查客户端核心是否启动、端口填的是 SOCKS 还是 HTTP。 - 明确经过节点的请求成功，浏览器仍失败：继续检查浏览器代理、系统代理、PAC 或 TUN 的接管情况，以及浏览器自身的 DNS 设置。
- 请求进入节点后失败：对照同一时刻的客户端与服务端日志，检查握手、解析、路由或出站连接错误。
HTTP 403、429 等响应表示收到了某个 HTTP 服务的响应，还需要读响应内容判断来自目标站还是中间组件。它们与根本没有建立连接的超时，应分开处理。
接着检查服务器本身能否访问相同目标。在服务器执行：
1 | curl --noproxy '*' --connect-timeout 5 --max-time 20 -sS -o /dev/null -w 'HTTP %{http_code}\n' https://example.com/ |
这次请求显式绕过环境变量中的代理，但仍可能受机器已有的透明代理或路由配置影响。服务器请求成功，只能说明这条测试路径可用，不能直接证明 Xray 使用的解析与出站配置正确。
如果需要比较地址族，在同一条命令上分别加 -4、-6 测试。两者表现不同，再检查服务器是否真的具备相应出口，以及 Xray 当前的解析、路由与出站策略。不要只因为一次 IPv6 请求失败，就假定所有节点问题都来自 IPv6。Xray DNS、出站配置
用户记录也值得同时检查：是否启用、流量是否耗尽、是否到期、是否触发 IP 限制。配置参数正确而账号被限制，同样会导致无法正常使用。
只有部分网站或图片视频失败
一个页面往往会访问多个域名。首页 HTML 打开了，图片、脚本或媒体请求可能走向另外的地址。此时先找出失败的具体请求，避免把所有现象都归为“节点断了”。
可以在浏览器开发者工具的 Network 面板里记录失败请求，再和客户端日志对应：
- 失败的是主站还是图片、媒体域名。
- 域名解析是否失败，解析结果是否符合当前网络条件。
- 请求实际匹配了哪条规则，最终选择哪个出站。
- 发生的是连接超时、TLS 错误，还是目标服务返回 HTTP 错误。
如果只是某个域名被分流到不可用的出站，就应检查相应规则；如果服务器自身也无法访问该目标，再排查其解析与出口条件。Xray 的 DNS、路由和最终出站有各自配置，系统命令能解析域名，并不足以验证 Xray 内部使用的全部设置。DNS 配置、路由配置
对于 UDP 或 QUIC 相关现象，需要核对实际协议、端口规则和客户端实现。暂时改用另一种传输做对照，可以帮助定位，但一次对照结果还不能证明完整根因。
更新后失效或不同导入方式结果不同
同一个客户端，在分享链接、Clash YAML 和完整 JSON 配置之间切换，可能得到不同结果。排查时，应比较实际配置，而不是只看界面上的节点名称。
项目曾有两个很具体的案例：
- 原始 VLESS 分享链接没有携带已有 Clash 订阅中的 REALITY ML-KEM 提示，导致某些客户端导入结果不同；相关 PR #6712 于 2026 年 10 月 2 日合并。
- 特定 Host SNI 覆盖使 JSON 客户端配置混入服务端的
serverNames字段，而分享链接与 Clash 输出表现不同；问题 #6690 已关联修复。
这些是有条件的历史问题。遇到相似症状时，先核对自己的版本是否包含相应修复，再检查实际输出，不能把旧问题当作当前所有版本都会出现的现象。
对于修改配置后表现没有变化，也要确认配置已经应用到正在处理连接的核心。项目历史上曾修复 REALITY 设置热更新未完整生效的问题，问题 #6010 可作为版本排查的线索。若现场需要重启 Xray 做验证，先保存日志和配置，并安排能接受连接中断的时间。
修复后再跑一次原来的请求
每次只调整有证据指向的一项配置，随后复测原故障：同一个节点、同一客户端、相同目标，检查两端日志是否仍出现原错误。确认请求确实经过预期节点，再检查网页内容或原先失败的资源。
若准备更新或回退，先导出面板配置，备份数据库及实际使用的证书，记录变更前后版本。SQLite 在线备份需要一致快照，停服务复制与在线备份应分别处理；跨主版本恢复还涉及数据库迁移。面板备份、SQLite 备份机制
找人协助排查时，提供系统、安装方式、双方核心版本、具体症状、失败时间和脱敏日志，通常比只发“面板正常但不能用”的截图更有帮助。账号密码、订阅链接、UUID、私钥和真实服务器地址不要直接贴出来。
