pjandro/3x-ui
1
0
Fork 0
mirror of https://github.com/MHSanaei/3x-ui.git synced 2026-10-05 05:32:07 +03:00
Code Issues Packages Projects Releases Wiki Activity

docs: vendor the documentation site into the monorepo

Browse Source 
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
2026-07-07 23:07:14 +02:00
parent 2c49dbf54e
commit 9b91f0f42e
283 changed files with 44179 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/content/docs/en/guide/first-login.mdx
+124
View File
@@ -0,0 +1,124 @@
---
title: First Login
description: Find your generated 3x-ui credentials, reach the panel, enable two-factor auth, and harden it before exposing anything.
icon: KeyRound
---
After installation, your first job is to log in and **secure the panel** before
exposing anything else.
## Reach the panel
The panel is served at:
```text
http://<your-server-ip>:<port>/<web-base-path>
```
The default port is **2053** and the default base path is `/` — but a script
install **randomly generates** the username, password, **port**, and web base
path, so check your actual values.
### Find your credentials
A script install prints a credential summary when it finishes and also writes it
to a root-only file:
```bash title="/etc/x-ui/install-result.env (mode 600)"
XUI_USERNAME=...
XUI_PASSWORD=...
XUI_PANEL_PORT=...
XUI_WEB_BASE_PATH=...
XUI_ACCESS_URL=...
XUI_API_TOKEN=...
XUI_DB_TYPE=sqlite
```
If you missed them, use the management tools:
```bash
x-ui # menu → 11 (View Current Settings)
x-ui settings # or the one-shot form
```
For **Docker**, read the generated credentials from the container logs, or run
`docker exec -it <container> x-ui setting -show`.
<Callout type="warn">
If your panel still uses the default `admin` / `admin` (the panel warns when it
does), change it immediately — before creating any inbounds.
</Callout>
## Change credentials, port, and path
A non-default port and a long, random **web base path** make the panel much
harder to find. Change them from **Panel Settings** in the UI, or from the
`x-ui` menu:
- **7 — Reset Username & Password** (optionally disabling 2FA at the same time)
- **8 — Reset Web Base Path** (randomizes it)
- **10 — Change Port**
Changing your username or password **logs out all existing sessions** and, if
two-factor auth was on, disables it.
## Two-factor authentication (2FA)
3x-ui supports TOTP two-factor auth (compatible with Google Authenticator, Aegis,
etc.). Enable it in **Panel Settings** — once enabled, the login page asks for a
6-digit code in addition to your password, and turning it on forces everyone to
log in again. You can disable it from the menu's **Reset Username & Password**
step or with `x-ui setting -resetTwoFactor`.
## Built-in login protection
- **Brute-force limiter:** after **5** failed logins from the same IP/username
within 5 minutes, that combination is blocked for **15 minutes**.
- **Generic errors:** the login page reports "wrong username or password" for
both bad credentials and bad 2FA codes, so it leaks nothing.
- **Sessions** last `sessionMaxAge` minutes (default **360** = 6 hours) and are
invalidated when you change credentials.
- **LDAP** can be enabled as an auth fallback in Panel Settings.
## Essential hardening checklist
<Steps>
<Step>
### Set strong, unique credentials
Replace the generated (or `admin/admin`) username and password with strong values.
</Step>
<Step>
### Use a non-default port and random base path
Move the panel off `2053` and serve it under a long random path.
</Step>
<Step>
### Enable two-factor authentication
Turn on 2FA so a leaked password alone can't grant access.
</Step>
<Step>
### Put the panel behind TLS
Use a valid certificate (via the `x-ui` menu's SSL management, or a reverse
proxy) so the panel is only reachable over HTTPS.
</Step>
<Step>
### Restrict access with a firewall
Open only the ports you actually need, and consider limiting panel access by IP.
</Step>
</Steps>
<Callout type="info">
Want the panel on a clean domain with automatic HTTPS? See
[Reverse proxy](/docs/operations/reverse-proxy). For deeper hardening, see
[Security](/docs/operations/security).
</Callout>
docs/content/docs/en/guide/index.mdx
+71
View File
@@ -0,0 +1,71 @@
---
title: Meet 3x-ui
description: A web panel for Xray-core — manage inbounds, protocols, clients, and subscriptions from your browser instead of editing JSON by hand.
icon: Info
---
**3x-ui** is a web control panel that sits on top of
[Xray-core](https://github.com/XTLS/Xray-core), the proxy engine that actually
moves your traffic. Instead of writing and reloading Xray's JSON configuration
by hand, you manage everything — inbounds, protocols, clients, certificates,
subscriptions — from a browser dashboard.
## How the pieces fit together
<Mermaid
chart={`
flowchart LR
Admin["Admin browser"] -->|HTTPS panel| Panel["3x-ui panel"]
Panel -->|writes config, reloads| Xray["Xray-core"]
Panel --- DB[("SQLite or PostgreSQL")]
Clients["Client apps"] -->|VLESS / VMess / Trojan / ...| Xray
Xray -->|proxied traffic| Internet["Internet"]
`}
/>
- **The panel** is the management layer: it stores your configuration in a
database, renders the dashboard, exposes a REST API, and writes the live Xray
configuration.
- **Xray-core** is the data plane: it terminates client connections on your
**inbounds** and forwards traffic to its destination.
- **Client apps** (such as v2rayNG, Clash/Mihomo, Hiddify, and others) connect
using a share link or a subscription that the panel generates for each client.
## What it gives you
- A dashboard for **inbounds** across every major protocol — VLESS, VMess,
Trojan, Shadowsocks, WireGuard, Hysteria2, SOCKS, HTTP, and Dokodemo-door.
- First-class **REALITY** and **XTLS-Vision** support for stealthy, fast
transports.
- **Per-client** traffic quotas, expiry dates, IP limits, online status, and
one-click share links / QR codes.
- **Subscriptions** in VLESS, Clash/Mihomo, and JSON formats.
- Operational tooling: **multi-node** management, a **Telegram bot**, backups,
Fail2ban-based IP limiting, and a documented REST API.
## Under the hood
| Layer | Technology |
| ------------ | -------------------------------------------- |
| Backend | Go with the Gin web framework |
| Frontend | TypeScript / React |
| Database | SQLite (default) or PostgreSQL |
| Proxy engine | Xray-core (bundled and managed by the panel) |
The default SQLite database lives at `/etc/x-ui/x-ui.db`, and the panel listens
on port **2053** by default. Both are configurable — see
[First login](/docs/guide/first-login) and the environment variable reference.
## Who it's for
3x-ui is aimed at anyone running their own Xray server: from a single personal
VPS to operators managing many nodes and clients. If you want the power of
Xray-core without living in JSON config files, this is for you.
<Callout type="info">
3x-ui is an enhanced fork of the original X-UI project, adding broader protocol
support, improved stability, per-client traffic accounting, multi-node
management, and many quality-of-life features.
</Callout>
Ready to install? Continue to [Installation](/docs/guide/installation).
docs/content/docs/en/guide/installation.mdx
+148
View File
@@ -0,0 +1,148 @@
---
title: Installation
description: Install 3x-ui via the official script (stable, pinned, or dev-latest), unattended/cloud-init, or Docker — and choose SQLite or PostgreSQL.
icon: Download
---
3x-ui runs on a wide range of Linux distributions — Ubuntu, Debian, Armbian,
Fedora, CentOS, RHEL, AlmaLinux, Rocky Linux, Oracle Linux, Amazon Linux,
Virtuozzo, Arch, Manjaro, openSUSE (Tumbleweed/Leap), Alpine — and Windows,
across `amd64`, `386`, `arm64`, `armv7`, `armv6`, `armv5`, and `s390x`.
<Callout type="warn">
Run the script installer as **root** (or with `sudo`). It installs a service,
sets up the `x-ui` management command, and enables the panel on boot.
</Callout>
<Tabs items={['Script', 'Docker', 'Manual']}>
<Tab value="Script">
The official script is the recommended path. During installation it generates a
**random** username, password, and access (web base) path, sets up the service,
and installs the `x-ui` management command.
```bash title="latest stable"
bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)
```
Install a **specific version** by appending its tag:
```bash title="pinned version"
bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh) v3.4.0
```
Install the rolling **dev** build (the latest per-commit pre-release from `main`
— not a stable release) by passing `dev-latest`:
```bash title="rolling dev build"
bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh) dev-latest
```
When it finishes, note the printed login details and run `x-ui` to open the
[management menu](/docs/guide/update-uninstall#the-x-ui-management-menu), then
continue to [First login](/docs/guide/first-login).
</Tab>
<Tab value="Docker">
The default Compose setup uses SQLite. Clone the repo (or copy its
`docker-compose.yml` and `Dockerfile`) and start it:
```bash
docker compose up -d
```
To run with the bundled **PostgreSQL** service, uncomment the two `XUI_DB_*`
lines in `docker-compose.yml` and start with the profile:
```bash
docker compose --profile postgres up -d
```
Prefer the prebuilt image? It's published to the GitHub Container Registry. The
image bundles Fail2ban (for [IP limits](/docs/operations/security)), which bans
with `iptables` and therefore needs `NET_ADMIN` (and `NET_RAW` for IPv6) —
otherwise bans are logged but never applied:
```bash title="docker run"
docker run -d \
--cap-add=NET_ADMIN \
--cap-add=NET_RAW \
-e XUI_ENABLE_FAIL2BAN=true \
-v $PWD/db/:/etc/x-ui/ \
-v $PWD/cert/:/root/cert/ \
--network=host \
--restart=unless-stopped \
--name 3x-ui \
ghcr.io/mhsanaei/3x-ui:latest
```
The `db/` volume holds the SQLite database (`/etc/x-ui/x-ui.db`) and `cert/`
holds TLS certificates, so your data survives upgrades.
</Tab>
<Tab value="Manual">
For advanced users, download a release archive for your architecture from the
[releases page](https://github.com/MHSanaei/3x-ui/releases), extract it, and run
the binary as a systemd service. The install script automates exactly these
steps, so it's preferred unless you have a specific reason to install by hand.
</Tab>
</Tabs>
## Build your install command
Tailor the command to your setup:
<InstallCommandBuilder />
## Choose a database
You pick the storage backend at install time:
- **SQLite** (default) — a single file at `/etc/x-ui/x-ui.db`. Zero setup.
- **PostgreSQL** — for high client counts or multi-node setups. The installer
can install it locally or use a DSN you provide.
See [Database](/docs/reference/database) for details and SQLite→PostgreSQL
migration.
## Unattended / cloud-init
The installer also runs **non-interactively** for automation. Set
`XUI_NONINTERACTIVE=1` (or run with no TTY) and it installs end-to-end with zero
prompts, generating random credentials and writing them to
`/etc/x-ui/install-result.env`:
```bash
XUI_NONINTERACTIVE=1 bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)
```
The repo's [`deploy/`](https://github.com/MHSanaei/3x-ui/tree/main/deploy)
directory has ready-made **cloud-init** user-data for unattended installs on any
cloud (Hetzner, AWS, DigitalOcean, Vultr, GCP, Azure, Oracle).
## Next steps
<Cards>
<Card
title="First login"
href="/docs/guide/first-login"
description="Reach the panel and secure it."
/>
<Card
title="Update & uninstall"
href="/docs/guide/update-uninstall"
description="The x-ui menu, updates, and removal."
/>
<Card
title="REALITY"
href="/docs/config/reality"
description="Configure your first stealthy inbound."
/>
</Cards>
docs/content/docs/en/guide/meta.json
+5
View File
@@ -0,0 +1,5 @@
{
"title": "Getting Started",
"icon": "Rocket",
"pages": ["index", "installation", "first-login", "update-uninstall"]
}
docs/content/docs/en/guide/update-uninstall.mdx
+99
View File
@@ -0,0 +1,99 @@
---
title: Update & Uninstall
description: Manage 3x-ui with the x-ui menu and CLI — update (stable, dev, or legacy), change settings, and uninstall cleanly.
icon: RefreshCw
---
After a script install, the `x-ui` command is your control center. Run it with
no arguments for the interactive menu, or pass a subcommand for a one-shot action.
```bash
x-ui
```
## The `x-ui` management menu
The menu (items `0`–`28`) shows the panel/Xray status at the top, then:
| # | Item | What it does |
| ----- | -------------------------------------- | --------------------------------------------------------- |
| 1 | Install | (Re)install from the remote script |
| 2 | Update | Update to the latest **stable** release |
| 3 | Update to Dev Channel (latest commit) | Update to the rolling `dev-latest` build |
| 4 | Update Menu | Update just the `x-ui` menu script |
| 5 | Legacy Version | Install a specific older version (prompts for a tag) |
| 6 | Uninstall | Remove 3x-ui (see below) |
| 7 | Reset Username & Password | Set new credentials; optionally disable 2FA |
| 8 | Reset Web Base Path | Randomize the web base path |
| 9 | Reset Settings | Reset panel settings (your account is preserved) |
| 10 | Change Port | Change the panel port |
| 11 | View Current Settings | Show username, port, web base path, cert paths |
| 12–14 | Start / Stop / Restart | Control the panel service |
| 15 | Restart Xray | Reload only Xray-core |
| 16 | Check Status | Service status |
| 17 | Logs Management | View debug logs / clear logs |
| 18–19 | Enable / Disable Autostart | Toggle start-on-boot |
| 20 | SSL Certificate Management | Let's Encrypt (domain or IP), custom paths, renew/revoke |
| 21 | Cloudflare SSL Certificate | DNS-01 wildcard cert via Cloudflare |
| 22 | IP Limit Management | Fail2ban-based per-client IP limits |
| 23 | Firewall Management | `ufw` install and port rules |
| 24 | SSH Port Forwarding Management | Bind the panel to localhost and tunnel over SSH |
| 25 | PostgreSQL Management | Install/migrate/manage PostgreSQL |
| 26 | Enable BBR | Toggle the BBR congestion-control sysctl |
| 27 | Update Geo Files | Update geoip/geosite data (Loyalsoldier, IR, RU) |
| 28 | Speedtest by Ookla | Run an Ookla speed test |
| 0 | Exit | — |
Some of these have their own pages: [SSL certificates](/docs/config/ssl-certificates)
(items 20–21), [Security](/docs/operations/security) (IP limits, firewall),
[Reverse proxy](/docs/operations/reverse-proxy) and [Panel settings](/docs/config/panel)
(TLS), and [Database](/docs/reference/database) (PostgreSQL).
## CLI subcommands
For scripts and quick actions, `x-ui` also takes a subcommand directly:
| Command | Action |
| -------------------------- | --------------------------------------------------- |
| `x-ui start` / `stop` / `restart` | Control the service |
| `x-ui restart-xray` | Reload only Xray-core |
| `x-ui status` | Show status |
| `x-ui settings` | Show current settings |
| `x-ui enable` / `disable` | Toggle autostart on boot |
| `x-ui log` | Tail the debug log |
| `x-ui banlog` | Show Fail2ban ban log |
| `x-ui update` | Update to the latest stable release |
| `x-ui update-dev` | Update to the rolling `dev-latest` build |
| `x-ui legacy` | Install a specific older version (prompts) |
| `x-ui update-all-geofiles` | Update all geo files, restart if changed |
| `x-ui migrate-db --dsn …` | Migrate SQLite → PostgreSQL (see [Database](/docs/reference/database)) |
| `x-ui install` / `uninstall` | Install / uninstall |
## Updating
- **Stable:** menu option **2** or `x-ui update`. Re-running the install script
also updates in place.
- **Dev channel:** menu option **3** or `x-ui update-dev` — the rolling
`dev-latest` per-commit build (not a stable release).
- **A specific older version:** menu option **5** (Legacy Version).
Updating preserves your database and settings. Take a
[backup](/docs/operations/backup-restore) before a major-version jump.
<Callout type="info">
Docker users update differently — pull the new image and recreate the
container (`docker compose pull && docker compose up -d`) rather than using the
`x-ui` update commands.
</Callout>
## Uninstalling
Menu option **6** or `x-ui uninstall`. It stops and disables the service, removes
the service unit, and deletes `/etc/x-ui/` and the install folder. If the panel
used a locally-installed PostgreSQL, it offers to purge that too (a separate,
irreversible confirmation).
<Callout type="warn">
Uninstalling removes the database (`/etc/x-ui/x-ui.db`) and your configuration.
[Back up](/docs/operations/backup-restore) first if you might need it.
</Callout>