docs: add Discord bot to READMEs, architecture, operations guides, and locales (#6513)

* docs: add Discord bot to READMEs, architecture, operations guides, and locales * docs: address review feedback on Discord bot formatting, backup commands, and architecture * docs(discord): fix Persian typo and literal arrows on fa/zh bot pages Senior review of #6513, two LOW findings in the two new pages: - fa/operations/discord-bot.mdx:30 spelled "developers" with Cyrillic "де" in place of Persian "ده", rendering a mixed-script word. - Both pages copied `$\rightarrow$` from the en page. The docs site has no math plugin (nothing in source.config.ts, no remark-math installed), so the built HTML shows the literal string "$\rightarrow$" in every menu path. Replaced with a Unicode arrow on fa and zh; en and ru have carried the same since #6486 and are left for a separate change. --------- Co-authored-by: Sanaei <ho3ein.sanaei@gmail.com>
2026-09-16 15:17:14 +00:00 · 2026-09-14 14:53:22 +05:00
parent 2d7c8c77f7
commit a09e136001
31 changed files with 310 additions and 79 deletions
@@ -40,7 +40,7 @@ flowchart LR
 - **Per-client** traffic quotas, expiry dates, IP limits, online status, and
  one-click share links / QR codes.
 - **Subscriptions** in VLESS, Clash/Mihomo, and JSON formats.
- Operational tooling: **multi-node** management, a **Telegram bot**, backups,
+- Operational tooling: **multi-node** management, **Telegram and Discord bots**, backups,
  Fail2ban-based IP limiting, and a documented REST API.

 ## Under the hood
@@ -46,7 +46,7 @@ leaves the page.
 - **Per-client controls** — traffic quotas, expiry dates, IP limits, share
  links, and QR codes.
 - **Subscriptions** — VLESS, Clash/Mihomo, and JSON formats.
- **Operations** — multi-node management, Telegram bot, backups, and a REST API.
+- **Operations** — multi-node management, Telegram and Discord bots, backups, and a REST API.

 <Callout type="info">
  New to Xray? Read [What is 3x-ui?](/docs/guide) first — it explains how the panel, Xray-core, and
@@ -31,13 +31,9 @@ To restore, stop the panel, put the database back in place, and start it again.
  old schema.
 </Callout>

-## Telegram backup
+## Automated bot backups (Telegram & Discord)

-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.
+If you've configured the [Telegram bot](/docs/operations/telegram-bot) or [Discord bot](/docs/operations/discord-bot), enable **`tgBotBackup`** or **`discordBotBackup`** to attach a backup to the periodic report (on the `tgRunTime` / `discordRunTime` schedule, default daily). The bot sends both the **database** and the **Xray `config.json`** directly to your admin chat or channel, ensuring an off-server copy. Admins can also request a backup on demand from the Telegram bot's menu or using `!backup` in Discord.

 ## SQLite dump / restore

@@ -31,7 +31,7 @@ Provide the node's connection details:
 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)).
+[Telegram bot](/docs/operations/telegram-bot) and [Discord bot](/docs/operations/discord-bot)).

 <Callout type="info">
  Nodes are identified by a stable per-panel GUID, so a node keeps its identity
@@ -67,6 +67,7 @@ icon: SlidersHorizontal

 <Cards>
  <Card title="ربات Telegram" href="/docs/operations/telegram-bot" description="توکن، شناسه‌های چت، هشدارها و گزارش‌ها." />
+  <Card title="ربات Discord" href="/docs/operations/discord-bot" description="توکن، شناسه کانال و هشدارهای رویداد." />
  <Card title="اشتراک" href="/docs/config/subscription" description="سرور اشتراک، قالب‌ها و مسیرها." />
  <Card title="امنیت" href="/docs/operations/security" description="۲FA، محدودیت‌های IP و سخت‌سازی." />
 </Cards>
@@ -41,7 +41,7 @@ flowchart LR
 - سهمیه‌های ترافیک **به‌ازای هر کلاینت**، تاریخ‌های انقضا، محدودیت‌های IP،
  وضعیت آنلاین و لینک‌های اشتراک‌گذاری / کدهای QR با یک کلیک.
 - **اشتراک‌ها** در قالب‌های VLESS، Clash/Mihomo و JSON.
- ابزارهای عملیاتی: مدیریت **چندنودی**، یک **ربات Telegram**، پشتیبان‌گیری،
+- ابزارهای عملیاتی: مدیریت **چندنودی**، **ربات‌های Telegram و Discord**، پشتیبان‌گیری،
  محدودسازی IP مبتنی بر Fail2ban و یک REST API مستندشده.

 ## پشت صحنه
@@ -46,7 +46,7 @@ icon: House
 - **کنترل‌های اختصاصی هر کلاینت** — سهمیه ترافیک، تاریخ انقضا، محدودیت IP، لینک‌های
  اشتراک‌گذاری و کدهای QR.
 - **سابسکریپشن‌ها** — قالب‌های VLESS، Clash/Mihomo و JSON.
- **عملیات** — مدیریت چندنودی، ربات Telegram، پشتیبان‌گیری و یک REST API.
+- **عملیات** — مدیریت چندنودی، ربات‌های Telegram و Discord، پشتیبان‌گیری و یک REST API.

 <Callout type="info">
  با Xray تازه آشنا شده‌اید؟ ابتدا [3x-ui چیست؟](/docs/guide) را بخوانید — توضیح می‌دهد که پنل، Xray-core و
@@ -31,13 +31,9 @@ cp /etc/x-ui/x-ui.db /root/x-ui-backup-$(date +%F).db
  مهاجرت‌های خود را اجرا کند.
 </Callout>

-## پشتیبان‌گیری با Telegram
+## پشتیبان‌گیری خودکار با ربات‌ها (Telegram و Discord)

-اگر [ربات Telegram](/docs/operations/telegram-bot) را پیکربندی کرده‌اید، گزینه‌ی
-**`tgBotBackup`** را فعال کنید تا یک نسخه‌ی پشتیبان به گزارش دوره‌ای ضمیمه شود (بر اساس
-زمان‌بندی `tgRunTime`، به‌صورت پیش‌فرض روزانه). ربات هم **پایگاه‌داده** و هم **`config.json`
-مربوط به Xray** را به چت ادمین شما می‌فرستد، بنابراین همیشه یک نسخه‌ی خارج از سرور در اختیار
-دارید. ادمین‌ها همچنین می‌توانند به‌صورت درخواستی از منوی ربات یک نسخه‌ی پشتیبان بخواهند.
+اگر [ربات Telegram](/docs/operations/telegram-bot) یا [ربات Discord](/docs/operations/discord-bot) را پیکربندی کرده‌اید، گزینه‌ی **`tgBotBackup`** یا **`discordBotBackup`** را فعال کنید تا یک نسخه‌ی پشتیبان به گزارش دوره‌ای ضمیمه شود (بر اساس زمان‌بندی `tgRunTime` / `discordRunTime`، به‌صورت پیش‌فرض روزانه). ربات هم **پایگاه‌داده** و هم **`config.json` مربوط به Xray** را مستقیماً به چت یا کانال ادمین شما می‌فرستد، بنابراین همیشه یک نسخه‌ی خارج از سرور در اختیار دارید. ادمین‌ها همچنین می‌توانند به‌صورت درخواستی از منوی ربات Telegram یا با دستور `!backup` در Discord یک نسخه‌ی پشتیبان دریافت کنند.

 ## دامپ / بازیابی SQLite

@@ -0,0 +1,121 @@
+---
+title: ربات Discord
+description: یک ربات Discord را به 3x-ui متصل کنید تا اعلان‌های بی‌درنگ Embed، گزارش‌های دوره‌ای همراه با نسخه پشتیبان پایگاه‌داده و فرمان‌های تعاملی را در یک کانال دریافت کنید.
+icon: Bot
+---
+
+3x-ui یکپارچگی کاملی با Discord فراهم می‌کند: ارسال هشدارهای بی‌درنگ از طریق گذرگاه رویدادها (`EventBus`)، گزارش‌های دوره‌ای وضعیت سرور به‌همراه فایل پشتیبان پایگاه‌داده، و پردازش فرمان‌های تعاملی از طریق Discord Gateway.
+
+<Callout type="info">
+  اعلان‌های لحظه‌ای و گزارش‌های دوره‌ای از تماس‌های خروجی HTTPS به Discord REST API v10 استفاده می‌کنند. فرمان‌های تعاملی ربات نیز از طریق یک اتصال پس‌زمینه WebSocket امن به Discord Gateway برقرار می‌شوند.
+</Callout>
+
+## راه‌اندازی
+
+<Steps>
+
+<Step>
+### ساخت برنامه و ربات در Discord
+
+1. وارد [Discord Developer Portal](https://discord.com/developers/applications) شوید.
+2. روی **New Application** در بالا سمت راست کلیک کنید، یک نام مشخص کنید (مثلاً `3x-ui Notifier`) و تایید نمایید.
+3. در نوار کناری چپ، به تب **Bot** بروید.
+4. روی **Reset Token** (یا **Add Bot**) کلیک کنید و **Bot Token** را کپی نمایید. این توکن را محفوظ نگه دارید.
+5. در بخش **Privileged Gateway Intents**، گزینه **Message Content Intent** را فعال کنید (برای خواندن فرمان‌هایی مانند `!status` ضروری است).
+</Step>
+
+<Step>
+### دعوت ربات به سرور Discord
+
+1. در پرتال توسعه‌دهندگان، به **OAuth2** → **URL Generator** بروید.
+2. در بخش **Scopes**، گزینه `bot` را علامت بزنید.
+3. در بخش **Bot Permissions**، دسترسی‌های زیر را انتخاب کنید:
+   - **Send Messages** (ارسال پیام)
+   - **Embed Links** (ارسال امبدها)
+   - **Attach Files** (پیوست فایل‌ها — جهت ارسال نسخه پشتیبان پایگاه‌داده ضروری است)
+   - **Read Message History** (خواندن تاریخچه پیام‌ها)
+4. لینک تولیدشده در پایین صفحه را کپی کرده و در مرورگر باز کنید تا ربات به سرور شما اضافه شود.
+</Step>
+
+<Step>
+### کپی کردن Channel ID
+
+1. در کلاینت دیسکورد، حالت توسعه‌دهنده را فعال کنید: **User Settings** → **Advanced** → **Developer Mode** (روشن).
+2. روی کانالی که می‌خواهید اعلان‌ها و تعامل با ربات در آن انجام شود راست‌کلیک کرده و **Copy Channel ID** را انتخاب کنید.
+3. مطمئن شوید ربات دسترسی مشاهده و ارسال پیام در این کانال را دارد.
+</Step>
+
+<Step>
+### پیکربندی پنل
+
+1. در پنل 3x-ui، به **تنظیمات پنل** → **ربات Discord** (یا آدرس `/settings#discord`) بروید.
+2. در بخش **عمومی**:
+   - گزینه **فعال‌سازی اعلان‌های Discord** را روشن کنید.
+   - **Bot Token** و **Channel ID** خود را وارد کنید.
+   - شناسه کاربری عددی دیسکورد خود را در **شناسه‌های کاربری ادمین** وارد نمایید (راست‌کلیک روی نام خودتان → **Copy User ID**؛ شناسه‌های متعدد را با کاما جدا کنید).
+   - زبان مورد نظر خود برای ربات را انتخاب کنید.
+3. در بخش **اعلان‌ها**:
+   - زمان‌بندی گزارش‌ها را تنظیم کنید (مثلاً `@daily`، `@weekly` یا عبارت crontab سفارشی).
+   - در صورت تمایل، گزینه **پشتیبان‌گیری پایگاه‌داده** را فعال کنید تا فایل `x-ui.db` به‌صورت خودکار ضمیمه گزارش‌ها شود.
+   - رویدادهای مورد نظر برای دریافت هشدار و آستانه‌های بار CPU/RAM را تنظیم نمایید.
+4. روی **ارسال اعلان آزمایشی** کلیک کنید تا از صحت ارتباط مطمئن شوید.
+5. برای اعمال تغییرات روی **ذخیره** کلیک نمایید.
+</Step>
+
+</Steps>
+
+## فرمان‌های ربات
+
+هنگام فعال بودن، ربات به فرمان‌های ارسال‌شده در کانال پیکربندی‌شده گوش می‌دهد (پشتیبانی از هر دو پیشوند `!` و `/`). تنها کاربرانی که شناسه‌ی آن‌ها در **شناسه‌های کاربری ادمین** ثبت شده مجاز به اجرای فرمان‌ها هستند؛ پیام‌های سایر کاربران نادیده گرفته می‌شود و در صورت خالی بودن این فیلد، اجرای فرمان‌ها غیرفعال خواهد بود. فرمان `!backup` فایل پایگاه‌داده را در کانال ارسال می‌کند، بنابراین کانالی را انتخاب کنید که فقط ادمین‌ها به آن دسترسی داشته باشند:
+
+| فرمان | عملکرد |
+| ----- | ------ |
+| `!status` | نمایش بار پردازشی سیستم، مصرف RAM، وضعیت هسته Xray، اتصالات و تعداد کاربران آنلاین. |
+| `!report` | تولید و ارسال فوری گزارش کامل وضعیت سرور و پروکسی. |
+| `!backup` | ارسال فوری فایل نسخه پشتیبان پایگاه‌داده (`x-ui.db`) و `config.json`. |
+| `!usage <email>` | بررسی مصرف ترافیک (دانلود/آپلود)، سقف حجم و تاریخ انقضای یک کلاینت خاص. |
+| `!inbounds` | فهرست تمام اینباندهای فعال به همراه پورت، پروتکل، ترافیک و تعداد کلاینت‌ها. |
+| `!restart` | راه‌اندازی مجدد ایمن هسته Xray بدون نیاز به ری‌استارت پنل تحت وب. |
+| `!help` | نمایش فهرست فرمان‌های در دسترس ربات. |
+
+## هشدارهای رویدادها
+
+هشدارها به‌صورت ساختاریافته در قالب Discord Embed همراه با رنگ‌بندی تشخیصی ارسال می‌شوند:
+
+| رویداد | نشانگر | توضیح |
+| ------ | ------ | ------ |
+| `xray.crash` | 🔴 قرمز | کرش کردن هسته Xray؛ همراه با علت و زمان دقیق |
+| `outbound.down` | 🔴 قرمز | شکست در آزمون اتصال اوتباند |
+| `outbound.up` | 🟢 سبز | برقراری مجدد اتصال اوتباند |
+| `node.down` | 🔴 قرمز | خارج از دسترس شدن یا قطع اتصال نود راه دور |
+| `node.up` | 🟢 سبز | اتصال مجدد و بازگشت سلامت نود راه دور |
+| `cpu.high` | 🟠 نارنجی | عبور میزان مصرف CPU از آستانه تعیین‌شده (`discordCpu`) |
+| `memory.high` | 🟠 نارنجی | عبور میزان مصرف RAM از آستانه تعیین‌شده (`discordMemory`) |
+| `login.attempt` | 🟢 / 🔴 | تلاش برای ورود به پنل تحت وب همراه با نام کاربری، IP و وضعیت ورود |
+
+<Callout type="warn">
+  هشدارهای ورود فقط نام کاربری و آدرس IP کلاینت را گزارش می‌دهند. رمزهای عبور هرگز ذخیره یا ارسال نمی‌شوند.
+</Callout>
+
+## راهنمای تنظیمات
+
+| پارامتر | مقدار پیش‌فرض | توضیح |
+| ------- | ------------- | ------ |
+| `discordBotEnable` | `false` | کلید اصلی فعال‌سازی ربات و هشدارهای Discord. |
+| `discordBotToken` | _(محرمانه)_ | توکن ربات دریافتی از Discord Developer Portal. |
+| `discordChannelId` | _(خالی)_ | شناسه عددی (Snowflake ID) کانال مقصد در دیسکورد. |
+| `discordAdminIds` | _(خالی)_ | شناسه‌های عددی کاربران مجاز به اجرای فرمان‌ها (با کاما جدا شوند). |
+| `discordLang` | `en-US` | زبان پیام‌ها و گزارش‌های ارسالی ربات دیسکورد. |
+| `discordRunTime` | `@daily` | زمان‌بندی Cron برای ارسال خودکار گزارش وضعیت. |
+| `discordBotBackup` | `false` | ضمیمه کردن خودکار فایل نسخه پشتیبان (`x-ui.db`) به گزارش‌ها. |
+| `discordEnabledEvents` | `login.attempt,cpu.high` | فهرست رویدادهای فعال برای ارسال هشدار (با کاما جدا شوند). |
+| `discordCpu` | `80` | آستانه درصد مصرف پردازنده (CPU) جهت ارسال هشدار (۰ تا ۱۰۰). |
+| `discordMemory` | `80` | آستانه درصد مصرف رم (RAM) جهت ارسال هشدار (۰ تا ۱۰۰). |
+
+## عیب‌یابی
+
+- **خطای invalid bot token (401)**: مطمئن شوید که توکن ربات را به‌طور کامل از تب **Bot** کپی کرده‌اید، نه Client Secret یا Application ID.
+- **خطای missing permissions (403)**: بررسی کنید که رول ربات در کانال یا دسته‌بندی مربوطه دارای دسترسی‌های **Send Messages**، **Embed Links** و **Attach Files** باشد.
+- **عدم پاسخگویی به فرمان‌ها**: بررسی کنید که شناسه‌ی عددی شما در **Admin User IDs** ثبت شده باشد. همچنین مطمئن شوید گزینه **Message Content Intent** در پرتال دیسکورد روشن است و پنل را ری‌استارت کنید؛ دیسکورد در صورت نبود این دسترسی اتصال را قطع می‌کند.
+- **خطای channel not found (404)**: از صحت Channel ID اطمینان حاصل کنید و بررسی کنید که ربات حتماً در سروری که کانال در آن قرار دارد عضو باشد.
+- **پراکسی برای درخواست‌های خروجی**: اگر سرور شما برای اتصال به دیسکورد به پروکسی نیاز دارد، در تنظیمات پنل گزینه **Panel Outbound** را پیکربندی کنید؛ درخواست‌های دیسکورد به‌صورت خودکار از طریق آن هدایت می‌شوند.
@@ -25,7 +25,7 @@ icon: Boxes
 | **Inbound sync**  | همهٔ inboundها (`all`) یا انتخاب‌شده (`selected`) بر اساس تگ.          |
 | **Outbound tag**  | به‌اختیار از طریق یک outbound نام‌دار به نود برسید (پل خروجی).         |

-مستر هنگام افزودن یا آزمودن یک نود، قابلیت دسترسی به آن را بررسی می‌کند. سپس هر چند ثانیه یک **ضربان قلب (heartbeat)** ارسال می‌کند، وضعیت نود را به‌روزرسانی می‌کند (`online` / `offline`) و رویدادهای `node.up` / `node.down` را منتشر می‌کند (به [بات Telegram](/docs/operations/telegram-bot) مراجعه کنید).
+مستر هنگام افزودن یا آزمودن یک نود، قابلیت دسترسی به آن را بررسی می‌کند. سپس هر چند ثانیه یک **ضربان قلب (heartbeat)** ارسال می‌کند، وضعیت نود را به‌روزرسانی می‌کند (`online` / `offline`) و رویدادهای `node.up` / `node.down` را منتشر می‌کند (به [بات Telegram](/docs/operations/telegram-bot) و [بات Discord](/docs/operations/discord-bot) مراجعه کنید).

 <Callout type="info">
  نودها با یک GUID پایدار به‌ازای هر پنل شناسایی می‌شوند، بنابراین یک نود هویت خود
@@ -40,7 +40,7 @@ flowchart LR
 - **Поклиентские** квоты трафика, даты истечения, ограничения по IP, статус «онлайн» и
  ссылки для подключения / QR-коды в один клик.
 - **Подписки** в форматах VLESS, Clash/Mihomo и JSON.
- Инструменты для эксплуатации: управление **несколькими узлами**, **Telegram-бот**, резервные копии,
+- Инструменты для эксплуатации: управление **несколькими узлами**, **Telegram- и Discord-боты**, резервные копии,
  ограничение по IP на базе Fail2ban и документированный REST API.

 ## Что под капотом
@@ -46,7 +46,7 @@ icon: House
 - **Управление каждым клиентом** — квоты трафика, даты истечения, ограничения по IP, ссылки
  для подключения и QR-коды.
 - **Подписки** — форматы VLESS, Clash/Mihomo и JSON.
- **Эксплуатация** — управление несколькими узлами, Telegram-бот, резервные копии и REST API.
+- **Эксплуатация** — управление несколькими узлами, Telegram- и Discord-боты, резервные копии и REST API.

 <Callout type="info">
  Впервые работаете с Xray? Сначала прочитайте [Что такое 3x-ui?](/docs/guide) — там объясняется, как панель, Xray-core и
@@ -33,14 +33,9 @@ cp /etc/x-ui/x-ui.db /root/x-ui-backup-$(date +%F).db
  выполнить миграции, а не навязывайте старую схему.
 </Callout>

-## Резервное копирование через Telegram
+## Автоматические бэкапы ботов (Telegram и Discord)

-Если вы настроили [Telegram-бота](/docs/operations/telegram-bot), включите
-**`tgBotBackup`**, чтобы прикреплять резервную копию к периодическому отчёту (по
-расписанию `tgRunTime`, по умолчанию ежедневно). Бот отправляет в чат
-администратора как **базу данных**, так и **`config.json` Xray**, поэтому у вас
-всегда будет копия за пределами сервера. Администраторы также могут запросить
-резервную копию по требованию через меню бота.
+Если вы настроили [Telegram-бота](/docs/operations/telegram-bot) или [Discord-бота](/docs/operations/discord-bot), включите **`tgBotBackup`** или **`discordBotBackup`**, чтобы прикреплять резервную копию к периодическому отчёту (по расписанию `tgRunTime` / `discordRunTime`, по умолчанию ежедневно). Бот отправляет в чат или канал администратора как **базу данных**, так и **`config.json` Xray**, поэтому у вас всегда будет копия за пределами сервера. Администраторы также могут запросить резервную копию по требованию через меню бота Telegram или с помощью команды `!backup` в Discord.

 ## Дамп / восстановление SQLite

@@ -32,7 +32,7 @@ API этого узла. Главная панель опрашивает каж
 Главная панель проверяет доступность при добавлении или тестировании узла. Затем
 она каждые несколько секунд отправляет **heartbeat**, обновляя статус узла
 (`online` / `offline`) и генерируя события `node.up` / `node.down` (см.
-[Telegram-бот](/docs/operations/telegram-bot)).
+[Telegram-бот](/docs/operations/telegram-bot) и [Discord-бот](/docs/operations/discord-bot)).

 <Callout type="info">
  Узлы идентифицируются по стабильному GUID, уникальному для каждой панели,
@@ -63,6 +63,7 @@ icon: SlidersHorizontal

 <Cards>
  <Card title="Telegram 机器人" href="/docs/operations/telegram-bot" description="令牌、聊天 ID、告警与报告。" />
+  <Card title="Discord 机器人" href="/docs/operations/discord-bot" description="令牌、频道 ID 与事件告警。" />
  <Card title="订阅" href="/docs/config/subscription" description="订阅服务器、格式与路径。" />
  <Card title="安全" href="/docs/operations/security" description="2FA、IP 限制与加固。" />
 </Cards>
@@ -31,7 +31,7 @@ flowchart LR
 - 一流的 **REALITY** 与 **XTLS-Vision** 支持，带来隐蔽、快速的传输方式。
 - **按客户端**设置的流量配额、到期日期、IP 限制、在线状态，以及一键生成分享链接 / 二维码。
 - 支持 VLESS、Clash/Mihomo 和 JSON 格式的**订阅**。
- 运维工具：**多节点**管理、**Telegram 机器人**、备份、基于 Fail2ban 的 IP 限制，以及一套有文档说明的 REST API。
+- 运维工具：**多节点**管理、**Telegram 和 Discord 机器人**、备份、基于 Fail2ban 的 IP 限制，以及一套有文档说明的 REST API。

 ## 底层原理

@@ -43,7 +43,7 @@ icon: House
 - **细粒度的客户端管理** —— 流量配额、到期日期、IP 限制、分享
  链接以及 QR 码。
 - **订阅** —— 支持 VLESS、Clash/Mihomo 以及 JSON 格式。
- **运维能力** —— 多节点管理、Telegram 机器人、备份以及 REST API。
+- **运维能力** —— 多节点管理、Telegram 和 Discord 机器人、备份以及 REST API。

 <Callout type="info">
  初次接触 Xray？请先阅读 [什么是 3x-ui？](/docs/guide) —— 它解释了面板、Xray-core 与
@@ -28,13 +28,9 @@ cp /etc/x-ui/x-ui.db /root/x-ui-backup-$(date +%F).db
  运行迁移，而不要强行套用旧的数据库结构。
 </Callout>

-## Telegram 备份
+## 机器人自动备份（Telegram 与 Discord）

-如果你已配置 [Telegram 机器人](/docs/operations/telegram-bot)，启用
-**`tgBotBackup`** 即可在周期性报告中附带一份备份（按 `tgRunTime`
-计划执行，默认每天一次）。机器人会将**数据库**与 Xray 的
-**`config.json`** 一并发送到你的管理员聊天，从而让你始终拥有一份服务器之外的副本。
-管理员也可以从机器人的菜单中按需请求备份。
+如果你已配置 [Telegram 机器人](/docs/operations/telegram-bot) 或 [Discord 机器人](/docs/operations/discord-bot)，启用 **`tgBotBackup`** 或 **`discordBotBackup`** 即可在周期性报告中附带一份备份（按 `tgRunTime` / `discordRunTime` 计划执行，默认每天一次）。机器人会将**数据库**与 Xray 的 **`config.json`** 一并发送到你的管理员聊天或频道，从而让你始终拥有一份服务器之外的副本。管理员也可以随时从 Telegram 机器人的菜单或使用 Discord 的 `!backup` 命令按需请求备份。

 ## SQLite 转储 / 恢复

@@ -0,0 +1,121 @@
+---
+title: Discord 机器人
+description: 将 Discord 机器人接入 3x-ui，在指定频道接收实时的面板事件 Embed 告警、周期性健康报告（含数据库备份）以及执行交互式控制命令。
+icon: Bot
+---
+
+3x-ui 提供了完整的 Discord 集成支持：通过事件总线（`EventBus`）实时推送事件告警、通过定时任务发送包含数据库备份的服务器状态报告，以及通过 Discord Gateway 执行交互式管理命令。
+
+<Callout type="info">
+  Discord 实时通知和周期性报告使用出站 HTTPS REST API v10 请求。交互式机器人命令则通过与 Discord Gateway 建立的后台安全 WebSocket 连接实现。
+</Callout>
+
+## 完成配置
+
+<Steps>
+
+<Step>
+### 创建 Discord 应用程序与机器人
+
+1. 打开 [Discord 开发者门户](https://discord.com/developers/applications) 并登录。
+2. 点击右上角的 **New Application**，输入名称（例如 `3x-ui Notifier`）并确认创建。
+3. 在左侧菜单中，进入 **Bot** 标签页。
+4. 点击 **Reset Token**（如果尚未创建机器人则点击 **Add Bot**），并复制生成的 **Bot Token**。请妥善保管该令牌。
+5. 在 **Privileged Gateway Intents** 区域，勾选启用 **Message Content Intent**（机器人读取 `!status` 等前缀命令所必需）。
+</Step>
+
+<Step>
+### 邀请机器人加入你的 Discord 服务器
+
+1. 在开发者门户左侧导航栏中，进入 **OAuth2** → **URL Generator**。
+2. 在 **Scopes** 中勾选 `bot`。
+3. 在下方展开的 **Bot Permissions** 中，勾选以下权限：
+   - **Send Messages**（发送消息）
+   - **Embed Links**（嵌入链接）
+   - **Attach Files**（附加文件 —— 发送数据库备份附件所必需）
+   - **Read Message History**（读取消息历史）
+4. 复制页面底部生成的邀请链接，在浏览器中打开并将机器人添加到你的目标服务器。
+</Step>
+
+<Step>
+### 复制频道 ID
+
+1. 在 Discord 客户端中开启开发者模式：**用户设置** → **高级** → **开发者模式**（开启）。
+2. 右键点击希望接收告警和执行命令的频道，选择**复制频道 ID**（Copy Channel ID）。
+3. 确保机器人拥有该频道的查看和发送消息权限。
+</Step>
+
+<Step>
+### 配置面板
+
+1. 在 3x-ui 面板中，打开**面板设置** → **Discord 机器人**（或直接访问 `/settings#discord`）。
+2. 在**通用**区域：
+   - 开启**启用 Discord 通知**。
+   - 填入你的 **Discord Bot Token** 和 **频道 ID**。
+   - 在**管理员用户 ID**中填入你自己的 Discord 用户数字 ID（右键你的个人头像 → **复制用户 ID**；多个 ID 请用英文逗号分隔）。
+   - 选择偏好的 **Discord 机器人语言**。
+3. 在**通知**区域：
+   - 设置**通知时间**（如 `@daily`、`@weekly` 或自定义 Cron 表达式）。
+   - 如需自动备份，可开启**数据库备份**，定时报告中将自动附带 `x-ui.db` 备份文件。
+   - 勾选需要触发告警的事件类型，并配置 CPU / 内存阈值。
+4. 点击**发送测试通知**以验证连通性。你的 Discord 频道应立刻收到一条测试 Embed 消息。
+5. 点击**保存**应用配置。
+</Step>
+
+</Steps>
+
+## 机器人命令
+
+启用后，机器人将在配置的 Discord 频道内监听命令（同时支持 `!` 和 `/` 前缀）。仅列在**管理员用户 ID**中的用户可以执行命令；来自其他用户的消息将被忽略，若未配置管理员 ID 则关闭命令响应。`!backup` 与定时备份会将数据库文件发送至频道中，因此请务必选择仅管理员可见的频道：
+
+| 命令 | 说明 |
+| ---- | ---- |
+| `!status` | 查看系统负载、内存占用、CPU 使用率、核心状态、TCP/UDP 连接数及当前在线用户。 |
+| `!report` | 立即生成并发送完整的服务器与代理状态报告 Embed。 |
+| `!backup` | 立即导出并发送当前数据库备份文件（`x-ui.db`）与 `config.json`。 |
+| `!usage <email>` | 查询指定客户端的流量用量（上传/下载）、配额上限及到期时间。 |
+| `!inbounds` | 列出所有活动的入站连接、监听端口、协议、已用流量及客户端数量。 |
+| `!restart` | 安全重启 Xray 核心，无需重启整个 Web 面板。 |
+| `!help` | 显示机器人可用命令列表及使用说明。 |
+
+## 事件告警
+
+告警以 Discord Embed 格式发送，带有颜色标识和关键诊断信息：
+
+| 事件类型 | 标识 | 说明 |
+| -------- | ---- | ---- |
+| `xray.crash` | 🔴 红色 | Xray 核心崩溃；包含崩溃原因及时间戳 |
+| `outbound.down` | 🔴 红色 | 出站连通性探测失败 |
+| `outbound.up` | 🟢 绿色 | 出站连通性已恢复 |
+| `node.down` | 🔴 红色 | 远程子节点离线或不可达 |
+| `node.up` | 🟢 绿色 | 远程子节点重新连接且健康 |
+| `cpu.high` | 🟠 橙色 | 服务器 CPU 使用率超过设定阈值（`discordCpu`） |
+| `memory.high` | 🟠 橙色 | 服务器内存使用率超过设定阈值（`discordMemory`） |
+| `login.attempt` | 🟢 / 🔴 | Web 面板登录尝试（包含用户名、客户端 IP 及登录结果） |
+
+<Callout type="warn">
+  登录告警仅包含尝试的用户名及客户端 IP 地址。系统绝不会记录或传输密码明文。
+</Callout>
+
+## 设置参考
+
+| 设置项 | 默认值 | 说明 |
+| ------ | ------ | ---- |
+| `discordBotEnable` | `false` | Discord 机器人与告警总开关。 |
+| `discordBotToken` | _(保密)_ | 从 Discord 开发者门户获取的 Bot Token。 |
+| `discordChannelId` | _(无)_ | 接收消息的目标 Discord 频道 Snowflake ID（17–20 位数字）。 |
+| `discordAdminIds` | _(无)_ | 允许执行命令的 Discord 用户数字 ID（逗号分隔）。留空则禁用命令交互。 |
+| `discordLang` | `en-US` | Discord 机器人消息与报告使用的语言。 |
+| `discordRunTime` | `@daily` | 发送周期性状态报告的 Cron 表达式或预设计划。 |
+| `discordBotBackup` | `false` | 是否在周期性报告中自动附带数据库备份文件（`x-ui.db`）。 |
+| `discordEnabledEvents` | `login.attempt,cpu.high` | 触发通知的事件类型列表（逗号分隔）。 |
+| `discordCpu` | `80` | 触发 CPU 告警的利用率百分比阈值（0–100）。 |
+| `discordMemory` | `80` | 触发内存告警的利用率百分比阈值（0–100）。 |
+
+## 故障排查
+
+- **测试报错 "invalid bot token (401)"**：请确认复制的是开发者门户 **Bot** 标签页中的 Bot Token，而非 Client Secret 或 Application ID。
+- **测试报错 "missing permissions (403)"**：请检查机器人角色在目标频道或对应分类目录中是否拥有 **Send Messages**、**Embed Links** 以及 **Attach Files** 权限。
+- **命令无响应**：请确认你的 Discord 用户 ID 已填入**管理员用户 ID**中。然后检查开发者门户中该机器人的 **Message Content Intent** 是否已开启，并重启面板（若缺少该意图，Discord 会直接关闭连接且不再重试）。
+- **测试报错 "channel not found (404)"**：请检查频道 ID 是否为纯数字，并确认机器人已加入拥有该频道的服务器。
+- **出站代理需求**：若你的服务器所在网络环境访问 Discord 需经过代理，请在面板设置中配置**面板出站代理**（Panel Outbound），Discord 的所有请求将自动经由该代理发出。
@@ -25,7 +25,7 @@ icon: Boxes
 | **Inbound sync**  | `all` 入站，或按标签 `selected`。                                     |
 | **Outbound tag**  | 可选地**通过**指定的出站到达节点（出口桥接）。                        |

-当你添加或测试节点时，主控会验证其可达性。随后它每隔几秒发送一次**心跳**，更新节点的状态（`online` / `offline`）并发出 `node.up` / `node.down` 事件（参见 [Telegram 机器人](/docs/operations/telegram-bot)）。
+当你添加或测试节点时，主控会验证其可达性。随后它每隔几秒发送一次**心跳**，更新节点的状态（`online` / `offline`）并发出 `node.up` / `node.down` 事件（参见 [Telegram 机器人](/docs/operations/telegram-bot) 与 [Discord 机器人](/docs/operations/discord-bot)）。

 <Callout type="info">
  节点通过每个面板稳定的 GUID 来标识，因此节点在重启后仍能保持其身份。节点本身也可以管理更多节点——主控会将这些以只读的**传递性**子节点形式呈现（Node 1 → Node 2 → Node 3）。