mirror of
https://github.com/MHSanaei/3x-ui.git
synced 2026-11-19 19:45:02 +03:00
docs: vendor the documentation site into the monorepo
Fold the standalone 3x-ui-docs project (Next.js 16 + Fumadocs, deployed to docs.sanaei.dev) into docs/ so the panel and its documentation share a single source of truth, the way sing-box keeps its docs in-tree. The old repo becomes redundant and can be retired. - Import the full site under docs/ (app, components, content, lib, public, scripts, config). The self-contained pnpm project sits alongside the existing engineering notes with no filename collisions. - Re-point "Edit on GitHub" links from MHSanaei/3x-ui-docs to this repo's docs/content/docs path (docs/lib/shared.ts, docs/app/.../page.tsx). - Add docs-ci.yml and docs-deploy.yml under .github/workflows/, scoped to docs/** and run with working-directory: docs, since GitHub only runs workflows from the repo-root .github/. deploy-static.yml's GitHub Pages publish (CNAME docs.sanaei.dev) carries over unchanged. Follow-up (outside this commit): attach the docs.sanaei.dev custom domain to this repository's Pages (or set the Vercel project's root directory to docs), confirm the site is live from the monorepo, then delete MHSanaei/3x-ui-docs.
This commit is contained in:
@@ -0,0 +1,54 @@
|
||||
---
|
||||
title: 备份与恢复
|
||||
description: 手动或通过 Telegram 机器人备份并恢复你的 3x-ui 数据库与证书。
|
||||
icon: DatabaseBackup
|
||||
---
|
||||
|
||||
你的全部配置——入站、客户端、各项设置——都存放在面板的数据库中。
|
||||
请定期备份,以便日后恢复或迁移。
|
||||
|
||||
## 需要备份的内容
|
||||
|
||||
- **数据库** —— 默认为位于 `/etc/x-ui/x-ui.db` 的 SQLite(如果你使用
|
||||
PostgreSQL 后端,则为对应的 PostgreSQL 数据库)。
|
||||
- **证书** —— `/root/cert/` 下的所有内容(或你存放 TLS 证书的任意位置)。
|
||||
|
||||
## 手动备份
|
||||
|
||||
你可以从面板的概览页下载备份,也可以直接从服务器上复制数据库文件:
|
||||
|
||||
```bash title="copy the SQLite database"
|
||||
cp /etc/x-ui/x-ui.db /root/x-ui-backup-$(date +%F).db
|
||||
```
|
||||
|
||||
要恢复时,先停止面板,把数据库文件放回原位,然后重新启动面板。
|
||||
|
||||
<Callout type="warn">
|
||||
尽量将备份恢复到与其来源**相同的主版本**上。跨主版本升级时,应让面板自行
|
||||
运行迁移,而不要强行套用旧的数据库结构。
|
||||
</Callout>
|
||||
|
||||
## Telegram 备份
|
||||
|
||||
如果你已配置 [Telegram 机器人](/docs/operations/telegram-bot),启用
|
||||
**`tgBotBackup`** 即可在周期性报告中附带一份备份(按 `tgRunTime`
|
||||
计划执行,默认每天一次)。机器人会将**数据库**与 Xray 的
|
||||
**`config.json`** 一并发送到你的管理员聊天,从而让你始终拥有一份服务器之外的副本。
|
||||
管理员也可以从机器人的菜单中按需请求备份。
|
||||
|
||||
## SQLite 转储 / 恢复
|
||||
|
||||
`x-ui migrate-db` 命令可在 SQLite 数据库与纯文本 SQL 转储之间相互转换
|
||||
(便于检查,或在不同机器之间转移):
|
||||
|
||||
```bash
|
||||
x-ui migrate-db --dump /root/x-ui.sql # SQLite -> SQL text
|
||||
x-ui migrate-db --restore /root/x-ui.sql # SQL text -> SQLite
|
||||
```
|
||||
|
||||
若想改用 PostgreSQL,请参阅[数据库](/docs/reference/database)。
|
||||
|
||||
<Callout type="info">
|
||||
无论采用哪种方式,都请将备份保存在**服务器之外**,并不时测试一次恢复——
|
||||
未经测试的备份算不上备份。
|
||||
</Callout>
|
||||
@@ -0,0 +1,12 @@
|
||||
{
|
||||
"title": "运维",
|
||||
"icon": "ServerCog",
|
||||
"pages": [
|
||||
"reverse-proxy",
|
||||
"multi-node",
|
||||
"outbounds-routing",
|
||||
"backup-restore",
|
||||
"telegram-bot",
|
||||
"security"
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,79 @@
|
||||
---
|
||||
title: 多节点与受管主机
|
||||
description: 通过 API 令牌或 mTLS 信任、心跳检测以及针对每个入站的主机覆盖,从一个主控面板统一管理多个 3x-ui 面板并定制订阅。
|
||||
icon: Boxes
|
||||
---
|
||||
|
||||
3x-ui 可以从单个主控面板管理**多台服务器**,并借助**受管主机**覆盖每个入站在订阅中的通告方式。
|
||||
|
||||
## 节点
|
||||
|
||||
**节点**是另一个由你的主控面板通过其 API 管理的 3x-ui 面板。主控会轮询每个节点,并在一处集中展示其状态、版本、CPU/内存、运行时间和流量。
|
||||
|
||||
### 添加节点
|
||||
|
||||
提供节点的连接信息:
|
||||
|
||||
| 字段 | 说明 |
|
||||
| ----------------- | --------------------------------------------------------------------- |
|
||||
| **Name** | 唯一标签(例如 `de-fra-1`)。 |
|
||||
| **Scheme** | `https`(默认)或 `http`。 |
|
||||
| **Address / Port**| 节点面板的主机和端口。 |
|
||||
| **Base path** | 节点的 Web 基础路径。 |
|
||||
| **API token** | 在节点上创建的 Bearer 令牌(mTLS 模式下不需要)。 |
|
||||
| **TLS verify** | `verify`(默认)、`skip`、`pin`(固定证书 SHA-256)或 `mtls`。 |
|
||||
| **Inbound sync** | `all` 入站,或按标签 `selected`。 |
|
||||
| **Outbound tag** | 可选地**通过**指定的出站到达节点(出口桥接)。 |
|
||||
|
||||
当你添加或测试节点时,主控会验证其可达性。随后它每隔几秒发送一次**心跳**,更新节点的状态(`online` / `offline`)并发出 `node.up` / `node.down` 事件(参见 [Telegram 机器人](/docs/operations/telegram-bot))。
|
||||
|
||||
<Callout type="info">
|
||||
节点通过每个面板稳定的 GUID 来标识,因此节点在重启后仍能保持其身份。节点本身也可以管理更多节点——主控会将这些以只读的**传递性**子节点形式呈现(Node 1 → Node 2 → Node 3)。
|
||||
</Callout>
|
||||
|
||||
### 主控与节点之间的双向 TLS(mTLS)
|
||||
|
||||
若要获得最强的信任,请使用 `tlsVerifyMode = mtls`(需要 `https`):
|
||||
|
||||
<Steps>
|
||||
|
||||
<Step>
|
||||
### 获取主控的 CA
|
||||
|
||||
在主控上获取其节点认证 CA 证书(CA 私钥永远不会离开面板)。
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### 在节点上信任该 CA
|
||||
|
||||
将该 CA 粘贴到节点的“受信任 CA”设置中。它会在节点下次重启时生效。
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### 将节点切换到 mTLS
|
||||
|
||||
将节点的 TLS 验证模式设置为 `mtls`。现在主控将出示客户端证书而非 API 令牌。
|
||||
</Step>
|
||||
|
||||
</Steps>
|
||||
|
||||
## 受管主机
|
||||
|
||||
**受管主机**是附加到入站上的覆盖端点。在订阅时,每个启用的主机会以其自己的地址、端口、TLS、SNI、主机头、路径等渲染出一条额外的分享链接 / 代理——取代旧的“外部代理”列表。可用于:
|
||||
|
||||
- 通过 **CDN**(Cloudflare)以不同的地址/SNI 为入站做前置,
|
||||
- 为单个入站通告**多个域名**或按地区划分的端点,
|
||||
- 为每个端点调整 ALPN、指纹、ECH 或 mux。
|
||||
|
||||
每个主机都有一个备注(支持相同的[模板变量](/docs/config/share-links#remark-template-variables))、一个启用开关、一个排序顺序,并且可以**从特定订阅格式中排除**或**限定到特定节点**。
|
||||
|
||||
<Callout type="info">
|
||||
将地址/端口指向 CDN 的主机让你能够在客户端通过 CDN 边缘连接的同时,保持真实服务器地址的私密性。
|
||||
</Callout>
|
||||
|
||||
## 相关内容
|
||||
|
||||
<Cards>
|
||||
<Card title="出站与路由" href="/docs/operations/outbounds-routing" description="WARP、NordVPN、出站订阅以及路由。" />
|
||||
<Card title="订阅" href="/docs/config/subscription" description="主机如何塑造订阅输出。" />
|
||||
</Cards>
|
||||
@@ -0,0 +1,147 @@
|
||||
---
|
||||
title: 出站与路由
|
||||
description: 在 3x-ui 中调整出口流量——WARP 与 NordVPN 出站、出站订阅(服务器池)、路由规则以及负载均衡器。
|
||||
icon: Route
|
||||
---
|
||||
|
||||
入站负责接受客户端;**出站**则决定客户端的流量接下来发往何处。
|
||||
3x-ui 可以让流量经由 Cloudflare WARP、NordVPN,或从订阅导入的任意出站池转发,
|
||||
并通过路由规则和均衡器在它们之间进行选择。
|
||||
|
||||
## 编辑出站与路由
|
||||
|
||||
出站、路由规则、均衡器、DNS 和日志全部都位于 **Xray
|
||||
配置**中(即你在 Xray 设置下编辑的配置模板)。这里没有单独的逐条规则界面——你直接编辑
|
||||
JSON,面板随后会重载 Xray。面板同时还提供**出站连通性测试**以及**路由测试**(向正在运行的核心查询某个目标地址将会使用哪个出站)。
|
||||
|
||||
## 构建出站
|
||||
|
||||
每个出站都是一个 JSON 对象,最多包含四个部分:一个 **`tag`**(供路由规则和均衡器引用)、
|
||||
一个 **`protocol`**、协议专属的 **`settings`**,以及——对于代理协议而言——必须与远程入站的
|
||||
传输方式和安全设置相匹配的 **`streamSettings`**。有两个出站几乎总是会存在:
|
||||
|
||||
- **`freedom`** 会将流量直接发往其目标地址——这是默认出口。
|
||||
可选地设置一个 `domainStrategy`(例如 `UseIP`)来控制主机名的解析方式。
|
||||
- **`blackhole`** 会丢弃流量。将不需要的目标地址(广告、种子下载)路由到这里。
|
||||
|
||||
```json title="freedom + blackhole"
|
||||
{
|
||||
"outbounds": [
|
||||
{ "tag": "direct", "protocol": "freedom", "settings": {} },
|
||||
{ "tag": "block", "protocol": "blackhole", "settings": {} }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**代理**出站(VLESS、VMess、Trojan、Shadowsocks)会转发到另一台
|
||||
服务器——便于进行链式代理或将部分流量发往境外。注意 3x-ui 所使用的各种线路
|
||||
结构:**VLESS 采用扁平形式**(`address`/`port`/`id`/`flow`/
|
||||
`encryption`),**VMess 使用 `settings.vnext[]`**,而 **Trojan/Shadowsocks 使用
|
||||
`settings.servers[]`**。`streamSettings` 必须与目标的
|
||||
[传输方式和安全设置](/docs/config/transports)保持一致。
|
||||
|
||||
在下方组装任意出站,并将生成的 JSON 粘贴到 **Xray 设置 → Outbounds** 中:
|
||||
|
||||
<OutboundGenerator />
|
||||
|
||||
## Cloudflare WARP
|
||||
|
||||
WARP 让你的服务器经由 Cloudflare 的网络出口。3x-ui 可以为你注册一个
|
||||
WARP 账户,并将其接入一个标签为 **`warp`** 的 WireGuard 出站:
|
||||
|
||||
<Steps>
|
||||
|
||||
<Step>
|
||||
### 添加一个标签为 `warp` 的出站
|
||||
|
||||
在你的 Xray 配置中创建一个标签为 `warp` 的 WireGuard 出站。
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### 注册 WARP
|
||||
|
||||
在面板的 WARP 控制项中注册一个账户。3x-ui 会自动填入该出站的
|
||||
密钥、地址、保留字节以及对端端点。
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### (可选)自动轮换 IP
|
||||
|
||||
设置一个 WARP 更新间隔(以**天**为单位),即可定期轮换 WARP IP。也可以
|
||||
应用一个免费许可证。
|
||||
</Step>
|
||||
|
||||
</Steps>
|
||||
|
||||
通过路由规则,将你希望的流量(例如特定域名)路由到 `warp` 出站。
|
||||
|
||||
## NordVPN
|
||||
|
||||
3x-ui 可以根据访问令牌获取 NordVPN(NordLynx/WireGuard)凭据(或
|
||||
直接接受一个私钥),并列出国家/服务器,从而让你构建一个
|
||||
NordVPN 出站。
|
||||
|
||||
## 出站订阅(服务器池)
|
||||
|
||||
**出站订阅**会导入一个远程分享链接订阅,并将其中的服务器作为**出站**注入到正在运行的
|
||||
Xray 配置中——而不会改动你已保存的模板。这是订阅一*池*服务器的推荐方式。
|
||||
|
||||
| 字段 | 默认值 | 含义 |
|
||||
| ---------------- | ------- | -------------------------------------------------------------- |
|
||||
| `url` | — | 远程订阅 URL(受 SSRF 防护)。 |
|
||||
| `tagPrefix` | auto | 生成的出站标签的前缀(例如 `hk-`);留空 = `subN-`。 |
|
||||
| `updateInterval` | `600` | 刷新间隔,以**秒**为单位。 |
|
||||
| `prepend` | `false` | 将这些出站放在你的手动出站之前。 |
|
||||
| `priority` | `0` | 合并顺序(数值越小越靠前)。 |
|
||||
|
||||
导入的出站会获得**稳定的标签**:同一台服务器在多次刷新之间始终保持同一个标签,
|
||||
因此精确标签的路由/均衡器选择器会保持固定——而前缀/通配符选择器(例如 `hk-*`)
|
||||
则会随着服务器池的变化自动纳入新的服务器。支持的链接协议:`vmess`、`vless`、`trojan`、`ss`、
|
||||
`hysteria2`(`hy2`)以及 `wireguard`(`wg`)。面板会按定时器刷新已启用的
|
||||
订阅,并在内容发生变化时重载 Xray。
|
||||
|
||||
## 路由规则
|
||||
|
||||
**路由规则**决定每个连接使用哪个出站(或均衡器)。每条
|
||||
规则都是一个 `field` 类型的匹配器:设置 `domain`、`ip`、`port`、`network`、
|
||||
`protocol`、`inboundTag`、`sourceIP` 等中的任意项,并将其指向一个 **`outboundTag`** 或
|
||||
**`balancerTag`**。规则会**自上而下**逐条求值——**第一个匹配者胜出**,因此请
|
||||
将具体的规则放在通用规则之上。
|
||||
|
||||
```json title="route ads to blackhole, private IPs direct"
|
||||
{
|
||||
"routing": {
|
||||
"domainStrategy": "IPIfNonMatch",
|
||||
"rules": [
|
||||
{ "type": "field", "domain": ["geosite:category-ads-all"], "outboundTag": "block" },
|
||||
{ "type": "field", "ip": ["geoip:private"], "outboundTag": "direct" }
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 均衡器
|
||||
|
||||
**均衡器**通过一个**选择器**(标签前缀,包括来自出站订阅的通配符池)将出站分组,
|
||||
并以某种**策略**在它们之间分散流量或进行故障转移:
|
||||
|
||||
| 策略 | 选取…… | 是否需要监视器 |
|
||||
| ------------- | ----------------------------------------------- | ------------------------ |
|
||||
| `random` | 每个连接随机选取一个成员 | 否 |
|
||||
| `roundRobin` | 轮流选取各个成员 | 否 |
|
||||
| `leastPing` | 延迟最低的成员 | **`observatory`** |
|
||||
| `leastLoad` | 按采样负载最稳定的成员 | **`burstObservatory`** |
|
||||
|
||||
通过 `balancerTag` 从规则中引用某个均衡器。`leastPing` 和 `leastLoad`
|
||||
需要一个健康监视器,Xray 会将其放置在配置的**顶层**
|
||||
(`observatory` / `burstObservatory`,**而不是**放在 `routing` 内部)。面板可以
|
||||
报告均衡器状态,并允许你为测试目的将某个均衡器**覆盖**为特定的出站。
|
||||
|
||||
在此构建路由块——规则、均衡器以及配套的 observatory:
|
||||
|
||||
<RoutingBuilder />
|
||||
|
||||
<Callout type="warn">
|
||||
访问外部服务的出站在获取时会受到 SSRF 防护——默认情况下,私有/内部地址会被
|
||||
阻止,除非你按来源明确允许它们。
|
||||
</Callout>
|
||||
@@ -0,0 +1,44 @@
|
||||
---
|
||||
title: 反向代理
|
||||
description: 通过 Nginx 或 Caddy 为 3x-ui 面板和订阅提供 Let's Encrypt TLS 保护。
|
||||
icon: Waypoints
|
||||
---
|
||||
|
||||
反向代理让你能够在一个简洁的域名上提供面板和订阅服务,并自动启用 HTTPS,同时将真实端口隐藏在 80/443 端口之后。更希望让面板直接终结 TLS?可以改用
|
||||
[`x-ui` SSL 菜单](/docs/config/ssl-certificates)来获取证书。
|
||||
|
||||
## 生成配置
|
||||
|
||||
<ReverseProxyGenerator />
|
||||
|
||||
<Callout type="info">
|
||||
面板使用 WebSocket 来实时更新,因此代理必须传递
|
||||
`Upgrade`/`Connection` 头(上面的 Nginx 输出已经做到了这一点)。Caddy
|
||||
会自动处理 WebSocket 升级。
|
||||
</Callout>
|
||||
|
||||
## Nginx + 证书
|
||||
|
||||
使用 Nginx 时,请通过 `certbot`(或 `acme.sh`)获取证书,并在 server 块中引用它:
|
||||
|
||||
```bash title="certbot"
|
||||
certbot certonly --nginx -d panel.example.com
|
||||
```
|
||||
|
||||
安装证书后请重新加载 Nginx,并设置自动续期(`certbot renew` 默认通过定时器运行)。
|
||||
|
||||
## Caddy
|
||||
|
||||
Caddy 会为你获取并续期证书——只需让 Caddyfile 指向面板,它便能正常工作:
|
||||
|
||||
```text title="Caddyfile"
|
||||
panel.example.com {
|
||||
reverse_proxy 127.0.0.1:2053
|
||||
}
|
||||
```
|
||||
|
||||
## 小贴士
|
||||
|
||||
- 即使在代理之后,也请保留面板的 **Web 基础路径**;这是纵深防御。
|
||||
- 如果你在代理处终结 TLS,可能需要在面板上设置 `XUI_SKIP_HSTS=true`——参见[环境变量参考](/docs/reference/env-vars)。
|
||||
- 也请代理[订阅](/docs/config/subscription)服务器,使其内容通过 HTTPS 提供。
|
||||
@@ -0,0 +1,62 @@
|
||||
---
|
||||
title: 安全加固
|
||||
description: 加固 3x-ui——面板认证与 2FA、Fail2ban IP 限制、防火墙规则、BBR,以及保持更新。
|
||||
icon: ShieldCheck
|
||||
---
|
||||
|
||||
代理面板是高价值目标。几层加固措施就能带来很大改善。
|
||||
|
||||
## 面板加固
|
||||
|
||||
- 强而唯一的凭据,并启用**双因素认证**(TOTP)。
|
||||
- 使用非默认的面板端口,以及一个长且随机的 Web 根路径。
|
||||
- 为面板启用 TLS(直接启用,或通过[反向代理](/docs/operations/reverse-proxy))。
|
||||
- 内置的**登录限制器**会在某个 IP/用户名于 5 分钟内连续 5 次登录失败后将其封锁
|
||||
(封锁 15 分钟),并且面板可以将自身的出站流量经由某个 outbound 路由出去。
|
||||
|
||||
完整的检查清单请参见[首次登录](/docs/guide/first-login)。
|
||||
|
||||
## Fail2ban 与 IP 限制
|
||||
|
||||
为每个客户端设置一个 **IP 限制**(参见[客户端](/docs/config/clients)),以限制同时使用的源
|
||||
IP 数量。限制的执行由 **Fail2ban** 负责,3x-ui 会为你安装并配置好它(脚本安装时默认启用,
|
||||
Docker 安装时通过 `XUI_ENABLE_FAIL2BAN=true` 启用)。
|
||||
|
||||
可从 `x-ui` 菜单(**22 — IP Limit Management**)进行管理:安装/配置、修改封锁时长
|
||||
(默认 **30 分钟**)、封锁/解封某个 IP、查看封锁日志,以及检查状态。其底层机制如下:
|
||||
|
||||
- 该 jail 名为 **`3x-ipl`**;封锁日志位于 `/var/log/x-ui/3xipl.log` 与
|
||||
`/var/log/x-ui/3xipl-banned.log`(也可通过 `x-ui banlog` 查看)。
|
||||
- 封锁覆盖所有 TCP/UDP,**但不包括**你的 SSH 端口和面板端口,因此封锁不会把你
|
||||
锁在服务器或面板之外。
|
||||
|
||||
<Callout type="warn">
|
||||
在 Docker 上,Fail2ban 使用 `iptables` 进行封锁,这需要 `NET_ADMIN`(以及
|
||||
`NET_RAW`)权能——`docker-compose.yml` 已授予这些权能。若使用裸的
|
||||
`docker run`,请添加 `--cap-add=NET_ADMIN --cap-add=NET_RAW`,否则封锁只会被
|
||||
记录但永远不会真正生效。
|
||||
</Callout>
|
||||
|
||||
## 防火墙
|
||||
|
||||
只开放你实际使用的端口:SSH、面板端口、订阅端口以及你的入站端口。`x-ui` 菜单
|
||||
(**23 — Firewall Management**)封装了 `ufw`,或者你也可以在此生成规则:
|
||||
|
||||
<FirewallRulesGenerator />
|
||||
|
||||
<Callout type="warn">
|
||||
在启用默认拒绝(default-deny)的防火墙之前,请确保 SSH 始终处于放行状态,否则你
|
||||
可能把自己锁在外面。请在保留第二个会话的情况下进行测试。
|
||||
</Callout>
|
||||
|
||||
## 网络调优(BBR)
|
||||
|
||||
`x-ui` 菜单(**26 — Enable BBR**)用于切换 Google 的 BBR 拥塞控制算法
|
||||
(`net.ipv4.tcp_congestion_control = bbr`、`net.core.default_qdisc = fq`),它在拥塞链路
|
||||
上通常能提升吞吐量。
|
||||
|
||||
## 保持更新
|
||||
|
||||
定期更新 3x-ui 和 Xray-core——安全修复会随新版本发布。请关注
|
||||
[发布页面](https://github.com/MHSanaei/3x-ui/releases),并参见
|
||||
[更新与卸载](/docs/guide/update-uninstall)。
|
||||
@@ -0,0 +1,110 @@
|
||||
---
|
||||
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`、`/help` | 任何人 | 问候语以及内联按钮菜单 |
|
||||
| `/status` | 任何人 | 确认机器人在线 |
|
||||
| `/id` | 任何人 | 显示你的 Telegram 数字 ID |
|
||||
| `/usage <arg>` | 两者 | 管理员可搜索客户端;用户则查询自己的用量 |
|
||||
| `/inbound <remark>`| 管理员 | 显示某个入站的详情 |
|
||||
| `/restart` | 管理员 | 重启 Xray |
|
||||
|
||||
管理员还可通过内联按钮使用一系列功能:服务器用量、按流量排序的报告、
|
||||
重置流量、数据库备份、封禁日志、列出入站/客户端、在线客户端、
|
||||
“即将耗尽”,以及完整的**添加客户端**向导。普通用户则可以使用按钮查看
|
||||
自己的用量、订阅链接、单条链接和 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>
|
||||
Reference in New Issue
Block a user