audio_codebuddy/deploy-package/health-monitor/README.md

线上后端健康监控

后端挂掉时邮件告警到 f1f3@qq.com。带去重防告警风暴，服务恢复时单独发 ✅。

文件清单

文件	部署到	说明
health-monitor.sh	/usr/local/bin/	主脚本
health-monitor.env.example	/etc/health-monitor.env (改名)	凭证模板
install.sh	(服务器上跑一次)	一键部署

部署步骤

# 1. 在本地打包
cd deploy-package/health-monitor && tar czf /tmp/health-monitor.tar.gz .

# 2. 上传到服务器
scp -P 22622 /tmp/health-monitor.tar.gz root@8.159.134.106:/tmp/

# 3. 服务器上安装
ssh -p 22622 root@8.159.134.106
cd /tmp && tar xzf health-monitor.tar.gz && cd health-monitor

# 4. 填 QQ 邮箱授权码
cp health-monitor.env.example /etc/health-monitor.env
vim /etc/health-monitor.env       # 填入 QQ_AUTH_CODE
chmod 600 /etc/health-monitor.env

# 5. 部署
bash install.sh

获取 QQ 邮箱授权码

1. 网页登录 https://mail.qq.com
2. 设置 → 账户 → POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务
3. 开启 SMTP 服务（手机短信验证）
4. 复制"授权码"（16 位字符串，不是你的 QQ 密码）

工作原理

• cron 每 5 分钟跑一次（错开整点 :03）
• 同时检测 /health 和 /api/navigation/config
• 连续 2 次失败 才触发告警（防抖动）
• 30 分钟冷却期 — 同一故障不会反复骚扰
• 服务恢复时单独发一条 ✅

排查命令

tail -f /var/log/health-monitor.log          # 实时日志
pm2 list                                      # PM2 进程状态
ss -lntp | grep 3100                          # 端口监听
curl -sS http://127.0.0.1:3100/health         # 直接验证
bash /usr/local/bin/health-monitor.sh         # 手动跑一次

验证告警链路

# 1. 暂停后端
pm2 stop server

# 2. 触发检测
bash /usr/local/bin/health-monitor.sh
bash /usr/local/bin/health-monitor.sh   # 第二次会发邮件

# 3. 启动后端
pm2 start server

# 4. 触发恢复检测
bash /usr/local/bin/health-monitor.sh   # 会发"已恢复"邮件

设计取舍

• 不依赖 Node.js 全局包 — 纯 bash + openssl，零依赖
• 走 465 SSL — 阿里云屏蔽 25 出站（防垃圾邮件），465 通畅
• 状态文件 /var/lib/health-monitor/state — 记录连续失败次数 + 上次告警时间，去重逻辑
• 错开 :03 而非整点 — 避免大量实例同时打到云服务