跳到主要内容

常见错误

下面是遇到最多的问题。格式统一： 现象 → 原因 → 解决。先从日志入手 —— 几乎总能从中 看到原因：

docker compose logs --tail=100 xpanel
docker compose ps
提示

完整的诊断命令集见 实用命令 一节。

快速速查表：看到什么 —— 该检查什么。

日志或界面中的现象可能原因
Reverse proxy and HTTPS are required来自代理的 X-Forwarded-* 请求头缺失
❌ METRICS_USER / ❌ METRICS_PASS未设置指标变量
节点无法连接NODE_PORT 被关闭或 SECRET_KEY 不完整
address already in use端口被其他进程占用
certbot 报错退出DNS、80 端口或他人的 server_name
xpanel-db 处于 unhealthy 状态.env、卷或 PostgreSQL 版本
来自 nginx 的 502 Bad Gateway面板没有监听 127.0.0.1:3000
登录不再可用APP_SECRET 被更改

“Reverse proxy and HTTPS are required”​

现象。 面板打不开，xpanel 日志中出现 Reverse proxy and HTTPS are required 一行。

原因。 请求到达面板时没有携带 X-Forwarded-For 和 X-Forwarded-Proto: https 请求头。面板代码中有 middleware，遇到这种情况会 断开连接。

解决。 确认面板前的 nginx 配置中有这两行：

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;

请通过 https:// 打开面板，而不是 http://。如果 TLS 在更早的地方 （CDN 或负载均衡器上）终止，不要把 X-Forwarded-Proto 替换为 http。 现成的配置见 反向代理 一节。

未设置 METRICS_USER 和 METRICS_PASS​

现象。 xpanel 容器不断重启，日志中出现 ❌ METRICS_USER 或 ❌ METRICS_PASS。

原因。 指标变量是必填项：没有它们面板无法启动。

解决。 将它们补充到 /opt/xlada/.env 并重启整个栈：

METRICS_USER=xpanel
METRICS_PASS=<强密码>
docker compose up -d

节点不出现在面板中​

现象。 节点已创建，但在面板中仍显示为未连接。

原因。 通常是三者之一：从面板服务器无法访问 NODE_PORT、 SECRET_KEY 没有完整复制，或者节点容器没有启动。

解决。 按顺序检查：

  1. docker logs -f xpanel-node —— 密钥错误时节点会自己打印原因。
  2. 从面板服务器执行：nc -vz <节点 ip> 2222。
  3. 确认密钥完整粘贴，没有换行。
  4. 在防火墙中仅对面板的 IP 开放端口 2222。

详情见 安装节点 一节。

说明

每个节点都有自己的 SECRET_KEY 和自己的证书。不支持多个 服务器共用同一个密钥 —— 不能把它从一个节点迁移到另一个节点。

端口冲突​

现象。 容器以 address already in use 启动失败，或者节点上的 Xray 没有监听指定端口。

原因。 端口被其他进程占用：面板服务器上的 3000、3001、3010， 或者节点上的 inbound 端口。

解决。 找到占用端口的进程并释放它：

ss -tlnp | grep -E ':(3000|3001|3010|2222)\b'

如果改端口比释放端口更简单，就修改 .env 中的 APP_PORT 或 METRICS_PORT，并且别忘了更新 nginx 中的 proxy_pass。在节点上 请确认容器以 --network host 启动：端口映射会破坏 客户端真实 IP 的识别。

证书无法签发​

现象。 certbot --nginx -d panel.example.com 报错退出。

原因。 域名没有指向这台服务器、80 端口被关闭，或者该域名 已被其他虚拟主机占用。

解决。

dig +short panel.example.com   # 应返回面板服务器的 IP
ss -tlnp | grep ':80'
certbot certificates           # 已经签发了什么
certbot renew --dry-run        # 检查自动续期

核对 nginx 配置中的 server_name，然后执行 nginx -t && systemctl reload nginx。 确认自动续期定时器已启用：systemctl list-timers | grep certbot。

数据库无法启动​

现象。 xpanel 等待数据库并崩溃，xpanel-db 处于 unhealthy 状态或不断重启。

原因。 最常见的是 DATABASE_URL 错误、POSTGRES_PASSWORD 与已存在的卷不一致，或者旧数据目录上的 PostgreSQL 主版本不兼容。

解决。

docker compose ps
docker compose logs --tail=100 xpanel-db
docker exec xpanel-db pg_isready -U xpanel -d xpanel

核对 POSTGRES_USER、POSTGRES_PASSWORD、POSTGRES_DB 和 DATABASE_URL。 不要重命名卷和服务：下次启动时 compose 会创建新的 空卷。PostgreSQL 数据目录在主版本之间不兼容，因此 升级到新版本只能通过转储和恢复来进行 —— 参见 从 Remnawave 迁移。

来自 nginx 的 502 Bad Gateway​

现象。 nginx 在 https://panel.example.com 上返回 502。

原因。 proxy_pass 后面什么都没有：面板容器没有启动、没有完成 迁移，或者监听了其他端口。

解决。

docker compose ps
curl -sI http://127.0.0.1:3000
docker compose logs --tail=100 xpanel

等待日志中出现 XLADA Backend v1.1.7 和 Nest application successfully started 两行。如果改过 APP_PORT，请修正 proxy_pass http://127.0.0.1:<端口> 并重新加载 nginx。

更改 APP_SECRET 后登录失效​

现象。 管理员密码不再匹配，TOTP 验证码不被 接受，活动会话被重置。

原因。 首次启动后更改了 APP_SECRET。密码哈希、JWT 和 TOTP 密钥加密都依赖它。在 .env 中留下 change_me 这个值 也会产生同样的效果。

解决。 从 .env 的备份中恢复原来的 APP_SECRET 值，并 执行 docker compose up -d。如果原值已丢失，只能通过数据库 重置来登录。密钥应提前生成（openssl rand -hex 32）并保存在 密钥管理器中 —— 参见 面板安全。

接下来​