目标：在 Uptime Kuma 上配置 QQ 邮箱 SMTP 邮件告警，采用 HTTP(s)–关键字 监控避免“关站仍被判正常”的误报，并给出常见故障的定位与修复方法。

说明：本文已脱敏，使用占位符域名（如 status.example.com、app.example.com），不包含真实服务器信息。

---

【实操教学】

0）前置假设与路径规范

• Kuma 已用 Docker Compose 部署在服务器（示例路径）：

cd /home/admin/uptime-kuma        # cd：切换到项目目录（change directory）
docker compose ps                 # 查看状态；应见本地回环端口映射（如 127.0.0.1:3001->3001）

• 外网通过反向代理访问：https://status.example.com。

• 你希望监控如下站点：app.example.com、rss.example.com、vault.example.com、sync.example.com 等。

---

1）开启 QQ 邮箱 SMTP 并取得“授权码”

1. 登录 QQ 邮箱网页版 → 右上角 设置 → 账户。

2. 找到 POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV 服务 → 开启 SMTP 服务。

3. 按页面指引完成验证（短信/扫码），页面会显示一串 16 位授权码（注意：这不是你的登录密码）。

4. 把授权码妥善保存到你的密码库（如 Vaultwarden），条目建议命名为“QQ SMTP 授权码”。

术语小抄

• SMTP：发邮件的协议/服务。

• 授权码：替代邮箱登录密码供程序使用的“专用密码”。

---

2）在 Uptime Kuma 创建“SMTP（Email）”通知通道

1. 打开 https://status.example.com → 右上角 菜单 → 设置 → 通知 → ＋新增通知。

2. 类型选择 SMTP（Email），按下表填写（推荐 465/SSL）：

字段	示例值
名称	QQ-Email（自定义）
SMTP 服务器	smtp.qq.com
端口	465
安全	SSL/TLS（或 587 + STARTTLS 二选一）
用户名	yourid@qq.com
密码	第 1 步生成的授权码
发件人（From）	yourid@qq.com（通常需与用户名一致）
收件人（To）	you@example.com（可多个，逗号分隔；失败时为每个收件人单独建通道）

3. 点击 测试，应该收到一封测试邮件 → 保存。

4. 可勾选“设为默认通知”，便于新建监控直接复用。

若失败，先看 Kuma 日志（第 6 节），常见是授权码错误或端口、安全选项不匹配。

---

3）为站点配置

HTTP(s)–关键字

监控（杜绝“关站仍 200/403”）

很多面板“关闭站点”会返回 200/403 的静态提示页。普通 HTTP(s) 监控只看状态码，很可能误判为 UP。

做法：统一使用 HTTP(s) – 关键字 类型，要求页面正文必须包含某段特征文字。

示例：为 app.example.com 新建监控

1. 新增监控 → 监控类型 选 HTTP(s) – 关键字。

2. URL：https://app.example.com/。

3. 关键字（Body must contain）：填一个只有正常页面才会出现的词/短句，例如站点标题里的一段、或页面独有元素：

MyApp Dashboard

4. 间隔：如 600 秒（你可按站点重要性调整）。

5. 通知：绑定上一步的 QQ-Email 通道，Down/Up 都勾选。

6. 保存并 测试。

同理，给 rss.example.com、vault.example.com、sync.example.com 分别添加关键词（如 FreshRSS、Vaultwarden、Syncthing 等）。博客可用页头/页脚的一句独有文字。

关键字选择建议：简短稳定，不随登录状态或 A/B 实验变化；避免太常见的词（例如 “Login” 可能在维护页也出现）。

---

4）可选：为“服务本体”再加一条 TCP 监控

为了快速定位是“入口（Nginx/证书）问题”还是“后端服务挂了”，建议组合监控：

• HTTP(s)-关键字：盯住“对外入口”，发现证书/反代/页面异常；

• TCP 端口：盯住“服务本体”是否在跑（如 Syncthing 的 22000）。

示例（新增 TCP 监控）：

• 类型：TCP Port

• 目标：SERVER_IP:22000

• 间隔：600 秒

• 绑定 QQ-Email 通知

---

5）做一次“拉闸演练”（确认真实能报警）

任选一个低风险站点做临时故障模拟：

• 在面板里把该站点“关闭”或把反代目标改成不存在的端口（例如 127.0.0.1:9）；

• 观察 Kuma：应先收到 Down 邮件，恢复后收到 Up 邮件；

• 恢复站点/反代配置。

---

6）查看与排查日志（出问题时第一现场）

cd /home/admin/uptime-kuma                # cd：切到项目目录
docker compose logs -f                    # 实时查看 Kuma 日志（Ctrl+C 退出）

常见报错速解：

• 535 Authentication failed / Invalid login → 授权码错、SMTP 未开启。

• ECONNREFUSED / ETIMEDOUT → 端口/安全选项与服务器不匹配，或临时网络问题。

• CERT_HAS_EXPIRED / TLS 相关 → 服务器时间不准或链路被劫持：

timedatectl status                 # 查看时间同步状态
sudo timedatectl set-ntp true      # 打开网络授时（仅需一次）

---

7）Kuma 的升级与备份

cd /home/admin/uptime-kuma
docker compose pull && docker compose up -d   # 拉取新镜像并平滑重建
docker compose logs -f                        # 观察启动日志

如需备份（数据在容器卷/挂载目录，按你的部署而定），可将数据目录打包存档。

---

【深度解析与知识扩展】

为什么“关闭站点”仍被判正常？

• 很多面板的“关闭/维护模式”会返回 200/403 的静态页；普通 HTTP(s) 监控只看状态码或连通性，不看页面内容。

• HTTP(s)–关键字 会抓取正文并校验关键字，不匹配直接判 Down，能准确识别“内容异常”。

关键字 vs. 普通 HTTP(s) vs. Browser Engine

• HTTP(s)：轻量，仅看状态码/响应时间；适合健康检查。

• HTTP(s)–关键字：抓正文校验关键字，能识别空白页/维护页/跳转页。

• HTTP(s)–Browser Engine (Chromium)：用无头浏览器渲染，能检测需要 JS 才显示的内容，但更重，用于少数复杂页面。

QQ SMTP 的 465 vs 587

• 465 + SSL/TLS：连接即加密，常见选择。

• 587 + STARTTLS：先纯文本握手，再升级到加密。两者安全性等价，QQ 均支持。

• 出站发送，无需在云防火墙开放端口（它不拦出站）。

邮件投递小贴士

• 发件人与用户名一致，避免被服务器拒收。

• 授权码泄露可随时在 QQ 邮箱设置里撤销并重建。

• 建议把授权码存放在密码库，而不是明文散落在笔记里。

组合监控的价值（HTTP + TCP）

• HTTP 报错但 TCP 正常 → 多半是证书/反代/应用逻辑问题；

• TCP 报错但 HTTP 正常不太可能（通常反过来），若出现，检查目标是否指向了错误主机/端口。

---

交付核对清单（Checklist）

• status.example.com 可访问，Kuma 正常运行

• QQ SMTP 通道测试成功（收到了测试邮件）

• 核心站点均使用 HTTP(s)–关键字 类型监控，并绑定邮件通知

• 至少为一个后端服务添加了 TCP 端口 监控

• 做过一次“拉闸演练”，能收到 Down/Up 邮件

• 记录了 Kuma 升级命令与日志查看方法

---

结语

监控只有在“真正出问题时能第一时间告诉你”才有价值。用 HTTP(s)–关键字 监控把“看得见的正常”变成“内容级正常”，再用 TCP 兜底服务本体状态；配合 QQ SMTP 的低门槛告警，你就拥有了一个轻量但可靠的可用性闭环。