openITCOCKPIT Docker Compose 部署指南

openITCOCKPIT 5.9.0 官方主推 Docker Compose 形态的从零部署实测:git clone 官方编排仓库、openitcockpit.env 改密、docker compose up 拉起 17 服务全栈(Naemon+ModGearman+Statusengine+MySQL+Graphite+Grafana+Prometheus),含 HTTPS 登录验证、数据持久化清单、环境变量表与 mysqladmin 等待死锁排障实录。

openITCOCKPITopenITCOCKPIT自托管监控2026/11/01

openITCOCKPIT Docker Compose 部署指南

目标:在单台服务器上从零拉起 openITCOCKPIT 5.9.0 全功能监控栈(Web 平台 + Naemon 引擎 + Gearman 分布式检查 + Statusengine 状态库 + Graphite/Grafana/Prometheus 图表链路),完成 HTTPS 登录验证并掌握日常运维命令。本文为部署实测篇,所有回显均为真实环境逐行照抄;平台定位与选型见《openITCOCKPIT 介绍与选型指南》,配置体系详解见《openITCOCKPIT 5.9.0 配置参数详解》,CLI 工具详解见《openITCOCKPIT 5.9.0 常用 CLI 命令与工具详解》。

一、环境信息

openITCOCKPIT 官方将 Docker Compose 列为社区版的首选交付形态:整个平台(含监控引擎、性能数据链路、Grafana、消息队列等 17 个服务)由官方仓库 openITCOCKPIT/openITCOCKPIT-ce-docker 的 compose.yml 一键编排,组件间版本经过官方配套验证,无需手工安装 apt 包。本节先交代本次部署的目标版本与全栈组成。

  • 部署版本:openITCOCKPIT Community Edition 5.9.0(镜像 tag latest,官方当前稳定版;版本线溯源见《openITCOCKPIT 介绍与选型指南》)
  • 编排仓库:github.com/openITCOCKPIT/openITCOCKPIT-ce-docker(compose.yml + openitcockpit.env + 各服务配置模板)
  • 镜像仓库:Docker Hub openitcockpit/*,支持 amd64 与 arm64(可在 Raspberry Pi 4 一类 SoC 上运行)
  • 验证环境:Ubuntu 24.04 LTS(Noble,Docker Engine 24+,Compose v2)

全栈 17 个服务及其职责如下(镜像名与端口均取自官方 compose.yml):

服务镜像端口(容器内)职责
openitcockpitopenitcockpit/openitcockpit-ce:latest80/443Web 平台(CakePHP 后端 + nginx + php-fpm + Angular SPA)
naemonopenitcockpit/naemon:latest9001/9099Naemon 监控引擎(含 mod_gearman NEB 模块)
mod_gearman_workeropenitcockpit/mod_gearman_worker:latest—分布式检查执行器(monitoring-plugins 2.4.0 插件集)
gearmandopenitcockpit/gearmand:latest4730Gearman 任务调度服务器
statusengine-workeropenitcockpit/statusengine-worker:latest8091/8092/9105Statusengine4 Go worker:状态入库、性能数据转发、外部命令 API
mysqlmysql:lts3306主数据库(实测 mysqld 9.7.4)
redisredis:latest6379缓存/会话后端
graphite-webopenitcockpit/graphite-web:latest8080性能数据查询 API
carbon-relayopenitcockpit/carbon-c-relay:latest2003指标路由分发
carbon-cache1/2openitcockpit/carbon-cache:latest—Whisper 存储写入(双实例可横向扩)
victoria-metricsopenitcockpit/victoria-metrics:latest8428Prometheus 远端存储
prometheusopenitcockpit/prometheus:latest9090指标抓取(经 openITCOCKPIT prometheus_bridge 同步配置)
grafanaopenitcockpit/grafana:latest3033仪表盘(经 nginx 反代,网络别名 grafana.docker)
puppeteeropenitcockpit/puppeteer:latest8084报表截图渲染
checkmkopenitcockpit/checkmk:latest1234Checkmk 集成 API 包装
postfixboky/postfix587邮件通知中继

实测组件版本(部署完成后在对应服务内核验):

# Naemon 引擎版本(status.dat 头部 info 段,实测)
info {
        created=1793524072
        version=1.5.1
        }

# 检查插件版本(mod_gearman_worker 服务内,实测)
/opt/openitc/nagios/libexec/check_http -V
check_http v2.4.0 (monitoring-plugins 2.4.0)
/opt/openitc/nagios/libexec/check_ping -V
check_ping v2.4.0 (monitoring-plugins 2.4.0)

# MySQL 服务端版本(mysql 服务内,实测)
mysqld  Ver 9.7.4 for Linux on x86_64 (MySQL Community Server - GPL)

要点:mysql:lts 是官方 compose 指定的镜像标签,实测拉到的服务端为 9.7.4;而 openitcockpit-ce 镜像内的 MySQL 客户端为 8.0.46(Ubuntu noble 发行版自带),客户端/服务端版本差异不影响使用,但排障时注意两边工具行为并不完全一致(见第十一节问题 1)。

二、镜像选型说明

官方文档对镜像 tag 的约定(来源:docs.openitcockpit.io「Docker → Tags」,查询日期 2026-11-01):

Tag含义适用
latest最新稳定版官方推荐,跟随稳定线升级
版本号(如 5.9.0)锁定指定稳定版本生产环境可复现部署
nightly自动构建的未测试版本仅测试新功能,禁止生产

选型建议:生产环境将 compose.yml 中所有 openitcockpit/*:latest 统一替换为当前稳定版本号(如 :5.9.0),避免 docker compose up --pull always 时意外跨版本跳升;本文环境使用 latest(构建于 2026-10-22,对应 5.9.0-20261022074458noble 包线)。

三、前置条件

官方「Docker → Requirements / System requirements」给出的最低要求(查询日期 2026-11-01):

  • 软件:Docker 与 Docker Compose v2(docker compose version 可验证)
  • 资源:2 CPU 核(x86-64 或 arm64)、4 GB 内存、60 GB 空闲磁盘(磁盘占用随被监控主机/服务数量增长)
  • 端口:宿主机 80(HTTP)与 443(HTTPS)空闲——Web UI 对外只暴露这两个端口,其余 15 个服务的端口仅在内部网络发布
  • 文件描述符:gearmand 与 mysql 需要 nofile 65536(官方 compose.yml 已内置 ulimits,无需宿主机调整)
# 宿主机验证 Compose v2 可用(实测)
docker compose version
Docker Compose version v2.x   # 以实际安装版本为准

四、部署步骤

4.1 获取官方编排

官方推荐用 git 克隆编排仓库(内含 compose.yml、openitcockpit.env、各服务配置模板):

git clone https://github.com/openITCOCKPIT/openITCOCKPIT-ce-docker.git
cd openITCOCKPIT-ce-docker

仓库自带的 compose.yml 没有 name: 字段,项目名默认取目录名。建议显式固定项目名,便于后续按名称操作容器:

# 在 compose.yml 顶部添加一行(实测环境采用)
name: openitcockpit-5.9.0-stack

要点:Compose 项目名会规范化进容器名(点号被剔除),因此 openitcockpit-5.9.0-stack 的容器前缀是 openitcockpit-590-stack-,下文回显即为此形态。

4.2 修改 openitcockpit.env

官方明确建议在首次启动前修改登录凭据(「Docker → Settings」):

# openitcockpit.env 关键项(实测环境取值)
OITC_ADMIN_EMAIL=admin@example.org
OITC_ADMIN_PASSWORD=q1w2e3r4
OITC_ADMIN_FIRSTNAME=Admin
OITC_ADMIN_LASTNAME=User

# Grafana 管理员密码,两个变量必须设为同一值
OITC_GRAFANA_ADMIN_PASSWORD=q1w2e3r4
GF_SECURITY_ADMIN_PASSWORD=q1w2e3r4

# MySQL 连接四要素(openitcockpit/naemon/statusengine 等服务共用)
MYSQL_ROOT_PASSWORD=root_password
MYSQL_DATABASE=openitcockpit
MYSQL_USER=openitcockpit
MYSQL_PASSWORD=openitcockpit_password

官方默认值为 user@example.org / asdf12,生产环境务必改掉;安全口令可用 pwgen -s -1 16 生成。完整环境变量分组说明见第六节。

4.3 启动全栈

docker compose up -d

首次启动时 openitcockpit 服务会在容器内自动执行安装初始化(数据库迁移、种子数据、权限树扫描、自签证书生成),耗时数分钟。官方给出的就绪标志是日志出现 ready 横幅(实测回显):

docker compose logs -f openitcockpit
Monitoring configuration successfully generated.
Execute "systemctl reload naemon" to load the new configuration
################################################################################
#                                                                              #
#                          openITCOCKPIT is now ready                          #
#                                                                              #
################################################################################
2026-11-01 08:48:37,653 INFO spawned: 'crond' with pid 809
2026-11-01 08:48:37,654 INFO spawned: 'gearman_worker' with pid 810
2026-11-01 08:48:37,655 INFO spawned: 'nginx' with pid 811
2026-11-01 08:48:37,655 INFO spawned: 'oitc_cmd' with pid 812
2026-11-01 08:48:37,656 INFO spawned: 'openitcockpit-websocket' with pid 813
2026-11-01 08:48:37,657 INFO spawned: 'php-fpm' with pid 814
2026-11-01 08:48:37,661 INFO spawned: 'prometheus_bridge' with pid 829
2026-11-01 08:48:38,776 INFO success: nginx entered RUNNING state, process has stayed up for > than 1 seconds (startsecs)

⚠️ 若日志反复出现 Waiting for MySQL to become available... 且服务不断重启,是本部署形态已实测踩中的 mysqladmin 兼容性死锁,完整定位与修复过程见第十一节问题 1,请先按该节处理再继续。

4.4 验证服务状态

docker compose ps --format '{{.Name}}\t{{.Status}}'
openitcockpit-590-stack-carbon-c-relay-1      Up 56 minutes
openitcockpit-590-stack-carbon-cache1-1       Up 56 minutes
openitcockpit-590-stack-carbon-cache2-1       Up 56 minutes
openitcockpit-590-stack-checkmk-1             Up 56 minutes
openitcockpit-590-stack-gearmand-1            Up 56 minutes
openitcockpit-590-stack-grafana-1             Up 56 minutes
openitcockpit-590-stack-graphite-web-1        Up 56 minutes
openitcockpit-590-stack-mod_gearman_worker-1  Up 56 minutes
openitcockpit-590-stack-mysql-1               Up 56 minutes
openitcockpit-590-stack-naemon-1              Up 56 minutes
openitcockpit-590-stack-openitcockpit-1       Up 15 minutes
openitcockpit-590-stack-postfix-1             Up 56 minutes (healthy)
openitcockpit-590-stack-prometheus-1          Up 56 minutes
openitcockpit-590-stack-puppeteer-1           Up 56 minutes
openitcockpit-590-stack-redis-1               Up 56 minutes
openitcockpit-590-stack-statusengine-worker-1 Up 21 minutes
openitcockpit-590-stack-victoria-metrics-1    Up 56 minutes

17 个服务全部 Up 即为栈就绪(Up 15/21/56 minutes 是排障期间个别服务重启后的真实运行时长,正常一次性部署应全部为同一时长)。

4.5 HTTPS 登录验证

平台强制 HTTPS:80 端口直接 301 跳转 443(实测):

curl -sI http://<服务器地址>/users/login
HTTP/1.1 301 Moved Permanently
Location: https://<服务器地址>/users/login

Web UI 与后端 REST 共用同一入口,API 采用「表单登录拿会话 + CSRF 令牌」模式(无独立 API 前缀,路径为 /{controller}/{action}.json)。完整实测流程:

# 1. GET 登录页,取 csrfToken cookie(需 URL 解码后作为 x-csrf-token 头)
curl -sk -c cookies.txt https://<服务器地址>/users/login -o /dev/null
grep csrfToken cookies.txt
# 2. POST 表单登录(字段名必须是 email/password,登录 URL 必须精确为 /users/login)
curl -sk -b cookies.txt -c cookies.txt -X POST https://<服务器地址>/users/login \
  -H "x-csrf-token: <解码后的令牌>" -H 'Accept: application/json' \
  -d 'email=admin@example.org&password=q1w2e3r4'
{"success":true}
HTTP=200
# 3. 带会话查询主机列表 API(实测节选)
curl -sk -b cookies.txt 'https://<服务器地址>/hosts.json?containertype=hosts' -H 'Accept: application/json'
{"all_hosts":[{"Host":{"id":1,"uuid":"c36b8048-93ce-4385-ac19-ab5c90574b77","hostname":"default host","address":"127.0.0.1","description":"default host","hosttemplate_id":1,"active_checks_enabled":true,...,"satelliteName":"Mastersystem",...},"Hoststatus":{"currentState":0,"isFlapping":false,"lastCheck":"09:44:00 - 01.11.2026","nextCheck":"11:44:00 - 01.11.2026",...}}],...}

回显说明:安装自带一个 default host(127.0.0.1,satelliteName: Mastersystem 表示由本栈主系统监控),Hoststatus.currentState=0 即 OK 状态、lastCheck 有真实时间——证明「Web → Gearman → 引擎 → 插件执行 → 状态回写」整条链路已闭环。浏览器访问 https://<服务器地址>/ 用 openitcockpit.env 中的邮箱/密码登录即可进入图形界面。

五、数据持久化说明

官方 compose.yml 定义了 19 个命名卷,全部数据与状态都在卷中,容器可随意删除重建:

卷挂载点内容
mysql-datamysql:/var/lib/mysql主数据库(配置对象+状态+事件)
graphite-datacarbon-cache1/2、graphite-web:/var/lib/graphite/whisperWhisper 性能数据
grafana-datagrafana:/var/lib/grafanaGrafana 仪表盘与用户
naemon-varopenitcockpit、naemon、mod_gearman_worker、checkmk:/opt/openitc/nagios/varstatus.dat、nagios.cmd、oitc.cmd 等引擎运行时交换数据
naemon-var-localnaemon:/opt/openitc/nagios/var_local引擎日志/归档(可弃)
naemon-configopenitcockpit:/opt/openitc/nagios/etc/config(引擎侧 :ro)openITCOCKPIT 生成的 Naemon 配置目录
oitc-frontend-srcopenitcockpit:/opt/openitc/src_sharing/frontend → worker:/opt/openitc/frontend:ro共享给 worker 的前端源码(EVC 插件/通知脚本)
oitc-webrootopenitcockpit、puppeteer:/opt/openitc/frontend/webroot上传图片、报表共享
oitc-maps / oitc-stylesMapModule/DesignModule 目录地图图片、自定义样式
oitc-agent-cert / oitc-agent-etc/opt/openitc/agent、/opt/openitc/receiver/etc监控 Agent TLS 证书与接收端配置
oitc-varopenitcockpit:/opt/openitc/var锁文件与安装标记 .installation_done
oitc-backups/opt/openitc/nagios/backup自动生成的 MySQL 备份
checkmk-etc/var/agents、prometheus-var/config对应服务Checkmk 与 Prometheus 状态

要点:.installation_done 标记位于 oitc-var 卷——只要卷还在,openitcockpit 容器重建后不会重跑安装初始化;反之删卷即全新安装。备份的最小集合是 mysql-data + graphite-data + grafana-data 三卷,其余可由平台再生。

六、环境变量表

openitcockpit.env(实测 311 行)按消费方分组,以下列出各组核心键(默认值即官方注释值/实测生效值):

MySQL 组(mysql/openitcockpit/statusengine-worker/mod_gearman_worker 共用)

变量默认值说明
MYSQL_ROOT_PASSWORDroot_passwordroot 口令,务必修改
MYSQL_DATABASE / MYSQL_USERopenitcockpit / openitcockpit官方建议不改
MYSQL_PASSWORDopenitcockpit_password业务库口令
MYSQL_HOST / MYSQL_PORTmysql / 3306compose 网络内服务名

openITCOCKPIT 组

变量默认值说明
OITC_ADMIN_EMAIL / OITC_ADMIN_PASSWORDuser@example.org / asdf12初始管理员(首启前修改)
OITC_DEBUG0置 1 开启 CakePHP debug
OITC_DB_BACKENDStatusengine4状态后端(可选 Nagios/Crate/Statusengine3)
OITC_PERFDATA_BACKENDWhisper性能数据后端(可选 Rrdtool/Crate)
OITC_GEARMAN_ADDRESS / PORTgearmand / 4730Gearman 任务服务器
OITC_GRAPHITE_WEB_ADDRESS / PORT / PREFIXgraphite-web / 8080 / openitcockpit图表查询入口
OITC_NAEMON_HOSTNAMEnaemon引擎服务名
OITC_MAIL_RELAYHOST / PORTpostfix / 587邮件中继
OITC_NGINX_SSL_CERTIFICATE / _KEYsnakeoil 自签换正式证书路径(见第八节)
OITC_GRAFANA_ADMIN_PASSWORD + GF_SECURITY_ADMIN_PASSWORD同值Grafana 管理员(成对修改)
OITC_PHP_MEMORY_LIMIT / UPLOAD_MAX_FILESIZE / MAX_EXECUTION_TIME512M / 25M / 300PHP 运行时

Naemon 引擎组(NAEMON_*,写入 nagios.cfg):NAEMON_SERVICE_CHECK_TIMEOUT=60、NAEMON_HOST_CHECK_TIMEOUT=30、NAEMON_MAX_CONCURRENT_CHECKS=0、NAEMON_LOW/HIGH_SERVICE_FLAP_THRESHOLD=5.0/20.0、NAEMON_LOG_NOTIFICATIONS=1 等 20+ 键,与 nagios.cfg 同名参数一一对应。

ModGearman 组:MOD_GEARMAN_*(引擎侧 NEB 模块)与 MOD_GEARMAN_WORKER_*(执行器侧),核心为 GEARMAN_SERVER=gearmand:4730、hosts/services/eventhandler/notifications=yes、ENCRYPTION=no、KEY=should_be_changed(跨网络部署时必须改)。

Statusengine 组(statusengine-worker):STATUSENGINE_GEARMAN_ADDR、STATUSENGINE_MYSQL_DSN(openitcockpit:openitcockpit_password@tcp(mysql:3306)/openitcockpit)、STATUSENGINE_MYSQL_BATCH_SIZE=500、STATUSENGINE_GRAPHITE_ADDR=carbon-c-relay:2003、监听端口 8091(事件流)/8092(命令 API)/9105(Prometheus exporter)。

存储/图表组:VICTORIA_METRICS_RETENTION_PERIOD=1(月)、CC_CARBON_STORAGE_SCHEMA=60s:365d(Whisper 保留策略)、CCR_CARBON_CACHE_1/2=carbon-cache1/2:2003(relay 后端列表)、GF_* 系列(Grafana 官方环境变量规范)。

要点:该文件同时被 8 个服务的 env_file: 引用,是「一处修改、全栈生效」的单一事实来源;各键的完整语义与三层配置体系的关系在《openITCOCKPIT 5.9.0 配置参数详解》展开。

七、配置参数说明

Docker 形态下 openITCOCKPIT 的配置分三层,理解它们才能正确改参数(详见《openITCOCKPIT 5.9.0 配置参数详解》):

  1. openitcockpit.env(可改):唯一推荐的手工入口。compose 将对应变量注入各服务容器,守护进程启动时渲染成自己的配置文件(naemon 的 nagios.cfg、mod_gearman 的 neb.conf/worker.cfg、statusengine 的 worker 配置、Grafana 的 GF_* 等)。

  2. config/*.php(禁手改):openitcockpit 服务内 /opt/openitc/frontend/config/ 下的 gearman.php、dbbackend.php、perfdatabackend.php、graphite.php、after_export.php 等由平台从环境变量自动生成,文件头固定标注:

    //////////////////////////////////////////////////////////////////////
    //    DO NOT EDIT THIS FILE BY HAND -- YOUR CHANGES WILL BE OVERWRITTEN  //
    //                   File generated by openITCOCKPIT                     //
    

    生成器即 oitc config_generator 命令,由内置 cronjob 每分钟执行(oitc cronjobs -l 实测可见 ConfigGenerator | Core | Interval 1)。手改会在下一分钟被覆盖。

  3. Web UI 系统设置(数据库):systemsettings 表 115 个键值(实测),如 MONITORING.CMD=/opt/openitc/nagios/var/rw/nagios.cmd、MONITORING.CORECONFIG=/opt/openitc/etc/nagios/nagios.cfg、WEBSERVER.USER=www-data,在 System → Settings 页面维护,优先级最高。

少数例外:config/app.php 的 debug 与 Session 段直接读环境变量(env('OITC_DEBUG', false)、env('OITC_SESSION_DEFAULTS', 'php')),属于「文件里内嵌 env() 回退」模式,同样只需改 openitcockpit.env。

八、配置文件挂载

  • env_file 机制:compose.yml 中 mysql/openitcockpit/naemon/mod_gearman_worker/statusengine-worker/grafana/prometheus/victoria-metrics/carbon-* 等服务的 env_file: - openitcockpit.env 把整份文件注入容器环境。

  • MySQL 凭据文件:openitcockpit 服务启动时由入口脚本 /run.sh 依据环境变量生成 /opt/openitc/etc/mysql/mysql.cnf([client] 段含 host/user/password/port/database),供 mysql --defaults-file=/opt/openitc/etc/mysql/mysql.cnf 免密登录;该文件每次启动重写,不要在容器内直接编辑。

  • TLS 证书:默认自签 snakeoil 证书。挂正式证书(如 Let's Encrypt)需两步——在 openitcockpit.env 指定路径,再在 compose.yml 给 openitcockpit 服务加 bind mount(官方示例):

    # openitcockpit.env
    OITC_NGINX_SSL_CERTIFICATE=/tmp/Lets_Encrypt/cert.crt
    OITC_NGINX_SSL_CERTIFICATE_KEY=/tmp/Lets_Encrypt/private.key
    # compose.yml → openitcockpit.volumes 追加
    - /host/ssl/Lets_Encrypt:/tmp/Lets_Encrypt:ro
    
  • Naemon 配置目录:naemon-config 卷由 openitcockpit 服务读写(生成配置)、naemon 服务只读挂载(加载配置),这是「Web 改配置 → 引擎热加载」的共享通道。

九、等价 docker run 说明

本栈是 17 服务强耦合编排:存在 depends_on 启动顺序(openitcockpit → redis/mysql/gearmand)、跨容器共享卷(naemon-var 被 4 个服务挂载)、网络别名(grafana 的 grafana.docker 供 nginx 反代路由)与 Gearman 任务协议对接,无法用单条 docker run 等价复现,官方文档也未提供 docker run 形态。可行的最小组合命令是显式指定编排文件与目录:

docker compose -f /path/to/openITCOCKPIT-ce-docker/compose.yml --project-directory /path/to/openITCOCKPIT-ce-docker up -d

单服务重建(如改了 openitcockpit.env 后只重建 openitcockpit):

docker compose up -d openitcockpit    # 实测可用,仅重建该服务容器

十、常用运维命令

以下均在 openitcockpit 服务容器内执行(docker compose exec openitcockpit bash 进入,官方「Execute commands in a container」):

# MySQL 免密控制台(官方排障入口,实测可进)
mysql --defaults-file=/opt/openitc/etc/mysql/mysql.cnf

# Gearman 队列状态(官方「Query Gearman status」,实测回显节选)
gearadmin --status -h gearmand
statusngin_cmd	0	0	1
oitc_gearman	0	0	5
statusngin_servicestatus	0	0	1
statusngin_hoststatus	0	0	1
eventhandler	0	0	5
notification	0	0	5
service	0	0	5
host	0	0	5
.

(三列为:队列名/运行中任务/等待中任务;host、service 队列 max=5 对应 5 个 mod_gearman worker 槽位。)

# 跨容器服务管控(oitc supervisor 封装,实测回显)
oitc supervisor status naemon
Service naemon is running. pid 53, uptime 0:17:56

# 监控配置重新导出(实测回显)
oitc nagios_export
Generating new monitoring configuration. This could take awhile...
Monitoring configuration successfully generated.
Execute "systemctl reload naemon" to load the new configuration

# 定时任务总览(实测节选)
oitc cronjobs -l
+---------------------------------+------------------+----------+---------------------+
| Task                            | Plugin           | Interval | Last scheduled      |
+---------------------------------+------------------+----------+---------------------+
| CleanupTemp                     | Core             | 10       | 2026-11-01 09:04:01 |
| ConfigGenerator                 | Core             | 1        | 2026-11-01 09:06:01 |
| SystemHealth                    | Core             | 1        | 2026-11-01 09:06:01 |
| VersionCheck                    | Core             | 1440     | 2026-11-01 08:44:02 |
| Autoreport                      | AutoreportModule | 720      | 2026-11-01 08:44:04 |
+---------------------------------+------------------+----------+---------------------+

全栈升级(官方「Update containers」三步):

git pull origin main
docker compose down
docker compose up --pull always -d

十一、常见问题

问题 1:openitcockpit 服务无限循环 Waiting for MySQL to become available...(本次部署实测踩坑,完整排障实录)

现象:首次 docker compose up -d 后,docker compose logs openitcockpit 持续输出 Waiting for MySQL to become available...,30 次重试后进程退出,restart_policy: on-failure 使服务反复重启;而 mysql 服务本身健康(mysqladmin ping 手动执行返回 alive)。

定位:进入 openitcockpit 容器检查初始化脚本 /opt/openitc/frontend/CONTAINER_SETUP.sh 第 89 行的等待循环——它用 mysqladmin --defaults-extra-file="$INIFILE" ping --silent 探测 MySQL,$INIFILE 即 /run.sh 生成的 /opt/openitc/etc/mysql/mysql.cnf。手工复现:

mysqladmin --defaults-extra-file=/opt/openitc/etc/mysql/mysql.cnf ping
mysqladmin: [ERROR] unknown variable 'database=openitcockpit'.
echo $?
7

根因:mysql.cnf 的 [client] 段含 database = openitcockpit。mysql 客户端认识 database 选项,但 mysqladmin 不认识该选项,直接报错退出(与 MySQL 8.0.x 客户端工具行为实测一致),导致等待循环永远失败。

修复尝试(两轮弯路,均有实测依据):

  1. 删掉 mysql.cnf 的 database 行 → mysqladmin ping 通过,但安装推进到数据库迁移时报 [RuntimeException] The 'default' connection has no 'database' key defined——CakePHP 的 config/datasource.php 用平台自带的 MysqlConfigFileParser 解析同一份 cnf,必须有 database 键。
  2. 把 database 行从 [client] 移到 [mysql] 段(mysqladmin 只读 [client]+[mysqladmin],mysql 客户端与 PHP 解析器读 [client]+[mysql])→ 安装全程通过并打出 ready 横幅,但 supervisor 中 openitcockpit-websocket(Go 二进制,只读 [client] 段)报 Error 1046 (3D000): No database selected 进入 FATAL。

最终修复:保持 /run.sh 与 mysql.cnf 官方原样([client] 段含 database),只给 CONTAINER_SETUP.sh 的等待循环打补丁——ping 时用过滤掉 database 行的临时配置:

# CONTAINER_SETUP.sh 第 89 行改为(备份原文件后):
grep -v "^database" "$INIFILE" > /opt/openitc/var/mysql_ping.cnf; chmod 600 /opt/openitc/var/mysql_ping.cnf; if mysqladmin --defaults-extra-file=/opt/openitc/var/mysql_ping.cnf ping --silent >/dev/null 2>&1; then

注意临时 cnf 必须放在 /opt/openitc/var/(放 /tmp 会因 world-writable 目录被 MySQL 客户端忽略配置文件)。重启后验证:ready 横幅出现、docker compose ps 17 服务全 Up、supervisor 各进程 RUNNING、登录 API {"success":true}。

衍生提醒:/run.sh 每次启动都会重写 mysql.cnf,任何手工修复必须在 30 秒等待循环窗口内完成或落在卷内持久文件上;容器重建(docker compose up -d --force-recreate)会丢失容器内补丁,但 .installation_done 在 oitc-var 卷中,重建后不再触发该等待循环。

问题 2:设置了 OITC_ADMIN_PASSWORD,登录仍报凭据错误

实测现象:openitcockpit.env 已设 OITC_ADMIN_EMAIL=admin@example.org / OITC_ADMIN_PASSWORD=q1w2e3r4,但安装后登录不生效(初始管理员注入流程未随该次安装执行)。用平台 CLI 重置即可:

oitc reset_password 1 --print --no-mail --enable
# 打印新生成的随机口令,用它登录 Web UI 后再在用户设置中改为目标口令

问题 3:浏览器访问 http:// 报 301

设计行为:平台 nginx 强制 80 → 443 HTTPS 跳转(实测 curl -I 见第四节),使用 https:// 访问即可;自签证书会有告警,正式环境按第八节挂证书。

问题 4:oitc nagios_export --verify 报 sudo: /opt/openitc/nagios/bin/nagios: command not found

非故障:Docker 形态下 Naemon 二进制在独立的 naemon 服务容器内,openitcockpit 容器里没有引擎可执行文件,--verify 的本地校验必然失败(实测回显 Verification failed!)。配置正确性应到 naemon 容器内校验(实测回显):

docker compose exec naemon su nagios -c '/opt/openitc/nagios/bin/naemon -v /opt/openitc/etc/nagios/nagios.cfg'
Total Warnings: 0
Total Errors:   0
Things look okay - No serious problems were detected during the pre-flight check

(注意必须以 nagios 用户运行,root 下 naemon 拒绝启动:ERROR: do not start naemon as root user.)导出本身(不带 --verify)在 openitcockpit 容器内执行完全正常,配置经 naemon-config 卷共享给引擎。

问题 5:gearmand 报 too many open files

官方 compose.yml 已内置 ulimits.nofile 65536(gearmand/mysql/carbon-cache1/2);若自行改写编排,务必保留,参考 statusengine.org 教程《Gearman too many open files》。

十二、参考链接

openITCOCKPIT Docker Compose 部署指南 - Quzuo