mirror of
https://github.com/MHSanaei/3x-ui.git
synced 2026-10-26 07:44:59 +03:00
Tuyến Trần
a403faee23
Admins who run the bot in a forum supergroup got every notification in the General topic. An admin chat ID may now carry a topic, chatId:topicId, and the bot's admin messages and reports go to that topic. Repeated chats collapse into one entry and a second, different topic for the same chat is rejected, in the panel and in the docs setup helper alike. The chat ID hint in every locale and the English, Persian, Russian and Chinese guides describe the form.
122 lines
6.6 KiB
Plaintext
122 lines
6.6 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**
|
||
（多个时以逗号分隔）。保存后，再向你的机器人发送消息。
|
||
|
||
要把通知发送到论坛超级群组的某个话题，在聊天 ID 后加冒号和话题 ID，例如
|
||
`-1001234567890:42`。话题 ID 是话题消息链接中聊天之后的数字
|
||
（`https://t.me/c/1234567890/42/…`）。General 话题不填（或填 `1`）。
|
||
</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；`chatId:topicId` 发送到论坛话题。 |
|
||
| `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>
|