trace/services/notify-gateway/README.md

notify-gateway

独立、可复用的 HTTP 通知网关。调用方必须显式指定渠道；Telegram 还必须指定命名 BOT。 当前支持 Telegram、企业微信群 Webhook，并保留默认关闭的 OneBot QQ 适配器。

API

POST /send
Authorization: Bearer $NOTIFY_GATEWAY_TOKEN
Content-Type: application/json

{
  "title": "通知标题",
  "text": "正文",
  "channels": ["telegram", "wecom_webhook"],
  "telegram_bot": "default",
  "idempotency_key": "caller:event:123"
}

可选 images 接受最多 4 张 JPEG/PNG Base64 图片，原始数据合计不超过 50 MB：

{"images":[{"filename":"photo.jpg","content_type":"image/jpeg","data_base64":"..."}]}

• Telegram：尺寸允许时直接以照片显示，过大时只发送压缩照片预览。
• 企业微信：尺寸允许时直接显示，过大时只发送不超过平台限制的压缩预览。
• 网关不再把原图作为文件附件发送，也不接受远程图片 URL。
• 空标题表示原样纯文本模式，不自动添加 emoji 或分割线。
• channels 必须显式指定且不能为空。
• 请求 Telegram 时必须提供配置中存在的 telegram_bot。
• 建议始终提供稳定的 idempotency_key，成功渠道在重试时会跳过。
• GET /health 无需鉴权。

启动

1. 复制 .env.example 为 .env 并填写所需渠道变量。
2. 复制 config.example.yaml 为 config/config.yaml，按需启用渠道和命名 BOT。
3. 创建共享网络：docker network create shared-services，或设置 SHARED_NETWORK_NAME。
4. 运行 docker compose up -d --build。

Python 调用客户端见 notifiers/client.py。