跳到主要内容

配置 Telegram 访问通知

PortGuard Server 可以在有效 SPA 敲门成功写入防火墙规则后发送 Telegram 通知。通知内容包括服务器 hostname、允许访问的来源 IP、数据包来源 IP、SPA 用户名、申请开放的端口、开放时间、过期时间和超时时长。

1. 创建 Telegram Bot​

  1. 在 Telegram 中打开 @BotFather。
  2. 发送 /newbot，按照提示创建机器人。
  3. 保存 BotFather 返回的 Bot Token，格式类似 123456789:AAExampleToken。

Bot Token 相当于机器人密码。不要把它提交到代码仓库、发送到客服消息中， 也不要在截图里暴露它。

2. 获取 Chat ID​

如果发送到私聊，请打开刚创建的机器人，点击 Start，然后给它发送一条消息。 如果发送到群组，请把机器人加入群组，再发送一条机器人能够收到的消息或命令。

在服务器上读取 Bot Token，避免把真实 Token 保存在 Shell 历史中：

read -rsp 'Telegram Bot Token: ' TG_TOKEN; echo

获取机器人最近收到的更新：

curl --config - <<EOF
silent
show-error
fail
url = "https://api.telegram.org/bot${TG_TOKEN}/getUpdates"
EOF
unset TG_TOKEN

在返回的 JSON 中查找 message.chat.id。私聊 Chat ID 通常是正整数，群组 Chat ID 通常是负整数，超级群组的 ID 通常以 -100 开头。

如果 result 为空，请重新给机器人发送一条消息后再次查询。发送到频道时， 也可以填写 @channel_username，但必须先把机器人添加为频道管理员并授予发消息权限。

3. 通过 PortGuard 控制台配置​

使用 root 权限打开防火墙管理控制台：

sudo portguard-fwknopd --fw-console

选择 5. Configure Telegram notifications，然后依次填写：

  • Bot token： BotFather 返回的 Token。
  • Chat ID： 私聊或群组的数字 ID，也可以是 @channel_username。
  • Minimum notification interval： 填写 0 表示每次成功敲门都推送； 填写更大的数字表示在该秒数内抑制后续通知。

确认保存，并在询问是否发送测试通知时选择 y。控制台会把配置写入 /etc/fwknop/fwknopd.conf，保持文件权限为 600，然后重新加载正在运行的服务。

4. 手工配置​

也可以直接在 /etc/fwknop/fwknopd.conf 中添加：

PORTGUARD_TG_BOT_TOKEN       123456789:replace_with_bot_token;
PORTGUARD_TG_CHAT_ID          -1001234567890;
PORTGUARD_TG_NOTIFY_INTERVAL  0;

Bot Token 和 Chat ID 必须同时配置。手工修改后检查文件权限、验证配置并重启服务：

sudo chmod 600 /etc/fwknop/fwknopd.conf
sudo portguard-fwknopd --exit-parse-config \
  -c /etc/fwknop/fwknopd.conf \
  -a /etc/fwknop/access.conf
sudo systemctl restart fwknopd

5. 验证通知​

从 PortGuard Client 发送有效 SPA 敲门时，可以实时查看服务日志：

sudo journalctl -u fwknopd -f

只有 SPA 数据包验证通过并成功写入防火墙规则后，服务端才会发送通知。如果同一条 临时规则仍然有效，重复敲门可能不会再次创建规则。测试时可以等待旧规则过期后再敲门。

如果控制台测试失败，或者敲门成功后没有收到通知，请检查：

  • 服务器能够解析 api.telegram.org 并访问外网 HTTPS。
  • 私聊中已经点击 Start，或者机器人拥有向目标群组、频道发消息的权限。
  • Chat ID 来自使用当前 Bot Token 查询到的同一会话。
  • PORTGUARD_TG_NOTIFY_INTERVAL 没有抑制本次通知。
  • 手工修改配置后已经重新加载或重启 fwknopd。

6. 禁用通知​

再次进入控制台并选择选项 5，在 Bot Token 处输入 disable 后确认。PortGuard 会删除三个 Telegram 配置项，并重新加载服务。