mirror of
https://github.com/MHSanaei/3x-ui.git
synced 2026-10-05 21:52:08 +03:00
pcxzs
7aa5fc085f
* feat(tgbot): gate the bot behind three user levels Every Telegram account that found the bot could run /help, /status and /usage, and tap any client button it could forge: nothing separated an account no admin had bound from a customer. Each update now resolves to stranger, client or admin, and commands are allowlisted per level so a command added later stays admin-only until it is listed. A stranger may run /start and /id only, and /start answers with the ChatID an admin needs to bind it; a stranger's callbacks are answered and dropped. Client detection reads the same tgId lookup as clientOwnedByTgUser, so the level gate and the ownership check agree. The bot also ignores everything outside private chats: authorization keys on the sender while wizard state keys on the chat, and the two are the same identity only in a private chat. * feat(tgbot): bind Telegram accounts through /start deep links Linking a customer meant the customer sending /id and an admin copying the ChatID into the client by hand, which does not scale past a few customers and is easy to get wrong. The admin client card now offers an invite link, t.me/<bot>?start=<subId>, and the first account to open it is bound through the existing SetClientTelegramUserID. A subId already grants the subscription, so binding gives the holder nothing the token did not. A subscription that spans several clients binds all of them, and is refused if any part belongs to another account; re-opening your own link is idempotent. Unknown and already-claimed tokens share one reply, so the link cannot be used to probe for valid subIds. * fix(tgbot): harden invite claims after review Review of the access-level and binding change found five problems: - Concurrent claims of one link all read the client as unbound, all bound and all were told so, while only the last write held. Resolving and binding now share one lock, and a bind that fails part-way through a multi-client subscription undoes the bindings it already made. - A subId has no minimum strength and the bot needs only its public username, so /start was an unthrottled guessing oracle. Non-admin claim attempts are capped at five per account per hour, the first refused one notifies the admins, and the Subscription ID field now says it doubles as the bot invite code. - levelOf expanded every inbound's client JSON on every non-admin update. It now reads the indexed tg_id column of the clients table. - A button tapped in a group chat was dropped unanswered and kept spinning, with nothing logged. It is answered now, and each ignored chat is logged once. - The subId was pasted raw into the t.me link, so '#' or '&' truncated it and Telegram rejects anything outside A-Za-z0-9_-. The payload is now base64url, and a subId too long for the 64-character limit is refused. * fix(tgbot): answer group chats again and make the claim race test bite ignoredChat dropped every non-private chat because wizard state was keyed by chat while authorization keyed on the sender. #6604 on main re-keyed that state by (chat, user) so admins can drive the bot from a group, so after the merge the drop only took the whole bot away from those admins, report keyboards sent to a group included. The level gate already keys on the sender, so group chats need no special case. TestConcurrentClaimsBindOnlyOneAccount passed with inviteClaimMu removed: the first claimant took the pool's idle connection and bound before the rest had opened theirs, so no two ever raced. It now holds the inbound write the binds need until every claimant has resolved, and fails without the lock ("6 accounts told they bound"). TestCommandAllowed restated the commandsByLevel map; TestGateCommand drives the same allowlist through gateCommand. TestIgnoredChat goes with the code it pinned. * docs(tgbot): document access levels and invite links The command table still said /help and /status answer anyone. An account no admin has linked now reaches only /start and /id, and a customer is linked through the client card's Invite Link, whose token is the Subscription ID. Updated in en, fa, ru and zh. --------- Co-authored-by: MHSanaei <ho3ein.sanaei@gmail.com>
122 lines
5.7 KiB
Plaintext
122 lines
5.7 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` | anyone | Greeting and the menu of inline buttons; an unlinked account gets only its Telegram ID |
|
|
| `/help` | both | The menu of inline buttons |
|
|
| `/status` | both | 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 |
|
|
|
|
A user is a Telegram account linked to at least one client. Any other account
|
|
can run only `/start` and `/id`; the bot ignores its other commands and
|
|
button taps. To link a customer, tap **Invite Link** on the client's card in the bot and
|
|
send them the `t.me` link: the first account to open it is linked to every
|
|
client that shares that Subscription ID. The Subscription ID is the invite code,
|
|
so keep it long and random. Each account gets five claim attempts an hour, and
|
|
admins are notified when one runs out.
|
|
|
|
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>
|