Telegram Bot 告警与通知配置实战指南 (Telegram Alert Setup Guide)

 💡 文档背景：本指南结合本项目在实际部署过程中的实战踩坑与配置经验编写，手把手指导如何从零创建 Telegram Bot、获取个人/群组 Chat ID、配置代理与阈值，并将现货-合约 Delta 中性套利监控服务部署至后台常驻运行。

目录 (Table of Contents)

一、准备工作：创建 Telegram 机器人与获取 Token

1. 向 @BotFather 申请 Bot

  1. 在 Telegram 搜索栏搜索官方机器人 @BotFather（带蓝色认证对勾）并打开对话。
  2. 发送指令：/newbot。
  3. 按照提示输入机器人的 显示名称（Name，如 My Arbitrage Alert）。
  4. 输入机器人的 唯一用户名（Username，必须以 bot 结尾，如 web3arbitrage_alert_bot）。
  5. BotFather 会生成一段 API Token（形如 8875314269:AAHR_ZNcI_I3e5ZINV22222222222222222）。

⚠️ 关键避坑点（Token 完整性）：

  • 完整的 Token 必须包含前面的数字 ID、英文冒号以及后缀密钥（例如 8875314269:AAxxxxxxxxx）。
  • 切勿漏掉冒号前面的数字 ID，否则请求 Telegram API 时会直接报错 HTTP 404 Not Found。
  • 配置时无需手动添加 bot 前缀（直接填写 8875314269:AAxxxx... 即可）。

二、获取接收通知的 Chat ID（私聊 vs 群组）

通知推送支持发送给个人私聊或多人协作群组。

场景 A：发送到「个人私聊」

  1. 打开 Telegram，私聊您的新机器人并点击一次底部的 START（或发送 /start）。
  2. 在终端运行本项目的内置辅助命令：
    python cli.py monitor get-chat-id
  3. 系统将自动输出您的个人 Chat ID（正整数，例如 6927319496）：
    • [👤 私聊 (Private)] 名称: Daveking ➔ Chat ID: 6927319496

场景 B：发送到「Telegram 群组」（多人告警协作，推荐）

Telegram 为了保护群聊隐私，默认对普通机器人开启了「群消息隐私隔离 (Group Privacy)」，因此普通在群里发文字，机器人是无法感知群 ID 的。

推荐获取群组 ID 的三步法：

  1. 拉机器人进群：将您的 Bot（如 @web3arbitrage_alert_bot）邀请加入目标群组。
  2. 在群内发送一条激活指令： 在群聊天框中输入并发送（注意包含 @机器人用户名）：
    /start@web3arbitrage_alert_bot

    💡 或者在群设置中将该 Bot 设为群管理员（Admin），无需给任何敏感权限。

  3. 在终端一键抓取群组 ID： 回到服务器终端，运行：
    python cli.py monitor get-chat-id
    系统会立刻扫描 Telegram API 并列出群组的 Chat ID（群组 ID 为负数，例如 -5572509478 或 -100xxxxxxxxxx）：
    ✅ 共发现 2 个交互 Chat 记录:
------------------------------------------------------------
 • [👤 私聊 (Private)] 名称: DavekingInNorth ➔ Chat ID: 6927319496
 • [👥 群组 (Group)] 名称: W3 start business ➔ Chat ID: -5572509478
------------------------------------------------------------

三、环境变量配置 (.env)

复制 .env.example 为 .env（若已有直接编辑）：

cp .env.example .env
nano .env

填入以下配置项：

# ==========================================
# Telegram Bot 告警通知配置
# ==========================================
# 完整的 Bot Token (含数字前缀与冒号)
TELEGRAM_BOT_TOKEN=8875314269:AAHR_ZNcI_I3e5ZINVrgKlhz22222222222

# 接收告警的 Chat ID (个人填正数如 6927319496，群组填负数如 -5572509488)
TELEGRAM_CHAT_ID=-5572509428

# 可选代理 (如果服务器位于国内等无法直连 Telegram 的网络环境，必须配置)
# 支持 HTTP 与 SOCKS5 协议，如: http://127.0.0.1:7890 或 socks5://127.0.0.1:1080
TELEGRAM_PROXY=

# ==========================================
# 监控与告警策略阈值配置
# ==========================================
# 监控目标交易所 (默认: binance，支持: binance, bybit, all)
MONITOR_EXCHANGES=binance

# 监控资产/交易对 (默认: ALL 自动扫描所有活跃合约持仓)
MONITOR_SYMBOLS=ALL

# 实时巡检轮询间隔 (秒，默认: 60)
MONITOR_INTERVAL_SECONDS=60

# 费率翻转预警阈值 (基准年化 APY %，低于此值或为负时触发告警，默认: 5.0)
ALERT_MIN_APY_PCT=5.0

# 单腿强平黄色补保警戒线 (% 距离，默认: 15.0)
ALERT_LIQ_WARNING_PCT=15.0

# 单腿强平红色紧急清仓警戒线 (% 距离，默认: 5.0)
ALERT_LIQ_DANGER_PCT=5.0

# 重复告警冷却防刷时间 (秒，默认: 1800 秒 / 30分钟)
ALERT_COOLDOWN_SECONDS=1800

四、连通性与推送功能验证

在正式启动 7x24 小时后台守护之前，请通过 CLI 工具执行以下四步验证：

1. 测试 Bot 连通性

python cli.py monitor test
  • 预期输出：✅ 测试成功！Bot @web3arbitragebot 已成功向 Chat ID -5572509488 发送通知。
  • 此时群内会收到一张自检测试卡片。

2. 执行单次实盘监控巡检 (控制台排版输出)

python cli.py monitor check
  • 系统会自动连入交易所接口，读取全部活跃持仓、计算当前标记价 vs 强平价距离、抓取实时资金费率与年化，并在控制台输出格式化报表。

3. 测试收益全景战报广播推送

python cli.py monitor broadcast
  • 系统会实时聚合当前合约历史资金费流水、扣除的手续费摩擦、累计套利净收益与实现净年化（APR），直接向 Telegram 群组推送一份排版精美的收益战报。

五、后台常驻运行（Tmux 与 Systemd）

监控系统需要 7x24 小时持续轮询，推荐以下两种后台运行方式：

方案 A：使用 tmux 会话运行（最轻量、推荐）

1. 创建并启动监控会话

tmux new-session -d -s cex-monitor "cd ~/src/github/xiluo/cex-arbitrage && .venv/bin/python cli.py monitor run"

2. 进入会话查看实时监控日志

tmux attach -t cex-monitor

3. 离开会话（保持后台继续运行）

按下键盘组合键：Ctrl + B，然后松开按 D（Detach）。

4. 重启或停止监控

# 重启监控
tmux kill-session -t cex-monitor && tmux new-session -d -s cex-monitor "cd ~/src/github/xiluo/cex-arbitrage && .venv/bin/python cli.py monitor run"

# 彻底停止监控
tmux kill-session -t cex-monitor

方案 B：使用 Linux systemd 系统服务（生产高可用，开机自启）

创建系统服务配置文件：

sudo nano /etc/systemd/system/cex-arbitrage-monitor.service

写入以下配置（请将路径和 User 替换为您的实际用户名与目录）：

[Unit]
Description=CEX Delta Neutral Arbitrage Monitor & Alert Daemon
After=network.target

[Service]
Type=simple
User=dave
WorkingDirectory=/home/ubuntu/src/github/xiluo/cex-arbitrage
ExecStart=/home/ubunut/src/github/dave/cex-arbitrage/.venv/bin/python cli.py monitor run
Restart=always
RestartSec=10
EnvironmentFile=/home/ubuntu/src/github/dave/cex-arbitrage/.env

[Install]
WantedBy=multi-user.target

启动并设置开机自启：

sudo systemctl daemon-reload
sudo systemctl enable cex-arbitrage-monitor
sudo systemctl start cex-arbitrage-monitor

# 查看运行状态与实时日志
sudo systemctl status cex-arbitrage-monitor
journalctl -u cex-arbitrage-monitor -f

六、实战高频踩坑与常见问题 (FAQ)

Q1: 在 Telegram 里私聊给 Bot 发送 START 或文字，Bot 没有任何回复？

  • 原因：本项目使用的 Telegram Bot 是服务端单向推送客户端（Outbound Push Client），专用于发生费率翻转、爆仓风险或定时结算时向您发送通知，未集成自动聊天回复逻辑。
  • 正常现象：只要运行 python cli.py monitor test 能正常在 Telegram 中收到卡片消息，即代表机器人工作完全正常。

Q2: 报错 Bot Token 鉴权失败 (HTTP 404): Not Found？

  • 原因：TELEGRAM_BOT_TOKEN 填写不完整。
  • 排查：检查 .env 中的 Token 是否缺失了冒号前的数字 ID（如只填了 AAHR_xxxx）。正确格式必须为：8875314269:AAHR_xxxx。

Q3: 报错 HTTP 403 Forbidden: the bot can't send messages to the bot？

  • 原因：TELEGRAM_CHAT_ID 误填了 Bot 自己的 ID。机器人无法给自己发送消息。
  • 解决：运行 python cli.py monitor get-chat-id 获取您的个人 ID 或群组 ID，并填入 .env。

Q4: 报错 HTTP 400 Bad Request: chat not found？

  • 原因：
    1. 如果是私聊：您尚未在 Telegram 中搜索该 Bot 并点击 START，Telegram 禁止机器人主动骚扰未主动发起会话的用户。
    2. 如果是群组：未将 Bot 拉入该群组，或群 ID 填错了负号（群组 ID 必须包含前面的 - 负号，如 -5572509478）。

Q5: 为什么拉入群组后运行 get-chat-id 依然看不到群？

  • 原因：Telegram 群组隐私模式限制了机器人接收普通群聊。
  • 解决办法：在群里艾特机器人发送一次指令（如 /start@您的bot用户名），或者在群设置里将 Bot 设为管理员 (Admin)，然后再运行 python cli.py monitor get-chat-id。

Q6: 为什么我的服务器连不上 Telegram API（提示超时或网络不可达）？

  • 原因：服务器位于中国大陆等限制访问 Telegram 域名的网络环境。
  • 解决办法：在服务器部署代理（如 Clash / V2ray / SOCKS5），并在 .env 中配置 TELEGRAM_PROXY=http://127.0.0.1:7890。

附录：告警卡片样式预览

1. 资金费率翻转 / 低 APY 预警卡片

🚨 【资金费率翻转预警 · 费率转负】
━━━━━━━━━━━━━━━━━━
• 交易所: Binance
• 标的合约: ETH/USDT
• 实时费率: -0.0150%
• 折合基准年化: -16.42%
• 预警阈值: APY < 5.00%
• 下次结算时间: 2026-08-23 00:00:00 UTC
━━━━━━━━━━━━━━━━━━
💡 建议操作:
资金费率已变为负数，做空套利需向多头支付资金费，持有将持续产生摩擦亏损！建议立即评估平仓对冲离场。
• 执行平仓指令: python cli.py trade close

2. 单腿强平风险警报卡片

⚠️ 【单腿强平预警 · 需立即补保】
━━━━━━━━━━━━━━━━━━
• 交易所: Binance
• 持仓标的: BNB/USDT [做空 (SHORT) 20X]
• 持仓数量: 13.0100
• 当前标记价: $696.25
• 预估强平价: $780.00
• 爆仓安全距离: 距离强平仅剩 12.03% (低于警戒线 15.0%)
━━━━━━━━━━━━━━━━━━
🚨 处置建议:
标的价格持续上涨，空单强平距离收窄！
👉 建议立即向合约账户划转保证金（USDT/ETH/BNB）提升安全边际，避免中性对冲单腿爆仓！
• 划转命令: python cli.py transfer usdt --amount <数量>

3. 定时费率结算与收益战报卡片

💰 【资金费率结算与套利收益播报】
━━━━━━━━━━━━━━━━━━
• 交易所: Binance | 标的: BNB/USDT
• 本次结算收入: +1.8540 USDT (费率: +0.0176%)
• 结算时间: 2026-08-22 16:00:00 UTC
━━━━━━━━━━━━━━━━━━
📊 套利全景绩效:
• 累计已收资金费: +185.6000 USDT
• 累计交易手续费: -14.2000 USDT
• 累计套利净收益: +171.4000 USDT
• 当前总持仓本金: $12,500.00 USDT
• 实际实现净年化: +15.32% (毛年化: +16.78%)
• 运行统计: 已运行 21.5 天 (共结算 64 次 | 正费率胜率 96.9%)
━━━━━━━━━━━━━━━━━━
⏰ 下次预计结算: 2026-08-23 00:00:00 UTC

Comments

Post a Comment

Popular posts from this blog

OpenDevin: Demystifying the Open-Source Quest for an Autonomous AI Software Engineer

Image
In early 2024, a company named Cognition AI unveiled " Devin ," a demo of what they called the world's first fully autonomous AI software engineer . The demo was stunning, showing an AI agent completing complex development tasks from a single prompt, debugging its own errors, and using common developer tools. While the world was impressed, a crucial element was missing: access. Devin was a closed-source, proprietary model. In the spirit of open innovation, the global developer community responded almost immediately with a resounding call to action, which materialized as OpenDevin. This article will explore the architecture, significance, and future of this ambitious open-source project. What is OpenDevin? Beyond a Smarter Autocomplete At its core, OpenDevin is an open-source project that aims to replicate and ultimately surpass the capabilities of an autonomous AI agent for software engineering . It is not merely a code suggestion tool like GitHub Copilot . While Copilot...
Read more

揭秘现代代理客户端：内核差异、协议封装与配置解析的底层逻辑

在配置跨平台代理网络时，我们经常会遇到“同一个节点，在这个 App 能用，在另一个 App 报错”的玄学问题。表面上看这是客户端的兼容性问题，但实际上，这涉及到代理内核的派系之争、配置文件的降级与兼容，以及不同解析器处理字符串时的容错率差异。 本文将以 iOS 环境下的代理配置为例，深入剖析 VLESS + Reality 协议在不同客户端之间流转的底层机制。 一、 内核之争：Xray-core vs. Sing-box 目前主流的代理客户端，其 UI 之下通常运行着两种主流的 Golang 内核： Xray-core 派系 (如 v2box, v2rayTun) ：这是目前使用最广泛的底层之一。它定义了 vless:// 这类 URI Scheme 的标准格式。因此，使用此类内核的客户端，对标准的分享链接拥有“原生级别的兼容性”。 Sing-box 派系 (如 Hiddify) ：这是一个相对较新、旨在统一各家协议且更加轻量化的通用代理平台。它同样由 Golang 编写，但采用了完全不同的 JSON 结构化配置标准。 问题根源： 当你在 Hiddify 中输入一个 vless:// 链接时，它并不是直接把这串 URI 丢给内核运行，而是必须先通过前端的一个 Parser（解析器），将其解构、提取参数，然后再重新序列化成 Sing-box 能够理解的 JSON 对象。 如果在解构过程中，遇到了非常规的参数组合（例如 xtls-rprx-vision 流控参数加上特定的 SNI 伪装），Parser 的正则表达式一旦匹配失败或抛出异常，前端就会直接阻断导入，报出“格式错误”，尽管内核其实完全支持这个协议。 二、 协议标准化的两难：URI 链接 vs. 声明式配置 在跨设备分享节点时，主要有两种载体： 1. 单行 URI Scheme ( vless://... ) 这是一种高密度的字符串压缩方式。它的优点是极其方便在即时通讯软件或剪贴板中传递，不需要处理换行和缩进。 但它的缺点在于 无法携带复杂的路由规则 。通过 URI 导入的节点，只能依赖客户端内置的全局规则（例如 GeoIP 或 GeoSite）来实现类似 GitHub、Cursor、OpenAI 走代理，局域网和国内 IP 直连的分流逻辑。 2. 声明式配置 (如 Clash 的 YAML) 对于习惯了...
Read more

Kubernetes: External Secrets Operator vs. CSI Driver, A Deep Dive Secret Management

Image
  Introduction In Kubernetes, managing secrets like API keys and database passwords is a critical task. While Kubernetes has a built-in  Secret  object, its default base64 encoding doesn't offer strong protection. This has led to the rise of better solutions. This article will introduce the  external-secrets  project, compare it with the popular Secrets Store CSI Driver, and explore other leading solutions to help everyone choose the right tool for their needs. What is External Secrets Operator? External Secrets Operator (ESO) is a Kubernetes operator that bridges the gap between external secret management systems and a Kubernetes cluster. It reads secrets from providers like AWS Secrets Manager, HashiCorp Vault, or Google Secret Manager and automatically creates and synchronizes them as native Kubernetes  Secret  objects within the cluster. The core idea is simple: the source of truth for secrets remains in a secure, external vault. ESO ensures that a...
Read more