mirror of
https://github.com/MHSanaei/3x-ui.git
synced 2026-11-05 12:45:00 +03:00
25f2002654
83ea59fb69
The v3.11.0 bot rebuild left the admin's client card without the subscription link, individual links and QR code, so an admin could not hand a config to a client who cannot reach Telegram yet. The card now carries Links and QR code buttons that open the existing screens. Closes #6984.
138 lines
10 KiB
Plaintext
138 lines
10 KiB
Plaintext
---
|
|
title: Telegram-бот
|
|
description: Подключите Telegram-бота к 3x-ui для выполнения команд, периодических отчётов, оповещений о событиях (вход, CPU, доступность узлов), резервных копий и самообслуживания клиентов.
|
|
icon: Send
|
|
---
|
|
|
|
3x-ui умеет управлять Telegram-ботом для мониторинга, оповещений, резервного
|
|
копирования и удалённого управления. Администраторы получают полный контроль;
|
|
обычные пользователи (привязанные по Telegram ID) могут проверять собственный
|
|
расход трафика и ссылки.
|
|
|
|
<Callout type="info">
|
|
Ищете новости и поддержку сообщества? Присоединяйтесь к официальному
|
|
Telegram-каналу [@XrayUI](https://t.me/XrayUI). Это отдельный канал, не
|
|
связанный с описанным ниже ботом, которого вы запускаете самостоятельно для
|
|
управления собственной панелью.
|
|
</Callout>
|
|
|
|
## Настройка
|
|
|
|
<Steps>
|
|
|
|
<Step>
|
|
### Создайте бота
|
|
|
|
Напишите [@BotFather](https://t.me/BotFather), отправьте `/newbot` и скопируйте
|
|
**токен бота**.
|
|
</Step>
|
|
|
|
<Step>
|
|
### Узнайте свой Telegram ID
|
|
|
|
Получите свой числовой идентификатор пользователя Telegram (после подключения
|
|
бот сообщит его по собственной команде `/id`). Это ваш **админский** ID.
|
|
</Step>
|
|
|
|
<Step>
|
|
### Настройте панель
|
|
|
|
В настройках панели включите Telegram-бота и задайте **токен** и **админские
|
|
chat ID** (через запятую). Сохраните, затем напишите своему боту.
|
|
|
|
Чтобы отправлять уведомления в определённую тему форумной супергруппы, добавьте
|
|
ID темы после двоеточия, например `-1001234567890:42`. ID темы — число после чата
|
|
в ссылке на сообщение темы (`https://t.me/c/1234567890/42/…`). Для темы General
|
|
не указывайте его (или укажите `1`).
|
|
</Step>
|
|
|
|
</Steps>
|
|
|
|
Проверьте свой токен, админские ID и расписание отчётов, прежде чем вставлять их
|
|
в панель:
|
|
|
|
<TelegramSetupHelper />
|
|
|
|
## Команды
|
|
|
|
Эти команды отображаются в меню команд Telegram: `/start`, `/help`, `/status`, `/id`.
|
|
Дополнительные команды:
|
|
|
|
| Команда | Кому | Действие |
|
|
| ------------------ | ------ | ------------------------------------------------------------ |
|
|
| `/start` | всем | Приветствие и меню встроенных кнопок; непривязанный аккаунт получает только свой Telegram ID |
|
|
| `/help` | обоим | Меню встроенных кнопок |
|
|
| `/status` | обоим | Подтверждает, что бот работает |
|
|
| `/id` | всем | Показывает ваш числовой Telegram ID |
|
|
| `/usage <arg>` | обоим | Администраторы ищут клиентов; пользователи смотрят свой расход |
|
|
| `/inbound <remark>`| админ | Показывает сведения о входящем подключении |
|
|
| `/restart` | админ | Перезапускает Xray |
|
|
|
|
Пользователь — это аккаунт Telegram, привязанный хотя бы к одному клиенту. Любой
|
|
другой аккаунт может выполнять только `/start` и `/id`; остальные его команды и
|
|
нажатия кнопок бот игнорирует. Чтобы привязать клиента, нажмите
|
|
**Ссылка-приглашение** в карточке клиента в боте и отправьте ему ссылку `t.me`: первый
|
|
открывший её аккаунт привязывается ко всем клиентам с этим ID подписки. ID
|
|
подписки служит кодом приглашения, поэтому делайте его длинным и случайным.
|
|
У каждого аккаунта пять попыток в час, после чего администраторы получают
|
|
уведомление.
|
|
|
|
Администраторам также доступны сценарии со встроенными кнопками: использование
|
|
сервера, отсортированные отчёты по трафику, сброс трафика, резервные копии БД,
|
|
журналы блокировок, список входящих подключений/клиентов, онлайн-клиенты,
|
|
«скоро исчерпают» и полноценный мастер **добавления клиента**. В карточке
|
|
клиента администратор получает ссылку на подписку, отдельные ссылки и QR-код —
|
|
конфигурацию можно передать клиенту, который ещё не может открыть Telegram.
|
|
Обычным пользователям доступны кнопки для своего расхода, ссылок на подписку,
|
|
отдельных ссылок и QR-кодов.
|
|
|
|
## Отчёты и оповещения
|
|
|
|
- **Периодический отчёт** — по расписанию `tgRunTime` (по умолчанию `@daily`) бот
|
|
отправляет администраторам сведения об использовании сервера (хост, версии,
|
|
время работы, нагрузка, память, онлайн-клиенты, трафик), список
|
|
исчерпанных/истекающих клиентов и — если включён `tgBotBackup` — резервную
|
|
копию базы данных и конфигурации Xray. Клиенты, привязанные по Telegram ID,
|
|
получают собственные предупреждения об истечении срока/исчерпании квоты.
|
|
- **Оповещения о событиях** — выбираются параметром `tgEnabledEvents` (по умолчанию `login.attempt,cpu.high`):
|
|
|
|
| Событие | Когда |
|
|
| --------------- | ------------------------------------------------------- |
|
|
| `login.attempt` | Вход в панель удался или не удался (с IP и именем пользователя) |
|
|
| `cpu.high` | Загрузка CPU превышает `tgCpu` процентов (по умолчанию 80) |
|
|
| `memory.high` | Использование памяти превышает `tgMemory` процентов (по умолчанию 80) |
|
|
| `xray.crash` | Аварийное завершение Xray-core |
|
|
| `outbound.down` / `outbound.up` | Исходящее подключение упало / восстановилось |
|
|
| `node.down` / `node.up` | Узел ушёл в офлайн / вернулся в строй |
|
|
|
|
Время предупреждения определяется параметрами `expireDiff` (дней до истечения
|
|
срока) и `trafficDiff` (ГБ оставшейся квоты); оба по умолчанию равны `0`
|
|
(отключено).
|
|
|
|
## Параметры
|
|
|
|
| Параметр | По умолчанию | Значение |
|
|
| -------------- | -------------------------- | ---------------------------------------------- |
|
|
| `tgBotEnable` | `false` | Главный переключатель вкл./выкл. |
|
|
| `tgBotToken` | _(секрет)_ | Токен Bot API. |
|
|
| `tgBotChatId` | _(нет)_ | **Админские** Telegram ID через запятую; `chatId:topicId` — в тему форума. |
|
|
| `tgBotProxy` | _(нет)_ | Прокси `socks5://`, `http://` или `https://`. |
|
|
| `tgBotAPIServer` | _(по умолчанию)_ | Пользовательский сервер Telegram Bot API. |
|
|
| `tgRunTime` | `@daily` | Расписание отчётов (cron / `@daily` / `@every …`).|
|
|
| `tgBotBackup` | `false` | Прикладывать резервную копию БД к периодическому отчёту. |
|
|
| `tgCpu` / `tgMemory` | `80` / `80` | Пороги оповещений по CPU / памяти (в процентах). |
|
|
| `tgLang` | `en-US` | Язык бота. |
|
|
| `tgEnabledEvents` | `login.attempt,cpu.high`| Какие события доставлять. |
|
|
|
|
<Callout type="warn">
|
|
Токен бота управляет вашим ботом — храните его в секрете и добавляйте только
|
|
**доверенные** админские chat ID. Оповещения о входе никогда не содержат
|
|
паролей.
|
|
</Callout>
|
|
|
|
<Callout type="info">
|
|
Уведомления по электронной почте (SMTP) дублируют те же события
|
|
(`smtpEnabledEvents`), если вы предпочитаете получать оповещения на почту —
|
|
настройте SMTP в настройках панели.
|
|
</Callout>
|