x-ui面板启动失败怎么办？先看日志，再按端口占用、数据库、重启次数超限逐项排查

发表于 分类于
x-ui或3x-ui面板启动失败、x-ui status显示没运行，多数时候日志里已经写了原因。这篇按3x-ui源码和服务文件，讲怎么看日志、端口被占用、数据库初始化失败、systemd重启次数超限怎么处理，并说明证书出错时面板其实不会停止，只是退回HTTP。

x-ui 面板启动失败，通常有这几种表现：x-ui status 显示没运行，x-ui start 或 x-ui restart 之后提示失败，或者浏览器打不开但又不确定是服务没起来还是网络问题。这类问题大多数时候日志里已经写了原因，不需要猜。这篇讲怎么看日志，再按日志里最常见的几类报错逐一处理。

先说明依据和范围：下面的判断来自我读 3x-ui（MHSanaei 版）当前主分支的源码、x-ui.sh 脚本和 systemd 服务文件，不是在一台真的启动失败的机器上逐个复现出来的。报错文字在不同版本里可能略有差异，老版本（比如 2.9.4）的行为我没有逐版本核对。原版 x-ui（vaxilu）我没有核对，这篇只讲 3x-ui。如果问题其实是服务在跑、只是浏览器打不开，看x-ui面板打不开的常见原因。

第一步：确认是不是真的没起来

1
x-ui status

这里有一个容易误判的地方：x-ui.sh 脚本在执行启动后，只会等一小会儿就去检查状态，失败时打印的提示里自己写了原因——“可能是因为启动时间超过了两秒，请稍后查看日志”。也就是说，看到"启动失败"的提示不一定是真失败。隔几秒再跑一次 x-ui status，确认确实不是运行状态，再往下排查。

第二步：看日志

脚本里的 x-ui log 对应的是 systemd 日志，下面这条是等价的、更直接：

1
journalctl -u x-ui -n 50 --no-pager

看最近 50 行，找带 Error 的那几行。x-ui log 在较新的版本里会先弹一个小菜单（调试日志、清除日志），选调试日志就是实时跟踪的 journalctl -u x-ui -f。Alpine 系统没有 systemd，脚本里是从 /var/log/messages 里按 x-ui[ 过滤。常用命令汇总见3x-ui常用命令。

看日志里是哪一类报错

我对照源码，把程序启动时会让进程直接退出的几处整理如下。

类型 1：Error starting web server（端口被占用等）

源码里面板启动 Web 服务时，先监听配置的地址和端口，监听失败就直接返回错误，主程序随即以 Error starting web server: ... 退出。最常见的原因是端口已经被别的程序占用，比如你把面板端口改成了和 Nginx、另一个面板或者某个节点相同的端口。

找出谁占着端口：

1
ss -lntp | grep :你的面板端口

处理有两条路：把占用端口的程序停掉或改端口；或者把面板改到别的端口。官方脚本里改端口用的命令是：

1
/usr/local/x-ui/x-ui setting -port 新端口

改完重启面板，并在系统防火墙和服务商安全组里放行新端口。端口和访问路径怎么查，用 x-ui settings。另外，3x-ui 还支持用环境变量 XUI_PORT 覆盖面板端口，服务文件会读取一个环境变量文件（Debian/Ubuntu 一类是 /etc/default/x-ui，RHEL 系是 /etc/sysconfig/x-ui，Arch 系是 /etc/conf.d/x-ui）；如果你或者某个脚本在里面设过，面板实际使用的端口会以它为准，排查端口时要一起看。

类型 2：Error initializing database（数据库问题）

主程序启动时会先初始化数据库，失败就以 Error initializing database: ... 退出。默认数据库是 SQLite，路径是 /etc/x-ui/x-ui.db（可以被环境变量 XUI_DB_FOLDER 改掉）。

我只能从源码确认"初始化失败会让程序退出"，具体什么情况会触发，没有逐一复现，下面是常见的几种可能，属于我的推断：

  • 数据库文件损坏、权限不对，或者磁盘满了写不进去；
  • 升级跨版本后迁移出错，源码里 initModels 启动时会自动迁移数据表结构，迁移出错会打印 Error auto migrating model；
  • 新版本支持 PostgreSQL，环境变量文件里如果写了 XUI_DB_TYPE=postgres 和连接串 XUI_DB_DSN，数据库连不上同样会失败。

处理方法：先看日志里具体错误文字。已经有备份的话，按面板备份和迁移的方法把 x-ui.db 还原；刚升级完出的问题，看升级和降级。动数据库文件之前先复制一份备份。

类型 3：Error loading certificates（证书出错，但面板不会停）

这一条是反直觉的：我在源码里看到，配置了证书文件路径，但证书加载失败时，面板只记一条 Error loading certificates: 日志，然后改用 HTTP 继续运行，不会退出。

所以证书路径写错、证书过期被删、权限读不了，典型表现是：服务在运行，x-ui status 正常，但用 https 访问打不开，改成 http 却能进。这种情况去查证书文件路径对不对、文件在不在，配置方法见3x-ui配置TLS证书。

类型 4：日志里没有明显 Error，但服务反复重启

先看服务文件里的重启设置。3x-ui 的 systemd 服务文件（Debian 系）里有几行：

  • Restart=on-failure，RestartSec=5s：失败后每 5 秒重试一次；
  • StartLimitIntervalSec=180，StartLimitBurst=10：180 秒内最多尝试启动 10 次。

超过这个次数之后，按 systemd 的通用行为，服务会被暂停自动重启，systemctl status x-ui 里会看到 start-limit 相关的提示。这是 systemd 的通用机制，我没有在失败机器上看到过这条输出。处理方法是先解决根本原因，再清掉失败计数：

1
2
systemctl reset-failed x-ui
systemctl start x-ui

不清计数就直接 start，可能还是被拒绝。

排查顺序

  1. x-ui status，隔几秒再看一次，确认是真没运行。
  2. journalctl -u x-ui -n 50 --no-pager，找最近的 Error 行。
  3. 对照上面三类：starting web server（端口）、initializing database（数据库）、loading certificates（证书，面板其实在跑）。
  4. 修好之后，如果服务被 systemd 暂停了，先 systemctl reset-failed x-ui 再启动。
  5. 运行成功后，用 x-ui settings 查看端口和访问路径，再在浏览器访问；访问还是失败，回到面板打不开的排查。

几件不要做的事

  • 不要一上来就卸载重装：卸载会连 xray 一起删除，数据库不手动清理会保留，见卸载方法，但没看日志就重装，原因没找到，很可能再来一次。
  • 改数据库前先备份：误改会让问题变得更复杂。
  • 忘记账号密码不属于启动失败：那是另一个问题，见忘记密码怎么办。

没有覆盖的

  • Docker 部署的启动失败：容器里看日志的方法是另一套，我没有核对，不写。
  • xray 内核本身启动失败（面板能开，但节点不通）：我没有在源码里逐项核对，不写。
  • 原版 x-ui（vaxilu）和 3x-ui 以外的分叉版：没有核对。
  • 各种报错的真实现场输出：本篇的报错文字来自源码，不是从失败机器上截取的，实际输出以你机器上的为准。

配置文件和数据库的位置见x-ui和3x-ui的配置文件在哪。