mirror of
https://github.com/MHSanaei/3x-ui.git
synced 2026-10-01 19:52:09 +03:00
pcxzs
7aa5fc085f
* 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>
118 lines
6.3 KiB
Plaintext
118 lines
6.3 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`，然后复制**机器人令牌**（bot token）。
|
||
</Step>
|
||
|
||
<Step>
|
||
### 查找你的 Telegram ID
|
||
|
||
获取你的数字 Telegram 用户 ID（机器人连接成功后，其自带的 `/id` 命令会显示该 ID）。
|
||
这就是你的**管理员** ID。
|
||
</Step>
|
||
|
||
<Step>
|
||
### 配置面板
|
||
|
||
在面板设置中启用 Telegram 机器人，并填写**令牌**和**管理员聊天 ID**
|
||
（多个时以逗号分隔）。保存后，再向你的机器人发送消息。
|
||
</Step>
|
||
|
||
</Steps>
|
||
|
||
在将令牌、管理员 ID 和报告计划粘贴到面板之前，先对它们进行校验：
|
||
|
||
<TelegramSetupHelper />
|
||
|
||
## 命令
|
||
|
||
以下命令会出现在 Telegram 命令菜单中：`/start`、`/help`、`/status`、`/id`。
|
||
其他命令：
|
||
|
||
| 命令 | 适用对象 | 作用 |
|
||
| ------------------ | ------ | ------------------------------------------------------------ |
|
||
| `/start` | 任何人 | 问候语以及内联按钮菜单；未绑定的账号只会收到自己的 Telegram ID |
|
||
| `/help` | 两者 | 内联按钮菜单 |
|
||
| `/status` | 两者 | 确认机器人在线 |
|
||
| `/id` | 任何人 | 显示你的 Telegram 数字 ID |
|
||
| `/usage <arg>` | 两者 | 管理员可搜索客户端；用户则查询自己的用量 |
|
||
| `/inbound <remark>`| 管理员 | 显示某个入站的详情 |
|
||
| `/restart` | 管理员 | 重启 Xray |
|
||
|
||
用户是指至少绑定了一个客户端的 Telegram 账号。其他账号只能使用 `/start` 和
|
||
`/id`，机器人会忽略它们的其他命令和按钮点击。要绑定客户，请在机器人的客户端卡片上点击
|
||
**邀请链接**，并把 `t.me` 链接发给对方：第一个打开该链接的账号会绑定到共用该订阅
|
||
ID 的所有客户端。订阅 ID 就是邀请码，因此请保持其足够长且随机。每个账号每小时
|
||
可尝试五次，用完后会通知管理员。
|
||
|
||
管理员还可通过内联按钮使用一系列功能：服务器用量、按流量排序的报告、
|
||
重置流量、数据库备份、封禁日志、列出入站/客户端、在线客户端、
|
||
“即将耗尽”，以及完整的**添加客户端**向导。普通用户则可以使用按钮查看
|
||
自己的用量、订阅链接、单条链接和 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`
|
||
（剩余配额的 GB 数）决定；两者默认均为 `0`（关闭）。
|
||
|
||
## 设置
|
||
|
||
| 设置项 | 默认值 | 含义 |
|
||
| -------------- | -------------------------- | ---------------------------------------------- |
|
||
| `tgBotEnable` | `false` | 总开关。 |
|
||
| `tgBotToken` | _（机密）_ | 机器人 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">
|
||
机器人令牌掌控着你的机器人——务必妥善保密，且只添加**可信的**管理员聊天 ID。
|
||
登录告警绝不会包含密码。
|
||
</Callout>
|
||
|
||
<Callout type="info">
|
||
如果你更倾向于通过邮件接收告警，邮件（SMTP）通知会镜像同样的这些事件
|
||
（`smtpEnabledEvents`）——请在面板设置中配置 SMTP。
|
||
</Callout>
|