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
2026-07-07 23:07:14 +02:00
parent 2c49dbf54e
commit 9b91f0f42e
283 changed files with 44179 additions and 0 deletions
@@ -0,0 +1,57 @@
---
title: Backup & Restore
description: Back up and restore your 3x-ui database and certificates, manually or via the Telegram bot.
icon: DatabaseBackup
---
Your entire configuration — inbounds, clients, settings — lives in the panel's
database. Back it up regularly so you can recover or migrate.
## What to back up
- **The database** — SQLite at `/etc/x-ui/x-ui.db` by default (or your
PostgreSQL database if you use that backend).
- **Certificates** — anything under `/root/cert/` (or wherever you store TLS
certs).
## Manual backup
You can download a backup from the panel's overview, or copy the database file
directly from the server:
```bash title="copy the SQLite database"
cp /etc/x-ui/x-ui.db /root/x-ui-backup-$(date +%F).db
```
To restore, stop the panel, put the database back in place, and start it again.
<Callout type="warn">
Restore a backup onto the **same major version** it came from when possible.
Across major upgrades, let the panel run its migrations rather than forcing an
old schema.
</Callout>
## Telegram backup
If you've configured the [Telegram bot](/docs/operations/telegram-bot), enable
**`tgBotBackup`** to attach a backup to the periodic report (on the `tgRunTime`
schedule, default daily). The bot sends both the **database** and the **Xray
`config.json`** to your admin chat, so you always have an off-server copy. Admins
can also request a backup on demand from the bot's menu.
## SQLite dump / restore
The `x-ui migrate-db` command converts the SQLite database to and from a plain
SQL text dump (handy for inspection or transferring between machines):
```bash
x-ui migrate-db --dump /root/x-ui.sql # SQLite -> SQL text
x-ui migrate-db --restore /root/x-ui.sql # SQL text -> SQLite
```
To move to PostgreSQL instead, see [Database](/docs/reference/database).
<Callout type="info">
Whatever method you use, store backups **off the server** and test a restore
occasionally — an untested backup isn't a backup.
</Callout>
+12
View File
@@ -0,0 +1,12 @@
{
"title": "Operations",
"icon": "ServerCog",
"pages": [
"reverse-proxy",
"multi-node",
"outbounds-routing",
"backup-restore",
"telegram-bot",
"security"
]
}
@@ -0,0 +1,97 @@
---
title: Multi-node & Managed Hosts
description: Manage multiple 3x-ui panels from one master, with API-token or mTLS trust, heartbeats, and per-inbound host overrides for subscriptions.
icon: Boxes
---
3x-ui can manage **multiple servers** from a single master panel, and override
how each inbound is advertised in subscriptions with **managed hosts**.
## Nodes
A **node** is another 3x-ui panel that your master panel manages over the node's
API. The master polls each node and shows its status, versions, CPU/memory,
uptime, and traffic in one place.
### Add a node
Provide the node's connection details:
| Field | Notes |
| ----------------- | --------------------------------------------------------------------- |
| **Name** | Unique label (e.g. `de-fra-1`). |
| **Scheme** | `https` (default) or `http`. |
| **Address / Port**| The node panel's host and port. |
| **Base path** | The node's web base path. |
| **API token** | A Bearer token created on the node (not needed in mTLS mode). |
| **TLS verify** | `verify` (default), `skip`, `pin` (pin a cert SHA-256), or `mtls`. |
| **Inbound sync** | `all` inbounds, or `selected` by tag. |
| **Outbound tag** | Optionally reach the node **through** a named outbound (egress bridge).|
The master verifies reachability when you add or test a node. It then sends a
**heartbeat** every few seconds, updating the node's status (`online` / `offline`)
and emitting `node.up` / `node.down` events (see the
[Telegram bot](/docs/operations/telegram-bot)).
<Callout type="info">
Nodes are identified by a stable per-panel GUID, so a node keeps its identity
across restarts. A node can itself manage further nodes — the master surfaces
those as read-only **transitive** sub-nodes (Node 1 → Node 2 → Node 3).
</Callout>
### Mutual TLS (mTLS) between master and node
For the strongest trust, use `tlsVerifyMode = mtls` (requires `https`):
<Steps>
<Step>
### Get the master's CA
On the master, fetch its node-auth CA certificate (the CA private key never
leaves the panel).
</Step>
<Step>
### Trust it on the node
Paste that CA into the node's "trusted CA" setting. It takes effect on the node's
next restart.
</Step>
<Step>
### Switch the node to mTLS
Set the node's TLS verify mode to `mtls`. The master now presents a client
certificate instead of an API token.
</Step>
</Steps>
## Managed hosts
A **managed host** is an override endpoint attached to an inbound. At
subscription time, each enabled host renders an additional share link / proxy
with its own address, port, TLS, SNI, host header, path, and more — superseding
the older "external proxy" list. Use them to:
- front an inbound through a **CDN** (Cloudflare) with a different address/SNI,
- advertise **multiple domains** or per-region endpoints for one inbound,
- tweak ALPN, fingerprint, ECH, or mux per endpoint.
Each host has a remark (which supports the same
[template variables](/docs/config/share-links#remark-template-variables)), an
enable toggle, a sort order, and can be **excluded from specific subscription
formats** or **scoped to specific nodes**.
<Callout type="info">
Hosts whose address/port point at a CDN let you keep the real server address
private while clients connect through the CDN edge.
</Callout>
## Related
<Cards>
<Card title="Outbounds & routing" href="/docs/operations/outbounds-routing" description="WARP, NordVPN, outbound subscriptions, and routing." />
<Card title="Subscription" href="/docs/config/subscription" description="How hosts shape subscription output." />
</Cards>
@@ -0,0 +1,157 @@
---
title: Outbounds & Routing
description: Shape egress in 3x-ui — WARP and NordVPN outbounds, outbound subscriptions (server pools), routing rules, and load balancers.
icon: Route
---
Inbounds accept clients; **outbounds** decide where their traffic goes next.
3x-ui can route traffic through Cloudflare WARP, NordVPN, or arbitrary outbound
pools imported from a subscription, and select between them with routing rules
and balancers.
## Editing outbounds & routing
Outbounds, routing rules, balancers, DNS, and logging all live in the **Xray
configuration** (the config template you edit under Xray Settings). There's no
separate per-rule UI — you edit the JSON, and the panel reloads Xray. The panel
also offers an **outbound connectivity test** and a **route test** (ask the
running core which outbound a given destination would use).
## Build an outbound
Every outbound is a JSON object with up to four parts: a **`tag`** (referenced by
routing rules and balancers), a **`protocol`**, protocol-specific **`settings`**,
and — for proxy protocols — **`streamSettings`** that must match the remote
inbound's transport and security. Two outbounds are almost always present:
- **`freedom`** sends traffic straight to its destination — the default egress.
Optionally set a `domainStrategy` (e.g. `UseIP`) to control how hostnames resolve.
- **`blackhole`** drops traffic. Route unwanted destinations (ads, torrents) here.
```json title="freedom + blackhole"
{
"outbounds": [
{ "tag": "direct", "protocol": "freedom", "settings": {} },
{ "tag": "block", "protocol": "blackhole", "settings": {} }
]
}
```
A **proxy** outbound (VLESS, VMess, Trojan, Shadowsocks) forwards to another
server — handy for chaining or sending select traffic abroad. Mind the wire
shapes 3x-ui uses: **VLESS is the flat form** (`address`/`port`/`id`/`flow`/
`encryption`), **VMess uses `settings.vnext[]`**, and **Trojan/Shadowsocks use
`settings.servers[]`**. The `streamSettings` must mirror the destination's
[transport and security](/docs/config/transports).
Assemble any outbound below and paste the JSON into **Xray Settings → Outbounds**:
<OutboundGenerator />
## Cloudflare WARP
WARP lets your server egress through Cloudflare's network. 3x-ui can register a
WARP account for you and wire it into a WireGuard outbound tagged **`warp`**:
<Steps>
<Step>
### Add a `warp`-tagged outbound
Create a WireGuard outbound with the tag `warp` in your Xray config.
</Step>
<Step>
### Register WARP
From the panel's WARP controls, register an account. 3x-ui fills the outbound's
keys, addresses, reserved bytes, and peer endpoint automatically.
</Step>
<Step>
### (Optional) auto-rotate the IP
Set a WARP update interval (in **days**) to periodically rotate the WARP IP. A
free license can also be applied.
</Step>
</Steps>
Route the traffic you want (for example specific domains) to the `warp` outbound
with a routing rule.
## NordVPN
3x-ui can fetch NordVPN (NordLynx/WireGuard) credentials from an access token (or
accept a private key directly) and list countries/servers, so you can build a
NordVPN outbound.
## Outbound subscriptions (server pools)
An **outbound subscription** imports a remote share-link subscription and injects
its servers as **outbounds** into the running Xray config — without touching your
saved template. This is the recommended way to subscribe to a *pool* of servers.
| Field | Default | Meaning |
| ---------------- | ------- | -------------------------------------------------------------- |
| `url` | — | The remote subscription URL (SSRF-guarded). |
| `tagPrefix` | auto | Prefix for generated outbound tags (e.g. `hk-`); blank = `subN-`. |
| `updateInterval` | `600` | Refresh interval in **seconds**. |
| `prepend` | `false` | Place these outbounds before your manual ones. |
| `priority` | `0` | Merge order (lower first). |
Imported outbounds get **stable tags**: the same server keeps the same tag across
refreshes, so exact-tag routing/balancer selectors stay pinned — while
prefix/wildcard selectors (e.g. `hk-*`) automatically pick up new servers as the
pool changes. Supported link schemes: `vmess`, `vless`, `trojan`, `ss`,
`hysteria2` (`hy2`), and `wireguard` (`wg`). The panel refreshes enabled
subscriptions on a timer and reloads Xray when something changes.
## Routing rules
**Routing rules** decide which outbound (or balancer) each connection uses. Each
rule is a `field`-type matcher: set any of `domain`, `ip`, `port`, `network`,
`protocol`, `inboundTag`, `sourceIP`, … and point it at an **`outboundTag`** or a
**`balancerTag`**. Rules are evaluated **top-to-bottom — the first match wins**, so
put specific rules above general ones.
```json title="route ads to blackhole, private IPs direct"
{
"routing": {
"domainStrategy": "IPIfNonMatch",
"rules": [
{ "type": "field", "domain": ["geosite:category-ads-all"], "outboundTag": "block" },
{ "type": "field", "ip": ["geoip:private"], "outboundTag": "direct" }
]
}
}
```
## Balancers
A **balancer** groups outbounds by a **selector** (tag prefixes, including the
wildcard pools from outbound subscriptions) and spreads or fails traffic over them
with a **strategy**:
| Strategy | Picks… | Needs a monitor |
| ------------- | ----------------------------------------------- | ------------------------ |
| `random` | a random member per connection | no |
| `roundRobin` | members in rotation | no |
| `leastPing` | the lowest-latency member | **`observatory`** |
| `leastLoad` | the most stable member by sampled load | **`burstObservatory`** |
Reference a balancer from a rule via `balancerTag`. `leastPing` and `leastLoad`
need a health monitor, which Xray places at the **top level** of the config
(`observatory` / `burstObservatory`, **not** inside `routing`). The panel can
report balancer status and **override** a balancer to a specific outbound for
testing.
Build the routing block — rules, balancers, and the matching observatory — here:
<RoutingBuilder />
<Callout type="warn">
Outbounds that reach external services are fetched with SSRF protection — by
default private/internal addresses are blocked unless you explicitly allow them
per source.
</Callout>
@@ -0,0 +1,51 @@
---
title: Reverse Proxy
description: Put the 3x-ui panel and subscription behind Nginx or Caddy with Let's Encrypt TLS.
icon: Waypoints
---
A reverse proxy lets you serve the panel and subscription on a clean domain with
automatic HTTPS, and hide the real ports behind ports 80/443. Prefer to let the
panel terminate TLS directly? Get a certificate with the
[`x-ui` SSL menu](/docs/config/ssl-certificates) instead.
## Generate a config
<ReverseProxyGenerator />
<Callout type="info">
The panel uses WebSockets for live updates, so the proxy must pass the
`Upgrade`/`Connection` headers (the Nginx output above already does). Caddy
handles WebSocket upgrades automatically.
</Callout>
## Nginx + certificate
With Nginx, obtain a certificate with `certbot` (or `acme.sh`) and reference it
in the server block:
```bash title="certbot"
certbot certonly --nginx -d panel.example.com
```
Reload Nginx after installing the certificate, and set up automatic renewal
(`certbot renew` runs on a timer by default).
## Caddy
Caddy obtains and renews certificates for you — point a Caddyfile at the panel
and it just works:
```text title="Caddyfile"
panel.example.com {
reverse_proxy 127.0.0.1:2053
}
```
## Tips
- Keep the panel's **web base path** even behind a proxy; defense in depth.
- If you terminate TLS at the proxy, you may want `XUI_SKIP_HSTS=true` on the
panel — see the [environment variables reference](/docs/reference/env-vars).
- Proxy the [subscription](/docs/config/subscription) server too, so its contents
are served over HTTPS.
@@ -0,0 +1,66 @@
---
title: Security
description: Harden 3x-ui — panel auth and 2FA, Fail2ban IP limits, firewall rules, BBR, and staying current.
icon: ShieldCheck
---
A proxy panel is a high-value target. A few layers of hardening go a long way.
## Panel hardening
- Strong, unique credentials and **two-factor auth** (TOTP).
- A non-default panel port and a long, random web base path.
- TLS on the panel (directly or via a [reverse proxy](/docs/operations/reverse-proxy)).
- The built-in **login limiter** blocks an IP/username after 5 failed attempts
in 5 minutes (for 15 minutes), and the panel can route its own egress through
an outbound.
See [First login](/docs/guide/first-login) for the full checklist.
## Fail2ban & IP limits
Set an **IP limit** per client (see [Clients](/docs/config/clients)) to cap the
number of simultaneous source IPs. Enforcement is handled by **Fail2ban**, which
3x-ui installs and configures for you (enabled by default on script installs, and
on Docker via `XUI_ENABLE_FAIL2BAN=true`).
Manage it from the `x-ui` menu (**22 — IP Limit Management**): install/configure,
change the ban duration (default **30 minutes**), ban/unban an IP, view ban logs,
and check status. Under the hood:
- The jail is named **`3x-ipl`**; ban logs live at `/var/log/x-ui/3xipl.log` and
`/var/log/x-ui/3xipl-banned.log` (also via `x-ui banlog`).
- Bans cover all TCP/UDP **except** your SSH and panel ports, so a ban can't lock
you out of the server or panel.
<Callout type="warn">
On Docker, Fail2ban bans with `iptables`, which needs the `NET_ADMIN` (and
`NET_RAW`) capability — `docker-compose.yml` grants them. With a bare
`docker run`, add `--cap-add=NET_ADMIN --cap-add=NET_RAW` or bans are logged
but never applied.
</Callout>
## Firewall
Open only the ports you actually use: SSH, the panel port, the subscription
port, and your inbound ports. The `x-ui` menu (**23 — Firewall Management**) wraps
`ufw`, or generate rules here:
<FirewallRulesGenerator />
<Callout type="warn">
Make sure SSH stays allowed before enabling a default-deny firewall, or you can
lock yourself out. Test with a second session open.
</Callout>
## Network tuning (BBR)
The `x-ui` menu (**26 — Enable BBR**) toggles Google's BBR congestion control
(`net.ipv4.tcp_congestion_control = bbr`, `net.core.default_qdisc = fq`), which
often improves throughput on congested links.
## Keep current
Update 3x-ui and Xray-core regularly — security fixes land in new releases. Watch
the [releases page](https://github.com/MHSanaei/3x-ui/releases) and see
[Update & uninstall](/docs/guide/update-uninstall).
@@ -0,0 +1,112 @@
---
title: Telegram Bot
description: Connect a Telegram bot to 3x-ui for commands, periodic reports, event alerts (login, CPU, node up/down), backups, and client self-service.
icon: Send
---
3x-ui can drive a Telegram bot for monitoring, alerts, backups, and remote
management. Admins get full control; regular users (linked by Telegram ID) can
check their own usage and links.
<Callout type="info">
Looking for news and community support? Join the official Telegram channel
[@XrayUI](https://t.me/XrayUI). That's separate from the bot below, which you
run yourself to manage your own panel.
</Callout>
## Set it up
<Steps>
<Step>
### Create a bot
Message [@BotFather](https://t.me/BotFather), send `/newbot`, and copy the **bot
token**.
</Step>
<Step>
### Find your Telegram ID
Get your numeric Telegram user ID (the bot's own `/id` command reports it once
connected). This is your **admin** ID.
</Step>
<Step>
### Configure the panel
In Panel Settings, enable the Telegram bot and set the **token** and **admin chat
ID(s)** (comma-separated). Save, then message your bot.
</Step>
</Steps>
Validate your token, admin IDs, and report schedule before pasting them into the
panel:
<TelegramSetupHelper />
## Commands
These appear in the Telegram command menu: `/start`, `/help`, `/status`, `/id`.
Additional commands:
| Command | Who | Action |
| ------------------ | ------ | ------------------------------------------------------------ |
| `/start`, `/help` | anyone | Greeting and the menu of inline buttons |
| `/status` | anyone | Confirm the bot is alive |
| `/id` | anyone | Show your Telegram numeric ID |
| `/usage <arg>` | both | Admins search clients; users look up their own usage |
| `/inbound <remark>`| admin | Show an inbound's details |
| `/restart` | admin | Restart Xray |
Admins also get inline-button flows for server usage, sorted traffic reports,
resetting traffic, DB backups, ban logs, listing inbounds/clients, online
clients, "depleting soon", and a full **add-client** wizard. Regular users get
buttons for their own usage, subscription links, individual links, and QR codes.
## Reports & alerts
- **Periodic report** — on the `tgRunTime` schedule (default `@daily`), the bot
sends admins server usage (host, versions, uptime, load, memory, online
clients, traffic), a list of exhausted/expiring clients, and — if
`tgBotBackup` is on — a database + Xray config backup. Clients linked by
Telegram ID get their own expiry/quota warnings.
- **Event alerts** — selected by `tgEnabledEvents` (default `login.attempt,cpu.high`):
| Event | When |
| --------------- | ------------------------------------------------------- |
| `login.attempt` | A panel login succeeds or fails (with IP and username) |
| `cpu.high` | CPU exceeds `tgCpu` percent (default 80) |
| `memory.high` | Memory exceeds `tgMemory` percent (default 80) |
| `xray.crash` | Xray-core crashes |
| `outbound.down` / `outbound.up` | An outbound goes down / recovers |
| `node.down` / `node.up` | A node goes offline / comes back |
The warning lead times come from `expireDiff` (days before expiry) and
`trafficDiff` (GB of quota remaining); both default to `0` (off).
## Settings
| Setting | Default | Meaning |
| -------------- | -------------------------- | ---------------------------------------------- |
| `tgBotEnable` | `false` | Master on/off. |
| `tgBotToken` | _(secret)_ | Bot API token. |
| `tgBotChatId` | _(none)_ | Comma-separated **admin** Telegram IDs. |
| `tgBotProxy` | _(none)_ | `socks5://`, `http://`, or `https://` proxy. |
| `tgBotAPIServer` | _(default)_ | Custom Telegram Bot API server. |
| `tgRunTime` | `@daily` | Report schedule (cron / `@daily` / `@every …`).|
| `tgBotBackup` | `false` | Attach a DB backup to the periodic report. |
| `tgCpu` / `tgMemory` | `80` / `80` | CPU / memory alert thresholds (percent). |
| `tgLang` | `en-US` | Bot language. |
| `tgEnabledEvents` | `login.attempt,cpu.high`| Which events to deliver. |
<Callout type="warn">
The bot token controls your bot — keep it secret and only add **trusted** admin
chat IDs. Login alerts never include passwords.
</Callout>
<Callout type="info">
Email (SMTP) notifications mirror the same events (`smtpEnabledEvents`) if you'd
rather receive alerts by email — configure SMTP in Panel Settings.
</Callout>