mirror of
https://github.com/MHSanaei/3x-ui.git
synced 2026-11-12 16:15:02 +03:00
25f2002654
83ea59fb69
The v3.11.0 bot rebuild left the admin's client card without the subscription link, individual links and QR code, so an admin could not hand a config to a client who cannot reach Telegram yet. The card now carries Links and QR code buttons that open the existing screens. Closes #6984.
124 lines
6.8 KiB
Plaintext
124 lines
6.8 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 码，因此可以把配置交给暂时还无法打开 Telegram 的客户端。
|
||
普通用户则可以使用按钮查看
|
||
自己的用量、订阅链接、单条链接和 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>
|