通知与提醒

ForwardX 支持邮件（SMTP）和 Telegram 两种通知渠道，可以同时启用，互不影响。

通知触发事件

事件	说明	邮件	Telegram
主机上线 / 下线	Agent 连接或断开时通知管理员	-	✓
用户套餐到期提醒	套餐到期前提前通知用户	✓	✓
用户流量不足提醒	剩余流量低于设定阈值时通知用户	✓	✓
服务器续费提醒	主机账单到期前通知管理员	-	✓

开启任意提醒前，需先完成对应渠道的配置并启用。提醒只会发送给已配置收件地址或已绑定 Telegram 的目标用户或管理员。

---

邮件通知（SMTP）

配置 SMTP

进入：

系统设置 -> 邮件通知

填写以下字段：

字段	说明
SMTP 服务器	邮件服务商提供的发送服务器地址，例如 smtp.gmail.com
端口	通常为 465（SSL/TLS）或 587（STARTTLS）
加密方式	与端口对应，选择 SSL/TLS 或 STARTTLS
发件人地址	发送通知的邮箱地址
发件人名称	显示给收件人的名称，例如 ForwardX
用户名	SMTP 登录账号，通常与发件人地址相同
密码	SMTP 登录密码或应用专用密码

也可以通过环境变量配置：

SMTP_HOST=smtp.example.com
SMTP_PORT=465
SMTP_TLS=true
SMTP_FROM=noreply@example.com
SMTP_FROM_NAME=ForwardX
SMTP_USER=noreply@example.com
SMTP_PASS=your_smtp_password

环境变量方式需要重启面板后生效。

WARNING

SMTP 密码具有发件权限，不要公开或写入版本控制。使用 Gmail 等支持应用密码的服务商时，建议生成应用专用密码而非使用账号密码。

测试邮件发送

配置完成后，点击"发送测试邮件"，填写收件地址，确认能正常收到。如果测试失败，请按以下顺序排查：

1. SMTP 服务器地址和端口是否正确。
2. 加密方式与端口是否匹配（465 对应 SSL/TLS，587 对应 STARTTLS）。
3. 用户名和密码是否正确。
4. 服务商是否需要开启"第三方客户端访问"或生成应用密码。
5. 服务器防火墙是否放行了对应端口的出站流量。

收件人

• 管理员通知发送至已填写邮箱的管理员账号。
• 用户到期提醒和流量提醒发送至用户账号绑定的邮箱。

---

Telegram 通知

Telegram 机器人支持用户绑定、用量查询、规则管理、一键登录、管理员通知、到期提醒和 AI 助手。

创建 Telegram 机器人

1. 在 Telegram 搜索 @BotFather。
2. 发送 /newbot 创建机器人。
3. 按提示填写机器人名称和用户名。
4. 复制 BotFather 返回的 Bot Token。

Bot Token 格式类似：

1234567890:AAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

WARNING

Bot Token 等同于机器人密码，不要发给普通用户，也不要公开到截图、群聊或工单里。

在面板中启用机器人

进入：

系统设置 -> Telegram

填写 Bot Token 后保存，并打开"启用机器人"。

也可以通过环境变量配置：

TELEGRAM_BOT_TOKEN=1234567890:AAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

环境变量方式需要重启面板后生效。使用环境变量配置时，后台会显示 Token 来源为环境变量。

TIP

机器人使用长轮询，不需要配置 Telegram webhook。服务器需要能访问 api.telegram.org。

用户绑定 Telegram

用户登录面板后，在右下角用户菜单中点击：

绑定 Telegram

然后点击"使用 Telegram 绑定"。Telegram 会打开机器人并携带一次性绑定码，用户点击 Start 即可完成绑定。

也可以在机器人里手动发送：

/bind 绑定码

绑定成功后，用户可以用机器人查询自己的账户和规则信息。

常用命令

用户命令：

命令	用途
/start	打开菜单或完成账号绑定
/menu	打开功能菜单
/usage	查询流量、到期时间、规则和端口配额
/rules	查看和管理自己的转发规则
/ask 问题	使用自然语言查询面板信息，启用 AI 后可识别更复杂的问题
/redeem	兑换余额或套餐兑换码
/login	生成网页登录链接
/webapp	在 Telegram 内打开面板
/unbind	解除当前 Telegram 绑定

管理员命令（需先绑定 Telegram）：

命令	用途
/users	查看用户概览
/reset 用户ID	重置指定用户流量
/renew	续期用户套餐
/updatepanel	更新面板，需要二次确认
/updateagent	更新 Agent，需要二次确认

通知提醒

Telegram 支持以下提醒：

• 管理员接收主机上下线通知。
• 用户到期提醒。
• 用户流量不足提醒。
• 服务器续费提醒。

提醒只会发送给已绑定 Telegram 的目标用户或管理员。

流量不足提醒可以配置百分比阈值，例如 20 表示剩余流量低于 20% 时发送提醒。

配置 AI 助手

AI 助手用于 Telegram 自然语言查询和管理指令解析。进入：

系统设置 -> Telegram -> AI 助手模型

按顺序配置：

1. 选择供应商：DeepSeek、SiliconFlow 或自定义 OpenAI 兼容接口。
2. 填写 API Key。
3. 检查 Base URL。DeepSeek 默认是 https://api.deepseek.com，SiliconFlow 默认是 https://api.siliconflow.cn/v1。
4. 选择或填写模型名称。
5. 按需调整最大输出 Tokens 和温度。
6. 打开"启用 AI 助手"并保存。

启用后，可以在机器人中发送：

/ask 我的流量用了多少
/ask 查看我的转发规则
/ask 哪条规则延迟最高
/ask 帮我关闭第 12 条规则

AI 助手内置 ForwardX Core Skill，用于理解主机、规则、隧道、转发组、用户和计费相关术语。模型只负责识别意图，不会直接读取面板数据库，也不会生成命令在服务器上执行。

• 查询由面板本地读取数据，并根据当前用户权限过滤结果。
• 管理操作与网页端共用相同业务校验，仍会检查协议、端口、资源权限、套餐和计费状态。
• 所有写操作必须先查看预览，再点击"确认执行"。
• 缺少金额、续期时长、兑换码数量或折扣力度时，机器人会给出常用选项；也可以点击"自定义输入"或直接发送自定义内容。
• 模型请求超过约 12 秒会自动停止并使用本地解析降级，连续异常时会暂时跳过远程模型，避免机器人长时间卡住。
• 每个用户每分钟最多发起 20 次 AI 交互，达到限制后需要等待提示时间再试。
• 同一聊天中的消息按顺序处理，不同用户的聊天可以并行处理。

管理员可以查询更多面板信息，也可以通过 AI 辅助执行部分管理操作。涉及修改数据的操作会要求二次确认。

普通用户 AI 管理开关

"普通用户可用 AI 管理"只控制普通用户是否能通过 AI 对话执行管理操作。

• 开启：普通用户可以用 AI 管理自己的可见规则，例如新增、删除、启用或停用自己的规则。
• 关闭：普通用户不能用 AI 对话执行管理操作。
• 普通查询不受影响。
• 管理员不受影响。

普通用户无论是否开启，都只能操作自己的账号和自己有权限的资源。

AI 消息自动撤回

打开"机器人信息自动撤回"后，AI 相关聊天内容会在设定时间后自动撤回。

可配置时间范围为 30 秒到 1200 秒。此功能只影响 AI 相关消息，不影响普通命令的必要提示。

---

常见问题

保存提醒时提示请先配置机器人

需要先填写 Bot Token，保存并启用机器人，再开启到期提醒、流量提醒或主机上下线通知。

机器人没有回复

按以下顺序排查：

1. 确认 Bot Token 是否正确。
2. 确认后台已经启用机器人。
3. 确认服务器能访问 https://api.telegram.org。
4. 查看面板日志。

Docker 部署查看日志：

docker logs -n 300 forwardx-panel

本地 systemd 部署查看日志：

journalctl -u forwardx-panel -n 300 --no-pager

AI 提示没有配置 API Key

进入"系统设置 -> Telegram -> AI 助手模型"，填写当前供应商的 API Key 并保存。AI API Key 建议在后台配置，不建议写入 Docker .env。

AI 模型列表加载失败

通常是 Base URL、API Key 或服务器网络问题。可以先手动填写模型名称保存，再检查服务器是否能访问对应 AI 服务商。

用户无法用 AI 管理规则

请检查：

1. 用户是否已经绑定 Telegram。
2. AI 助手是否已启用。
3. "普通用户可用 AI 管理"是否打开。
4. 用户是否有对应主机、隧道或规则权限。
5. 操作是否超出了普通用户允许范围。