Checkmk需严格遵循安装路径、端口策略与agent通信机制；必须用omd create创建站点并确保端口未被占用，check-mk-agent须由xinetd托管且仅支持TCP 6556，添加主机后须执行cmk -I和cmk -O激活服务。
Checkmk 不是“装上就能用”的开箱即用型工具，它依赖明确的安装路径、端口策略和 agent 通信机制。跳过 omd 站点创建或忽略 xinetd 配置，90% 的连接失败都源于此。
用 omd create 创建站点前必须确认端口未被占用
omd create 默认绑定 80 端口（HTTP）和 8000（site admin UI），若 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：
- 安装后检查 /etc/xinetd.d/check_mk 是否存在且 disable = no
- 手动触发重载：systemctl restart xinetd（CentOS/RHEL）或 service xinetd restart（旧版）
- 测试本地连通：telnet localhost 6556 或 nc -v localhost 6556，应返回 ASCII 格式主机信息（含 >> 分隔符）
- 防火墙必须放行 6556/tcp，且仅限 TCP —— UDP 无效，6556/udp 是常见误配
添加主机后必须执行 cmk -I 和 cmk -O
Web 界面添加主机只是注册元数据，不触发自动发现或服务激活：
- cmk -I <hostname>：从 agent 抓取最新指标并生成服务清单（如 CPU、磁盘、内存）
- cmk -O：重载监控配置，使新服务进入调度队列
- 若跳过 -I，主机在界面上显示“未发现服务”；若跳过 -O，即使 -I 成功，服务也始终为“待激活”状态
- 多主机批量操作可用：cmk -I --all + cmk -OAgent 无法连接时优先查 DNS 和 hosts 解析
check_mk -d <host> 报 Connection refused 或超时，90% 不是防火墙问题：
- 检查服务器端 /etc/hosts 是否包含目标主机的 IP 和 FQDN 映射（checkmk 默认用 hostname 建立 TCP 连接）
- 若使用 IP 监控，需在 Web 界面编辑主机属性 → “Network address” 改为 IP，并确保 agent 配置中未强制绑定 hostname
- check_mk -d 的输出里若出现 getaddrinfo failed，说明解析失败，不是端口不通
omd 站点目录结构（如 /opt/omd/sites/checkmk）下所有配置变更都需通过 cmk 命令触发生效，直接改 main.mk 或 wato 文件不会同步到运行时。这是最容易被忽略的隐性依赖。
