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.
2026-10-27 00:04:59 +03:00 · 2026-07-07 23:07:14 +02:00
parent 2c49dbf54e
commit 9b91f0f42e
283 changed files with 44179 additions and 0 deletions
@@ -0,0 +1,120 @@
+---
+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** (через запятую). Сохраните, затем напишите своему боту.
+</Step>
+
+</Steps>
+
+Проверьте свой токен, админские ID и расписание отчётов, прежде чем вставлять их
+в панель:
+
+<TelegramSetupHelper />
+
+## Команды
+
+Эти команды отображаются в меню команд Telegram: `/start`, `/help`, `/status`, `/id`.
+Дополнительные команды:
+
+| Команда            | Кому   | Действие                                                     |
+| ------------------ | ------ | ------------------------------------------------------------ |
+| `/start`, `/help`  | всем   | Приветствие и меню встроенных кнопок                         |
+| `/status`          | всем   | Подтверждает, что бот работает                               |
+| `/id`              | всем   | Показывает ваш числовой Telegram ID                          |
+| `/usage <arg>`     | обоим  | Администраторы ищут клиентов; пользователи смотрят свой расход |
+| `/inbound <remark>`| админ  | Показывает сведения о входящем подключении                   |
+| `/restart`         | админ  | Перезапускает Xray                                          |
+
+Администраторам также доступны сценарии со встроенными кнопками: использование
+сервера, отсортированные отчёты по трафику, сброс трафика, резервные копии БД,
+журналы блокировок, список входящих подключений/клиентов, онлайн-клиенты,
+«скоро исчерпают» и полноценный мастер **добавления клиента**. Обычным
+пользователям доступны кнопки для своего расхода, ссылок на подписку, отдельных
+ссылок и 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 через запятую.       |
+| `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>