pjandro/3x-ui
1
0
Fork 0
mirror of https://github.com/MHSanaei/3x-ui.git synced 2026-11-12 16:15:02 +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/config/clients.mdx
+67
View File
@@ -0,0 +1,67 @@
---
title: Clients
description: Manage 3x-ui clients — credentials, traffic and expiry limits, IP limits, groups, bulk actions, external links, and online status.
icon: Users
---
A **client** is a single user, identified by a unique **email**. In the current
panel, clients are first-class records that can be attached to **multiple
inbounds** at once, with per-client traffic accounting.
## Client fields
| Field | Applies to | Meaning |
| -------------- | --------------------- | ------------------------------------------------------------------ |
| **Email** | all | Unique identifier used for accounting and lookups. |
| **ID (UUID)** | VLESS, VMess | The client credential. |
| **Password** | Trojan, Shadowsocks | The client credential. |
| **Auth** | Hysteria2 | The client credential. |
| **Flow** | VLESS | XTLS flow, e.g. `xtls-rprx-vision`. |
| **Limit IP** | all | Max simultaneous source IPs (enforced via Fail2ban). |
| **Total (GB)** | all | Traffic quota; the client is disabled when exhausted. |
| **Expiry** | all | Date after which the client stops working. |
| **Reset** | all | Auto-renew period in **days** (rolls the quota over). |
| **Telegram ID**| all | Links the client to a Telegram user for self-service/notifications.|
| **Sub ID** | all | Subscription identifier grouping this client's links. |
| **Group** | all | Optional client group for organization and bulk filtering. |
| **Comment** | all | Free-text note. |
<Callout type="info">
Reaching the **traffic** or **expiry** limit disables the client; the panel can
restart Xray automatically when clients are auto-disabled
(`restartXrayOnClientDisable`, on by default).
</Callout>
## Limits and IP control
- **Traffic / expiry** caps disable the client when hit; a **Reset** period
auto-renews the quota.
- **Limit IP** caps simultaneous source IPs. Enforcement relies on Fail2ban —
see [Security](/docs/operations/security). You can view a client's recent IPs
and clear them from the client's actions.
- **Online status** and **last-online** times are tracked per client (and per
node in multi-node setups).
## Share links and external links
Every client has share links and a QR code for its inbounds, plus a combined
[subscription](/docs/config/subscription). You can also attach **external
links** to a client — extra `vless://`, `vmess://`, `trojan://`, `ss://`,
`hysteria2://`, or `wireguard://` links, or a remote subscription URL — so they
appear alongside the panel-generated ones in the client's subscription.
To inspect exactly what a link contains, paste it into the
[share-link inspector](/docs/config/share-links).
## Bulk actions
For managing many clients at once, the panel supports bulk **create, enable,
disable, delete, attach/detach** (to inbounds), **reset traffic**, and
**adjust** (add days / add bytes / set flow). Maintenance actions also let you
delete **depleted** clients (quota/expiry exhausted) and **orphaned** clients
(not attached to any inbound).
<Callout type="warn">
A client's share link contains its credential. Treat links and QR codes like
passwords, and rotate the credential if one leaks.
</Callout>
docs/content/docs/en/config/inbounds.mdx
+97
View File
@@ -0,0 +1,97 @@
---
title: Inbounds & Protocols
description: Create inbounds in 3x-ui — protocols, transports, traffic reset and expiry, and fallbacks that serve multiple protocols on one port.
icon: ArrowDownToLine
---
An **inbound** is a listener that accepts client connections on a port using a
particular protocol and transport. Most of your day-to-day work is creating and
managing inbounds and the clients inside them.
## Create an inbound
<Steps>
<Step>
### Add an inbound
Open **Inbounds → Add**, give it a remark, pick a **protocol**, and choose a
**port** and listen address.
</Step>
<Step>
### Choose a transport and security
Pick the transport (TCP, WebSocket, gRPC, HTTPUpgrade, XHTTP, …) and the security
layer (none, TLS, or REALITY). See [Transports](/docs/config/transports) and
[REALITY](/docs/config/reality).
</Step>
<Step>
### Add clients
Add one or more clients, each with its own credential, limits, and share link.
See [Clients](/docs/config/clients).
</Step>
<Step>
### Set traffic limit, expiry, and reset
Optionally cap total traffic and set an expiry date for the inbound, and choose a
periodic **traffic reset** schedule: `never` (default), `hourly`, `daily`,
`weekly`, or `monthly`.
</Step>
</Steps>
## Supported protocols
The inbound editor accepts these protocols:
| Protocol | Notes |
| ---------------------- | ------------------------------------------------------------------------ |
| **VLESS** | Lightweight; the basis for REALITY + XTLS-Vision. Recommended. |
| **VMess** | Older but very widely supported by clients. |
| **Trojan** | TLS-based; supports XTLS and fallbacks. |
| **Shadowsocks** | Includes Shadowsocks-2022 (`2022-blake3-*`) ciphers. |
| **WireGuard** | Modern tunnel. |
| **Hysteria2** | Selected as `hysteria`; the panel emits `hysteria2://` links. |
| **HTTP** | HTTP proxy. |
| **Mixed (SOCKS/HTTP)** | A combined SOCKS + HTTP listener. |
| **Dokodemo-door / Tunnel** | Port forwarding / traffic redirect. |
| **MTProto** | Telegram MTProto proxy, served by a bundled `mtg` process (not Xray). |
<Callout type="info">
Hysteria2 isn't a separate protocol internally — it's the `hysteria` protocol
with the transport version set to 2, and the panel generates `hysteria2://`
share links for it.
</Callout>
## Fallbacks — multiple protocols on one port
Fallbacks let a single TLS port (e.g. `443`) serve more than one protocol — for
example VLESS **and** Trojan — by routing unmatched handshakes to a child
inbound. In 3x-ui, fallbacks are managed in the panel (a master inbound's
**Fallbacks** list) rather than hand-written into JSON.
Fallbacks are available only when the master inbound is:
- **VLESS** or **Trojan**,
- on the raw **TCP** transport,
- with **TLS** or **REALITY** security.
Each fallback rule targets a child inbound and can match on `path`, `alpn`, and
`dest`. Client share links for a fallback child are automatically rewritten to
advertise the master's address, port, and TLS.
## Not sure which to pick?
Use the wizard to get a recommendation based on your goals and clients:
<ProtocolWizard />
<Callout type="info">
For censorship resistance with modern clients, **VLESS + REALITY +
XTLS-Vision** is the usual best choice — continue to
[REALITY](/docs/config/reality).
</Callout>
docs/content/docs/en/config/meta.json
+14
View File
@@ -0,0 +1,14 @@
{
"title": "Configuration",
"icon": "Settings",
"pages": [
"panel",
"ssl-certificates",
"inbounds",
"reality",
"transports",
"clients",
"subscription",
"share-links"
]
}
docs/content/docs/en/config/panel.mdx
+77
View File
@@ -0,0 +1,77 @@
---
title: Panel Settings
description: Every 3x-ui panel setting — web server, TLS, display, security, and notifications — with defaults from the source.
icon: SlidersHorizontal
---
**Panel Settings** controls how the panel itself is served and secured (separate
from your inbounds and clients). Settings are stored as key/value pairs; the
defaults below come straight from the panel source. Secrets (tokens, passwords)
are shown only as a "set / not set" indicator and are never returned to the
browser in full.
## Web server
| Setting | Default | Meaning |
| ------------------- | ----------------------- | ----------------------------------------------------------------------- |
| `webPort` | `2053` | Panel port (1–65535). The `XUI_PORT` env var overrides it at runtime. |
| `webListen` | _(all interfaces)_ | Bind the panel to a specific IP. |
| `webBasePath` | `/` | URL path the panel is served under (always normalized to `/…/`). |
| `webCertFile` / `webKeyFile` | _(none)_ | TLS certificate + key. When both are set, the panel serves **HTTPS**. |
| `sessionMaxAge` | `360` | Session lifetime in **minutes** (default 6 hours). |
| `trustedProxyCIDRs` | `127.0.0.1/32,::1/128` | IPs/CIDRs whose forwarded headers (real client IP) are trusted. |
| `panelOutbound` | _(none)_ | Route the panel's own egress (update checks, Telegram, geo/sub fetches) through a named Xray outbound. |
After changing the port or base path, the panel URL becomes
`http(s)://<server>:<port><web-base-path>`. You can preset the base path on first
launch with [`XUI_INIT_WEB_BASE_PATH`](/docs/reference/env-vars).
### TLS
Serving the panel over HTTPS protects your credentials in transit. Either set
`webCertFile` + `webKeyFile` — the [`x-ui` SSL menu](/docs/config/ssl-certificates)
can obtain a Let's Encrypt certificate for you — or terminate TLS at a
[reverse proxy](/docs/operations/reverse-proxy).
<Callout type="warn">
Never expose the panel over plain HTTP on the public internet. Use TLS, a
non-default port, and a long random web base path.
</Callout>
## Display
| Setting | Default | Meaning |
| ---------------- | ------------------------------------------------ | ------------------------------------------------------------- |
| `pageSize` | `25` | Rows per page in lists (`0` disables pagination). |
| `expireDiff` | `0` | Days before expiry to start warning. |
| `trafficDiff` | `0` | Percent of quota remaining at which to start warning. |
| `remarkTemplate` | `{{INBOUND}}-{{EMAIL}}\|📊{{TRAFFIC_LEFT}}\|⏳{{DAYS_LEFT}}D` | Default client remark template (see [Share links](/docs/config/share-links#remark-template-variables)). |
| `timeLocation` | `Local` | Time zone for stats and expiry. |
| `datepicker` | `gregorian` | Calendar for date inputs (Gregorian or Jalali/Persian). |
## Security & authentication
Credentials, two-factor auth, the brute-force limiter, sessions, and LDAP are
covered in [First login](/docs/guide/first-login) and
[Security](/docs/operations/security). In short:
- Passwords are stored as **bcrypt** hashes; changing them logs out all sessions.
- **2FA (TOTP)** can be required at login.
- An **LDAP** fallback can authenticate users when the local password check fails.
- API access uses **API tokens** managed under Panel Settings (see the
[API reference](/docs/reference/api/api-tokens)).
## Notifications & subscription
These have their own settings groups and pages:
<Cards>
<Card title="Telegram bot" href="/docs/operations/telegram-bot" description="Token, chat IDs, alerts, and reports." />
<Card title="Subscription" href="/docs/config/subscription" description="Subscription server, formats, and paths." />
<Card title="Security" href="/docs/operations/security" description="2FA, IP limits, and hardening." />
</Cards>
<Callout type="info">
Email (SMTP) notifications are also configurable (host, port, encryption,
recipients) with the same event types as the Telegram bot.
</Callout>
docs/content/docs/en/config/reality.mdx
+135
View File
@@ -0,0 +1,135 @@
---
title: REALITY
description: Set up a VLESS + REALITY inbound with XTLS-Vision in 3x-ui — keys, short IDs, SNI, fingerprints, and common pitfalls.
icon: ShieldCheck
---
**REALITY** is an Xray transport security that disguises your proxy as ordinary
traffic to a real, popular website. Unlike classic TLS, your server needs **no
certificate of its own** — it borrows the TLS handshake of the target site
(`dest`). Combined with the **XTLS-Vision** flow, it is fast and resistant to
deep-packet inspection.
REALITY is used with **VLESS** (and Trojan). The recommended flow is
`xtls-rprx-vision`.
## Key settings
When you choose **REALITY** as the security mode on a VLESS inbound, 3x-ui
exposes these fields:
| Field | What it is |
| ------------------------ | ------------------------------------------------------------------ |
| **Dest (target)** | A real TLS site to impersonate, e.g. `www.microsoft.com:443`. |
| **SNI / Server Names** | The hostname(s) clients send; must match the target's certificate. |
| **Public / Private key** | An **x25519** keypair. The private key stays on the server. |
| **Short IDs** | Hex strings used to authenticate clients (you can have several). |
| **Flow** | Set to `xtls-rprx-vision`. |
| **Fingerprint (uTLS)** | The client TLS fingerprint to mimic, e.g. `chrome`. |
The private key is generated with Xray's `x25519` utility (the panel can
generate the pair for you):
```bash title="generate an x25519 keypair"
xray x25519
```
## Set it up in the panel
<Steps>
<Step>
### Create a VLESS inbound
Add a new inbound, choose protocol **VLESS**, and set **Security** to
**reality**.
</Step>
<Step>
### Choose a target (dest) and SNI
Pick a reputable site that supports TLS 1.3 and HTTP/2 and is reachable from your
server and your clients (for example `www.microsoft.com:443`). Set the server
names / SNI to match that site's certificate.
</Step>
<Step>
### Generate keys and short IDs
Generate the x25519 keypair and one or more short IDs. Keep the **private key**
secret; clients only ever receive the **public key**.
</Step>
<Step>
### Set the flow and fingerprint
Use the `xtls-rprx-vision` flow and a common uTLS fingerprint such as `chrome`.
</Step>
<Step>
### Add a client and share the link
Create a client, then use its share link or QR code in a compatible app
(v2rayNG, Hiddify, Mihomo, and others).
</Step>
</Steps>
## What the configuration looks like
On the server, a REALITY inbound's `streamSettings` looks roughly like this:
```json title="server inbound (excerpt)"
{
"network": "tcp",
"security": "reality",
"realitySettings": {
"dest": "www.microsoft.com:443",
"serverNames": ["www.microsoft.com"],
"privateKey": "<x25519 private key>",
"shortIds": ["<hex short id>"],
"fingerprint": "chrome"
}
}
```
The matching client share link carries the **public** parameters:
```text title="vless:// (excerpt)"
vless://<uuid>@<server>:443?security=reality&pbk=<public-key>&sid=<short-id>&sni=www.microsoft.com&fp=chrome&spx=%2F&flow=xtls-rprx-vision#my-reality
```
- `pbk` — REALITY **public** key
- `sid` — short ID (matches one on the server)
- `sni` — server name (matches the target's certificate)
- `fp` — client fingerprint
- `spx` — spiderX path
- `flow` — `xtls-rprx-vision`
## Common pitfalls
<Callout type="warn">
- **Bad target.** The `dest` must be a real site that supports **TLS 1.3** and
**HTTP/2**, is reachable, and isn't blocked in your region. Pick a site you do
not own and that sees lots of traffic.
- **SNI mismatch.** The SNI / server names must match the target's real
certificate, or the handshake gives the disguise away.
- **Leaked private key.** Only ever distribute the **public** key to clients.
- **Wrong flow.** REALITY + XTLS-Vision needs `flow = xtls-rprx-vision` on both
the inbound client entry and the share link.
</Callout>
## Generate a config
Use the generator below to create a fresh X25519 keypair, UUID, and short ID,
then copy the server inbound JSON and the client share link. Everything is
computed **in your browser** — no keys or links are sent anywhere.
<RealityConfigGenerator />
<Callout type="info">
The **private key** belongs only on your server. Share the generated
`vless://` link (which contains the **public** key) with clients.
</Callout>
docs/content/docs/en/config/share-links.mdx
+82
View File
@@ -0,0 +1,82 @@
---
title: Share Links
description: 3x-ui share-link formats (vless, vmess, trojan, ss, hysteria2, mtproto), the remark template variables, and an in-browser link inspector.
icon: Link
---
3x-ui generates a **share link** (and QR code) for each client. Client apps such
as v2rayNG, Hiddify, and Mihomo import these links to configure themselves.
## Link formats
| Scheme | Shape |
| -------------- | --------------------------------------------------------------- |
| `vless://` | `vless://<uuid>@<host>:<port>?<params>#<remark>` |
| `vmess://` | `vmess://<base64-json>` (a base64-encoded JSON object) |
| `trojan://` | `trojan://<password>@<host>:<port>?<params>#<remark>` |
| `ss://` | `ss://<userinfo>@<host>:<port>?<params>#<remark>` (SIP002; Shadowsocks-2022 uses percent-encoded userinfo) |
| `hysteria2://` | `hysteria2://<auth>@<host>:<port>?<params>#<remark>` |
| `tg://proxy` | `tg://proxy?server=…&port=…&secret=…` (MTProto) |
The query parameters carry the transport and security settings — `security`,
`sni`, `fp`, `pbk`, `sid`, `spx`, `flow`, `type`, `path`, `host`, `alpn`, and
more.
## Inspect a link
Paste any share link to decode every field. Parsing happens **entirely in your
browser** — the link is never sent over the network.
<ShareLinkInspector />
<Callout type="warn">
Share links contain everything needed to connect as a client, including the
client's credential. Treat them like passwords.
</Callout>
## Remark template variables
The text after `#` in each link (the **remark**) is generated from a template
you control in Panel Settings (`remarkTemplate`). The default is:
```text
{{INBOUND}}-{{EMAIL}}|📊{{TRAFFIC_LEFT}}|⏳{{DAYS_LEFT}}D
```
Tokens use `{{UPPER_CASE}}` syntax. The template is split on `|` into segments;
a segment whose only value is the unlimited marker `∞` (for `TRAFFIC_LEFT`,
`TRAFFIC_TOTAL`, `DAYS_LEFT`, or `TIME_LEFT`) is dropped, so unlimited clients
don't show empty decorations.
### Available tokens
| Token | Value |
| ----- | ----- |
| `{{EMAIL}}` / `{{USERNAME}}` | Client email (identifier) |
| `{{INBOUND}}` | Inbound remark |
| `{{HOST}}` | Host-row remark (managed hosts) |
| `{{ID}}` / `{{SHORT_ID}}` | Client UUID / its first 8 chars |
| `{{TELEGRAM_ID}}` · `{{SUB_ID}}` · `{{COMMENT}}` | Telegram ID, subscription ID, comment |
| `{{STATUS}}` / `{{STATUS_EMOJI}}` | `active`/`expired`/`depleted`/`disabled` (or ✅⏳🚫) |
| `{{DAYS_LEFT}}` / `{{TIME_LEFT}}` | Days, or `Xd Xh Xm`, remaining (`∞` if unlimited) |
| `{{EXPIRE_DATE}}` / `{{JALALI_EXPIRE_DATE}}` / `{{EXPIRE_UNIX}}` | Expiry as Gregorian / Jalali date / Unix seconds |
| `{{CREATED_UNIX}}` | Creation time (Unix seconds) |
| `{{TRAFFIC_USED}}` / `{{TRAFFIC_LEFT}}` / `{{TRAFFIC_TOTAL}}` | Human-readable usage (`∞` if unlimited) |
| `{{TRAFFIC_USED_BYTES}}` / `{{TRAFFIC_LEFT_BYTES}}` / `{{TRAFFIC_TOTAL_BYTES}}` | Same, in bytes |
| `{{UP}}` / `{{DOWN}}` | Upload / download (human-readable) |
| `{{RESET_DAYS}}` · `{{USAGE_PERCENTAGE}}` | Reset period (days) · used percent |
| `{{PROTOCOL}}` / `{{TRANSPORT}}` / `{{SECURITY}}` | e.g. `VLESS` / `ws` / `REALITY` |
<Callout type="info">
Usage tokens (traffic, days, status) appear in the subscription **body** but
are stripped from the display/QR view, so a shared QR doesn't leak a client's
remaining quota. Date tokens follow the `datepicker` setting (Gregorian or
Jalali).
</Callout>
## Related
<Cards>
<Card title="REALITY" href="/docs/config/reality" description="Generate a VLESS + REALITY config and link." />
<Card title="Subscription" href="/docs/config/subscription" description="Serve all of a client's links from one URL." />
</Cards>
docs/content/docs/en/config/ssl-certificates.mdx
+181
View File
@@ -0,0 +1,181 @@
---
title: SSL Certificates
description: Get and renew TLS certificates for the 3x-ui panel and inbounds — with the x-ui ACME menu (domain or bare IP), a Cloudflare DNS-01 wildcard, or manual Certbot.
icon: ShieldCheck
---
A TLS certificate lets you serve the **panel** over HTTPS (so your login and API
traffic are encrypted) and terminate TLS on **inbounds** (VLESS-TLS, Trojan,
Shadowsocks-TLS, and friends). There are three ways to obtain one:
- **The `x-ui` menu** — built-in [ACME](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment)
client. Easiest for a single domain or a bare IP.
- **Cloudflare DNS-01** — also from the menu; needed for **wildcard** certs or
when port 80 is blocked / the server sits behind Cloudflare's proxy.
- **Manual Certbot** — if you'd rather manage `acme.sh`/Certbot yourself.
<Callout type="info">
If you put the panel behind Nginx or Caddy, let the proxy handle the
certificate instead — see [Reverse proxy](/docs/operations/reverse-proxy).
[REALITY](/docs/config/reality) inbounds need **no** certificate at all; they
borrow a real site's TLS. This page is for the panel and for classic TLS
inbounds.
</Callout>
## The `x-ui` SSL menu (Let's Encrypt)
Run `x-ui` and choose **`20` — SSL Certificate Management**. It drives
[acme.sh](https://github.com/acmesh-official/acme.sh) and offers:
| Option | What it does |
| ------------------------------ | ------------------------------------------------------------------- |
| Get SSL (Domain) | Issue a certificate for a domain via HTTP validation. |
| Get SSL for IP Address | Issue a short-lived (6-day, auto-renewing) cert for a **bare IP**. |
| Revoke | Revoke an existing certificate. |
| Force Renew | Renew now, before expiry. |
| Show Existing Domains | List certificates already on the server. |
| Set Cert paths for the panel | Point the panel's TLS at an issued cert (sets the fields for you). |
### Issue a certificate for a domain
<Steps>
<Step>
### Point the domain at the server
Create an `A` (and/or `AAAA`) record for your domain that resolves to this
server's public IP. Validation fails until DNS has propagated.
</Step>
<Step>
### Free up port 80
HTTP validation needs **port 80** reachable from the internet and not already in
use. Stop anything bound to it for the duration, and allow it through the
[firewall](/docs/reference/ports-firewall).
</Step>
<Step>
### Run the issuer
`x-ui` → `20` → **Get SSL (Domain)**, then enter the domain. acme.sh requests
the certificate and saves it under `/root/cert/<domain>/` as `fullchain.pem`
(the certificate chain) and `privkey.pem` (the private key).
</Step>
<Step>
### Wire it into the panel
Choose **Set Cert paths for the panel** to fill in `webCertFile` and
`webKeyFile` and restart the panel, or set them yourself in
[Panel Settings](/docs/config/panel#tls). The panel serves HTTPS as soon as both
are set.
</Step>
</Steps>
### Issue a certificate for a bare IP
No domain? Choose **Get SSL for IP Address** to obtain a short-lived
certificate (valid ~6 days, renewed automatically) bound to the server's IP.
Useful for reaching the panel over HTTPS before you've set up a domain.
## Cloudflare (DNS-01 wildcard)
DNS validation proves you control the domain by creating a TXT record instead of
answering on port 80 — so it works **behind Cloudflare's proxy**, on servers
where port 80 is blocked, and for **wildcard** certificates (`*.example.com`).
Your domain's DNS must be managed by Cloudflare, and you need one of:
- a **scoped API token** with the `Zone:DNS:Edit` permission (recommended), or
- your account **email + Global API Key**.
<Steps>
<Step>
### Create a scoped API token
In the Cloudflare dashboard go to **My Profile → API Tokens →
[Create Token](https://dash.cloudflare.com/profile/api-tokens)**, pick the
**Edit zone DNS** template, scope it to the zone you're issuing for, and create
it. Copy the token — it's shown only once.
</Step>
<Step>
### Run the Cloudflare issuer
`x-ui` → **`21` — Cloudflare SSL Certificate**. When asked, choose **`t`** for an
API token (the default) or **`g`** for the Global API Key, then enter your
domain (and, for the Global API Key, your account email and key). acme.sh creates
the TXT record, validates, and cleans it up.
</Step>
<Step>
### Point the panel at it
As with the domain flow, use **Set Cert paths for the panel** (menu `20`) or set
`webCertFile` / `webKeyFile` in [Panel Settings](/docs/config/panel#tls).
</Step>
</Steps>
<Callout type="info">
Prefer a scoped token over the Global API Key — it only grants DNS edits on the
zone you choose, so a leak can't touch the rest of your Cloudflare account.
</Callout>
## Manual (Certbot)
If you'd rather not use the menu, issue a certificate with Certbot's standalone
plugin (again, this needs port 80 free and the domain resolving to the server):
```bash
apt-get install certbot -y
certbot certonly --standalone --agree-tos --register-unsafely-without-email -d yourdomain.com
certbot renew --dry-run
```
Certbot writes the certificate to `/etc/letsencrypt/live/yourdomain.com/`
(`fullchain.pem` and `privkey.pem`). Point the panel at those two files in
[Panel Settings](/docs/config/panel#tls), and set up renewal — `certbot renew`
runs on a systemd timer by default.
## Using the certificate
- **Panel** — set `webCertFile` (the full chain) and `webKeyFile` (the private
key) in [Panel Settings](/docs/config/panel#tls). Both must be set for the
panel to switch to HTTPS. Menu option **`11` — View Current Settings** prints
the paths currently in use.
- **Inbounds** — when you enable TLS on an inbound, reference the same
certificate and key files (or paste their contents) in the inbound's TLS
settings. See [Inbounds](/docs/config/inbounds) and
[Transports](/docs/config/transports).
<Callout type="warn">
Certificates expire (Let's Encrypt: 90 days; IP certs: ~6 days). The menu and
Certbot both renew automatically, but the panel keeps reading the **files** at
their fixed paths — so renew **in place** rather than moving the files, and the
panel picks up the new cert on its next restart. **Force Renew** (menu `20`)
triggers a renewal on demand.
</Callout>
## Next steps
<Cards>
<Card
title="Panel Settings"
href="/docs/config/panel#tls"
description="webCertFile / webKeyFile and the rest of the web-server settings."
/>
<Card
title="Reverse proxy"
href="/docs/operations/reverse-proxy"
description="Let Nginx or Caddy terminate TLS for you instead."
/>
<Card
title="REALITY"
href="/docs/config/reality"
description="Stealth TLS for inbounds — no certificate required."
/>
</Cards>
docs/content/docs/en/config/subscription.mdx
+86
View File
@@ -0,0 +1,86 @@
---
title: Subscription
description: Run the 3x-ui subscription server — base64/JSON/Clash formats, ports and paths, TLS, response headers, and custom templates.
icon: Rss
---
A **subscription** is a single URL that returns all of a client's
configurations. Client apps refresh it periodically, so when you change an
inbound, clients pick up the change automatically. The subscription server runs
as a **separate** server from the panel.
## Enable and configure
The subscription server is **on by default** (`subEnable`). Configure it in the
panel's subscription settings:
| Setting | Default | Meaning |
| ------------- | ------- | --------------------------------------------------------------- |
| `subPort` | `2096` | Listen port (separate from the panel). |
| `subListen` | _(all)_ | Bind address. |
| `subPath` | `/sub/` | Base path for raw subscription URLs. |
| `subDomain` | _(none)_| Public host; if set, the server only answers for that Host. |
| `subCertFile` / `subKeyFile` | _(none)_ | TLS cert + key — when set, the server serves **HTTPS**. |
| `subEncrypt` | `true` | Base64-encode the raw subscription body. |
| `subUpdates` | `12` | Suggested refresh interval (hours) sent to clients. |
A subscription URL looks like:
```text
https://<sub-host>:<sub-port>/sub/<sub-id>
```
where `<sub-id>` is the client's **Sub ID**.
The same Sub ID is served in several formats on different paths — the **Base64**
list at `subPath` and the **JSON** (Xray-json) config at the JSON path. Build the
URLs and preview both bodies here:
<SubscriptionBuilder />
## Output formats
The **format is chosen by path**, each with its own enable toggle:
| Format | Path | Enabled by | Output |
| --------------------- | --------- | ---------------- | --------------------------------------------------- |
| **Raw links** | `/sub/` | always (if on) | A list of `vless://`, `vmess://`, … links (base64-encoded when `subEncrypt` is on). |
| **JSON** | `/json/` | `subJsonEnable` | Full Xray client config(s). |
| **Clash / Mihomo** | `/clash/` | `subClashEnable` | YAML profile. |
Only enabled inbounds using **VLESS, VMess, Trojan, Shadowsocks, or Hysteria2**
appear in a subscription, ordered by their sub-sort index. Requesting `/sub/`
with an `Accept: text/html` header (or `?html=1`) returns a human-readable info
page instead of the raw body.
### Base64 vs JSON
The **Base64** body is just the newline-joined share links, standard-base64
encoded (toggle with `subEncrypt`). The **JSON** body wraps each client in a
complete Xray client config — a fixed skeleton (local mixed/HTTP inbounds, DNS,
routing, policy) plus a `proxy` outbound pointing at the inbound. 3x-ui emits a
**single config object for one client and an array for several**, uses the flat
outbound `settings` form (`address`/`port`/`id`, `level: 8`), and strips
`sockopt` from `streamSettings`.
## Response headers
Subscriptions return standard headers that compatible apps read:
- **`Subscription-Userinfo`** — `upload`, `download`, `total` (bytes; `total=0`
means unlimited) and `expire` (Unix seconds).
- **`Profile-Update-Interval`** — refresh interval in hours (`subUpdates`).
- **`Profile-Title`**, **`Support-Url`**, **`Profile-Web-Page-Url`**,
**`Announce`** — optional branding shown by some clients.
## Custom page templates
Point `subThemeDir` at a folder containing a custom info-page template to brand
the HTML subscription page. The per-client remark on each link is fully
templated — see [Share links → remark variables](/docs/config/share-links#remark-template-variables).
<Callout type="info">
Put the subscription server behind TLS (set `subCertFile`/`subKeyFile`, or a
[reverse proxy](/docs/operations/reverse-proxy)) so subscription contents
aren't exposed in transit.
</Callout>
docs/content/docs/en/config/transports.mdx
+199
View File
@@ -0,0 +1,199 @@
---
title: Transports & Security
description: Every transport 3x-ui exposes — TCP, mKCP, WebSocket, gRPC, HTTPUpgrade, XHTTP, Hysteria — with their settings, plus FinalMask obfuscation, sockopt, TLS/REALITY, XTLS-Vision, and VLESS encryption.
icon: Network
---
A **transport** decides how packets are carried between client and server, a
**security** layer decides how they're encrypted and disguised, and **FinalMask**
can obfuscate what's left. The panel only offers valid combinations; this page
lists every transport's settings and the rules the panel enforces.
## Transports
Pick the transport (the inbound's `network`) in the inbound/outbound form. Each
network writes its own settings key on the wire (`tcpSettings`, `kcpSettings`, …).
| Transport | Settings key | When to use it |
| --------------- | --------------------- | ---------------------------------------------------------------------- |
| **TCP (Raw)** | `tcpSettings` | Lowest overhead. The basis for REALITY + XTLS-Vision and fallbacks; optional HTTP/1.1 header camouflage. |
| **mKCP** | `kcpSettings` | Reliable protocol over **UDP** — trades bandwidth for lower latency on lossy links. Carries no TLS/REALITY. |
| **WebSocket** | `wsSettings` | Works through CDNs and HTTP reverse proxies; very compatible. |
| **gRPC** | `grpcSettings` | HTTP/2-based; multiplexes well and proxies cleanly through Nginx. |
| **HTTPUpgrade** | `httpupgradeSettings` | CDN-friendly HTTP/1.1 `Upgrade`; lighter than full WebSocket. |
| **XHTTP** | `xhttpSettings` | Modern stream-multiplexed HTTP transport; CDN-friendly and REALITY-capable. |
| **Hysteria** | `hysteriaSettings` | QUIC-based transport — only for the **Hysteria2** protocol. |
<Callout type="info">
**WireGuard** and **Tunnel** (dokodemo-door) inbounds expose no transport
selector — their stream carries only security/sockopt. Earlier panels also
exposed a raw **HTTP/2 (`http`)** transport; it has been superseded by **XHTTP**
and is no longer selectable.
</Callout>
### TCP (Raw) — `tcpSettings`
| Field | Default | Meaning |
| ------------------------------ | ------- | ----------------------------------------------------------------------- |
| `acceptProxyProtocol` | `false` | Accept the PROXY protocol from an upstream proxy so the real client IP is preserved. |
| `header.type` | `none` | `none`, or `http` for HTTP/1.1 camouflage. |
| `header.request` / `response` | — | When `type: http`: method, path, version and a header map that mimic a normal HTTP exchange. |
### mKCP — `kcpSettings`
| Field | Default | Meaning |
| ------------------ | ----------- | ---------------------------------------------------------------- |
| `mtu` | `1350` | Maximum transmission unit, in bytes (576–1460). |
| `tti` | `20` | Transmission time interval, in ms (10–100). Lower = more responsive, more overhead. |
| `uplinkCapacity` | `5` | Upload bandwidth budget, in **MB/s**. |
| `downlinkCapacity` | `20` | Download bandwidth budget, in **MB/s**. |
| `cwndMultiplier` | `1` | Congestion-window multiplier; raise to push harder on good links. |
| `maxSendingWindow` | `2097152` | Upper bound on in-flight packets. |
<Callout type="info">
mKCP can't carry TLS or REALITY. To disguise it, add a **FinalMask** UDP mask —
the `mkcp-legacy` mask reproduces the classic header obfuscation that older Xray
stored in `kcpSettings.header`/`seed` (those fields no longer exist here).
</Callout>
### WebSocket — `wsSettings`
| Field | Default | Meaning |
| --------------------- | ------- | ---------------------------------------------------------------- |
| `path` | `/` | Request path — route on it when several services share one host. |
| `host` | _(none)_| `Host` header override (useful behind a CDN). |
| `headers` | `{}` | Extra request headers. |
| `heartbeatPeriod` | `0` | Seconds between keepalive pings; `0` disables them. |
| `acceptProxyProtocol` | `false` | Accept the PROXY protocol from an upstream. |
### gRPC — `grpcSettings`
| Field | Default | Meaning |
| ------------- | ------- | --------------------------------------------------------- |
| `serviceName` | _(none)_| gRPC service path; acts like a secret route. |
| `authority` | _(none)_| `:authority` pseudo-header override. |
| `multiMode` | `false` | Multiplex several streams over one connection. |
### HTTPUpgrade — `httpupgradeSettings`
| Field | Default | Meaning |
| --------------------- | ------- | --------------------------------------------- |
| `path` | `/` | Request path. |
| `host` | _(none)_| `Host` header override. |
| `headers` | `{}` | Extra request headers. |
| `acceptProxyProtocol` | `false` | Accept the PROXY protocol from an upstream. |
HTTPUpgrade is a one-shot HTTP/1.1 `Upgrade` with no WebSocket framing — there's
no heartbeat field.
### XHTTP — `xhttpSettings`
XHTTP (SplitHTTP) has a large field set; the panel fills sensible defaults. The
ones you'll usually touch:
| Field | Default | Meaning |
| ---------------------- | ----------- | ---------------------------------------------------------------------- |
| `path` | `/` | Request path. |
| `host` | _(none)_ | `Host` header override. |
| `mode` | `auto` | `auto`, `packet-up`, `stream-up`, or `stream-one`. `packet-up` is the most CDN-compatible; `stream-*` are lower latency. |
| `xPaddingBytes` | `100-1000` | Random padding range that blurs packet sizes. |
| `scMaxBufferedPosts` | `30` | Server-side buffer for uploaded POSTs. |
| `scStreamUpServerSecs` | `20-80` | Stream-up server window (dash range). |
| `xmux` (`enableXmux`) | _(off)_ | Connection multiplexing — `maxConcurrency` `16-32`, `maxConnections` `6`, … Turn on for high concurrency. |
Session-ID fields (`sessionIDPlacement`, `sessionIDKey`, `sessionIDTable`,
`sessionIDLength`) and the `scMin/MaxEachPostBytes` knobs are advanced; leave them
empty unless you're matching a specific upstream.
### Hysteria — `hysteriaSettings`
Only valid when the protocol is **Hysteria2**.
| Field | Default | Meaning |
| ---------------- | ------- | ----------------------------------------------------------------------- |
| `version` | `2` | Hysteria protocol version. |
| `auth` | _(none)_| Shared authentication string. |
| `udpIdleTimeout` | `60` | Seconds (2–600) before idle UDP sessions are dropped. |
| `masquerade` | — | Disguise as an HTTP/3 server: `type` `proxy`/`file`/`string` with `url`/`dir`/`content`, plus `headers` and `statusCode`. |
## FinalMask — late-layer obfuscation
**FinalMask** wraps traffic **after** the transport and security layers, so it can
disguise transports that don't carry TLS (like mKCP) or add a second skin on top of
TLS. Masks are configured per direction:
- **TCP masks** — `fragment`, `sudoku`, `header-custom`.
- **UDP masks** — `salamander`, `mkcp-legacy`, `header-custom`, `xdns`, `xicmp`,
`noise`, `sudoku`, `realm`. (`mkcp-legacy` reproduces the old mKCP header
obfuscation.)
- **QUIC params** — congestion control (`reno`, `bbr`, `brutal`, `force-brutal`),
Brutal up/down rates, `udpHop` (rotate the QUIC port across a range to dodge
port blocking), and receive-window tuning.
FinalMask replaces the per-transport `header`/`seed` obfuscation that older Xray
builds exposed.
## sockopt — low-level socket options
`sockopt` rides alongside any transport and tunes the underlying socket. The most
useful fields:
| Field | Default | Meaning |
| --------------------- | ------- | ---------------------------------------------------------------- |
| `tcpFastOpen` | `false` | Enable TCP Fast Open. |
| `tcpcongestion` | `bbr` | Congestion control: `bbr`, `cubic`, or `reno`. |
| `tproxy` | `off` | Transparent proxy mode: `off`, `redirect`, or `tproxy`. |
| `domainStrategy` | `AsIs` | How addresses resolve (`UseIP`, `ForceIPv4`, …). |
| `dialerProxy` | _(none)_| Chain this outbound's dialing through another outbound tag. |
| `interface` | _(none)_| Bind to a specific network interface. |
| `mark` | `0` | SO_MARK for policy routing (`0` = unset). |
Numeric fields left at `0` are omitted on the wire so Xray keeps OS defaults.
Advanced entries (`happyEyeballs`, `customSockopt[]`, keepalive timers) are
available for special cases.
## Security
The security layer is one of **`none`**, **`tls`**, or **`reality`**, with these
eligibility rules:
| Security | Eligible transports | Eligible protocols |
| ----------- | -------------------------------------------- | --------------------------------------------------- |
| **TLS** | `tcp`, `ws`, `grpc`, `httpupgrade`, `xhttp` | VLESS, VMess, Trojan, Shadowsocks (Hysteria2 is always TLS) |
| **REALITY** | `tcp`, `grpc`, `xhttp` | VLESS, Trojan |
mKCP and Hysteria don't take a separate TLS/REALITY layer — mKCP runs plaintext
(obfuscate with FinalMask), and Hysteria is QUIC/TLS by design. REALITY disguises
your server as a real TLS site and needs no certificate — see
[REALITY](/docs/config/reality).
## XTLS-Vision flow
The `xtls-rprx-vision` flow is fast and DPI-resistant. It's available for
**VLESS** when either:
- the transport is raw **TCP** with **TLS** or **REALITY** security (classic
XTLS-Vision), or
- the transport is **XHTTP** with VLESS encryption enabled (see below).
Set the flow on the VLESS **client**, not the inbound. With classic Vision on
TCP, the panel can also offer a **Vision seed** once a client uses the flow.
## VLESS encryption (ML-KEM)
VLESS supports post-quantum **encryption** (ML-KEM / `mlkem768x25519`), stored in
the inbound's `decryption` (server) and clients' `encryption` (for link
generation). When enabled, it unlocks the Vision flow over XHTTP. Generate the
keys from the panel's VLESS settings.
## Shadowsocks ciphers
Shadowsocks inbounds support both classic ciphers and **Shadowsocks-2022**
(method names starting with `2022-blake3-`). Most ciphers are multi-user;
`2022-blake3-chacha20-poly1305` is single-user.
<Callout type="info">
Transports and security must match on both ends. The client's share link
encodes them (`type=ws`, `security=reality`, `flow=xtls-rprx-vision`, …) —
decode any link with the [share-link inspector](/docs/config/share-links).
</Callout>