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: Troubleshooting
|
|
description: Fix common 3x-ui problems — the panel won't start, 502 errors, certificate issues, and clients that can't connect.
|
|
icon: Wrench
|
|
---
|
|
|
|
A checklist for the most common issues. When in doubt, raise the log level
|
|
(`XUI_LOG_LEVEL=debug`) and check the panel and Xray logs.
|
|
|
|
## The panel won't start
|
|
|
|
- Check the service status and logs (`x-ui` menu → status/logs).
|
|
- Make sure the **panel port isn't already in use** by another service.
|
|
- Verify the database path is writable (default `/etc/x-ui/x-ui.db`).
|
|
|
|
## 502 / panel unreachable behind a proxy
|
|
|
|
- Confirm the panel is actually listening on the upstream port (e.g. `2053`).
|
|
- Ensure your [reverse proxy](/docs/operations/reverse-proxy) passes WebSocket
|
|
upgrade headers and points at the correct port and **web base path**.
|
|
- Check the firewall isn't blocking the proxy → panel connection.
|
|
|
|
## Certificate problems
|
|
|
|
- The domain's DNS must point at the server before issuing a certificate.
|
|
- Ports 80/443 must be reachable for HTTP/TLS validation (or use DNS validation).
|
|
- For REALITY, remember it needs **no certificate** — the issue is usually a bad
|
|
`dest`/SNI instead (see [REALITY pitfalls](/docs/config/reality)).
|
|
|
|
## A client can't connect
|
|
|
|
- Decode the client's link with the
|
|
[share-link inspector](/docs/config/share-links) and confirm every parameter.
|
|
- Check the **transport and security match** on both ends.
|
|
- Make sure the client hasn't hit its **traffic, expiry, or IP limit**.
|
|
- Confirm the inbound port is open in the firewall.
|
|
|
|
<Callout type="info">
|
|
Still stuck? Search the
|
|
[GitHub issues](https://github.com/MHSanaei/3x-ui/issues) — your symptom has
|
|
probably been seen before.
|
|
</Callout>
|