mirror of
https://github.com/MHSanaei/3x-ui.git
synced 2026-11-19 19:45:02 +03: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:
@@ -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>
|
||||
@@ -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>
|
||||
Reference in New Issue
Block a user