mirror of
https://github.com/MHSanaei/3x-ui.git
synced 2026-07-16 09:36:07 +00:00
docs: vendor the documentation site into the monorepo
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.
This commit is contained in:
MHSanaei
@@ -0,0 +1,64 @@
|
||||
---
|
||||
title: Contributing
|
||||
description: How to contribute to 3x-ui and to translate this documentation.
|
||||
icon: GitPullRequestArrow
|
||||
---
|
||||
|
||||
3x-ui is community-driven. Contributions to the panel and to these docs are
|
||||
welcome.
|
||||
|
||||
## Support the developer
|
||||
|
||||
3x-ui is free and open source, built and maintained in the open. If it's useful
|
||||
to you, consider supporting continued development:
|
||||
|
||||
- **Donate** at [donate.sanaei.dev](https://donate.sanaei.dev/) — the page shows
|
||||
current funding **goals and targets** you can help reach.
|
||||
- **Star** the [repository](https://github.com/MHSanaei/3x-ui) and share the
|
||||
project.
|
||||
- **Join** the Telegram channel [@XrayUI](https://t.me/XrayUI) to follow news and
|
||||
help others.
|
||||
|
||||
## Contribute to 3x-ui
|
||||
|
||||
- Read the project's `CONTRIBUTING.md` in the
|
||||
[repository](https://github.com/MHSanaei/3x-ui).
|
||||
- Open issues for bugs and feature requests with clear reproduction steps.
|
||||
- Use Conventional Commits and keep pull requests focused.
|
||||
|
||||
## Translate the documentation
|
||||
|
||||
This site is built for translation. Content lives under `content/docs/<locale>/`
|
||||
(`en`, `fa`, `ru`, `zh`), and untranslated pages **fall back to English**, so you
|
||||
can translate incrementally.
|
||||
|
||||
<Steps>
|
||||
|
||||
<Step>
|
||||
### Copy a page
|
||||
|
||||
Copy a page from `content/docs/en/...` to the same path under your locale, e.g.
|
||||
`content/docs/fa/guide/installation.mdx`.
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### Translate the prose only
|
||||
|
||||
Translate the body and the frontmatter `title`/`description`. **Do not** translate
|
||||
code, commands, environment variable names, protocol names, or share links.
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### Mind direction
|
||||
|
||||
Persian (`fa`) renders right-to-left. Keep code blocks and links left-to-right
|
||||
(the layout already handles this), and check the page in both directions.
|
||||
</Step>
|
||||
|
||||
</Steps>
|
||||
|
||||
<Callout type="info">
|
||||
Missing a page in your locale is fine — it falls back to English rather than
|
||||
404ing. Translate the highest-traffic pages first (installation, first login,
|
||||
REALITY).
|
||||
</Callout>
|
||||
@@ -0,0 +1,47 @@
|
||||
---
|
||||
title: FAQ
|
||||
description: Frequently asked questions about 3x-ui — licensing, supported systems, databases, and clients.
|
||||
icon: CircleQuestionMark
|
||||
---
|
||||
|
||||
## Is 3x-ui free and open source?
|
||||
|
||||
Yes. 3x-ui is open source under the GPL-3.0 license. The source is on
|
||||
[GitHub](https://github.com/MHSanaei/3x-ui).
|
||||
|
||||
## What systems does it run on?
|
||||
|
||||
Most major Linux distributions (Ubuntu, Debian, CentOS/RHEL and derivatives,
|
||||
Fedora, Arch, Alpine, and more) across `amd64`, `arm64`, and other architectures.
|
||||
It also runs as a Docker container. See [Installation](/docs/guide/installation).
|
||||
|
||||
## SQLite or PostgreSQL?
|
||||
|
||||
SQLite is the default and is fine for most deployments. PostgreSQL is available
|
||||
for larger setups via `XUI_DB_TYPE=postgres` and `XUI_DB_DSN` — see the
|
||||
[environment variables](/docs/reference/env-vars).
|
||||
|
||||
## Which client apps work with it?
|
||||
|
||||
Any Xray-compatible client — for example v2rayNG, Hiddify, and Clash/Mihomo.
|
||||
Import a client's share link or QR code, or use a
|
||||
[subscription](/docs/config/subscription).
|
||||
|
||||
## How is 3x-ui different from x-ui?
|
||||
|
||||
3x-ui is an enhanced fork of the original X-UI project. It adds broader protocol
|
||||
support, improved stability, per-client traffic accounting, multi-node
|
||||
management, a 13-language UI, and many quality-of-life features.
|
||||
|
||||
## How do I update?
|
||||
|
||||
Re-run the install script (it updates in place), or pull the new Docker image.
|
||||
See [Installation](/docs/guide/installation) and the
|
||||
[releases page](https://github.com/MHSanaei/3x-ui/releases).
|
||||
|
||||
## Where can I get help?
|
||||
|
||||
Join the official Telegram channel [@XrayUI](https://t.me/XrayUI) for
|
||||
announcements and community support, or open an issue on
|
||||
[GitHub](https://github.com/MHSanaei/3x-ui/issues). For common problems, start
|
||||
with [Troubleshooting](/docs/help/troubleshooting).
|
||||
@@ -0,0 +1,5 @@
|
||||
{
|
||||
"title": "Help",
|
||||
"icon": "LifeBuoy",
|
||||
"pages": ["troubleshooting", "faq", "migration", "contributing"]
|
||||
}
|
||||
@@ -0,0 +1,52 @@
|
||||
---
|
||||
title: Migration
|
||||
description: Migrate to 3x-ui from x-ui, between servers, or between 3x-ui versions.
|
||||
icon: ArrowRightLeft
|
||||
---
|
||||
|
||||
## Between servers
|
||||
|
||||
Moving to a new server is a database move:
|
||||
|
||||
<Steps>
|
||||
|
||||
<Step>
|
||||
### Back up the old server
|
||||
|
||||
Copy the database (default `/etc/x-ui/x-ui.db`) and your certificates. See
|
||||
[Backup & restore](/docs/operations/backup-restore).
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### Install 3x-ui on the new server
|
||||
|
||||
Use the same install method and a compatible version. See
|
||||
[Installation](/docs/guide/installation).
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### Restore the database
|
||||
|
||||
Stop the panel, put the database in place, restore certificates, and start the
|
||||
panel. Update any IP/domain-specific settings.
|
||||
</Step>
|
||||
|
||||
</Steps>
|
||||
|
||||
## Between 3x-ui versions
|
||||
|
||||
Within the same backend, upgrading is usually just re-running the installer or
|
||||
pulling a new image — the panel migrates its own database. Across **major**
|
||||
versions, read the [release notes](https://github.com/MHSanaei/3x-ui/releases)
|
||||
first and take a backup.
|
||||
|
||||
## From x-ui
|
||||
|
||||
Importing an older x-ui panel's database directly into 3x-ui is **not
|
||||
supported** — the schemas differ. Install 3x-ui fresh and recreate
|
||||
inbounds/clients, exporting share links from the old panel as you go.
|
||||
|
||||
<Callout type="warn">
|
||||
Always take a backup before any migration, and keep the old server running
|
||||
until you've verified the new one.
|
||||
</Callout>
|
||||
@@ -0,0 +1,42 @@
|
||||
---
|
||||
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>
|
||||
Reference in New Issue
Block a user