bt-telegram-webhook

宝塔面板 Telegram 通知转发器

宝塔面板（BT Panel / aaPanel）缺少官方 Telegram 通知通道，bt-telegram-webhook 填补这一空白。 它同时是一个通用 JSON Webhook 服务——面板机上的所有服务（备份脚本、监控 cron、运维告警）都可以共用同一个端点，将任意 JSON 消息格式化后转发到 Telegram。

---

为什么需要它？

痛点	解决方案
宝塔面板无官方 Telegram 通知通道	开箱即用的 Telegram Bot 转发
面板机上多个服务需要各自通知	通用 JSON Webhook，一个端点服务所有
小内存 VPS 资源紧张	纯 Go 标准库、零依赖、常驻内存极低

特性

• 零依赖 — 纯 Go 标准库，CGO_ENABLED=0 编译
• 交叉编译 — 覆盖 Linux / macOS / Windows × amd64 / arm64
• 灵活鉴权 — URL Query / Header / Bearer Token 三选一
• 安全加固 — 恒定时间 token 比较、请求体大小限制、systemd 沙箱
• 智能分段 — 超长消息自动按换行符拆分（适配 Telegram 4096 字符上限）
• 即插即用 — 单二进制 + .env 文件，无需数据库

---

快速开始

1. 下载

从 Releases 下载对应平台的压缩包：

平台	文件
Linux x86_64	bt-telegram-webhook-linux-amd64.tar.gz
Linux ARM64	bt-telegram-webhook-linux-arm64.tar.gz
macOS x86_64	bt-telegram-webhook-darwin-amd64.tar.gz
macOS Apple Silicon	bt-telegram-webhook-darwin-arm64.tar.gz
Windows x86_64	bt-telegram-webhook-windows-amd64.zip

或自行编译：

CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o bt-telegram-webhook .

2. 配置

cp .env.example .env

编辑 .env，填入你的 Telegram Bot Token 和 Chat ID：

TG_BOT_TOKEN=123456:your_bot_token
TG_CHAT_ID=1234567890
WEBHOOK_TOKEN=your_secret_here

3. 运行

./bt-telegram-webhook

程序启动时自动读取当前目录下的 .env 文件。

环境变量

变量	必填	默认值	说明
TG_BOT_TOKEN	是	-	Telegram Bot Token
TG_CHAT_ID	是	-	Telegram Chat ID
WEBHOOK_TOKEN	否	空（不鉴权）	共享密钥
LISTEN_HOST	否	0.0.0.0	监听地址
LISTEN_PORT	否	8417	监听端口
WEBHOOK_PATH	否	/webhook	Webhook 路径
TELEGRAM_API_BASE	否	https://api.telegram.org	Telegram API 地址（可用于自建反代）
ENV_FILE	否	./.env	.env 文件路径

.env 中的值不会覆盖已存在的环境变量。值不支持多行，不支持 export 前缀。

宝塔面板配置

请求 URL（三选一）

Query 参数方式：

http://127.0.0.1:8417/webhook?token=your_secret_here

请求头（可选，替代 URL 传 token）

{"X-Webhook-Token": "your_secret_here"}

或：

{"Authorization": "Bearer your_secret_here"}

请求体

{
  "title": "$title",
  "msg": "$msg",
  "type": "$type"
}

通用 Webhook

面板机上的任何服务都可以复用同一端点。推荐的 JSON 格式：

{
  "source": "backup-script",
  "title": "备份完成",
  "message": "站点 example.com 已完成全量备份",
  "level": "info",
  "data": {
    "duration": "32s",
    "files": 18
  }
}

程序不限制 JSON 结构——任何合法 JSON 都会被格式化后转发到 Telegram。

curl 测试

curl -X POST 'http://127.0.0.1:8417/webhook?token=your_secret_here' \
  -H 'Content-Type: application/json' \
  -d '{"title":"测试通知","msg":"这是一条测试消息","type":"测试"}'

systemd 部署

mkdir -p /opt/bt-telegram-webhook
cp bt-telegram-webhook .env /opt/bt-telegram-webhook/
cp bt-telegram-webhook.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable --now bt-telegram-webhook

查看状态：

systemctl status bt-telegram-webhook
journalctl -u bt-telegram-webhook -f

service 文件已包含完整的安全加固（DynamicUser、ProtectSystem=strict、MemoryDenyWriteExecute 等），无需手动创建系统用户。

日志

程序日志输出到 stderr（systemd 自动收集到 journal）。

场景	日志示例	说明
成功转发	200 ok 128ms	不记录来源 IP（本机调用为主）
鉴权失败	401 unauthorized (10.0.0.5:34221)	记录 IP，便于排查
方法错误	405 PUT /webhook (10.0.0.5:34221)	记录 IP 和方法
JSON 解析失败	400 render: invalid JSON: ...	记录错误原因
Telegram 发送失败	502 telegram: status 429: ...	记录下游错误

端点

路径	方法	说明
/healthz	GET	健康检查，返回 {"ok":true}
/webhook（可配置）	GET	就绪检查，返回 {"ok":true,"message":"ready"}
/webhook（可配置）	POST	接收 JSON 并转发到 Telegram

安全说明

• 本项目设计为本机服务间通信（宝塔面板和面板机上的脚本通过 127.0.0.1 调用）
• 如果需要从外部网络访问，务必设置 WEBHOOK_TOKEN 并通过 HTTPS 反代暴露
• 不要将 .env 文件提交到版本控制

FAQ

宝塔面板怎么配置 Telegram 通知？ 在宝塔面板「告警设置 → Webhook」中填入 http://127.0.0.1:8417/webhook?token=your_secret_here，请求体使用 {"title":"$title","msg":"$msg","type":"$type"}。

宝塔面板支持哪些通知渠道？ 官方支持邮件、短信、企业微信等，但没有 Telegram。bt-telegram-webhook 通过 Webhook 接口补上了这个缺失。

可以用在 aaPanel（英文版宝塔）上吗？ 可以。aaPanel 和宝塔面板的 Webhook 接口完全一致，配置方式相同。

只转发宝塔面板的消息吗？ 不是。它是通用 JSON Webhook——面板机上的任何服务（备份脚本、监控 cron、自定义告警）都可以向同一端点 POST JSON，内容会被格式化后转发到 Telegram。

支持 Telegram 群组和频道吗？ 支持。将 TG_CHAT_ID 设为群组或频道的 Chat ID 即可。

适合小内存 VPS 吗？ 非常适合。纯 Go 编写、零第三方依赖、常驻内存极低，在 256 MB 内存的 VPS 上也能稳定运行。

License

MIT