简介：HKmonitor是面向海康威视摄像头的多窗口监控客户端，适合需要同时查看多路实时画面并快速切换布局的安防值守人员，也适合 Qt 开发者借鉴界面与视频交互实现。压缩包共 226 个文件，包含 cpp、h、ui 等源码文件，dll、lib 等运行依赖，以及 png、qrc 等界面资源，整体约 38.66MB，可作为基于 Qt 的监控系统参考工程。该资源重点覆盖多窗口拖拽预览、语音对讲、视频回放与全屏切换，并提供自定义视频播放进度条控件，能够满足日常监控布局调整、远程语音沟通和录像快速定位等典型需求。结合源码目录与工程配置，读者可以理清视频流接入、窗口管理和播放控制的基本结构，进而扩展或嵌入到自己的客户端中。目前已有 618 人学习下载，适合具备一定 C++/Qt 基础、希望快速搭建海康摄像头预览与回放界面的开发者参考。
1. 一个压缩包里的监控方案，到底解决了什么
凌晨两点，值班手机没响，第二天到公司才发现核心服务已经挂了四个小时——这种经历做过运维的人多少都遇到过。监控面板飘红没用，因为告警根本没发出来。后来排查发现不是规则没配，是采集器自己先停了，而没有人盯着“监控自己”这件事。HKmonitor.rar这类打包发布的监控工具套件，就是冲着这种场景来的：一个压缩包把采集端、服务端、告警通道和简易面板都装进去，解压改配置就能用。它不追求撑起几千台机器的超大规模，主打的是中小团队、单机或十几台节点内快速建立“看得见、能告警、留得下记录”的观测能力。适合谁？适合不想引入重量级监控平台、又受够了脚本定时任务那种黑匣子式日志检查的开发者与运维。如果你刚接手一批服务器却没有任何监控，或者现有监控误报漏报让你半夜白醒，那这份笔记正好对路。
2. 拆开 HKmonitor：它由哪几块构成，思路为什么这么设计
很多这类监控工具包表面上是一个解压即用的黑匣子，但内部结构基本逃不开“采集—汇聚—存储—告警—展示”五段式。先把这个结构理清楚，后面改配置和排查才有方向。
2.1 采集层：agent 设计里的两个关键决策
采集层是监控的地基，最常见的实现是每台被监控机器上放一个轻量 agent。这个 agent 做三件事：按固定周期读本机指标、把指标按约定格式上报、在本地保留最近一段原始数据作为兜底。这里有两个决策直接决定了这套监控好不好用。
第一个决策是采集走主动上报还是被动拉取。常见做法是主动上报：agent 自己按周期向服务端推送数据，服务端不开额外监听端口。这样做的好处是节点数增加时服务端压力可控，也绕开了被监控机器上开放额外端口的麻烦。坏处是服务端对节点的实时状态感知有延迟，节点掉线要等超时才暴露。如果你要监控的网络里设备种类杂、有虚拟机也有物理机，我会优先选主动上报；如果全是自己的服务器且网络可控，被动拉取能拿到更准的“当前状态”，但实现和调优成本高得多。
第二个决策是采集周期与数据粒度。拿 CPU 来说，读一次/proc/stat得到的是累计值，必须算两次采样之间的差值才是瞬时利用率；采样间隔越短曲线越真实，但上报频率和存储量会翻倍。我习惯的基线是：CPU、内存、磁盘空间这类变化慢的指标 30 秒一次，网络流量和 TCP 连接数这类突发性强的指标 10 秒一次。这个包默认值一般偏保守，拿到手先改成适合自己规模的周期，别上来就最细粒度，否则半小时后存储就把磁盘写满了。
2.2 存储与展示：为什么 SQLite 够用，指标库怎么留
存储层是这类轻量监控最容易拍脑袋的地方。有人一上来就上时序数据库，几台机器没必要；有人直接写文本文件，查询又痛苦。我见到的合理方案是两步走：热数据进 SQLite，冷数据按天滚动清理。SQLite 单文件部署，不用额外维护服务进程，查询能力对几台到几十台机器的规模完全够用。关键参数是保留策略：原始数据保留 7 天、按 5 分钟聚合的数据保留 30 天、按 1 小时聚合的数据保留 12 个月。这样磁盘占用是可控的，而且查“昨天下午某台机器内存走势”这种问题响应还在毫秒级。
展示层则分成实时视图和历史趋势两类。实时视图要的是“一屏看完全部节点”的简洁感：节点名、状态、CPU、内存、磁盘、最近一次上报时间，顶多加个上下行流量数字。历史趋势反而应该做得克制，点进具体节点能看到 24 小时的曲线即可。真正让这类工具省心的是告警状态在面板上的颜色变化——告警了节点标红、恢复后回到绿色，值班的人扫一眼就知道现在有没有事在发生，不用点进每个页面。
2.3 告警层：通知通道背后的门道
告警是监控系统的灵魂。没有告警的监控只是录像机，出了事还是靠人发现。这里面有一个绝大多数人踩过的坑：第一个版本只做了“指标超过阈值就发通知”，结果半夜告警轰炸，把真正重要的事淹没了。后来才意识到告警必须有三个状态：触发、持续、恢复。指标第一次超过阈值发一次“触发”，之后持续超限不再重复发，直到恢复后发一条“恢复”。这个设计能让告警从噪音变成信号。
通知通道的选择上，邮件还是最稳妥的兜底，但邮件有延迟且容易被提醒淹没；IM Webhook 是即时性最好的，配置也简单，核心就一个 URL。我一般建议两条通道都配：Webhook 管实时响应，邮件管留痕。阈值判定本身倒不必做得太花哨，固定阈值加上一个简单的持续 N 个周期才触发，比任何自适应算法都可靠。自适应阈值听起来高级，但没有足够长的历史数据时它就是玄学，误报起来比不报警更让人崩溃。
3. 在本地跑通 HKmonitor：完整流程与配置改动点
理论部分先落住，现在动手。假设你已经拿到HKmonitor.rar并解压到一台 Linux 服务器上，按照三分钟能跑通、默认配置能出数、改动最少能告警的优先级来操作。
3.1 解压与目录结构：先搞清楚东西放在哪
这类打包工具解压后，目录结构通常长这样：
$ mkdir -p /opt/hkmonitor && cd /opt/hkmonitor $ unrar x ../HKmonitor.rar # 或者用 unar，取决于你装的是哪个解压工具 $ tree -L 2 . ├── agent │ └── hkmonitor-agent # 采集端二进制/脚本 ├── server │ ├── hkmonitor-server # 服务端主程序 │ └── data/ # SQLite 数据文件会生成在这 ├── ui │ └── index.html # 内置的简易面板，静态文件 ├── conf │ ├── agent.yaml # 采集端配置 │ ├── server.yaml # 服务端配置 │ └── rules.yaml # 告警规则 ├── scripts │ ├── install_agent.sh # 批量下发 agent 的脚本模板 │ └── check_health.sh # 自检脚本 └── logs/ # 运行日志目录这里有一个容易看漏的点：conf/下面三个 yaml 文件各自对应不同的进程，agent.yaml改的是被监控机器的行为，server.yaml管的是服务端端口和数据保留，rules.yaml是告警规则。新手最容易把客户端配置写到服务端配置里，然后发现完全不生效。
逻辑说明：这个布局把采集与汇聚分开，agent 只管上报，server 只管接收、存储、判规则，ui 只是静态页面，不需要单独起一个 Web 服务。改动任何配置后对应的进程要重启才生效，而logs/里每个进程有独立日志文件——排查问题先看对应日志，全堆在一个文件里反而难找。
参数说明：data/目录的磁盘空间直接决定能存多久的历史数据，如果/opt挂载的磁盘很小，应该在server.yaml里把数据目录改到容量充裕的挂载点。
3.2 最小配置：只要改四个值就能跑起来
打开agent.yaml，最精简的可用配置如下：
# agent.yaml node_name: "web-01" # 节点名，在面板上显示的名字 server_addr: "http://10.0.0.10:9100" # 服务端上报地址 interval_seconds: 30 # 指标采集周期，单位秒 heartbeat_seconds: 10 # 心跳间隔，用于服务端判断节点存活 # 采集项开关 enable_cpu: true enable_memory: true enable_disk: true enable_network: true enable_tcp: truenode_name是这台机器在监控面板里的唯一标识，重复了会导致数据互相覆盖，务必唯一。server_addr指向服务端 IP 和端口，端口要和server.yaml里的监听端口一致，差了就静默丢数据，日志里没有任何报错。interval_seconds控制采集粒度，大多数场景 30 秒够用；如果你有监控突发流量的需求，单独把 network 的周期调低到 5 到 10 秒，而不是全局调低，否则存储压力大好几倍。
服务端的server.yaml改动更少，核心是监听地址、端口、数据保留策略：
# server.yaml listen_addr: "0.0.0.0" listen_port: 9100 data_dir: "/var/lib/hkmonitor" # SQLite 文件位置 retention_raw_days: 7 # 原始数据保留天数 retention_agg_days: 30 # 聚合数据保留天数 # Web 面板端口 ui_port: 9101逻辑说明：data_dir我在上面特意改到/var/lib/hkmonitor而不是默认的./data，原因很实际：很多人把程序放在/opt或家目录，磁盘空间本身紧张，而监控数据又是持续增长的，放在独立分区更容易控制。ui_port是打开浏览器看面板的端口，注意别和业务端口冲突。
参数说明：retention_raw_days决定原始数据保留多久，直接对应磁盘占用。如果监控目标是十几台机器，7 天原始 + 30 天聚合大概是几百 MB 的量级；如果上百台节点，建议把原始数据保留压到 3 天，否则 SQLite 文件会涨到几 GB。聚合间隔这类细参数不急着调，跑一周后再按磁盘占用情况改。
3.3 启动与验证：先用一条命令确认链路通了
启动顺序上，先起服务端再起 agent，反过来会出现 agent 上报失败重试的日志，虽然不影响最终结果，但会增加不必要的排查干扰。
# 1. 启动服务端（前台运行，看输出） $ cd /opt/hkmonitor $ ./server/hkmonitor-server -c conf/server.yaml & # 2. 确认服务端监听端口 $ ss -tlnp | grep 9100 LISTEN 0 128 0.0.0.0:9100 # 看到这行说明监听成功 # 3. 启动 agent（本地自监控，验证链路） $ ./agent/hkmonitor-agent -c conf/agent.yaml & # 4. 自检：脚本会检查进程、端口、磁盘三个维度 $ ./scripts/check_health.sh [OK] server process alive [OK] agent process alive [OK] port 9100 listening [OK] data dir writable逻辑说明：前台启动是为了第一轮验证时能直接看到输出；确认没问题后改成 systemd 或 nohup 托管。ss -tlnp是验证端口监听最快的方式，比ps aux | grep可靠，因为进程活着不代表端口在监听，可能是端口被占、配置没加载成功但进程没退出。
参数说明：如果check_health.sh输出里出现[FAIL] data dir writable，大概率是/var/lib/hkmonitor不存在或者当前用户没权限，先mkdir -p再chown给运行用户；如果出现[FAIL] port 9100 listening，先检查server.yaml里listen_port有没有被注释掉，再看是不是防火墙把端口挡了。
启动后，浏览器打开http://服务器IP:9101，面板页面应该能看到本机节点，CPU、内存、磁盘信息在 30 秒内开始刷新，最近上报时间列距离当前时间不超过 1 分钟。能看到这个画面，整套链路就算通了。
4. 告警规则怎么设：阈值、持续周期与通知通道配置
监控跑通了只是开始，让它在关键时刻喊出声才是价值所在。告警配置的核心集中在rules.yaml，这一节把最常见也最实用的规则写法、参数含义和调整思路讲透。
4.1 一条告警规则的结构拆解
看一条针对磁盘使用率的规则：
# rules.yaml rules: - name: "disk_usage_high" metric: "disk_used_percent" condition: "> 85" duration: 120 # 持续 120 秒才触发，防止瞬时抖动误报 interval: 3600 # 同一规则重复触发的最小间隔（秒） channels: - "webhook" - "email" receivers: - "ops@example.local" webhook_url: "http://your-im-webhook.example.local/send"逻辑说明：这条规则的意思是，磁盘使用率超过 85% 并且持续 120 秒，才判定为告警。duration是最重要的防误报参数：磁盘使用率不会在几秒内暴涨暴跌，但某些磁盘监控在文件删除瞬间会出现瞬时高位的假读数，120 秒持续窗口可以把这类毛刺滤掉。interval是重复通知的最小间隔，设为 3600 秒，即同一规则在已告警状态下 1 小时内不会重复发消息。
条件部分支持><>=<=和==，metric名称必须与 agent 上报的指标名一一对应。最常见的错误是规则里写了 agent 没有采集的指标，告警永远不触发，日志里也没有提示。所以配规则前，先确认指标真实存在：在服务器数据目录下用 SQLite 查询一下，比对着文档猜要靠谱得多。
参数调整建议：CPU 和内存这类瞬时波动大的指标，duration建议 60 秒起步；磁盘和进程存活类指标，30 秒就够。阈值设定别追求一次到位，先按保守值配，跑一周看告警历史里的触发次数再动态调，这比任何“最佳实践表”都适合你自己的环境。
4.2 通知通道配置：双通道与告警恢复
channels数组支持同时配多个通道。常见做法是 Webhook 做即时通知，邮件做留痕备份。Webhook 配置只需要一个 URL，服务端在告警触发时向该 URL POST 一段 JSON，内容包含规则名、节点名、当前值、触发时间。具体 JSON 字段不用死记，你完全可以用 Webhook 调试工具先把请求体打印出来，再根据自己平台的要求做字段映射。第一次对接时先手动 POST 一条测试数据，比直接等真告警快速得多。
恢复通知是另一个必须配的点。很多人在rules.yaml里只定义了触发条件，没配恢复条件，导致结果是：告警发了一次后，问题解决了也不会再发消息，值班的人不知道系统已恢复正常。这类工具一般有现成字段，比如recovery: true，或者在规则里加一个低于阈值才触发的隐性规则。我看到一个用的最多、最省心的写法是：服务端内置“进入告警状态后，指标回落到阈值以下并且持续 120 秒，自动发送恢复通知”，全局开关打开就行。恢复通知的重要性怎么强调都不过分——没有恢复通知的监控，告警一次后状态永远悬着，人只能手动去确认。
4.3 规则数量与告警风暴控制
还有一个听得最多的问题：规则配多少条合适？见过有人一口气配了五十条规则，结果告警风暴把真正要紧的事全淹了。我个人的判断标准是：每个节点有效告警规则控制在 5 到 8 条以内。核心节点的规则覆盖 CPU、内存、磁盘、网络连通性、关键进程、日志关键字这六类，每一类只配一条规则，优先保证“该知道的都第一时间知道”，而不是“什么都配了但真假分不清”。
如果节点规模上了几十台，务必用rules.yaml里的节点匹配字段，比如node_match: "web-.*"，让一组规则作用于同类型节点，而不是把几十台机器都写进同一条规则。否则某台机器磁盘告警发出来，所有机器的运维都要在通知群里看到这条与自己无关的消息，通知疲劳就是这么来的——发多了，人就习惯性忽略了。
批量下发 agent 的时候，scripts/install_agent.sh模板里最重要的变量是server_addr，这也是最容易配错的地方。下发前先在一台机器上跑通，再去铺量。我习惯先手工在 3 台不同类型的机器上装好，观察半天上报数据没问题，再写巡检脚本批量检查所有节点在服务端的最近上报时间，这一步能过滤掉九成以上“装了但没上报”的翻车现场。
5. 常见问题与排查：五个让监控翻车的坑和对应解法
这部分是血泪经验汇总。每一条都是在真实环境里踩过、磨过、最后定位到根因的问题，从“现象”到“原因”再到“解决”一次说清。
5.1 监控面板显示节点离线，但机器明明活着
现象：面板上某个节点标红，显示“离线”，但 SSH 登上去系统负载正常，网络也通。
原因：agent 进程退出了。最容易被忽略的是 agent 默认前台运行，会话关闭后进程跟着没了；或者 agent 启动时没有写日志文件的权限，崩溃后没有任何提示。
解决：把 agent 用 systemd 托管，设置Restart=always，并且确认logs/目录对运行用户可写。systemd 托管方式简单可靠，比 nohup 更稳，因为 nohup 只防挂断不防崩溃，进程挂掉后没人拉起来。配好之后，systemctl status hkmonitor-agent能看到运行状态和最近重启时间，排查问题时信息量比看日志大得多。
5.2 告警重复轰炸，同一个问题一晚上发了 30 条消息
现象：磁盘超过阈值后，告警消息每隔几分钟发一条，值班手机被刷屏，最后只能把通知通道 Webhook 临时停掉。
原因：规则里interval参数没配或设得太小。服务端默认的重复通知间隔可能只有 5 分钟甚至更短，而阈值的持续超限状态会不断触发发送。
解决：把interval调到 3600 秒以上，并开启恢复通知。这样同一个问题 1 小时内最多 1 条消息，恢复后再超阈值才会重新触发。告警风暴对值班注意力的消耗是隐性成本，宁可一次多等几分钟，也不要半夜被连续轰炸到直接关掉通知。
5.3 监控文件一天涨到几十 GB
现象：运行一周后查看磁盘，data/目录占了 30 多 GB，比业务数据还大。
原因：保留策略没有真正生效。常见情况是server.yaml里retention_raw_days写成了0或者没写，某些实现的默认值可能是“永不清理”；另一个常见原因是清理任务的周期性检查没触发，数据文件只增不减。
解决：确认配置文件里的保留参数是数字且大于 0，比如retention_raw_days: 7，然后重启服务端进程让配置生效。部署满一周后养成一个习惯：每周看一眼数据目录的大小变化趋势，如果持续增长而规则没变，多半是清理机制出了问题，这比等到磁盘写满再处理成本低得多。
5.4 节点时区不一致，凌晨数据出现空洞
现象：某些机器白天数据正常，每天凌晨 2 点到 3 点没有数据点，曲线断了一截。
原因：多台机器的系统时区不一致，agent 上报的时间戳混有 UTC 和本地时间。服务端做按小时聚合时，时间戳落在不同小时桶里，导致“空洞”和峰值错位。实际排查时才发现是时区惹的祸，AC 机器是 UTC+8，各机器的本地时区没校准。
解决：统一所有被监控机器的时区，最省事的是在批量下发脚本里加上timedatectl set-timezone Asia/Shanghai（按你的实际时区选），同时配置 NTP 同步。这个问题的隐蔽性在于数据没丢，只是“跑偏了桶”，看起来像监控漂移，实则是时间基准不一致。
5.5 告警规则配了，但就是不触发
现象：规则已经在rules.yaml里写好了，重启服务端后等了大半天，指标明明超过阈值，一条告警都没发。
原因：十有八九是metric的名称和服务端实际存储的指标名对不上。可能是大小写差异，也可能是把 agent 采集的内部名称当成了面板上显示的名字，比如面板显示“磁盘使用率”，但存储里的指标名是disk_used_percent而不是disk_usage。
解决：配规则前，先进 SQLite 看真实的指标名。命令很简单：
$ sqlite3 /var/lib/hkmonitor/monitor.db ".tables" $ sqlite3 /var/lib/hkmonitor/monitor.db "SELECT name FROM sqlite_master WHERE type='table';" # 找到指标字典表，查看最新吸入的指标名 $ sqlite3 /var/lib/hkmonitor/monitor.db "SELECT DISTINCT metric_name FROM metrics ORDER BY metric_name;"逻辑说明：第一行看库里有哪几张表，第二行查所有表的清单，第三行直接列出当前已存储的全部指标名。把规则里metric字段和查询结果逐字对照，一眼就能看出拼写差异。
参数说明：如果你的实现里表名不是metrics，用.tables里看到的实际表名替代。这一步只读不改，对正在运行的监控没有影响，放心执行。
6. 把 HKmonitor 用出彩：告警收敛、数据自检与自定义扩展
监控能用和好用之间，差的往往不是功能而是细节。这个压缩包覆盖了基础链路，但要长期稳定产生价值，还有三个方向值得投入。
第一个是告警收敛。单一节点的告警在集群场景里往往会同时爆发，比如交换机故障导致几十台机器同时失联，你不想收到几十条“节点离线”的重复信息。常见的做法是利用服务端的“告警聚合”字段：把node_match相同的规则设置一个聚合窗口，比如aggregate_window: 300，同一批匹配节点在 5 分钟内的同类告警合并为一条摘要，列出受影响节点数量和前三台节点名。这个字段未必在默认配置里，但这类工具一般都预留了扩展位。找不到配置字段时，退而求其次的做法是在接收端做过滤——但最好还是在源头收敛，最不济也能靠规则写法的巧劲，比如只监控代表节点而不是全部节点。
第二个是数据自检习惯。我见过太多监控系统自己挂了没人发现，等出事时才意识到监控早就没数了。我的做法是写一条固定任务，每天上午九点检查服务端最近 5 分钟内是否收到了所有节点的数据：
#!/bin/bash # 数据自检，每日执行 for node in web-01 web-02 db-01; do last_time=$(sqlite3 /var/lib/hkmonitor/monitor.db \ "SELECT MAX(ts) FROM metrics WHERE node_name='$node'") now=$(date +%s) diff=$(( (now - last_time) / 60 )) if [ $diff -gt 5 ]; then echo "[WARN] $node 最近上报时间在 $diff 分钟前" >> /var/log/hkmonitor/check_report.log fi done这段脚本的逻辑是把每个节点最后一次上报时间戳和当前时间比较，超过 5 分钟没新数据就记录下来。ts字段如果你用的存储里是别的名字，先查表结构再替换。这比看面板靠谱得多，因为你不用主动打开浏览器——脚本的日志本身就是一个持续运转的监控。
第三个方向是自定义扩展。如果你发现默认指标不够用，这类工具一般支持自定义采集脚本。最常见的方式是在 agent 配置里加一条自定义采集项，指向一个输出 JSON 的脚本：
# agent.yaml 自定义采集示例 custom_metrics: - name: "mysql_slave_delay" script: "/opt/hkmonitor/scripts/mysql_delay.sh" interval: 30脚本输出格式约定是 JSON，例如{"value": 5, "unit": "s"}。agent 会把value当作指标值上报，服务端存储后就能配告警规则。这个机制打开了很大的想象空间：数据库主从延迟、队列堆积量、证书过期天数，只要能写成脚本输出数值，都能纳入监控体系。第一版脚本先写死输出测试值，确认端到端通了再接真实数据，这个习惯能省很多排查时间。
最后说一个我自己保持的习惯：每季度抽一个小时做一次“切断演练”——把一台节点上的 agent 手动停掉，看告警是否如期触发、恢复是否正常。监控系统只有在定期验证过才值得信任，否则它只是个自我安慰的面板。配好的监控不该是黑匣子，它要能在你真正需要它的时候喊出声，而验证过的东西才让人觉得踏实。希望这份笔记帮到你，至少能少踩几个我当年踩过的坑。
本文还有配套的精品资源，点击获取
