mirror of
https://github.com/MHSanaei/3x-ui.git
synced 2026-09-30 19:22:10 +03:00
Egor
a09e136001
* 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>
122 lines
10 KiB
Plaintext
122 lines
10 KiB
Plaintext
---
|
|
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** را پیکربندی کنید؛ درخواستهای دیسکورد بهصورت خودکار از طریق آن هدایت میشوند.
|