mirror of
https://github.com/MHSanaei/3x-ui.git
synced 2026-07-16 09:36:07 +00:00
MHSanaei
9b91f0f42e
Fold the standalone 3x-ui-docs project (Next.js 16 + Fumadocs, deployed to docs.sanaei.dev) into docs/ so the panel and its documentation share a single source of truth, the way sing-box keeps its docs in-tree. The old repo becomes redundant and can be retired. - Import the full site under docs/ (app, components, content, lib, public, scripts, config). The self-contained pnpm project sits alongside the existing engineering notes with no filename collisions. - Re-point "Edit on GitHub" links from MHSanaei/3x-ui-docs to this repo's docs/content/docs path (docs/lib/shared.ts, docs/app/.../page.tsx). - Add docs-ci.yml and docs-deploy.yml under .github/workflows/, scoped to docs/** and run with working-directory: docs, since GitHub only runs workflows from the repo-root .github/. deploy-static.yml's GitHub Pages publish (CNAME docs.sanaei.dev) carries over unchanged. Follow-up (outside this commit): attach the docs.sanaei.dev custom domain to this repository's Pages (or set the Vercel project's root directory to docs), confirm the site is live from the monorepo, then delete MHSanaei/3x-ui-docs.
43 lines
1.7 KiB
Plaintext
43 lines
1.7 KiB
Plaintext
---
|
||
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>
|