在基础设施监控领域，Checkmk以其强大的功能和灵活性著称。但必须承认，它并非那种“下载即用”的傻瓜式工具。许多初次部署的挫败感，往往源于对几个核心机制的误解：其严格的安装路径依赖、特定的端口策略，以及独特的Agent通信模型。跳过omd站点创建或忽视xinetd的配置，后续90%的连接问题都与此有关。

用 omd create 创建站点前必须确认端口未被占用

创建站点的第一步omd create，默认会尝试绑定80端口（用于HTTP访问）和8000端口（用于站点管理界面）。如果服务器上已有Nginx或Apache在运行，这个操作可能会静默失败，导致后续服务监听异常。稳妥的做法是，先运行ss -tlnp | grep ':80\|:8000'命令，检查这两个端口是否已被占用。

一旦发现冲突，你有几个选择：使用omd create --apache-reload --no-apache-site checkmk来跳过与现有Apache的集成；或者，直接指定一个非标准端口，例如omd create --port=8080 checkmk。无论如何，务必确保omd version命令能成功返回版本号，这是后续所有操作有效的前提。

check-mk-agent 必须通过 xinetd 启动，不能直接运行

这里有个关键概念：check-mk-agent本身是一个无状态的守护进程，它并不像常规服务那样由systemd管理。试图用systemctl start check-mk-agent来启动它，注定会失败。

正确的路径是通过xinetd这个超级守护进程来托管。安装Agent后，你需要检查/etc/xinetd.d/check_mk这个配置文件是否存在，并且其中的disable参数是否为no。确认后，手动触发配置重载：在CentOS/RHEL 7及以上版本使用systemctl restart xinetd，在旧版本系统则使用service xinetd restart。

测试连通性时，用telnet localhost 6556或nc -v localhost 6556。如果成功，你会看到返回的ASCII格式主机信息，其中包含>>分隔符。另外，防火墙必须放行6556/tcp端口，并且仅限TCP——将6556/udp一并放行是常见的无效配置。

添加主机后必须执行 cmk -I 和 cmk -O

在Web界面上添加一台主机，这仅仅是在系统中注册了它的元数据，并不会自动开始监控。要让监控真正运转起来，两个命令行步骤缺一不可。

首先，执行cmk -I 。这个命令会主动联系目标主机的Agent，抓取最新的指标数据，并生成一份待监控的服务清单（比如CPU负载、磁盘使用率、内存状态等）。如果跳过这一步，主机在界面上就会一直显示“未发现服务”。

接着，执行cmk -O。这个命令的作用是重载整个监控配置，将上一步发现的新服务正式纳入调度队列。即使-I执行成功，但缺少-O，那些服务也会永远停留在“待激活”状态。对于批量操作，可以使用cmk -I --all一次性发现所有主机，再执行一次cmk -O完成激活。

Agent 无法连接时优先查 DNS 和 hosts 解析

当使用check_mk -d 测试连接，遇到“Connection refused”或超时错误时，别急着排查防火墙——大约90%的情况下，问题出在名字解析上。

Checkmk默认会使用主机名（hostname）去建立TCP连接。因此，你需要检查监控服务器本地的/etc/hosts文件，是否包含了目标主机的IP地址和完整域名（FQDN）的正确映射。

如果打算直接使用IP地址进行监控，则需要在Web界面编辑该主机的属性，将“Network address”字段改为IP地址，同时确保Agent端的配置没有强制绑定某个主机名。如果check_mk -d的输出中间出现了getaddrinfo failed这类提示，那几乎可以断定是解析失败，而非端口不通。

最后提醒一点：omd站点目录（例如/opt/omd/sites/checkmk）下的所有配置文件，其变更都必须通过cmk系列命令来触发生效。直接手动修改main.mk或wato目录下的文件，并不会自动同步到运行时的监控系统中。这个隐性的依赖关系，是最容易被忽略却又至关重要的细节。