Checkmk 2.4.0p37 部署指南

Checkmk 2.4.0p37 Docker Compose 部署指南：官方 Raw 镜像选型、compose 编排、首次初始化、Web 控制台与 REST API 验证、数据持久化、环境变量与运维命令，基于 Ubuntu 22.04 全量实测。

CheckmkCheckmk监控2026/10/20

Checkmk 2.4.0p37 部署指南

目标：用 Docker Compose 从零部署 Checkmk Raw 2.4.0p37 监控平台，覆盖镜像选型、首次初始化、Web 控制台验证、数据持久化、环境变量与日常运维。全部命令与回显已在 Ubuntu 22.04 + Docker Compose v2 环境实测通过。

一、环境信息

项目值
操作系统Ubuntu 22.04（x86_64）
Checkmk 版本Raw Edition 2.4.0p37（镜像内置 2.4.0p37.cre）
容器镜像checkmk/check-mk-raw:2.4.0p37（amd64/linux，解压后 3.06GB）
镜像摘要sha256:8ac16beb6ff2ff32682ea71376c4bfe6fcd83833a2be213606c92c26fbb01da4
Compose 编排Docker Compose v2（docker compose 子命令）
监控 Web UI 端口8140（映射到站点 Apache 5000）
Agent 上报端口8141（映射到 agent receiver 8000）
站点数据持久化目录/opt/checkmk/sites（挂载到容器 /omd/sites）
管理账号cmkadmin / q1w2e3r4（首次初始化时通过环境变量设定）
版本取证日期2026-10-20（Raw 开源版当前最新稳定版，GitHub Releases 与官方下载站实查）

二、镜像选型说明

Checkmk 官方在 Docker Hub 维护两套镜像仓库，选型时不要混用：

镜像仓库对应版本线适用场景
checkmk/check-mk-rawRaw 开源版（GPLv2）免费全功能，本篇实测所用
checkmk/check-mk-enterprise企业版（CEE，需订阅激活）需 CMC 内核/agent bakery 等企业能力

本篇采用 checkmk/check-mk-raw:2.4.0p37，标签与 Raw 开源版最新稳定版补丁级一致（官方下载站 Raw 线最高 2.4.0，2.4.0p37 为该线最新补丁，2026-09-21 发布，查询日期 2026-10-20）。镜像内置完整的 OMD 运行环境：首次启动时自动完成「创建站点 → 初始化配置 → 启动全部服务」，无需人工介入。

💡 技术拓展：拉取镜像时可固定摘要防止标签漂移。docker pull checkmk/check-mk-raw@sha256:8ac16beb6ff2ff32682ea71376c4bfe6fcd83833a2be213606c92c26fbb01da4 等价于拉取当前 2.4.0p37 标签内容，生产部署建议在 compose 中用 image: checkmk/check-mk-raw@sha256:... 固定。本文为可读性仍写标签形式。

关键内部端口（compose 映射时需要了解）：

容器内端口用途默认状态
5000站点 Apache（Web UI 入口，站点 URL 前缀 /cmk/）开启（APACHE_TCP_ADDR: 0.0.0.0）
8000Agent Receiver（被监控端 push agent 上报/注册）开启
6557Livestatus TCP（外部程序查询监控状态）关闭（LIVESTATUS_TCP: off，可用环境变量打开）
6556被监控端 agent 端口（在被监控主机上，不在监控服务端）—

三、前置条件

  1. Ubuntu 22.04 服务器，已安装 Docker Engine 与 Compose v2 插件： 
    docker version --format '{{.Server.Version}}'
docker compose version
  2. 端口 8140/8141 未被占用（ss -ltn | grep -E "8140|8141" 无输出）。
  3. 服务器时钟同步（NTP/chrony），监控数据与图表时间轴依赖系统时间。
  4. 磁盘空间 ≥ 10GB（镜像 3GB + 站点数据与 RRD 增长预留）。
  5. 持久化目录提前创建并归属 UID 1000（镜像内站点用户为 uid=1000）： 
    mkdir -p /opt/checkmk/sites
chown 1000:1000 /opt/checkmk/sites

四、部署步骤

4.1 编写 docker-compose.yml

在部署目录（本文用 /opt/checkmk）创建 docker-compose.yml：

services:
  checkmk:
    image: checkmk/check-mk-raw:2.4.0p37
    container_name: checkmk-2-4-0p37-server
    hostname: cmk-server
    environment:
      CMK_SITE_ID: cmk
      CMK_PASSWORD: q1w2e3r4
      CMK_AUTOMATION_USER: automation
      CMK_AUTOMATION_PASSWORD: q1w2e3r4
    ulimits:
      nofile:
        soft: 8192
        hard: 8192
    tmpfs:
      - /opt/omd/sites/cmk/tmp:uid=1000,gid=1000,mode=750
    volumes:
      - /opt/checkmk/sites:/omd/sites
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "8140:5000"
      - "8141:8000"
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:5000/cmk/check_mk/"]
      interval: 60s
      timeout: 10s
      retries: 3
      start_period: 60s
    networks:
      - checkmk-net

networks:
  checkmk-net:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.61.0/24

配置项逐项说明：

配置项说明
CMK_SITE_ID站点名（OMD 实例名），URL 前缀随之变化；默认 cmk，本文显式声明
CMK_PASSWORDcmkadmin 初始密码，仅首次初始化时生效，之后改密码走 Web 界面或 cmk-passwd
CMK_AUTOMATION_USER / CMK_AUTOMATION_PASSWORD自动化接口用户（REST API/自动化调用用）
ulimits.nofile官方镜像要求最低 1024，本文设 8192 应对中大规模监控项打开文件数
tmpfs把站点临时目录挂到内存，提升核心配置编译与检查吞吐；mode=750 与站点用户权限匹配
volumes/omd/sites 是全部站点数据（配置、RRD、日志）所在，必须持久化；/etc/localtime 保持时区一致
ports8140→5000（Web UI）、8141→8000（agent 上报），按宿主机空闲端口调整
healthcheck直接探测 Web 入口，start_period 给首次初始化留 60 秒
networks.ipam显式指定子网，避免与既有 Docker 网段冲突

⚠️ 注意：官方文档示例中 tmpfs 写法为 u=rx，在新版 Docker Engine 上会报 invalid tmpfs option "u" 启动失败（实测报错原文：Error response from daemon: invalid tmpfs option "u"）。请使用本文的 uid=1000,gid=1000,mode=750 写法。

4.2 启动并观察首次初始化

cd /opt/checkmk
docker compose up -d

实测回显（首次启动，数据目录为空时镜像内自动建站）：

 Network compose_checkmk-net Created
 Container checkmk-2-4-0p37-server Creating
 Container checkmk-2-4-0p37-server Created
 Container checkmk-2-4-0p37-server Starting
 Container checkmk-2-4-0p37-server Started

首次启动日志（docker compose logs checkmk | head -22 输出节选）可见建站全过程，且确认 CMK_PASSWORD 已生效：

### CREATING SITE 'cmk'
Generating configuration for core (type nagios)...
Precompiling host checks...OK
Adding /opt/omd/sites/cmk/tmp to /etc/fstab.
Going to set TMPFS to off.
Executing post-create script "01_create-sample-config.py"...OK
Executing post-create script "02_cmk-compute-api-spec"...OK
Executing post-create script "03_message-broker-certs"...OK
Updating core configuration...
Created new site cmk with version 2.4.0p37.cre.

  The site can be started with omd start cmk.
  The default web UI is available at http://cmk-server/cmk/

  The admin user for the web applications is cmkadmin with password: q1w2e3r4
  For command line administration of the site, log in with 'omd su cmk'.
  After logging in, you can change the password for cmkadmin with 'cmk-passwd cmkadmin'.

日志尾部出现 ### CONTAINER STARTED 即初始化完成（实测 40–60 秒内完成，数据目录已存在时跳过建站直接启动）：

Starting crontab...OK
### STARTING CRON
### CONTAINER STARTED

4.3 确认运行状态

docker compose ps

实测回显（同机若有其他无关服务会一并列出，关注 checkmk 一行）：

NAME                      STATUS                    PORTS
checkmk-2-4-0p37-server   Up 59 seconds (healthy)   6557/tcp, 0.0.0.0:8140->5000/tcp, [::]:8140->5000/tcp, 0.0.0.0:8141->8000/tcp, [::]:8141->8000/tcp

进入容器确认站点服务状态（omd status）：

docker exec checkmk-2-4-0p37-server omd status cmk

实测回显：

agent-receiver:     running
mkeventd:           running
rrdcached:          running
redis:              running
npcd:               running
automation-helper:  running
ui-job-scheduler:   running
nagios:             running
apache:             running
crontab:            running
---------------------------
Overall state:      running

4.4 验证 Web 控制台与 REST API

宿主机上用 curl 验证 Web UI（站点 URL 固定前缀为 /cmk/check_mk/，cmkadmin 密码来自 CMK_PASSWORD）：

curl -s -o /dev/null -w "Web UI: HTTP %{http_code}\n" \
  -u cmkadmin:q1w2e3r4 http://localhost:8140/cmk/check_mk/login.py
curl -s -u cmkadmin:q1w2e3r4 http://localhost:8140/cmk/check_mk/api/1.0/version

实测回显（登录重定向 302、API 返回版本信息）：

Web UI: HTTP 302
{"site": "cmk", "group": "", "rest_api": {"revision": "0"}, "versions": {"apache": [2, 4, 52], "checkmk": "2.4.0p37.cre", "python": "3.12.13 (main, Aug 14 2026, 09:49:44) [GCC 14.2.0]", "mod_wsgi": [4, 9, 4], "wsgi": [1, 0]}, "edition": "cre", "demo": false}

浏览器访问 http://<服务器IP>:8140/cmk/check_mk/，浏览器会先弹出 HTTP Basic 认证框（Checkmk 站点在 Apache 层启用 htpasswd 认证），输入 cmkadmin / q1w2e3r4 后进入 Checkmk 主界面。

💡 说明：Apache 层的 htpasswd 认证是 OMD 站点默认行为，认证文件位于站点目录 etc/htpasswd。未认证的请求返回 401（实测响应头 WWW-Authenticate: Basic realm="OMD Monitoring"）。

五、数据持久化说明

所有监控数据都在容器的 /omd/sites/<站点名> 下，本方案整体挂载到宿主机 /opt/checkmk/sites。首次启动后目录结构：

/opt/checkmk/sites/
└── cmk/                       # 站点名即目录名
    ├── etc/check_mk/          # WATO 配置（主机、规则集）
    ├── etc/htpasswd           # Web 用户认证文件
    ├── var/check_mk/core/     # 监控核心状态
    ├── var/check_mk/rrd/      # 性能数据 RRD 文件
    ├── var/mkeventd/          # 事件控制台数据
    └── log/                   # 站点日志

备份与迁移：整个 /opt/checkmk/sites 打包即可带走全部配置与历史数据；也可以用 OMD 自带备份命令做单站点归档：

docker exec checkmk-2-4-0p37-server omd backup cmk /tmp/cmk-backup.tar.gz

恢复用 omd restore（先停站点再恢复，详见官方 OMD 管理文档）。

⚠️ 注意：不要只挂载 /omd/sites/cmk 的某个子目录（如仅挂 var/check_mk），首次建站时入口点需要对站点目录整体做初始化，部分挂载可能导致初始化失败。整目录挂载 /omd/sites 是最稳妥的方式。

六、环境变量表

镜像入口点识别以下环境变量（实测 docker exec checkmk-2-4-0p37-server env | grep -i cmk 回显与镜像文档核对）：

环境变量默认值说明
CMK_SITE_IDcmk站点名，决定 URL 前缀与数据目录名
CMK_PASSWORD随机生成cmkadmin 初始密码，仅首次建站生效
CMK_AUTOMATION_USERautomation自动化用户名
CMK_AUTOMATION_PASSWORD随机生成自动化用户密码，仅首次建站生效
CMK_LIVESTATUS_TCP空（off）设为 on 时启用 Livestatus TCP 6557，供外部程序查询
CMK_CONTAINERIZEDTRUE（镜像内置）容器化运行标记，入口点据此关闭 tmpfs 自挂载等主机特权操作

💡 说明：CMK_PASSWORD 只在「数据目录为空、首次建站」时生效。忘记密码时可进入容器执行 omd su cmk -c 'cmk-passwd cmkadmin' 重置（按提示输入新密码）。

七、配置参数说明

站点级配置通过 omd config 管理（进入容器执行）。查看当前配置：

docker exec checkmk-2-4-0p37-server omd config cmk show | grep -E "APACHE|LIVESTATUS|AUTOSTART|TMPFS|CORE"

实测回显：

APACHE_MODE: own
APACHE_TCP_ADDR: 0.0.0.0
APACHE_TCP_PORT: 5000
AUTOSTART: on
LIVESTATUS_TCP: off
TMPFS: off
CORE: nagios
参数含义常用调整
CORE监控内核类型Raw 版固定 nagios（企业版镜像可选 cmc）
APACHE_TCP_ADDR站点 Apache 监听地址镜像内已设 0.0.0.0 以接受端口映射，勿改回 127.0.0.1
APACHE_TCP_PORT站点 Apache 端口默认 5000，与 compose 端口映射对应
AUTOSTART容器启动时自动拉起站点保持 on
LIVESTATUS_TCPLivestatus TCP 查询外部对接（如自研看板）设 on，并在 compose 放行 6557
TMPFS站点 tmpfs 自挂载容器内无挂载权限保持 off，由 compose 的 tmpfs 承担加速职责

修改示例（打开 Livestatus TCP，实测命令与回显）：

docker exec checkmk-2-4-0p37-server omd config cmk set LIVESTATUS_TCP on

Creating temporary filesystem /opt/omd/sites/cmk/tmp...Reloading monitoring core...OK

八、配置文件挂载

如需把配置模板带入容器，可在 volumes 中追加只读挂载，常见两类：

    volumes:
      - /opt/checkmk/sites:/omd/sites
      - /etc/localtime:/etc/localtime:ro
  • /omd/sites：站点全量数据（必挂，持久化核心）。
  • /etc/localtime:ro：与宿主机时区保持一致，避免图表时间轴偏移（只读挂载）。

Checkmk 自身的监控配置（主机、规则）不走外部文件挂载，而是通过 Web 界面（WATO）或 REST API 管理，落盘在 /omd/sites/cmk/etc/check_mk/ 下，已随数据卷持久化。

九、等价 docker run

不用 Compose 时，等价的单命令启动方式：

docker run -d \
  --name checkmk-2-4-0p37-server \
  --hostname cmk-server \
  -p 8140:5000 \
  -p 8141:8000 \
  -e CMK_SITE_ID="cmk" \
  -e CMK_PASSWORD="q1w2e3r4" \
  -e CMK_AUTOMATION_USER="automation" \
  -e CMK_AUTOMATION_PASSWORD="q1w2e3r4" \
  --ulimit nofile=8192:8192 \
  --tmpfs /opt/omd/sites/cmk/tmp:uid=1000,gid=1000,mode=750 \
  -v /opt/checkmk/sites:/omd/sites \
  -v /etc/localtime:/etc/localtime:ro \
  --restart unless-stopped \
  checkmk/check-mk-raw:2.4.0p37

与 Compose 方式行为一致（首次启动建站、后续直接启动），验证方法同 4.3/4.4。

十、常用运维命令

操作命令说明
查看状态docker compose ps含 healthcheck 结果
跟踪日志docker compose logs -f checkmk首次建站日志也在这里
站点服务状态docker exec checkmk-2-4-0p37-server omd status cmk逐服务 running/stopped
重启站点（不动数据）docker exec checkmk-2-4-0p37-server omd restart cmk核心重编译配置并重启
重启容器docker compose restart数据卷不受影响
升级镜像改 image: 标签 → docker compose up -d → docker exec checkmk-2-4-0p37-server omd update cmk站点数据卷跨版本保留，升级后需执行 omd update 迁移站点
站点备份docker exec checkmk-2-4-0p37-server omd backup cmk /tmp/cmk.tar.gz归档单站点
完全清理docker compose down -v 并清空 /opt/checkmk/sites连数据一起删除，慎用

⚠️ 注意：跨版本升级（如 2.4.0 → 2.4.1p1 或 2.5.x）必须逐线进行且先看官方兼容矩阵；企业版与 Raw 版镜像不能互换挂载同一数据目录后再降回，企业版写入的格式部分内容 Raw 版无法识别。

十一、常见问题

Q1：启动报 Error response from daemon: invalid tmpfs option "u"

官方文档示例的 tmpfs 写法 uid=1000,gid=1000,u=rx 在新版 Docker Engine 上不被接受（实测报错）。把 u=rx 改为 mode=750（本文 4.1 配置）即可正常启动。

Q2：首次启动后访问 Web 返回 401

这是 Apache 层 htpasswd 认证在等待凭据（WWW-Authenticate: Basic realm="OMD Monitoring"），不是故障。用 cmkadmin + CMK_PASSWORD 设定的密码通过 Basic 认证即可。若密码未知且非首次初始化设定，进容器 omd su cmk -c 'cmk-passwd cmkadmin' 重置。

Q3：CMK_PASSWORD 设了但登录密码不对

该变量只在数据目录为空的首次建站时生效。如果容器曾无此变量启动过（比如先跑了官方默认 compose），站点已用随机密码初始化；删掉数据目录重建，或按 Q2 重置密码。

Q4：外部工具连不上 Livestatus 6557

默认关闭（LIVESTATUS_TCP: off，实测 omd config cmk show 回显）。设 CMK_LIVESTATUS_TCP: on 环境变量（或在容器内 omd config cmk set LIVESTATUS_TCP on），并在 compose 的 ports 中增加 6557:6557。

Q5：容器 healthy 但 Web 无响应

检查是否访问了错误端口/路径：Web 入口是映射到站点 Apache 5000 的端口加 /cmk/check_mk/ 前缀（本篇为 8140），直接访问 / 会 302 重定向，属于正常行为。

十二、参考链接