docker 部署 Checkmate 监控听起来就是一条命令拉镜像的事但真到了生产环境你依然会踩到端口冲突、数据库初始化失败、数据卷挂错路径这些坑。我这次把整个过程完整走了一遍从选型、compose 编写到监控项配置整理成一份可以直接抄作业的记录。先说清楚这套东西的定位。Checkmate 是开源领域里一个上手门槛比较低的监控工具它会定期对网站、服务器、网络设备和关键端口做探测把结果统一展示在 Web 仪表盘上并在异常时触发告警。对于有十几台机器的小团队、个人站长或者临时搭一套内网监控的场景来说这比商业监控软件划算也比老牌重型开源方案轻得多。下面默认你已经装好了 Docker Engine 和 compose 插件会一点命令行就行不需要提前懂监控原理。1. 部署前先弄清 Checkmate 到底解决什么问题很多人看到“监控工具”就急着拉镜像结果部署完发现和预期完全不符。所以我想先花点时间把 Checkmate 的用途讲透避免你盲目迁移到一个不合适的方案上。1.1 它监控什么我的日常场景Checkmate 的核心能力可以分成几块第一是可用性探测比如网站能不能访问、某个端口是否开放、服务器能不能 ping 通第二是网络设备指标采集像交换机、路由器、防火墙设备的 CPU、内存、接口流量这类通常走 SNMP 协议第三是把这些探测结果存下来做成仪表盘展示并按条件发告警。我实际用的场景很直白一台部署机每天要盯几个对外网站的 HTTP 状态还要看两台内网服务器的存活情况以及几个自建服务的 TCP 端口是否正常。以前我是人肉刷新网址后来写脚本扫端口再后来发现脚本只告诉我“现在挂了”但没法告诉我“挂了多久、什么时候恢复的、趋势怎么样”。Checkmate 这类工具补上的正是这段历史记录和可视化能力。需要注意的是Checkmate 的定位是“快速发现问题”不是“深度分析历史数据”。它适合中小规模的监控点比如几十个 HTTP 检查和几十台设备的存活监控。如果你要的是海量指标聚合、复杂告警规则、长时间趋势预测那该选重型的时序监控平台而不是这个。1.2 为什么用 Docker 而不是源码或裸机这套工具本身依赖的不只是单个程序它后端要一个数据库存监控记录还需要缓存或队列来支撑任务调度。如果源码部署你得先装 Node 运行时、数据库、缓存再处理版本兼容、开机自启、日志切割、权限隔离一套流程下来两小时起步。Docker 方案最大的价值是把这些复杂依赖打包成标准容器我只要维护一个 docker-compose 文件就能把 Web 服务、数据库、缓存一次性拉起。升级时也不用担心宿主机上残留旧版本的配置文件回滚时就换回旧镜像重新启动整个过程非常干净。我自己踩过一次坑以前手动装某个开源工具结果宿主机上的 Node 版本太新和项目要求的版本不兼容为了不动生产环境里其他服务只好又去装版本管理器折腾半天。用 Docker 之后就再没这种破事每个服务都待在独立沙箱里互不污染。所以只要目标主机能用 Docker我基本都会优先选容器化部署。2. 环境准备与 compose 设计开工前想清楚部署前不要把注意力全放在“敲命令”上先花十分钟把目录、端口、网络方案定下来后面能少走很多弯路。2.1 硬件、系统与网络的基本要求先说硬件。部署机建议 2 核 4G 内存起步磁盘至少预留 20G。原因很简单MongoDB 存储监控数据时会持续占用空间虽然单条记录很小但探测频率一高数据量增长很快。我给你一个粗略估算如果配置 50 个监控项每个每 60 秒记录一次一天会产生大约 7 万条记录按单条约 0.5KB 到 2KB 计算一个月大概是 4GB 到 8GB。如果把探测间隔缩小到 10 秒数据量还会再放大 6 倍所以磁盘预留不能太抠。操作系统和架构基本不限Linux 发行版都能跑Docker Engine 版本建议 20.10 以上compose 插件要能支持depends_on.condition: service_healthy否则容器启动顺序控制会麻烦一些。这个在后面的 compose 文件里会用到。网络方面要提前确认三件事。第一部署机到被监控目标之间的网络是通的包括 ICMP、TCP、UDP 等协议如果要走 SNMP 监控网络设备还要确保 UDP 161 端口可达。第二Web 控制台端口要开放给需要使用的人别把端口暴露到公网更不要把数据库端口映射出去。第三如果监控点在多个网段需要让部署机能够路由到那些网段或者给容器单独配置网络否则什么都测不到。2.2 compose 服务拆分为什么是应用、Mongo、Redis 三件套Checkmate 的容器化部署通常不是单个容器搞定全部而是拆成几个服务协同工作。我从实际维护角度解释一下主应用容器负责 Web 界面、探测调度和告警逻辑前端静态页面也由它托管属于“门面”。MongoDB 负责持久化监控配置和历史记录相当于仓库。Redis 负责缓存、任务队列这类临时数据相当于工作台。把数据存储和主应用拆开好处是主应用容器可以随时重建、升级数据不会丢如果将来想加第二台部署节点也能共用同一个数据层。在 compose 文件里我建议让 MongoDB 和 Redis 只暴露在容器内部网络不映射宿主机端口。因为监控数据的隐私性虽然不高但数据库端口一旦暴露就可能被扫描工具盯上而主应用只需要通过服务名就能访问它们根本不需要对外端口。数据卷的规划也要提前想好。MongoDB 和 Redis 分别挂独立的数据卷升级时容器可以换但数据卷必须保留。主应用如果有配置文件建议用目录挂载方式放到宿主机固定路径方便备份和查看。这个设计看起来简单但能避免很多升级后的“数据神秘消失”问题。3. 从零部署到添加监控项完整实操记录现在进入正题。下面这套 compose 文件是我实测后留下日常用的版本每一步都有对应说明。镜像名称部分请你以项目官方文档为准不同仓库的镜像名可能有差异但整体编排思路是一致的。3.1 编写 docker-compose.yml可直接套用的部署文件先建一个项目目录比如checkmate然后创建docker-compose.yml。文件内容如下services: checkmate: image: checkmate:latest # 换成项目官方镜像地址 container_name: checkmate-app restart: unless-stopped cap_add: - NET_RAW ports: - 3000:3000 environment: PORT: 3000 TZ: Asia/Shanghai JWT_SECRET: ${JWT_SECRET:-please-change-me} MONGO_URL: mongodb://mongo:27017/checkmate REDIS_URL: redis://redis:6379 depends_on: mongo: condition: service_healthy redis: condition: service_healthy volumes: - ./checkmate-data:/app/data logging: driver: json-file options: max-size: 20m max-file: 5 mongo: image: mongo:7 restart: unless-stopped environment: TZ: Asia/Shanghai volumes: - mongo-data:/data/db healthcheck: test: [CMD, mongosh, --quiet, --eval, db.runCommand({ping:1}).ok] interval: 10s timeout: 5s retries: 5 redis: image: redis:7-alpine restart: unless-stopped command: [redis-server, --appendonly, yes] volumes: - redis-data:/data healthcheck: test: [CMD, redis-cli, ping] interval: 10s timeout: 5s retries: 5 volumes: mongo-data: redis-data:同目录下再建一个.env文件用来放敏感变量JWT_SECRET$(openssl rand -hex 32) TZAsia/ShanghaiJWT_SECRET是登录态加密用的密钥必须随机生成不要用默认值。用openssl rand -hex 32生成一长串随机字符填进去就行。如果留空或者太简单Web 登录会不稳定严重的还可能出现会话串号。这里有两个容易忽略的设计点。第一cap_add: - NET_RAW是为了让后端容器有能力发起 ICMP ping。如果缺少这个权限HTTP 和 TCP 监控正常但 ping 监控会一直失败。特权权限能不加就不加只加这一项足够。第二depends_on配了健康检查条件意味着主应用会等到 MongoDB 和 Redis 都真正可用了再启动避免出现“应用先起来了数据库还没就绪然后反复重启”的尴尬局面。3.2 启动、初始化与 Web 端首登配置文件准备好后第一次启动直接在项目目录里执行docker compose up -d这个命令会拉取镜像并以后台模式启动所有服务。执行完后先看状态docker compose ps正常情况下三个服务都应该是running状态。如果某个服务在restarting不要慌继续执行docker compose logs -f checkmate查看主应用日志输出。最常见的失败原因是MONGO_URL写错、MongoDB 没就绪、端口被占用。等日志稳定后再打开浏览器访问http://你的服务器IP:3000。首次访问一般会进入初始化页面需要创建一个管理员账号。某些版本会预置默认账号遇到登录页就按页面提示操作。如果页面一直转圈可能是 MongoDB 正在建索引多等一会儿再刷新通常不会超过一分钟。初始化成功的标志是能正常看到仪表盘并且在界面上能选择添加监控项。到这里部署环节就基本完成了。3.3 添加第一批监控项HTTP、Ping、TCP、SNMP 参数说明部署完只是刚开始真正见效果的是把监控项配起来。我在 Web 界面上添加监控项时最常用的有四类参数差异很大。HTTP 监控最简单填一个 URL比如https://example.com/health然后设置期望状态码默认通常期望 200。这里有三个细节值得注意第一超时时间不要设太短比如有些页面因为大图片或慢接口 3 秒才能响应设 2 秒会导致误报第二如果网站会重定向要确认工具是否跟随重定向大部分场景应该勾选跟随第三带登录态的页面要小心监控工具拿到的状态码可能是 302 跳转到登录页这时候可以改成监控一个公开的静态资源接口。Ping 监控用来判断服务器是否在线。填写目标 IP 或域名设置探测间隔和连续失败次数。我一般设 60 秒探测一次连续 3 次失败才告警。太频繁会增加网络负担太慢又不够实时。如果你发现添加 ping 监控后一直显示失败而宿主机 ping 目标又是通的优先检查容器有没有NET_RAW权限。TCP 端口监控适合自建服务比如数据库端口、SSH 端口、消息队列端口。填目标主机和端口号工具会定期尝试建立 TCP 连接。这个方式比业务层面监控更底层但也更直接端口不开就是服务不可用。SNMP 监控用于网络设备部署前要确认设备已经开启 SNMP 服务并拿到社区字符串。默认值通常是public但生产环境别用建议改成随机字符串。界面上一般会让你选择指标模板比如 CPU、内存、接口流量它会通过 OID 去采集。这类监控踩坑大部分是网络问题比如 UDP 161 被防火墙挡了或者社区字符串权限不足。3.4 验证告警是否真正触发的实操技巧监控项加完后一定不要直接关页面走人先验证告警链路是否真的通。我习惯在正式监控项之外先添加一个测试用监控项专门指向一个不存在的端口或故意停掉的服务。等一两分钟看看仪表盘上的状态是否变成红色再检查通知是否收到。如果告警没触发按顺序排查先看监控项的探测间隔和阈值是否设置过大再查通知渠道配置是否正确最后看 Web 控制台里该监控项是否处于启用状态。很多人忘了设置“恢复通知”导致故障恢复后没收到任何消息这个问题比告警本身更隐蔽。4. 踩过的坑启动失败、数据备份和日常运维任何部署方案都有“文档没写”的实战细节我把这段时间积累下来的问题排查方法和运维经验整理成一套速查方便你以后直接对照。4.1 容器异常重启的排查顺序场景执行docker compose up -d后主应用容器一直处于restarting状态。这不是特殊问题但新手容易慌。按下面顺序排查大多数情况十分钟内能定位。先看进程状态确认是哪个服务在重启。如果是主应用执行docker compose logs --tail100 checkmate重点看报错里有没有数据库连接字符串、认证失败、端口被占用字样。如果是 MongoDB 健康检查没过先看docker compose logs mongo确认数据库有没有完成初始化。很多情况下是宿主机磁盘空间不足MongoDB 启动失败主应用连不上数据库就反复重启。执行df -h看一眼磁盘最直接。端口冲突也常见。如果3000已经被其他程序占用主应用自然起不来。检查方式ss -lntp | grep 3000找到占用进程后要么停掉旧服务要么改掉 compose 里的宿主端口映射比如改成8080:3000。注意冒号左边是宿主机端口右边是容器内端口容器内端口尽量别改因为应用内部监听的端口跟着环境变量走。如果用的是老版本 compose可能不认识condition: service_healthy这种写法会直接报配置错误。这时把 compose 插件升级到 v2 版本就行不要试图删掉健康检查没有健康检查的启动顺序控制很容易引发另一轮踩坑。4.2 数据卷、备份恢复与版本升级动作监控工具跑了一段时间后数据就成了最有价值的部分配置可以重建历史故障记录没法重来。我建议至少每周做一次 MongoDB 数据备份。备份最简单的方式是用mongodump生成归档文件。在宿主机上执行docker compose exec -T mongodump --archive checkmate-backup.archive如果是 mongodb 版本7上面命令里的mongodump默认在镜像里就有执行前建议先确认容器名别在错误的容器里执行。恢复时先把备份文件拷贝进容器再执行mongorestore。整个流程里有三个容易出错的地方第一备份文件所在目录要有足够权限否则写入失败第二恢复前最好停掉主应用避免它一边写数据一边恢复产生冲突第三恢复完成后一定要重启主应用让它重新连接数据库否则界面上可能看不到最新状态。版本升级时我的操作顺序是先备份数据再拉新镜像然后执行docker compose up -d重建服务最后观察日志确认没报错。如果新版本有问题回滚也很简单把docker-compose.yml里的镜像版本改成之前的标签再执行一次docker compose up -d就行。数据卷不要乱动只要数据卷还在回滚基本都能保住历史数据。这里必须提醒一点Redis 虽然是持久化存储但在这种架构里它更适合做缓存和任务调度别指望它保存关键数据。升级或重启后Redis 数据丢了顶多重建缓存MongoDB 里的配置和历史记录才是核心。4.3 资源限制与告警防打扰监控工具本身不能成为新的不稳定因素。如果部署机资源紧张建议给每个服务加上资源限制避免 MongoDB 把内存吃光导致整台服务器卡死。compose 里可以这样追加deploy: resources: limits: memory: 1g我给主应用限 512MBMongoDB 限 1GBRedis 限 256MB实际用起来完全够。限制资源的好处是即便某个容器出现内存泄漏也不会拖垮整台部署机。更重要的是别把数据库端口暴露到宿主机否则外部连接可能不受资源限制地打进来。告警防打扰是另一个经验。刚开始我设了“失败一次就告警”结果某个网站因为暂时性网络抖动一晚上收到几十条通知。后来我把连续失败次数调整为 3 次间隔时间调整为 60 秒告警立刻理性了很多。如果监控项有维护窗口功能升级维护时记得开启否则这边正在发布那边告警响个不停全组人都得跟着紧张。4.4 和同类方案怎么选什么场景才值得换过去最后聊一个实际问题什么时候该选 Checkmate什么时候不该。如果你手头没有任何监控系统需求是盯网站可用性和内网设备存活那这套方案非常合适部署快、配置直观、资源占用低。如果只是想临时验证一个服务端口是否开放也可以快速搭一套。但如果团队已经在用成熟的商业监控方案或者已经搭好了一套重型开源监控平台那我不建议仅仅因为“新工具看起来现代”就迁移。迁移是有成本的历史数据怎么搬、告警规则怎么重建、团队要不要重新培训都得算进去。Checkmate 更适合从零开始、中小规模、快速见效的场景。说到底监控工具的价值不在于它支持多少种协议而在于出了问题能不能第一时间被人看见、能不能帮你自己少背几口锅。Checkmate 在这一点上已经做得很称职了。我在实际部署中最大的体会是不要一开始就堆一大堆监控项先把最核心的三五个网站和服务器盯起来跑一周稳定了再慢慢加不迟。