我最近在整理服务器上的旧项目时翻出一个代号叫caveman的小工具。这名字有点自嘲——在别人都在用容器编排、可观测性平台、告警路由那一整套现代基础设施的时候我这边是一个纯 Python 标准库写成的、不到 300 行的健康检查脚本靠 systemd 拉起来安安静静跑了半年多。但就是这么个“返祖”项目反而让我想明白了很多事。尤其是那次线上监控栈自己先挂了、业务宕机没人发现的尴尬事故之后我越发觉得监控工具本身不应该成为整个系统里最复杂、最需要被监控的东西。这篇文章就从头讲讲 caveman 的设计思路、核心代码、部署细节以及这半年里踩过的那些坑。如果你也在维护小规模服务、家庭网络或自建应用被 Prometheus 全家桶压得喘不过气这篇应该对你有用。1. 从一次监控失效事故说起我们到底在用什么监控1.1 事故经过Docker 守护进程卡死导致监控全部失明事情发生在去年秋天。我有一套跑在单机 Docker 上的监控组合Prometheus 负责抓指标Grafana 出面板Alertmanager 发告警中间还挂了一堆 exporter。表面上挺专业实际上这套东西本身占了我那台小服务器 1.5G 内存Docker 镜像加起来十几个。有一天凌晨那台服务器的 Docker daemon 直接卡死了所有容器进入假死状态包括负责告警的几个容器。讽刺的是被监控的业务服务也恰好在那天凌晨出了故障网站返回 502 持续了将近两个小时。事后我复盘发现整个排查过程非常黑色幽默我先发现业务挂了然后想去看监控数据结果 Grafana 打不开。再去看 Prometheus也没响应。最后发现 Docker daemon 自己挂掉了。也就是说这堆监控工具不但没能帮我发现问题反而成为了一个需要排障的新问题——而且因为目标服务不可达和监控本身崩溃的表现高度相似反而干扰了排查。1.2 复盘时的三个扎心问题事故之后我列了一个问题清单三句话就能概括这套监控栈本身需要至少 3 到 4 个容器的协作Prometheus、Grafana、Alertmanager、exporter任何一个环节出问题告警链路就断掉而且我根本不知情。配置体系太复杂。Prometheus 的 relabel 规则、Alertmanager 的路由树半个月不碰就得翻文档才能改明白。我真正需要的其实很简单。业务高峰期我只有一个诉求服务不可达时在我手机上弹一条消息。监控面板一个月也未必打开一次。所以本质上我为自己 80% 的场景付了 200% 的复杂度。而这个度就是 caveman 这个项目要解决的问题。1.3 Cave Man 风格的工具哲学Cave Man 这个词在开发者圈里通常指那种不引框架、不用中间件、纯靠基础语言特性和系统能力把活干完的“原始作风”。很多人会觉得这是技术倒退但从稳定性角度看它有一个现代工具链比不上的优点故障半径小得肉眼可见。我给 caveman 定了几条硬规矩依赖为零。只用 Python 标准库socket、smtplib、sqlite3、urllib、fcntl连第三方 requests 都不用。总共一个代码文件任何一段代码都能被团队里任何一个人看懂。状态持久化用 sqlite单文件跑挂了删掉再建也就几秒钟。不引入消息队列、不引入时间序列数据库、不引入配置中心。这条哲学特别适合中小规模的自运维场景。大型系统该用 Prometheus 还得用但对一台服务器、几个服务端口的场景caveman 这种方案反而更可靠——因为它几乎没有可以被破坏的中间层。2. caveman 设计定位一台旧笔记本就能跑的零依赖监控2.1 功能范围控制只做三件事写代码之前我先把所有“想要”的功能列了一遍然后无情地砍到只剩三件探测每隔固定时间探测目标主机的指定 TCP 端口是否可达。记录把每次探测结果和状态变化写入本地 sqlite 数据库方便事后追溯。通知状态从正常变为异常时发告警从异常恢复时发通知异常持续过久时发升级提醒。你没看错没有面板、没有历史曲线、没有 API、没有多租户。监控的核心价值在于“及时知道出事了”而不是“把历史曲线画得多好看”。曲线图这种东西真出事的时候你是没心思看的。2.2 和现成方案怎么选caveman vs PrometheusGrafana vs Uptime Kuma我特意花时间对比了几个方案列成表格供你参考维度cavemanPrometheus GrafanaUptime Kuma部署复杂度复制一个 py 文件和一份 jsonDocker Compose 十几行配置五个容器容器一条命令但依赖 Node.js 和前端构建内存占用常驻进程 20-30MB1.2-1.5GB200-300MB依赖数量0Python 标准库不夸张地说几十个 Go 和 JS 组件光 npm 依赖就几百兆告警渠道任意可以手写 SMTP / Webhook官方支持较多但配置复杂内置很多渠道比较方便扩展性要加功能得自己改代码极强生态最完整中等适合规模个人项目、内网几个服务多服务、多指标、需要 SLO 追踪个人博客、小站点数量多结论很明确我需要的不是功能更多而是维护成本更低。Uptime Kuma 也很香我承认它界面很漂亮、告警渠道开箱即用。但当时我的目标还包括一个学习需求我想彻底搞明白一个健康检查工具的内部逻辑。所以与其用轮子不如亲手造一个看得见每一颗螺丝的裸轮子。2.3 为什么没直接用现成轮子我要的是能改任何渠道的自由用过现成监控方案的人都懂它给你一堆预设的告警渠道但你想加一个钉钉机器人的时候得去翻它的文档、看它支持不支持、然后也许还要写插件。caveman 的做法很土每次探测完状态有变化就调用一个send_notify()函数渠道逻辑全在一个文件里。加一个渠道加一个函数就行。这种自由度对于一个需要折腾各种奇奇怪怪告警场景的人来说是刚需。比如我后来把自己的手机号短信网关也接了进去——因为 SMTP 那封邮件我已经看腻了。3. 核心代码拆解300 行标准库实现的可监控引擎3.1 配置文件JSON 本身就是最好的DSLcaveman 的配置我用了一个 JSON 文件没用 YAML。原因有两点第一Python 标准库直接import json零依赖第二JSON 不支持注释和奇怪的数据类型这反而迫使配置保持简单、语义清晰。我的config.json长这样{ interval: 60, locale: Asia/Shanghai, targets: [ { name: blog-nginx, host: 127.0.0.1, port: 80, timeout: 5, threshold: 3, upgrade_interval: 3600 }, { name: nas-synology, host: 192.168.1.10, port: 5000, timeout: 5, threshold: 5 } ], notify: { email: { from: monitorexample.com, to: [opsexample.com], smtp_host: smtp.example.com, smtp_port: 587, username: monitor, password: xxxx } } }关键参数解释一下threshold连续多少次失败才触发告警。这个就是抗网络抖动的第一道防线。upgrade_interval如果故障一直存在每隔多少秒发一封“还在失败哦”的升级提醒避免故障持续几小时后人都忘了。timeout单次 TCP 连接的超时秒数。我一般设 5 秒内网目标这个值足够。3.2 探测模块TCP 四层检查为什么比 HTTP 更普适先看最简单、也最关键的一段代码它是一个标准库 socket 实现的 TCP 端口探测import socket def check_tcp(host: str, port: int, timeout: float 5.0) - bool: try: with socket.create_connection((host, port), timeouttimeout): return True except OSError: return False为什么用 TCP 而不是 HTTP 探测因为我的监控对象有很大一部分压根不是 Web 服务——比如 NAS 的 SSH 端口、MySQL 的 3306 端口、内网 Git 仓库的 22 端口。TCP 四层探测对它们全部适用而且实现成本极低。如果想对 HTTP 服务做真正的业务可用性检查可以让配置里多一个http_path字段然后这样升级from urllib.request import Request, urlopen def check_http(host: str, port: int, path: str /, timeout: float 5.0) - bool: url fhttp://{host}:{port}{path} try: with urlopen(url, timeouttimeout) as resp: return resp.status 200 except OSError: return False注意TCP 通不代表业务正常。TCP 握手只要服务器内核的网络栈还活着就能成功但应用层可能已经卡死。比如 MySQL 连接数耗尽时3306 端口照样能建立 TCP 连接但查询语句进去就卡死。所以对核心服务我会优先用 HTTP/应用层探测而一般的内网小服务用 TCP 就够。3.3 状态持久化小小的 sqlite 承载全部历史状态和事件记录用 sqlite建表就一句CREATE TABLE IF NOT EXISTS。我一开始尝试过每次探测写一行 JSON 到日志文件但排查问题时要按目标名过滤、按时间排序几百行之后就很痛苦。sqlite 是标准库自带模块代码量也只多三行import sqlite3 def init_db(db_path: str state.db): with sqlite3.connect(db_path) as conn: conn.execute( CREATE TABLE IF NOT EXISTS events ( id INTEGER PRIMARY KEY AUTOINCREMENT, ts TEXT NOT NULL, target TEXT NOT NULL, state TEXT NOT NULL, detail TEXT ) ) def record_event(target: str, state: str, detail: str ): with sqlite3.connect(state.db) as conn: conn.execute( INSERT INTO events (ts, target, state, detail) VALUES (?, ?, ?, ?), (datetime.now().astimezone().isoformat(), target, state, detail), )每次记录时用with sqlite3.connect自动提交连接用完即关避免了长期持有连接导致的文件句柄堆积问题。这算是我吃过亏之后才养成的习惯。3.4 通知模块SMTP 和 Webhook 两条腿走路邮件用smtplibWebhook 用urllib都是标准库。发送邮件的代码我加了两个容易被忽略的细节显式设置超时、把发信人和收件人做进模板。import smtplib from email.mime.text import MIMEText def send_email(cfg: dict, subject: str, body: str): msg MIMEText(body, plain, utf-8) msg[Subject] subject msg[From] cfg[from] msg[To] , .join(cfg[to]) try: with smtplib.SMTP(cfg[smtp_host], cfg[smtp_port], timeout10) as s: s.starttls() s.login(cfg[username], cfg[password]) s.send_message(msg) except smtplib.SMTPException as e: # 通知失败不能影响主流程记录后继续 record_event(notification, failed, str(e))重点是最后这个try/except。刚开始写的时候通知模块直接卡住了整个主循环——邮件服务器一抖探测也跟着全停这个坑后面专门讲。Webhook 的发送大同小异from urllib.request import Request, urlopen def send_webhook(url: str, payload: dict): data json.dumps(payload).encode(utf-8) req Request(url, datadata, headers{Content-Type: application/json}) try: with urlopen(req, timeout10) as resp: return resp.status except OSError: return -13.5 主循环和状态机让失败孕育出告警的算法核心循环非常朴素就是while True: 遍历所有 targets; 逐个探测; 调用状态机; sleep(interval)。状态机才是整个工具的灵魂它决定了什么情况下发哪种通知def update_target_state(target_name: str, ok: bool, threshold: int, upgrade_interval: int): st states[target_name] if ok: if st.fail_count threshold: send_notify(target_name, 恢复, f{target_name} 已恢复正常) record_event(target_name, recovered, ) st.fail_count 0 st.notified False st.last_notify_ts 0 else: st.fail_count 1 if st.fail_count threshold: send_notify(target_name, 告警, f{target_name} 连续失败 {threshold} 次) st.notified True st.last_notify_ts time.time() elif st.notified and upgrade_interval 0: if time.time() - st.last_notify_ts upgrade_interval: send_notify(target_name, 升级提醒, f{target_name} 异常已持续) st.last_notify_ts time.time()逻辑要点在于前threshold - 1次失败只是默默计数不发任何消息避免网络抖动引发的连环误报。第threshold次失败才发首次告警这是“转状态”的关键节点。之后每隔upgrade_interval秒发一次升级提醒保证不会因为用户没看到邮件而漏掉持续故障。成功恢复后必须通知否则人会一直以为服务还是挂的。这套逻辑写下来不超过 40 行但它覆盖了我能想到的所有监控语义不误报、不漏报、故障不沉默、恢复有交代。4. 部署实录一条 systemd 单元让 caveman 跑半年不用管4.1 为什么用 systemd 而不是 cron说真的cron 也能跑这个脚本很多服务器上 cron 活得好好的。但我最终选择 systemd有两个实际好处。第一systemd 对“守护进程”的语义更完整。cron 只是到点执行命令命令异常退出后没人管systemd 的Restarton-failure可以在进程崩溃后自动拉起还有RestartSec控制拉起间隔。第二日志管理更舒服。caveman 的 print 输出会被 journald 自动收集用journalctl -u caveman -f就能实时看日志配合journalctl --since 1 hour ago查历史不用自己造日志轮转的轮子。4.2 service 单元完整配置逐行说明我的/etc/systemd/system/caveman.service是这个样子[Unit] Descriptioncaveman health monitor Afternetwork-online.target Wantsnetwork-online.target [Service] Typesimple Usercaveman Groupcaveman ExecStart/usr/bin/python3 /opt/caveman/caveman.py --config /etc/caveman/config.json WorkingDirectory/var/lib/caveman Restarton-failure RestartSec30 NoNewPrivilegestrue ProtectSystemstrict ProtectHometrue ReadWritePaths/var/lib/caveman PrivateTmptrue [Install] WantedBymulti-user.target几个配置项解释一下Afternetwork-online.target确保机器网络已经就绪再启动监控进程避免开机时误报。NoNewPrivilegestrue和ProtectSystemstrictsystemd 的加固选项让进程没有权限写系统目录即使被人注入代码也搞不了破坏。这就是模块化下的安全防护不用额外装 seccomp 工具。WorkingDirectory/var/lib/caveman数据库文件放在这个固定目录备份起来只拷一个目录就行。RestartSec30崩溃后等 30 秒再拉起避免频繁重启把日志刷爆。部署完成后三步走sudo systemctl daemon-reload sudo systemctl enable --now caveman.service sudo systemctl status caveman.serviceenable --now一步到位同时完成开机自启和立刻启动。4.3 日志持久化和大小控制journald 不配置会无限涨journald 默认可能会把日志攒得很大尤其是调试阶段可能每分钟打一行。我一般这样限制sudo journalctl --vacuum-size100M这是在清空历史日志到 100M 以内。如果想让 systemd 自动限制编辑/etc/systemd/journald.conf把SystemMaxUse设为100M然后重启 journald[Journal] SystemMaxUse100M对我来说caveman 的日志本来就是“平时没人看”的只会在排查问题时翻一下100M 上限绰绰有余。4.4 多实例和目录布局一个目录搞定所有我的目录布局是按“配置、代码、数据”分离的/opt/caveman/caveman.py— 主程序/etc/caveman/config.json— 配置文件/var/lib/caveman/state.db— 运行时数据库为什么这么分因为/opt和/var可以分别做备份策略配置文件改成只读权限防止手滑改坏sudo chmod 600 /etc/caveman/config.json sudo chown root:caveman /etc/caveman/config.json这样即使是运行用户 caveman 也只能读配置不能改避免在程序有漏洞时被恶意写入配置。5. 跑了半年踩过的坑从误报到漏报的排查全记录5.1 误报的来源不只是网络抖动IPv6 双栈超时翻倍caveman 上线第一个星期某个目标突然连续收到两封“恢复-告警-恢复-告警”的邮件。排查之后发现问题出在socket.create_connection对 IPv6 的处理上。这只函数默认会走系统的地址解析逻辑如果目标域名同时有 A 记录和 AAAA 记录它会先尝试 IPv6 地址。而我这台监控机所在的网络IPv6 路由其实没有完全配好连接 IPv6 地址会一直卡到超时然后才退回 IPv4导致探测耗时超过了 timeout被判定为失败。解法非常简单强制 IPv4。def check_tcp_ipv4(host: str, port: int, timeout: float 5.0) - bool: try: with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s: s.settimeout(timeout) s.connect((host, port)) return True except OSError: return False如果你的目标都在内网绝大多数是纯 IPv4直接用这个更干净。有 IPv6 需求的话再单独做地址族适配。5.2 通知通道拖垮监控循环SMTP 服务器一抖探测全线阻塞这是我在 3.4 节埋的雷。最初的实现里send_email没有设置超时也没有包裹 try/except。结果某次 SMTP 服务器 TLS 握手异常starttls()一直挂着smtplib默认超时时间非常长整个主循环被卡住后面的探测全部冻结。这个坑的本质是故障处理路径本身成为单点故障。修复方法有两层第一给所有外部调用加显式超时。smtplib.SMTP(host, port, timeout10)urlopen(..., timeout10)都在创建连接阶段就设好。第二通知模块的异常绝对不能往上抛必须局部捕获、记录一条notification failed事件然后继续执行后续探测。告警发不出去是次要问题监控本身停摆才是致命问题。5.3 告警风暴和重复提醒指数退避才是对人友好的节奏最开始我的升级提醒写的是“每 10 分钟签到一次”。结果有一次 NAS 硬盘故障维修了两个小时我的邮箱收到了 12 封“NAS 异常已持续”的邮件差点把邮箱塞满。后来我改成指数退避首次告警后5 分钟、30 分钟、2 小时、6 小时各提醒一次之后每 6 小时一次。逻辑实现上就是让upgrade_interval可以传一个数组upgrade_sequence [300, 1800, 7200, 21600] # 根据 fail_count 命中对应的间隔这样既保证故障不会在中途被遗忘又不至于把人的注意力轰炸到麻木。5.4 重启风暴监控端先启动导致全量误报有一次服务器重启caveman 被 systemd 拉起来的时候网络和 NAS 都还在启动过程中。结果就是所有目标前 3 次探测全部失败caveman 齐刷刷地给所有目标各发了一封告警。解法有两个层面。第一在 service 里加Afternetwork-online.target尽量等网络就绪后再启动第二在配置里加一个startup_grace参数意思是程序启动后前 N 秒内只探测、不判断、不发告警startup_grace config.get(startup_grace, 0) if time.time() - start_time startup_grace: continue # 不计数不通知只管把状态跑通我把startup_grace设成 120 秒足够等 NAS 和自建服务慢慢起来。这个机制非常管用从那以后再也没出现过开机误报。5.5 一次真实的漏报排查TCP 黑洞与业务假死最后这个坑是最难的——它曾让一个服务故障完全没有触发告警。现象是某个数据库服务连接不上但 caveman 没有告警。日志显示 TCP 探测始终成功fail_count 一直是 0。原因是这台服务器的 iptables 有一条规则在特定条件下会把入站连接直接 drop不是拒绝 reset而是静默丢包。对发起方来说TCP 连接一直卡在 SYN_SENT 状态直到超时但对监控机来说create_connection如果只是建立了 TCP 连接就返回它就认为一切正常——但此时应用层其实根本没起来。这个案例教会我一件事TCP 探测只保证“内核网络栈活着”不保证“业务活着”。对核心业务服务我最终改成了 HTTP 或自定义协议层探测。比如数据库我会定期执行一个最轻量的查询确认服务真的可以处理请求对 Nginx就请求/healthz校验返回状态码。这类探测代码与业务绑定不能做成通用模块但这是“可靠监控”绕不过去的一环。6. 你该怎么判断 caveman 方案适不适合你6.1 适合用 caveman 的三类场景根据我这半年的体验如果符合下面的情况caveman 会非常顺手内网小规模监控自己家里或办公室几台服务器、NAS、树莓派目标是端口可达性。个人项目和原型阶段业务还没稳定监控告警逻辑先跑通没必要引入重量级基础设施。学习型项目想彻底搞明白监控背后的原理用 caveman 入门比啃 Prometheus 文档强得多。6.2 哪些情况坚决别用 caveman我也得说句公道话caveman 不是万能的。下面这些情况请直接上 Prometheus/云厂商监控多云、多地域、多租户需要统一采集、统一告警路由caveman 的配置会爆炸。需要 SLA/SLO 追踪、容量预测这需要历史指标的高精度存储和查询不是 sqlite 能搞定的。告警联系人复杂不同的服务、不同的值班组、不同的通知渠道需要一个成熟的告警管理系统。监控是产品的一部分如果你的系统要对外提供“可用性报告”这种能力还是选严肃的时间序列数据库。6.3 从复杂监控降级到 caveman我建议砍掉哪些指标如果你已经是 Prometheus 老用户想“返祖”一把我建议保留的指标最低限度是端口可达性、HTTP 状态码、磁盘使用率、系统负载和内存水位。其他花里胡哨的指标在中小规模场景下都是噪音。砍指标不是功能退化而是减少认知负担。一个目标每天给你 20 个指标99% 的时间里你一个都不会看不如留 4 个每一个真出问题时都值得让你被叫醒。提示凡是告警消息请确保包含四个要素——什么东西、什么现象、持续多久、谁能处理。少一个都是在给对方制造熬夜排查的麻烦。我个人折腾 caveman 过程里最大的收获不是省下多少内存而是重新养成了一个习惯拿到任何需求先问自己一句“最少的依赖能不能先跑起来”很多场景的答案是能而且跑得还挺稳。如果你手头也有几个小服务又不甘心被复杂工具链绑架试试写一个属于自己的“caveman”吧哪怕它只有 100 行那种掌控感绝对值得体验一次。
我最近在整理服务器上的旧项目时翻出一个代号叫caveman的小工具。这名字有点自嘲——在别人都在用容器编排、可观测性平台、告警路由那一整套现代基础设施的时候我这边是一个纯 Python 标准库写成的、不到 300 行的健康检查脚本靠 systemd 拉起来安安静静跑了半年多。但就是这么个“返祖”项目反而让我想明白了很多事。尤其是那次线上监控栈自己先挂了、业务宕机没人发现的尴尬事故之后我越发觉得监控工具本身不应该成为整个系统里最复杂、最需要被监控的东西。这篇文章就从头讲讲 caveman 的设计思路、核心代码、部署细节以及这半年里踩过的那些坑。如果你也在维护小规模服务、家庭网络或自建应用被 Prometheus 全家桶压得喘不过气这篇应该对你有用。1. 从一次监控失效事故说起我们到底在用什么监控1.1 事故经过Docker 守护进程卡死导致监控全部失明事情发生在去年秋天。我有一套跑在单机 Docker 上的监控组合Prometheus 负责抓指标Grafana 出面板Alertmanager 发告警中间还挂了一堆 exporter。表面上挺专业实际上这套东西本身占了我那台小服务器 1.5G 内存Docker 镜像加起来十几个。有一天凌晨那台服务器的 Docker daemon 直接卡死了所有容器进入假死状态包括负责告警的几个容器。讽刺的是被监控的业务服务也恰好在那天凌晨出了故障网站返回 502 持续了将近两个小时。事后我复盘发现整个排查过程非常黑色幽默我先发现业务挂了然后想去看监控数据结果 Grafana 打不开。再去看 Prometheus也没响应。最后发现 Docker daemon 自己挂掉了。也就是说这堆监控工具不但没能帮我发现问题反而成为了一个需要排障的新问题——而且因为目标服务不可达和监控本身崩溃的表现高度相似反而干扰了排查。1.2 复盘时的三个扎心问题事故之后我列了一个问题清单三句话就能概括这套监控栈本身需要至少 3 到 4 个容器的协作Prometheus、Grafana、Alertmanager、exporter任何一个环节出问题告警链路就断掉而且我根本不知情。配置体系太复杂。Prometheus 的 relabel 规则、Alertmanager 的路由树半个月不碰就得翻文档才能改明白。我真正需要的其实很简单。业务高峰期我只有一个诉求服务不可达时在我手机上弹一条消息。监控面板一个月也未必打开一次。所以本质上我为自己 80% 的场景付了 200% 的复杂度。而这个度就是 caveman 这个项目要解决的问题。1.3 Cave Man 风格的工具哲学Cave Man 这个词在开发者圈里通常指那种不引框架、不用中间件、纯靠基础语言特性和系统能力把活干完的“原始作风”。很多人会觉得这是技术倒退但从稳定性角度看它有一个现代工具链比不上的优点故障半径小得肉眼可见。我给 caveman 定了几条硬规矩依赖为零。只用 Python 标准库socket、smtplib、sqlite3、urllib、fcntl连第三方 requests 都不用。总共一个代码文件任何一段代码都能被团队里任何一个人看懂。状态持久化用 sqlite单文件跑挂了删掉再建也就几秒钟。不引入消息队列、不引入时间序列数据库、不引入配置中心。这条哲学特别适合中小规模的自运维场景。大型系统该用 Prometheus 还得用但对一台服务器、几个服务端口的场景caveman 这种方案反而更可靠——因为它几乎没有可以被破坏的中间层。2. caveman 设计定位一台旧笔记本就能跑的零依赖监控2.1 功能范围控制只做三件事写代码之前我先把所有“想要”的功能列了一遍然后无情地砍到只剩三件探测每隔固定时间探测目标主机的指定 TCP 端口是否可达。记录把每次探测结果和状态变化写入本地 sqlite 数据库方便事后追溯。通知状态从正常变为异常时发告警从异常恢复时发通知异常持续过久时发升级提醒。你没看错没有面板、没有历史曲线、没有 API、没有多租户。监控的核心价值在于“及时知道出事了”而不是“把历史曲线画得多好看”。曲线图这种东西真出事的时候你是没心思看的。2.2 和现成方案怎么选caveman vs PrometheusGrafana vs Uptime Kuma我特意花时间对比了几个方案列成表格供你参考维度cavemanPrometheus GrafanaUptime Kuma部署复杂度复制一个 py 文件和一份 jsonDocker Compose 十几行配置五个容器容器一条命令但依赖 Node.js 和前端构建内存占用常驻进程 20-30MB1.2-1.5GB200-300MB依赖数量0Python 标准库不夸张地说几十个 Go 和 JS 组件光 npm 依赖就几百兆告警渠道任意可以手写 SMTP / Webhook官方支持较多但配置复杂内置很多渠道比较方便扩展性要加功能得自己改代码极强生态最完整中等适合规模个人项目、内网几个服务多服务、多指标、需要 SLO 追踪个人博客、小站点数量多结论很明确我需要的不是功能更多而是维护成本更低。Uptime Kuma 也很香我承认它界面很漂亮、告警渠道开箱即用。但当时我的目标还包括一个学习需求我想彻底搞明白一个健康检查工具的内部逻辑。所以与其用轮子不如亲手造一个看得见每一颗螺丝的裸轮子。2.3 为什么没直接用现成轮子我要的是能改任何渠道的自由用过现成监控方案的人都懂它给你一堆预设的告警渠道但你想加一个钉钉机器人的时候得去翻它的文档、看它支持不支持、然后也许还要写插件。caveman 的做法很土每次探测完状态有变化就调用一个send_notify()函数渠道逻辑全在一个文件里。加一个渠道加一个函数就行。这种自由度对于一个需要折腾各种奇奇怪怪告警场景的人来说是刚需。比如我后来把自己的手机号短信网关也接了进去——因为 SMTP 那封邮件我已经看腻了。3. 核心代码拆解300 行标准库实现的可监控引擎3.1 配置文件JSON 本身就是最好的DSLcaveman 的配置我用了一个 JSON 文件没用 YAML。原因有两点第一Python 标准库直接import json零依赖第二JSON 不支持注释和奇怪的数据类型这反而迫使配置保持简单、语义清晰。我的config.json长这样{ interval: 60, locale: Asia/Shanghai, targets: [ { name: blog-nginx, host: 127.0.0.1, port: 80, timeout: 5, threshold: 3, upgrade_interval: 3600 }, { name: nas-synology, host: 192.168.1.10, port: 5000, timeout: 5, threshold: 5 } ], notify: { email: { from: monitorexample.com, to: [opsexample.com], smtp_host: smtp.example.com, smtp_port: 587, username: monitor, password: xxxx } } }关键参数解释一下threshold连续多少次失败才触发告警。这个就是抗网络抖动的第一道防线。upgrade_interval如果故障一直存在每隔多少秒发一封“还在失败哦”的升级提醒避免故障持续几小时后人都忘了。timeout单次 TCP 连接的超时秒数。我一般设 5 秒内网目标这个值足够。3.2 探测模块TCP 四层检查为什么比 HTTP 更普适先看最简单、也最关键的一段代码它是一个标准库 socket 实现的 TCP 端口探测import socket def check_tcp(host: str, port: int, timeout: float 5.0) - bool: try: with socket.create_connection((host, port), timeouttimeout): return True except OSError: return False为什么用 TCP 而不是 HTTP 探测因为我的监控对象有很大一部分压根不是 Web 服务——比如 NAS 的 SSH 端口、MySQL 的 3306 端口、内网 Git 仓库的 22 端口。TCP 四层探测对它们全部适用而且实现成本极低。如果想对 HTTP 服务做真正的业务可用性检查可以让配置里多一个http_path字段然后这样升级from urllib.request import Request, urlopen def check_http(host: str, port: int, path: str /, timeout: float 5.0) - bool: url fhttp://{host}:{port}{path} try: with urlopen(url, timeouttimeout) as resp: return resp.status 200 except OSError: return False注意TCP 通不代表业务正常。TCP 握手只要服务器内核的网络栈还活着就能成功但应用层可能已经卡死。比如 MySQL 连接数耗尽时3306 端口照样能建立 TCP 连接但查询语句进去就卡死。所以对核心服务我会优先用 HTTP/应用层探测而一般的内网小服务用 TCP 就够。3.3 状态持久化小小的 sqlite 承载全部历史状态和事件记录用 sqlite建表就一句CREATE TABLE IF NOT EXISTS。我一开始尝试过每次探测写一行 JSON 到日志文件但排查问题时要按目标名过滤、按时间排序几百行之后就很痛苦。sqlite 是标准库自带模块代码量也只多三行import sqlite3 def init_db(db_path: str state.db): with sqlite3.connect(db_path) as conn: conn.execute( CREATE TABLE IF NOT EXISTS events ( id INTEGER PRIMARY KEY AUTOINCREMENT, ts TEXT NOT NULL, target TEXT NOT NULL, state TEXT NOT NULL, detail TEXT ) ) def record_event(target: str, state: str, detail: str ): with sqlite3.connect(state.db) as conn: conn.execute( INSERT INTO events (ts, target, state, detail) VALUES (?, ?, ?, ?), (datetime.now().astimezone().isoformat(), target, state, detail), )每次记录时用with sqlite3.connect自动提交连接用完即关避免了长期持有连接导致的文件句柄堆积问题。这算是我吃过亏之后才养成的习惯。3.4 通知模块SMTP 和 Webhook 两条腿走路邮件用smtplibWebhook 用urllib都是标准库。发送邮件的代码我加了两个容易被忽略的细节显式设置超时、把发信人和收件人做进模板。import smtplib from email.mime.text import MIMEText def send_email(cfg: dict, subject: str, body: str): msg MIMEText(body, plain, utf-8) msg[Subject] subject msg[From] cfg[from] msg[To] , .join(cfg[to]) try: with smtplib.SMTP(cfg[smtp_host], cfg[smtp_port], timeout10) as s: s.starttls() s.login(cfg[username], cfg[password]) s.send_message(msg) except smtplib.SMTPException as e: # 通知失败不能影响主流程记录后继续 record_event(notification, failed, str(e))重点是最后这个try/except。刚开始写的时候通知模块直接卡住了整个主循环——邮件服务器一抖探测也跟着全停这个坑后面专门讲。Webhook 的发送大同小异from urllib.request import Request, urlopen def send_webhook(url: str, payload: dict): data json.dumps(payload).encode(utf-8) req Request(url, datadata, headers{Content-Type: application/json}) try: with urlopen(req, timeout10) as resp: return resp.status except OSError: return -13.5 主循环和状态机让失败孕育出告警的算法核心循环非常朴素就是while True: 遍历所有 targets; 逐个探测; 调用状态机; sleep(interval)。状态机才是整个工具的灵魂它决定了什么情况下发哪种通知def update_target_state(target_name: str, ok: bool, threshold: int, upgrade_interval: int): st states[target_name] if ok: if st.fail_count threshold: send_notify(target_name, 恢复, f{target_name} 已恢复正常) record_event(target_name, recovered, ) st.fail_count 0 st.notified False st.last_notify_ts 0 else: st.fail_count 1 if st.fail_count threshold: send_notify(target_name, 告警, f{target_name} 连续失败 {threshold} 次) st.notified True st.last_notify_ts time.time() elif st.notified and upgrade_interval 0: if time.time() - st.last_notify_ts upgrade_interval: send_notify(target_name, 升级提醒, f{target_name} 异常已持续) st.last_notify_ts time.time()逻辑要点在于前threshold - 1次失败只是默默计数不发任何消息避免网络抖动引发的连环误报。第threshold次失败才发首次告警这是“转状态”的关键节点。之后每隔upgrade_interval秒发一次升级提醒保证不会因为用户没看到邮件而漏掉持续故障。成功恢复后必须通知否则人会一直以为服务还是挂的。这套逻辑写下来不超过 40 行但它覆盖了我能想到的所有监控语义不误报、不漏报、故障不沉默、恢复有交代。4. 部署实录一条 systemd 单元让 caveman 跑半年不用管4.1 为什么用 systemd 而不是 cron说真的cron 也能跑这个脚本很多服务器上 cron 活得好好的。但我最终选择 systemd有两个实际好处。第一systemd 对“守护进程”的语义更完整。cron 只是到点执行命令命令异常退出后没人管systemd 的Restarton-failure可以在进程崩溃后自动拉起还有RestartSec控制拉起间隔。第二日志管理更舒服。caveman 的 print 输出会被 journald 自动收集用journalctl -u caveman -f就能实时看日志配合journalctl --since 1 hour ago查历史不用自己造日志轮转的轮子。4.2 service 单元完整配置逐行说明我的/etc/systemd/system/caveman.service是这个样子[Unit] Descriptioncaveman health monitor Afternetwork-online.target Wantsnetwork-online.target [Service] Typesimple Usercaveman Groupcaveman ExecStart/usr/bin/python3 /opt/caveman/caveman.py --config /etc/caveman/config.json WorkingDirectory/var/lib/caveman Restarton-failure RestartSec30 NoNewPrivilegestrue ProtectSystemstrict ProtectHometrue ReadWritePaths/var/lib/caveman PrivateTmptrue [Install] WantedBymulti-user.target几个配置项解释一下Afternetwork-online.target确保机器网络已经就绪再启动监控进程避免开机时误报。NoNewPrivilegestrue和ProtectSystemstrictsystemd 的加固选项让进程没有权限写系统目录即使被人注入代码也搞不了破坏。这就是模块化下的安全防护不用额外装 seccomp 工具。WorkingDirectory/var/lib/caveman数据库文件放在这个固定目录备份起来只拷一个目录就行。RestartSec30崩溃后等 30 秒再拉起避免频繁重启把日志刷爆。部署完成后三步走sudo systemctl daemon-reload sudo systemctl enable --now caveman.service sudo systemctl status caveman.serviceenable --now一步到位同时完成开机自启和立刻启动。4.3 日志持久化和大小控制journald 不配置会无限涨journald 默认可能会把日志攒得很大尤其是调试阶段可能每分钟打一行。我一般这样限制sudo journalctl --vacuum-size100M这是在清空历史日志到 100M 以内。如果想让 systemd 自动限制编辑/etc/systemd/journald.conf把SystemMaxUse设为100M然后重启 journald[Journal] SystemMaxUse100M对我来说caveman 的日志本来就是“平时没人看”的只会在排查问题时翻一下100M 上限绰绰有余。4.4 多实例和目录布局一个目录搞定所有我的目录布局是按“配置、代码、数据”分离的/opt/caveman/caveman.py— 主程序/etc/caveman/config.json— 配置文件/var/lib/caveman/state.db— 运行时数据库为什么这么分因为/opt和/var可以分别做备份策略配置文件改成只读权限防止手滑改坏sudo chmod 600 /etc/caveman/config.json sudo chown root:caveman /etc/caveman/config.json这样即使是运行用户 caveman 也只能读配置不能改避免在程序有漏洞时被恶意写入配置。5. 跑了半年踩过的坑从误报到漏报的排查全记录5.1 误报的来源不只是网络抖动IPv6 双栈超时翻倍caveman 上线第一个星期某个目标突然连续收到两封“恢复-告警-恢复-告警”的邮件。排查之后发现问题出在socket.create_connection对 IPv6 的处理上。这只函数默认会走系统的地址解析逻辑如果目标域名同时有 A 记录和 AAAA 记录它会先尝试 IPv6 地址。而我这台监控机所在的网络IPv6 路由其实没有完全配好连接 IPv6 地址会一直卡到超时然后才退回 IPv4导致探测耗时超过了 timeout被判定为失败。解法非常简单强制 IPv4。def check_tcp_ipv4(host: str, port: int, timeout: float 5.0) - bool: try: with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s: s.settimeout(timeout) s.connect((host, port)) return True except OSError: return False如果你的目标都在内网绝大多数是纯 IPv4直接用这个更干净。有 IPv6 需求的话再单独做地址族适配。5.2 通知通道拖垮监控循环SMTP 服务器一抖探测全线阻塞这是我在 3.4 节埋的雷。最初的实现里send_email没有设置超时也没有包裹 try/except。结果某次 SMTP 服务器 TLS 握手异常starttls()一直挂着smtplib默认超时时间非常长整个主循环被卡住后面的探测全部冻结。这个坑的本质是故障处理路径本身成为单点故障。修复方法有两层第一给所有外部调用加显式超时。smtplib.SMTP(host, port, timeout10)urlopen(..., timeout10)都在创建连接阶段就设好。第二通知模块的异常绝对不能往上抛必须局部捕获、记录一条notification failed事件然后继续执行后续探测。告警发不出去是次要问题监控本身停摆才是致命问题。5.3 告警风暴和重复提醒指数退避才是对人友好的节奏最开始我的升级提醒写的是“每 10 分钟签到一次”。结果有一次 NAS 硬盘故障维修了两个小时我的邮箱收到了 12 封“NAS 异常已持续”的邮件差点把邮箱塞满。后来我改成指数退避首次告警后5 分钟、30 分钟、2 小时、6 小时各提醒一次之后每 6 小时一次。逻辑实现上就是让upgrade_interval可以传一个数组upgrade_sequence [300, 1800, 7200, 21600] # 根据 fail_count 命中对应的间隔这样既保证故障不会在中途被遗忘又不至于把人的注意力轰炸到麻木。5.4 重启风暴监控端先启动导致全量误报有一次服务器重启caveman 被 systemd 拉起来的时候网络和 NAS 都还在启动过程中。结果就是所有目标前 3 次探测全部失败caveman 齐刷刷地给所有目标各发了一封告警。解法有两个层面。第一在 service 里加Afternetwork-online.target尽量等网络就绪后再启动第二在配置里加一个startup_grace参数意思是程序启动后前 N 秒内只探测、不判断、不发告警startup_grace config.get(startup_grace, 0) if time.time() - start_time startup_grace: continue # 不计数不通知只管把状态跑通我把startup_grace设成 120 秒足够等 NAS 和自建服务慢慢起来。这个机制非常管用从那以后再也没出现过开机误报。5.5 一次真实的漏报排查TCP 黑洞与业务假死最后这个坑是最难的——它曾让一个服务故障完全没有触发告警。现象是某个数据库服务连接不上但 caveman 没有告警。日志显示 TCP 探测始终成功fail_count 一直是 0。原因是这台服务器的 iptables 有一条规则在特定条件下会把入站连接直接 drop不是拒绝 reset而是静默丢包。对发起方来说TCP 连接一直卡在 SYN_SENT 状态直到超时但对监控机来说create_connection如果只是建立了 TCP 连接就返回它就认为一切正常——但此时应用层其实根本没起来。这个案例教会我一件事TCP 探测只保证“内核网络栈活着”不保证“业务活着”。对核心业务服务我最终改成了 HTTP 或自定义协议层探测。比如数据库我会定期执行一个最轻量的查询确认服务真的可以处理请求对 Nginx就请求/healthz校验返回状态码。这类探测代码与业务绑定不能做成通用模块但这是“可靠监控”绕不过去的一环。6. 你该怎么判断 caveman 方案适不适合你6.1 适合用 caveman 的三类场景根据我这半年的体验如果符合下面的情况caveman 会非常顺手内网小规模监控自己家里或办公室几台服务器、NAS、树莓派目标是端口可达性。个人项目和原型阶段业务还没稳定监控告警逻辑先跑通没必要引入重量级基础设施。学习型项目想彻底搞明白监控背后的原理用 caveman 入门比啃 Prometheus 文档强得多。6.2 哪些情况坚决别用 caveman我也得说句公道话caveman 不是万能的。下面这些情况请直接上 Prometheus/云厂商监控多云、多地域、多租户需要统一采集、统一告警路由caveman 的配置会爆炸。需要 SLA/SLO 追踪、容量预测这需要历史指标的高精度存储和查询不是 sqlite 能搞定的。告警联系人复杂不同的服务、不同的值班组、不同的通知渠道需要一个成熟的告警管理系统。监控是产品的一部分如果你的系统要对外提供“可用性报告”这种能力还是选严肃的时间序列数据库。6.3 从复杂监控降级到 caveman我建议砍掉哪些指标如果你已经是 Prometheus 老用户想“返祖”一把我建议保留的指标最低限度是端口可达性、HTTP 状态码、磁盘使用率、系统负载和内存水位。其他花里胡哨的指标在中小规模场景下都是噪音。砍指标不是功能退化而是减少认知负担。一个目标每天给你 20 个指标99% 的时间里你一个都不会看不如留 4 个每一个真出问题时都值得让你被叫醒。提示凡是告警消息请确保包含四个要素——什么东西、什么现象、持续多久、谁能处理。少一个都是在给对方制造熬夜排查的麻烦。我个人折腾 caveman 过程里最大的收获不是省下多少内存而是重新养成了一个习惯拿到任何需求先问自己一句“最少的依赖能不能先跑起来”很多场景的答案是能而且跑得还挺稳。如果你手头也有几个小服务又不甘心被复杂工具链绑架试试写一个属于自己的“caveman”吧哪怕它只有 100 行那种掌控感绝对值得体验一次。
