3x-ui/docs/content/docs/fa/operations/telegram-bot.mdx
pcxzs 7aa5fc085f
feat(tgbot): access levels and /start account binding (#6518)
* feat(tgbot): gate the bot behind three user levels

Every Telegram account that found the bot could run /help, /status and
/usage, and tap any client button it could forge: nothing separated an
account no admin had bound from a customer.

Each update now resolves to stranger, client or admin, and commands are
allowlisted per level so a command added later stays admin-only until it
is listed. A stranger may run /start and /id only, and /start answers with
the ChatID an admin needs to bind it; a stranger's callbacks are answered
and dropped. Client detection reads the same tgId lookup as
clientOwnedByTgUser, so the level gate and the ownership check agree.

The bot also ignores everything outside private chats: authorization keys
on the sender while wizard state keys on the chat, and the two are the
same identity only in a private chat.

* feat(tgbot): bind Telegram accounts through /start deep links

Linking a customer meant the customer sending /id and an admin copying
the ChatID into the client by hand, which does not scale past a few
customers and is easy to get wrong.

The admin client card now offers an invite link, t.me/<bot>?start=<subId>,
and the first account to open it is bound through the existing
SetClientTelegramUserID. A subId already grants the subscription, so
binding gives the holder nothing the token did not. A subscription that
spans several clients binds all of them, and is refused if any part
belongs to another account; re-opening your own link is idempotent.
Unknown and already-claimed tokens share one reply, so the link cannot
be used to probe for valid subIds.

* fix(tgbot): harden invite claims after review

Review of the access-level and binding change found five problems:

- Concurrent claims of one link all read the client as unbound, all bound
  and all were told so, while only the last write held. Resolving and
  binding now share one lock, and a bind that fails part-way through a
  multi-client subscription undoes the bindings it already made.
- A subId has no minimum strength and the bot needs only its public
  username, so /start was an unthrottled guessing oracle. Non-admin claim
  attempts are capped at five per account per hour, the first refused one
  notifies the admins, and the Subscription ID field now says it doubles
  as the bot invite code.
- levelOf expanded every inbound's client JSON on every non-admin update.
  It now reads the indexed tg_id column of the clients table.
- A button tapped in a group chat was dropped unanswered and kept
  spinning, with nothing logged. It is answered now, and each ignored chat
  is logged once.
- The subId was pasted raw into the t.me link, so '#' or '&' truncated it
  and Telegram rejects anything outside A-Za-z0-9_-. The payload is now
  base64url, and a subId too long for the 64-character limit is refused.

* fix(tgbot): answer group chats again and make the claim race test bite

ignoredChat dropped every non-private chat because wizard state was
keyed by chat while authorization keyed on the sender. #6604 on main
re-keyed that state by (chat, user) so admins can drive the bot from a
group, so after the merge the drop only took the whole bot away from
those admins, report keyboards sent to a group included. The level gate
already keys on the sender, so group chats need no special case.

TestConcurrentClaimsBindOnlyOneAccount passed with inviteClaimMu
removed: the first claimant took the pool's idle connection and bound
before the rest had opened theirs, so no two ever raced. It now holds
the inbound write the binds need until every claimant has resolved,
and fails without the lock ("6 accounts told they bound").

TestCommandAllowed restated the commandsByLevel map; TestGateCommand
drives the same allowlist through gateCommand. TestIgnoredChat goes
with the code it pinned.

* docs(tgbot): document access levels and invite links

The command table still said /help and /status answer anyone. An
account no admin has linked now reaches only /start and /id, and a
customer is linked through the client card's Invite Link, whose token
is the Subscription ID. Updated in en, fa, ru and zh.

---------

Co-authored-by: MHSanaei <ho3ein.sanaei@gmail.com>
2026-09-27 13:33:29 +02:00

122 lines
9 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` خودِ ربات
آن را گزارش می‌کند). این همان **شناسه‌ی ادمین** شماست.
</Step>
<Step>
### پیکربندی پنل
در تنظیمات پنل، ربات Telegram را فعال کنید و **توکن** و **شناسه‌(های) چت ادمین** را
(با کاما جداشده) تنظیم نمایید. ذخیره کنید، سپس به ربات خود پیام بدهید.
</Step>
</Steps>
پیش از چسباندن توکن، شناسه‌های ادمین و زمان‌بندی گزارش در پنل، آن‌ها را اعتبارسنجی
کنید:
<TelegramSetupHelper />
## فرمان‌ها
این‌ها در منوی فرمان Telegram ظاهر می‌شوند: `/start`، `/help`، `/status`، `/id`.
فرمان‌های دیگر:
| فرمان | چه کسی | عملکرد |
| ------------------ | ------ | ------------------------------------------------------------ |
| `/start` | همه | پیام خوش‌آمدگویی و منوی دکمه‌های درون‌خطی؛ حساب متصل‌نشده فقط شناسه‌ی Telegram خود را می‌گیرد |
| `/help` | هر دو | منوی دکمه‌های درون‌خطی |
| `/status` | هر دو | تأیید فعال بودن ربات |
| `/id` | همه | نمایش شناسه‌ی عددی Telegram شما |
| `/usage <arg>` | هر دو | ادمین‌ها کلاینت‌ها را جست‌وجو می‌کنند؛ کاربران مصرف خود را می‌بینند |
| `/inbound <remark>`| ادمین | نمایش جزئیات یک ورودی |
| `/restart` | ادمین | راه‌اندازی مجدد Xray |
کاربر یعنی حساب Telegramی که دست‌کم به یک کلاینت متصل است. هر حساب دیگری فقط
`/start` و `/id` را می‌تواند اجرا کند و ربات فرمان‌ها و دکمه‌های دیگر آن را نادیده
می‌گیرد. برای اتصال یک مشتری، در کارت کلاینت در ربات روی **لینک دعوت** بزنید و لینک `t.me`
را برایش بفرستید: نخستین حسابی که آن را باز کند به همه‌ی کلاینت‌هایی که آن شناسه
اشتراک را دارند متصل می‌شود. شناسه اشتراک همان کد دعوت است، پس آن را طولانی و
تصادفی نگه دارید. هر حساب در هر ساعت پنج بار می‌تواند تلاش کند و پس از آن به
ادمین‌ها اطلاع داده می‌شود.
ادمین‌ها همچنین جریان‌های دکمه‌ی درون‌خطی برای مصرف سرور، گزارش‌های ترافیک مرتب‌شده،
بازنشانی ترافیک، پشتیبان‌گیری از DB، گزارش‌های مسدودسازی، فهرست کردن ورودی‌ها/کلاینت‌ها،
کلاینت‌های آنلاین، «به‌زودی تمام‌شونده» و یک جادوگر کامل **افزودن کلاینت** را در اختیار دارند.
کاربران عادی دکمه‌هایی برای مصرف خودشان، لینک‌های اشتراک، لینک‌های منفرد و کدهای QR دارند.
## گزارش‌ها و هشدارها
- **گزارش دوره‌ای** — بر اساس زمان‌بندی `tgRunTime` (به‌صورت پیش‌فرض `@daily`)، ربات
مصرف سرور (هاست، نسخه‌ها، آپ‌تایم، بار، حافظه، کلاینت‌های آنلاین، ترافیک)، فهرستی از
کلاینت‌های تمام‌شده/در‌حال‌انقضا و — اگر `tgBotBackup` فعال باشد — یک نسخه‌ی پشتیبان از
پایگاه‌داده و پیکربندی Xray را برای ادمین‌ها می‌فرستد. کلاینت‌هایی که با Telegram ID
پیوند خورده‌اند، هشدارهای انقضا/سهمیه‌ی خودشان را دریافت می‌کنند.
- **هشدارهای رویداد** — با `tgEnabledEvents` انتخاب می‌شوند (به‌صورت پیش‌فرض `login.attempt,cpu.high`):
| رویداد | چه زمانی |
| --------------- | ------------------------------------------------------- |
| `login.attempt` | ورود به پنل موفق یا ناموفق شود (همراه با IP و نام کاربری) |
| `cpu.high` | CPU از `tgCpu` درصد فراتر برود (به‌صورت پیش‌فرض ۸۰) |
| `memory.high` | حافظه از `tgMemory` درصد فراتر برود (به‌صورت پیش‌فرض ۸۰) |
| `xray.crash` | Xray-core کرش کند |
| `outbound.down` / `outbound.up` | یک خروجی از کار بیفتد / بازیابی شود |
| `node.down` / `node.up` | یک نود آفلاین شود / بازگردد |
زمان‌های پیش‌هشدار از `expireDiff` (روزهای پیش از انقضا) و `trafficDiff` (گیگابایتِ
باقی‌مانده از سهمیه) می‌آیند؛ هر دو به‌صورت پیش‌فرض `0` هستند (خاموش).
## تنظیمات
| تنظیم | پیش‌فرض | معنا |
| -------------- | -------------------------- | ---------------------------------------------- |
| `tgBotEnable` | `false` | روشن/خاموش اصلی. |
| `tgBotToken` | _(محرمانه)_ | توکن API ربات. |
| `tgBotChatId` | _(هیچ‌کدام)_ | شناسه‌های Telegram **ادمین**، جداشده با کاما. |
| `tgBotProxy` | _(هیچ‌کدام)_ | پروکسی `socks5://`، `http://` یا `https://`. |
| `tgBotAPIServer` | _(پیش‌فرض)_ | سرور سفارشی Telegram Bot API. |
| `tgRunTime` | `@daily` | زمان‌بندی گزارش (cron / `@daily` / `@every …`). |
| `tgBotBackup` | `false` | ضمیمه کردن یک نسخه‌ی پشتیبان DB به گزارش دوره‌ای. |
| `tgCpu` / `tgMemory` | `80` / `80` | آستانه‌های هشدار CPU / حافظه (درصد). |
| `tgLang` | `en-US` | زبان ربات. |
| `tgEnabledEvents` | `login.attempt,cpu.high`| اینکه کدام رویدادها تحویل داده شوند. |
<Callout type="warn">
توکن ربات کنترل ربات شما را در دست دارد — آن را محرمانه نگه دارید و فقط شناسه‌های چت
ادمین **مورد اعتماد** را اضافه کنید. هشدارهای ورود هرگز شامل رمزهای عبور نمی‌شوند.
</Callout>
<Callout type="info">
اگر ترجیح می‌دهید هشدارها را از طریق ایمیل دریافت کنید، اعلان‌های ایمیل (SMTP) همان
رویدادها را بازتاب می‌دهند (`smtpEnabledEvents`) — SMTP را در تنظیمات پنل پیکربندی نمایید.
</Callout>