From a09e136001b877510048b95d5d3bfb381c9d284b Mon Sep 17 00:00:00 2001 From: Egor Date: Mon, 14 Sep 2026 14:53:22 +0500 Subject: [PATCH] docs: add Discord bot to READMEs, architecture, operations guides, and locales (#6513) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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 --- CLAUDE.md | 4 +- README.ar_EG.md | 2 +- README.es_ES.md | 2 +- README.fa_IR.md | 2 +- README.md | 2 +- README.ru_RU.md | 2 +- README.tr_TR.md | 2 +- README.zh_CN.md | 2 +- docs/README.md | 2 +- docs/architecture.md | 51 ++++---- docs/content/docs/en/guide/index.mdx | 2 +- docs/content/docs/en/index.mdx | 2 +- .../docs/en/operations/backup-restore.mdx | 8 +- .../content/docs/en/operations/multi-node.mdx | 2 +- docs/content/docs/fa/config/panel.mdx | 1 + docs/content/docs/fa/guide/index.mdx | 2 +- docs/content/docs/fa/index.mdx | 2 +- .../docs/fa/operations/backup-restore.mdx | 8 +- .../docs/fa/operations/discord-bot.mdx | 121 ++++++++++++++++++ .../content/docs/fa/operations/multi-node.mdx | 2 +- docs/content/docs/ru/guide/index.mdx | 2 +- docs/content/docs/ru/index.mdx | 2 +- .../docs/ru/operations/backup-restore.mdx | 9 +- .../content/docs/ru/operations/multi-node.mdx | 2 +- docs/content/docs/zh/config/panel.mdx | 1 + docs/content/docs/zh/guide/index.mdx | 2 +- docs/content/docs/zh/index.mdx | 2 +- .../docs/zh/operations/backup-restore.mdx | 8 +- .../docs/zh/operations/discord-bot.mdx | 121 ++++++++++++++++++ .../content/docs/zh/operations/multi-node.mdx | 2 +- docs/lib/site-i18n.ts | 17 +-- 31 files changed, 310 insertions(+), 79 deletions(-) create mode 100644 docs/content/docs/fa/operations/discord-bot.mdx create mode 100644 docs/content/docs/zh/operations/discord-bot.mdx diff --git a/CLAUDE.md b/CLAUDE.md index 359a27582..13342bfb6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -58,8 +58,8 @@ file locations when it can answer in one hop. - `internal/web/` — Gin server (embeds `dist/` + `translation/`). - `controller/` — panel + REST API handlers; OpenAPI at /panel/api/openapi.json. - `service/` — business logic (InboundService, SettingService, XrayService, - node sync); subpackages tgbot/, email/, outbound/, panel/, integration/. - - `job/` — 18 cron jobs (traffic, fail2ban IP-limit, node heartbeat/sync, LDAP, + node sync); subpackages tgbot/, discord/, email/, outbound/, panel/, integration/. + - `job/` — 19 cron jobs (traffic, fail2ban IP-limit, node heartbeat/sync, LDAP, CPU/memory watchdogs, …); full table in `docs/architecture.md` §5.4. - `middleware/`, `entity/`, `global/`, `session/` (CSRF), `network/`, `runtime/` (master/sub-node over mTLS), `websocket/`. diff --git a/README.ar_EG.md b/README.ar_EG.md index 3e737940d..7204d4847 100644 --- a/README.ar_EG.md +++ b/README.ar_EG.md @@ -37,7 +37,7 @@ - **دعم العقد المتعددة** — إدارة وتوسيع عبر عدة خوادم من لوحة واحدة، بما في ذلك استنساخ الاتصالات الواردة على عقد أخرى. - **الاتصالات الصادرة والتوجيه** — WARP، NordVPN، PIA، قواعد توجيه مخصصة، موازنات تحميل مع تجاوز الفشل بين الموازنات، وتسلسل الوكلاء الصادرة. ويمكن تصفّح فئات geosite و geoip المضمّنة مباشرةً من محرر القواعد. - **خادم اشتراك مدمج** — إخراج raw و JSON و Clash يُختار تلقائيًا حسب User-Agent الخاص بالعميل، مع [قوالب صفحات مخصصة](docs/custom-subscription-templates.md). -- **روبوت تيليجرام** للمراقبة والإدارة عن بُعد. +- **روبوتات تيليجرام وديسكورد** للمراقبة والإدارة عن بُعد. - **واجهة RESTful API** مع رموز وصول محدودة النطاق وقابلة لانتهاء الصلاحية، ومرجع API داخل اللوحة. - **لوحة قابلة للتثبيت (PWA)** — ثبّت 3X-UI على سطح المكتب أو شاشة هاتفك الرئيسية. - **تخزين مرن** — SQLite (افتراضي) أو PostgreSQL. diff --git a/README.es_ES.md b/README.es_ES.md index 8387ccf75..3a96d7ba6 100644 --- a/README.es_ES.md +++ b/README.es_ES.md @@ -37,7 +37,7 @@ Construido como un fork mejorado del proyecto X-UI original, 3X-UI añade un sop - **Soporte multinodo** — gestiona y escala a través de varios servidores desde un único panel, incluida la clonación de entradas en otros nodos. - **Salida y enrutamiento** — WARP, NordVPN, PIA, reglas de enrutamiento personalizadas, balanceadores de carga con conmutación por error entre balanceadores y encadenamiento de proxy de salida. Las categorías geosite y geoip incluidas se pueden explorar directamente desde el editor de reglas. - **Servidor de suscripción integrado** — salida raw, JSON y Clash, seleccionada automáticamente según el User-Agent del cliente, además de [plantillas de página personalizables](docs/custom-subscription-templates.md). -- **Bot de Telegram** para monitorización y gestión remotas. +- **Bots de Telegram y Discord** para monitorización y gestión remotas. - **API RESTful** con tokens de alcance limitado y caducidad opcional, y una referencia de la API dentro del panel. - **Panel instalable (PWA)** — ancla 3X-UI al escritorio o a la pantalla de inicio del móvil. - **Almacenamiento flexible** — SQLite (predeterminado) o PostgreSQL. diff --git a/README.fa_IR.md b/README.fa_IR.md index 6da2425df..aaaf25f03 100644 --- a/README.fa_IR.md +++ b/README.fa_IR.md @@ -37,7 +37,7 @@ - **پشتیبانی از چند نود** — مدیریت و مقیاس‌دهی روی چندین سرور از یک پنل واحد، از جمله کلون‌کردن اینباندها روی نودهای دیگر. - **اوتباند و مسیریابی** — WARP، NordVPN، PIA، قوانین مسیریابی سفارشی، متعادل‌کننده‌های بار (load balancer) با فال‌بک بین متعادل‌کننده‌ها و زنجیره‌کردن پراکسی اوتباند. دسته‌بندی‌های geosite و geoip همراه‌شده مستقیماً از ویرایشگر قوانین قابل مرور هستند. - **سرور سابسکریپشن داخلی** — خروجی raw، JSON و Clash که بر پایه‌ی User-Agent کلاینت به‌صورت خودکار انتخاب می‌شود، به‌همراه [قالب‌های صفحه‌ی سفارشی](docs/custom-subscription-templates.md). -- **ربات تلگرام** برای نظارت و مدیریت از راه دور. +- **ربات‌های تلگرام و دیسکورد** برای نظارت و مدیریت از راه دور. - **‏RESTful API** با توکن‌های محدودشده (scoped) و دارای انقضای اختیاری، به‌همراه مرجع API درون‌پنل. - **پنل قابل نصب (PWA)** — 3X-UI را به دسکتاپ یا صفحه‌ی اصلی گوشی خود سنجاق کنید. - **ذخیره‌سازی منعطف** — SQLite (پیش‌فرض) یا PostgreSQL. diff --git a/README.md b/README.md index 6720da6b8..adc47d7b4 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ Built as an enhanced fork of the original X-UI project, 3X-UI adds broader proto - **Multi-node support** — manage and scale across multiple servers from a single panel, including cloning inbounds onto other nodes. - **Outbound & routing** — WARP, NordVPN, PIA, custom routing rules, load balancers with balancer-to-balancer fallback, and outbound proxy chaining. Bundled geosite and geoip categories are browsable straight from the rule editor. - **Built-in subscription server** — raw, JSON, and Clash output, auto-selected from the client's User-Agent, plus [custom page templates](docs/custom-subscription-templates.md). -- **Telegram bot** for remote monitoring and management. +- **Telegram and Discord bots** for remote monitoring and management. - **RESTful API** with scoped, optionally expiring tokens and an in-panel API reference. - **Installable panel (PWA)** — pin 3X-UI to a desktop or phone home screen. - **Flexible storage** — SQLite (default) or PostgreSQL. diff --git a/README.ru_RU.md b/README.ru_RU.md index 1a5f16878..3a64ab15b 100644 --- a/README.ru_RU.md +++ b/README.ru_RU.md @@ -37,7 +37,7 @@ - **Поддержка нескольких узлов** — управление и масштабирование на несколько серверов из одной панели, включая клонирование входящих на другие узлы. - **Исходящие подключения и маршрутизация** — WARP, NordVPN, PIA, пользовательские правила маршрутизации, балансировщики нагрузки с переключением между балансировщиками и цепочки исходящих прокси. Встроенные категории geosite и geoip можно просматривать прямо в редакторе правил. - **Встроенный сервер подписок** — вывод в форматах raw, JSON и Clash, выбираемый автоматически по User-Agent клиента, а также [пользовательские шаблоны страниц](docs/custom-subscription-templates.md). -- **Telegram-бот** для удалённого мониторинга и управления. +- **Telegram- и Discord-боты** для удалённого мониторинга и управления. - **RESTful API** с токенами ограниченной области действия и необязательным сроком действия, а также справочником API внутри панели. - **Устанавливаемая панель (PWA)** — закрепите 3X-UI на рабочем столе или главном экране телефона. - **Гибкое хранилище** — SQLite (по умолчанию) или PostgreSQL. diff --git a/README.tr_TR.md b/README.tr_TR.md index 7f97e749d..d89298c96 100644 --- a/README.tr_TR.md +++ b/README.tr_TR.md @@ -37,7 +37,7 @@ Orijinal X-UI projesinin geliştirilmiş bir çatallaması (fork) olarak inşa e - **Çoklu düğüm (Multi-node) desteği** — Tek bir panel üzerinden birden fazla sunucuyu yönetin ve ölçeklendirin; gelen bağlantıları diğer düğümlere klonlayın. - **Giden bağlantı (Outbound) ve yönlendirme** — WARP, NordVPN, PIA, özel yönlendirme kuralları, dengeleyiciler arası yük devretme destekli yük dengeleyiciler (load balancers) ve giden bağlantı proxy zincirleme (proxy chaining). Pakete dahil geosite ve geoip kategorileri doğrudan kural düzenleyicisinden taranabilir. - **Dahili abonelik sunucusu** — İstemcinin User-Agent bilgisine göre otomatik seçilen raw, JSON ve Clash çıktısı ve [özel sayfa şablonları](docs/custom-subscription-templates.md). -- Uzaktan izleme ve yönetim için **Telegram botu**. +- Uzaktan izleme ve yönetim için **Telegram ve Discord botları**. - Kapsamı sınırlanmış, isteğe bağlı olarak süresi dolan token'lar ve panel içi API referansı sunan **RESTful API**. - **Kurulabilir panel (PWA)** — 3X-UI'yi masaüstüne veya telefon ana ekranına sabitleyin. - **Esnek depolama** — SQLite (varsayılan) veya PostgreSQL. diff --git a/README.zh_CN.md b/README.zh_CN.md index 913d15edf..277af2eaa 100644 --- a/README.zh_CN.md +++ b/README.zh_CN.md @@ -37,7 +37,7 @@ - **多节点支持** — 从单一面板管理并扩展到多台服务器，并可将入站克隆到其他节点。 - **出站与路由** — WARP、NordVPN、PIA、自定义路由规则、支持均衡器间回退的负载均衡器，以及出站代理链。内置的 geosite 与 geoip 分类可直接在规则编辑器中浏览。 - **内置订阅服务器** — 提供 raw、JSON 和 Clash 输出，可依据客户端 User-Agent 自动选择，并支持[自定义页面模板](docs/custom-subscription-templates.md)。 -- **Telegram 机器人**，用于远程监控和管理。 +- **Telegram 和 Discord 机器人**，用于远程监控和管理。 - **RESTful API**，支持带作用域、可设置有效期的令牌，并提供面板内置的 API 参考文档。 - **可安装面板 (PWA)** — 将 3X-UI 固定到桌面或手机主屏幕。 - **灵活的存储** — SQLite（默认）或 PostgreSQL。 diff --git a/docs/README.md b/docs/README.md index d73d2457d..d97d507d3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -43,7 +43,7 @@ The documentation walks you through 3x-ui from first install to day-to-day opera - **Getting Started** — installation, first login, and updating or uninstalling the panel. - **Configuration** — the panel, inbounds, REALITY, transports, clients, subscriptions, and share links. -- **Operations** — reverse proxy, multi-node setups, outbounds & routing, backup/restore, the Telegram bot, and security. +- **Operations** — reverse proxy, multi-node setups, outbounds & routing, backup/restore, Telegram and Discord bots, and security. - **Reference** — environment variables, the database, ports & firewall, and the HTTP API. - **Help** — troubleshooting, FAQ, migration, and how to contribute. diff --git a/docs/architecture.md b/docs/architecture.md index 6f4d6afb4..2561f2dbd 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -65,7 +65,7 @@ Two key ideas that explain most of the complexity: - Scheduler: **robfig/cron/v3** (seconds-precision) for all background jobs. - Xray: **xtls/xray-core** vendored as a library; the panel talks to the running core over its **gRPC API** and also shells out to manage the process. -- Telegram bot: **mymmrac/telego**. i18n: **nicksnyder/go-i18n**. +- Bots: Telegram bot (**mymmrac/telego**), Discord bot (Discord REST API v10 + **gorilla/websocket** Gateway v10). i18n: **nicksnyder/go-i18n**. - Misc: gorilla/websocket, gopsutil (system stats), go-qrcode, gotp (2FA TOTP). **Frontend (`frontend/`):** @@ -217,6 +217,7 @@ node heartbeat every 5s, periodic traffic resets (hourly/daily/weekly/monthly). │ │ │ │ ├── user.go # admin user auth (bcrypt) │ │ │ │ ├── api_token.go # API token CRUD (SHA-256 hashed) │ │ │ │ └── websocket.go # WS hub / push service +│ │ │ ├── discord/ # Discord bot client, Gateway v10, and subscriber │ │ │ └── tgbot/ # Telegram bot command handlers │ │ ├── runtime/ # ⭐⭐ The Local/Remote node abstraction (see §5.2) │ │ │ ├── runtime.go # the Runtime interface (the contract) @@ -372,27 +373,28 @@ Periodic resets: `job/periodic_traffic_reset_job.go` (keyed off `Inbound.Traffic All registered in `web.go` → `startTask()`. Each is a struct with a `Run()` method in `internal/web/job/`: -| Schedule | Job | Purpose / condition | -| ------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | -| `@every 1s` | `check_xray_running_job` | Restart Xray if it died (2 consecutive down checks) | -| `@every 30s` | (inline func in `startTask`) | Debounced Xray restart — consumes the "need restart" flag (§5.1) | -| `@every 5s` | `xray_traffic_job` | Pull traffic stats from Xray (5s start delay) | -| `@every 5s` | `node_heartbeat_job` | Probe child nodes (online/offline) | -| `@every 5s` | `node_traffic_sync_job` | Pull + merge node traffic; push reconciliation | -| `@every 10s` | `check_client_ip_job` | Enforce per-client IP limits | -| `@every 10s` | `mtproto_job` | Reconcile `mtg` sidecars against enabled MTProto inbounds | -| `@every 10s` | `amneziawg_job` | Reconcile embedded AmneziaWG interfaces against enabled local inbounds | -| `@every 5m` | `outbound_subscription_job` | Refresh outbound provider configs | -| `@every 10m` | `clear_logs_job` (`PruneXrayLogsJob`) | Truncate Xray access/error logs once either exceeds 64 MiB | -| `@hourly` | `warp_ip_job`, `periodic_traffic_reset_job("hourly")` | WARP IP rotation; traffic resets | -| `@daily` | `clear_logs_job`, `periodic_traffic_reset_job("daily")`, `periodic_traffic_reset_job("monthly")` | IP-limit and Xray access/error log cleanup; daily resets and due monthly resets | -| `@weekly` | `periodic_traffic_reset_job("weekly")` | Weekly traffic resets | -| default `@every 1m` | `ldap_sync_job` | Only if LDAP enabled; schedule configurable | -| default `@daily` | `stats_notify_job` | Only if TG bot enabled; schedule configurable | -| `@every 2m` | `check_hash_storage` | Only if TG bot enabled; expires bot callback hashes | -| `@every 1m` | `check_cpu_usage` | Only if a CPU alarm is configured (TG or email); publishes `cpu.high` | -| `@every 1m` | `check_memory_usage` | Only if a memory alarm is configured; publishes `memory.high` | -| configurable | `free_os_memory` | Only if `sys.MemoryReleaseIntervalMinutes() > 0`; returns heap to OS | +| Schedule | Job | Purpose / condition | +| ------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- | +| `@every 1s` | `check_xray_running_job` | Restart Xray if it died (2 consecutive down checks) | +| `@every 30s` | (inline func in `startTask`) | Debounced Xray restart — consumes the "need restart" flag (§5.1) | +| `@every 5s` | `xray_traffic_job` | Pull traffic stats from Xray (5s start delay) | +| `@every 5s` | `node_heartbeat_job` | Probe child nodes (online/offline) | +| `@every 5s` | `node_traffic_sync_job` | Pull + merge node traffic; push reconciliation | +| `@every 10s` | `check_client_ip_job` | Enforce per-client IP limits | +| `@every 10s` | `mtproto_job` | Reconcile `mtg` sidecars against enabled MTProto inbounds | +| `@every 10s` | `amneziawg_job` | Reconcile embedded AmneziaWG interfaces against enabled local inbounds | +| `@every 5m` | `outbound_subscription_job` | Refresh outbound provider configs | +| `@every 10m` | `clear_logs_job` (`PruneXrayLogsJob`) | Truncate Xray access/error logs once either exceeds 64 MiB | +| `@hourly` | `warp_ip_job`, `periodic_traffic_reset_job("hourly")` | WARP IP rotation; traffic resets | +| `@daily` | `clear_logs_job`, `periodic_traffic_reset_job("daily")`, `periodic_traffic_reset_job("monthly")` | IP-limit and Xray access/error log cleanup; daily resets and due monthly resets | +| `@weekly` | `periodic_traffic_reset_job("weekly")` | Weekly traffic resets | +| default `@every 1m` | `ldap_sync_job` | Only if LDAP enabled; schedule configurable | +| default `@daily` | `stats_notify_job` | Only if TG bot enabled; schedule configurable | +| default `@daily` | `discord_notify_job` | Only if Discord bot enabled; schedule configurable | +| `@every 2m` | `check_hash_storage` | Only if TG bot enabled; expires bot callback hashes | +| `@every 1m` | `check_cpu_usage` | Only if a CPU alarm is configured (TG, Discord, or email); publishes `cpu.high` | +| `@every 1m` | `check_memory_usage` | Only if a memory alarm is configured (TG, Discord, or email); publishes `memory.high` | +| configurable | `free_os_memory` | Only if `sys.MemoryReleaseIntervalMinutes() > 0`; returns heap to OS | To change _when_ something runs, edit `startTask()`. To change _what_ it does, edit the job file. @@ -433,7 +435,7 @@ also has protocol schemas under `frontend/src/schemas/protocols/` and `frontend/ `xray.crash`, `node.down|up`, `cpu.high`, `memory.high`, `login.attempt`, with structured payloads (OutboundHealthData, NodeHealthData, LoginEventData, SystemMetricData). Producers include the CPU/memory jobs, node heartbeat, and login handling; consumers include the -Telegram bot and the email notifier (`service/email/`). Use it for cross-cutting +Telegram bot, the Discord bot (`service/discord/`), and the email notifier (`service/email/`). Use it for cross-cutting notifications instead of importing notification services into producers. ### 5.8 Tunnel health monitor @@ -504,6 +506,7 @@ for AutoMigrate in `internal/database/db.go`. | **Geo category browser** empty / won't open | `xray/geodata/` (`Store`, `reader.go`), `service/geodata.go` | `controller/xray_setting.go` (`/panel/api/xray/geodata/*`), asset dir = `config.GetBinFolderPath()` | | **`geosite:`/`geoip:` token** reported unknown in a routing rule | `xray/geodata/token.go`, `service/geodata.go` (`Validate`) | `frontend/src/lib/xray/geoTokens.ts`, `frontend/src/components/geodata/` | | **Telegram bot** commands | `service/tgbot/` | `job/stats_notify_job.go` | +| **Discord bot** commands & reports | `service/discord/` | `job/discord_notify_job.go` | | **Email notifications** | `service/email/` | `internal/eventbus/` (consumers) | | **CPU / memory alerts** not firing | `job/check_cpu_usage.go`, `job/check_memory_usage.go` | `internal/eventbus/`, notifier settings in `service/setting.go` | | Xray auto-restart on **dead tunnel** | `internal/tunnelmonitor/` | `XUI_TUNNEL_HEALTH_*` in `internal/config/` | @@ -539,7 +542,7 @@ for AutoMigrate in `internal/database/db.go`. 8. **Two servers, two concerns.** Admin features go in `internal/web`; anything an _end user_ fetches goes in `internal/sub`. Don't blur them. 9. **Cross-cutting notifications go through `internal/eventbus/`** — publish an event instead - of importing the Telegram/email services into producers. + of importing the Telegram/Discord/email services into producers. --- diff --git a/docs/content/docs/en/guide/index.mdx b/docs/content/docs/en/guide/index.mdx index 33ce6ea45..eec4c238e 100644 --- a/docs/content/docs/en/guide/index.mdx +++ b/docs/content/docs/en/guide/index.mdx @@ -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 diff --git a/docs/content/docs/en/index.mdx b/docs/content/docs/en/index.mdx index e570bbb11..4761760a1 100644 --- a/docs/content/docs/en/index.mdx +++ b/docs/content/docs/en/index.mdx @@ -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. New to Xray? Read [What is 3x-ui?](/docs/guide) first — it explains how the panel, Xray-core, and diff --git a/docs/content/docs/en/operations/backup-restore.mdx b/docs/content/docs/en/operations/backup-restore.mdx index 41fd7c875..e73032fe0 100644 --- a/docs/content/docs/en/operations/backup-restore.mdx +++ b/docs/content/docs/en/operations/backup-restore.mdx @@ -31,13 +31,9 @@ To restore, stop the panel, put the database back in place, and start it again. old schema. -## 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 diff --git a/docs/content/docs/en/operations/multi-node.mdx b/docs/content/docs/en/operations/multi-node.mdx index 509f23a3d..f2ae13e38 100644 --- a/docs/content/docs/en/operations/multi-node.mdx +++ b/docs/content/docs/en/operations/multi-node.mdx @@ -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)). Nodes are identified by a stable per-panel GUID, so a node keeps its identity diff --git a/docs/content/docs/fa/config/panel.mdx b/docs/content/docs/fa/config/panel.mdx index 2f8bd5278..bfed0b1bb 100644 --- a/docs/content/docs/fa/config/panel.mdx +++ b/docs/content/docs/fa/config/panel.mdx @@ -67,6 +67,7 @@ icon: SlidersHorizontal + diff --git a/docs/content/docs/fa/guide/index.mdx b/docs/content/docs/fa/guide/index.mdx index b6b401581..276f54cd6 100644 --- a/docs/content/docs/fa/guide/index.mdx +++ b/docs/content/docs/fa/guide/index.mdx @@ -41,7 +41,7 @@ flowchart LR - سهمیه‌های ترافیک **به‌ازای هر کلاینت**، تاریخ‌های انقضا، محدودیت‌های IP، وضعیت آنلاین و لینک‌های اشتراک‌گذاری / کدهای QR با یک کلیک. - **اشتراک‌ها** در قالب‌های VLESS، Clash/Mihomo و JSON. -- ابزارهای عملیاتی: مدیریت **چندنودی**، یک **ربات Telegram**، پشتیبان‌گیری، +- ابزارهای عملیاتی: مدیریت **چندنودی**، **ربات‌های Telegram و Discord**، پشتیبان‌گیری، محدودسازی IP مبتنی بر Fail2ban و یک REST API مستندشده. ## پشت صحنه diff --git a/docs/content/docs/fa/index.mdx b/docs/content/docs/fa/index.mdx index e4fd01c15..5a1b5fcc9 100644 --- a/docs/content/docs/fa/index.mdx +++ b/docs/content/docs/fa/index.mdx @@ -46,7 +46,7 @@ icon: House - **کنترل‌های اختصاصی هر کلاینت** — سهمیه ترافیک، تاریخ انقضا، محدودیت IP، لینک‌های اشتراک‌گذاری و کدهای QR. - **سابسکریپشن‌ها** — قالب‌های VLESS، Clash/Mihomo و JSON. -- **عملیات** — مدیریت چندنودی، ربات Telegram، پشتیبان‌گیری و یک REST API. +- **عملیات** — مدیریت چندنودی، ربات‌های Telegram و Discord، پشتیبان‌گیری و یک REST API. با Xray تازه آشنا شده‌اید؟ ابتدا [3x-ui چیست؟](/docs/guide) را بخوانید — توضیح می‌دهد که پنل، Xray-core و diff --git a/docs/content/docs/fa/operations/backup-restore.mdx b/docs/content/docs/fa/operations/backup-restore.mdx index aad89cb09..e25ba9778 100644 --- a/docs/content/docs/fa/operations/backup-restore.mdx +++ b/docs/content/docs/fa/operations/backup-restore.mdx @@ -31,13 +31,9 @@ cp /etc/x-ui/x-ui.db /root/x-ui-backup-$(date +%F).db مهاجرت‌های خود را اجرا کند. -## پشتیبان‌گیری با 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 diff --git a/docs/content/docs/fa/operations/discord-bot.mdx b/docs/content/docs/fa/operations/discord-bot.mdx new file mode 100644 index 000000000..650d87db0 --- /dev/null +++ b/docs/content/docs/fa/operations/discord-bot.mdx @@ -0,0 +1,121 @@ +--- +title: ربات Discord +description: یک ربات Discord را به 3x-ui متصل کنید تا اعلان‌های بی‌درنگ Embed، گزارش‌های دوره‌ای همراه با نسخه پشتیبان پایگاه‌داده و فرمان‌های تعاملی را در یک کانال دریافت کنید. +icon: Bot +--- + +3x-ui یکپارچگی کاملی با Discord فراهم می‌کند: ارسال هشدارهای بی‌درنگ از طریق گذرگاه رویدادها (`EventBus`)، گزارش‌های دوره‌ای وضعیت سرور به‌همراه فایل پشتیبان پایگاه‌داده، و پردازش فرمان‌های تعاملی از طریق Discord Gateway. + + + اعلان‌های لحظه‌ای و گزارش‌های دوره‌ای از تماس‌های خروجی HTTPS به Discord REST API v10 استفاده می‌کنند. فرمان‌های تعاملی ربات نیز از طریق یک اتصال پس‌زمینه WebSocket امن به Discord Gateway برقرار می‌شوند. + + +## راه‌اندازی + + + + +### ساخت برنامه و ربات در 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` ضروری است). + + + +### دعوت ربات به سرور Discord + +1. در پرتال توسعه‌دهندگان، به **OAuth2** → **URL Generator** بروید. +2. در بخش **Scopes**، گزینه `bot` را علامت بزنید. +3. در بخش **Bot Permissions**، دسترسی‌های زیر را انتخاب کنید: + - **Send Messages** (ارسال پیام) + - **Embed Links** (ارسال امبدها) + - **Attach Files** (پیوست فایل‌ها — جهت ارسال نسخه پشتیبان پایگاه‌داده ضروری است) + - **Read Message History** (خواندن تاریخچه پیام‌ها) +4. لینک تولیدشده در پایین صفحه را کپی کرده و در مرورگر باز کنید تا ربات به سرور شما اضافه شود. + + + +### کپی کردن Channel ID + +1. در کلاینت دیسکورد، حالت توسعه‌دهنده را فعال کنید: **User Settings** → **Advanced** → **Developer Mode** (روشن). +2. روی کانالی که می‌خواهید اعلان‌ها و تعامل با ربات در آن انجام شود راست‌کلیک کرده و **Copy Channel ID** را انتخاب کنید. +3. مطمئن شوید ربات دسترسی مشاهده و ارسال پیام در این کانال را دارد. + + + +### پیکربندی پنل + +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. برای اعمال تغییرات روی **ذخیره** کلیک نمایید. + + + + +## فرمان‌های ربات + +هنگام فعال بودن، ربات به فرمان‌های ارسال‌شده در کانال پیکربندی‌شده گوش می‌دهد (پشتیبانی از هر دو پیشوند `!` و `/`). تنها کاربرانی که شناسه‌ی آن‌ها در **شناسه‌های کاربری ادمین** ثبت شده مجاز به اجرای فرمان‌ها هستند؛ پیام‌های سایر کاربران نادیده گرفته می‌شود و در صورت خالی بودن این فیلد، اجرای فرمان‌ها غیرفعال خواهد بود. فرمان `!backup` فایل پایگاه‌داده را در کانال ارسال می‌کند، بنابراین کانالی را انتخاب کنید که فقط ادمین‌ها به آن دسترسی داشته باشند: + +| فرمان | عملکرد | +| ----- | ------ | +| `!status` | نمایش بار پردازشی سیستم، مصرف RAM، وضعیت هسته Xray، اتصالات و تعداد کاربران آنلاین. | +| `!report` | تولید و ارسال فوری گزارش کامل وضعیت سرور و پروکسی. | +| `!backup` | ارسال فوری فایل نسخه پشتیبان پایگاه‌داده (`x-ui.db`) و `config.json`. | +| `!usage ` | بررسی مصرف ترافیک (دانلود/آپلود)، سقف حجم و تاریخ انقضای یک کلاینت خاص. | +| `!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 و وضعیت ورود | + + + هشدارهای ورود فقط نام کاربری و آدرس IP کلاینت را گزارش می‌دهند. رمزهای عبور هرگز ذخیره یا ارسال نمی‌شوند. + + +## راهنمای تنظیمات + +| پارامتر | مقدار پیش‌فرض | توضیح | +| ------- | ------------- | ------ | +| `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** را پیکربندی کنید؛ درخواست‌های دیسکورد به‌صورت خودکار از طریق آن هدایت می‌شوند. diff --git a/docs/content/docs/fa/operations/multi-node.mdx b/docs/content/docs/fa/operations/multi-node.mdx index 3c987c304..63aa1078d 100644 --- a/docs/content/docs/fa/operations/multi-node.mdx +++ b/docs/content/docs/fa/operations/multi-node.mdx @@ -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) مراجعه کنید). نودها با یک GUID پایدار به‌ازای هر پنل شناسایی می‌شوند، بنابراین یک نود هویت خود diff --git a/docs/content/docs/ru/guide/index.mdx b/docs/content/docs/ru/guide/index.mdx index 024408aa2..e59f58020 100644 --- a/docs/content/docs/ru/guide/index.mdx +++ b/docs/content/docs/ru/guide/index.mdx @@ -40,7 +40,7 @@ flowchart LR - **Поклиентские** квоты трафика, даты истечения, ограничения по IP, статус «онлайн» и ссылки для подключения / QR-коды в один клик. - **Подписки** в форматах VLESS, Clash/Mihomo и JSON. -- Инструменты для эксплуатации: управление **несколькими узлами**, **Telegram-бот**, резервные копии, +- Инструменты для эксплуатации: управление **несколькими узлами**, **Telegram- и Discord-боты**, резервные копии, ограничение по IP на базе Fail2ban и документированный REST API. ## Что под капотом diff --git a/docs/content/docs/ru/index.mdx b/docs/content/docs/ru/index.mdx index b08b5ec52..2b28845c0 100644 --- a/docs/content/docs/ru/index.mdx +++ b/docs/content/docs/ru/index.mdx @@ -46,7 +46,7 @@ icon: House - **Управление каждым клиентом** — квоты трафика, даты истечения, ограничения по IP, ссылки для подключения и QR-коды. - **Подписки** — форматы VLESS, Clash/Mihomo и JSON. -- **Эксплуатация** — управление несколькими узлами, Telegram-бот, резервные копии и REST API. +- **Эксплуатация** — управление несколькими узлами, Telegram- и Discord-боты, резервные копии и REST API. Впервые работаете с Xray? Сначала прочитайте [Что такое 3x-ui?](/docs/guide) — там объясняется, как панель, Xray-core и diff --git a/docs/content/docs/ru/operations/backup-restore.mdx b/docs/content/docs/ru/operations/backup-restore.mdx index 4c57453ee..59315283e 100644 --- a/docs/content/docs/ru/operations/backup-restore.mdx +++ b/docs/content/docs/ru/operations/backup-restore.mdx @@ -33,14 +33,9 @@ cp /etc/x-ui/x-ui.db /root/x-ui-backup-$(date +%F).db выполнить миграции, а не навязывайте старую схему. -## Резервное копирование через 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 diff --git a/docs/content/docs/ru/operations/multi-node.mdx b/docs/content/docs/ru/operations/multi-node.mdx index d7975f338..6c3cb4ccd 100644 --- a/docs/content/docs/ru/operations/multi-node.mdx +++ b/docs/content/docs/ru/operations/multi-node.mdx @@ -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)). Узлы идентифицируются по стабильному GUID, уникальному для каждой панели, diff --git a/docs/content/docs/zh/config/panel.mdx b/docs/content/docs/zh/config/panel.mdx index d9f52686f..9c929d536 100644 --- a/docs/content/docs/zh/config/panel.mdx +++ b/docs/content/docs/zh/config/panel.mdx @@ -63,6 +63,7 @@ icon: SlidersHorizontal + diff --git a/docs/content/docs/zh/guide/index.mdx b/docs/content/docs/zh/guide/index.mdx index 266098248..6a0650ec8 100644 --- a/docs/content/docs/zh/guide/index.mdx +++ b/docs/content/docs/zh/guide/index.mdx @@ -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。 ## 底层原理 diff --git a/docs/content/docs/zh/index.mdx b/docs/content/docs/zh/index.mdx index 1b76a8471..445e66fd0 100644 --- a/docs/content/docs/zh/index.mdx +++ b/docs/content/docs/zh/index.mdx @@ -43,7 +43,7 @@ icon: House - **细粒度的客户端管理** —— 流量配额、到期日期、IP 限制、分享 链接以及 QR 码。 - **订阅** —— 支持 VLESS、Clash/Mihomo 以及 JSON 格式。 -- **运维能力** —— 多节点管理、Telegram 机器人、备份以及 REST API。 +- **运维能力** —— 多节点管理、Telegram 和 Discord 机器人、备份以及 REST API。 初次接触 Xray？请先阅读 [什么是 3x-ui？](/docs/guide) —— 它解释了面板、Xray-core 与 diff --git a/docs/content/docs/zh/operations/backup-restore.mdx b/docs/content/docs/zh/operations/backup-restore.mdx index 38425d87b..2420f63f3 100644 --- a/docs/content/docs/zh/operations/backup-restore.mdx +++ b/docs/content/docs/zh/operations/backup-restore.mdx @@ -28,13 +28,9 @@ cp /etc/x-ui/x-ui.db /root/x-ui-backup-$(date +%F).db 运行迁移，而不要强行套用旧的数据库结构。 -## 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 转储 / 恢复 diff --git a/docs/content/docs/zh/operations/discord-bot.mdx b/docs/content/docs/zh/operations/discord-bot.mdx new file mode 100644 index 000000000..7132f364c --- /dev/null +++ b/docs/content/docs/zh/operations/discord-bot.mdx @@ -0,0 +1,121 @@ +--- +title: Discord 机器人 +description: 将 Discord 机器人接入 3x-ui，在指定频道接收实时的面板事件 Embed 告警、周期性健康报告（含数据库备份）以及执行交互式控制命令。 +icon: Bot +--- + +3x-ui 提供了完整的 Discord 集成支持：通过事件总线（`EventBus`）实时推送事件告警、通过定时任务发送包含数据库备份的服务器状态报告，以及通过 Discord Gateway 执行交互式管理命令。 + + + Discord 实时通知和周期性报告使用出站 HTTPS REST API v10 请求。交互式机器人命令则通过与 Discord Gateway 建立的后台安全 WebSocket 连接实现。 + + +## 完成配置 + + + + +### 创建 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` 等前缀命令所必需）。 + + + +### 邀请机器人加入你的 Discord 服务器 + +1. 在开发者门户左侧导航栏中，进入 **OAuth2** → **URL Generator**。 +2. 在 **Scopes** 中勾选 `bot`。 +3. 在下方展开的 **Bot Permissions** 中，勾选以下权限： + - **Send Messages**（发送消息） + - **Embed Links**（嵌入链接） + - **Attach Files**（附加文件 —— 发送数据库备份附件所必需） + - **Read Message History**（读取消息历史） +4. 复制页面底部生成的邀请链接，在浏览器中打开并将机器人添加到你的目标服务器。 + + + +### 复制频道 ID + +1. 在 Discord 客户端中开启开发者模式：**用户设置** → **高级** → **开发者模式**（开启）。 +2. 右键点击希望接收告警和执行命令的频道，选择**复制频道 ID**（Copy Channel ID）。 +3. 确保机器人拥有该频道的查看和发送消息权限。 + + + +### 配置面板 + +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. 点击**保存**应用配置。 + + + + +## 机器人命令 + +启用后，机器人将在配置的 Discord 频道内监听命令（同时支持 `!` 和 `/` 前缀）。仅列在**管理员用户 ID**中的用户可以执行命令；来自其他用户的消息将被忽略，若未配置管理员 ID 则关闭命令响应。`!backup` 与定时备份会将数据库文件发送至频道中，因此请务必选择仅管理员可见的频道： + +| 命令 | 说明 | +| ---- | ---- | +| `!status` | 查看系统负载、内存占用、CPU 使用率、核心状态、TCP/UDP 连接数及当前在线用户。 | +| `!report` | 立即生成并发送完整的服务器与代理状态报告 Embed。 | +| `!backup` | 立即导出并发送当前数据库备份文件（`x-ui.db`）与 `config.json`。 | +| `!usage ` | 查询指定客户端的流量用量（上传/下载）、配额上限及到期时间。 | +| `!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 及登录结果） | + + + 登录告警仅包含尝试的用户名及客户端 IP 地址。系统绝不会记录或传输密码明文。 + + +## 设置参考 + +| 设置项 | 默认值 | 说明 | +| ------ | ------ | ---- | +| `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 的所有请求将自动经由该代理发出。 diff --git a/docs/content/docs/zh/operations/multi-node.mdx b/docs/content/docs/zh/operations/multi-node.mdx index 9878d7ef2..2f7101ee2 100644 --- a/docs/content/docs/zh/operations/multi-node.mdx +++ b/docs/content/docs/zh/operations/multi-node.mdx @@ -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)）。 节点通过每个面板稳定的 GUID 来标识，因此节点在重启后仍能保持其身份。节点本身也可以管理更多节点——主控会将这些以只读的**传递性**子节点形式呈现（Node 1 → Node 2 → Node 3）。 diff --git a/docs/lib/site-i18n.ts b/docs/lib/site-i18n.ts index 162c8c20c..47bdd7db6 100644 --- a/docs/lib/site-i18n.ts +++ b/docs/lib/site-i18n.ts @@ -65,9 +65,9 @@ const en: SiteMessages = { 'Coordinate multiple servers, managed hosts and external proxies, and serve VLESS / Clash / JSON subscriptions.', }, { - title: 'Telegram bot & alerts', + title: 'Telegram & Discord bots', description: - 'Built-in Telegram notifications for traffic caps, expiry warnings and system load, plus admin actions.', + 'Built-in Telegram and Discord notifications for traffic caps, expiry warnings and system load, plus admin actions.', }, { title: 'Self-hosted & scriptable', @@ -116,9 +116,9 @@ const fa: SiteMessages = { 'هماهنگ‌سازی چند سرور، هاست‌های مدیریت‌شده و پروکسی‌های خارجی، و ارائه‌ی سابسکریپشن‌های VLESS / Clash / JSON.', }, { - title: 'ربات Telegram و هشدارها', + title: 'ربات‌های Telegram و Discord', description: - 'اعلان‌های داخلیِ Telegram برای سقف ترافیک، هشدار انقضا و بار سیستم، به‌علاوه‌ی کنش‌های مدیریتی.', + 'اعلان‌های داخلیِ Telegram و Discord برای سقف ترافیک، هشدار انقضا و بار سیستم، به‌علاوه‌ی کنش‌های مدیریتی.', }, { title: 'خودمیزبان و قابل‌اسکریپت', @@ -167,9 +167,9 @@ const ru: SiteMessages = { 'Координация нескольких серверов, управляемых хостов и внешних прокси, а также выдача подписок VLESS / Clash / JSON.', }, { - title: 'Telegram-бот и оповещения', + title: 'Telegram- и Discord-боты', description: - 'Встроенные уведомления Telegram о лимитах трафика, истечении срока и нагрузке системы, а также действия администратора.', + 'Встроенные уведомления Telegram и Discord о лимитах трафика, истечении срока и нагрузке системы, а также действия администратора.', }, { title: 'Свой хостинг и скрипты', @@ -217,8 +217,9 @@ const zh: SiteMessages = { description: '协调多台服务器、托管主机和外部代理，并提供 VLESS / Clash / JSON 订阅。', }, { - title: 'Telegram 机器人与告警', - description: '内置 Telegram 通知，覆盖流量上限、到期提醒和系统负载，并支持管理员操作。', + title: 'Telegram 与 Discord 机器人', + description: + '内置 Telegram 和 Discord 通知，覆盖流量上限、到期提醒和系统负载，并支持管理员操作。', }, { title: '自托管且可脚本化',