mirror of
https://hubproxy.babadafafafafa.cn/https://github.com/MHSanaei/3x-ui.git
synced 2026-09-20 08:04:05 +08:00
9b91f0f42e
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.
113 lines
5.1 KiB
Plaintext
113 lines
5.1 KiB
Plaintext
---
|
|
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>
|