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 等待死锁排障实录。
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):
| 服务 | 镜像 | 端口(容器内) | 职责 |
|---|---|---|---|
| openitcockpit | openitcockpit/openitcockpit-ce:latest | 80/443 | Web 平台(CakePHP 后端 + nginx + php-fpm + Angular SPA) |
| naemon | openitcockpit/naemon:latest | 9001/9099 | Naemon 监控引擎(含 mod_gearman NEB 模块) |
| mod_gearman_worker | openitcockpit/mod_gearman_worker:latest | — | 分布式检查执行器(monitoring-plugins 2.4.0 插件集) |
| gearmand | openitcockpit/gearmand:latest | 4730 | Gearman 任务调度服务器 |
| statusengine-worker | openitcockpit/statusengine-worker:latest | 8091/8092/9105 | Statusengine4 Go worker:状态入库、性能数据转发、外部命令 API |
| mysql | mysql:lts | 3306 | 主数据库(实测 mysqld 9.7.4) |
| redis | redis:latest | 6379 | 缓存/会话后端 |
| graphite-web | openitcockpit/graphite-web:latest | 8080 | 性能数据查询 API |
| carbon-relay | openitcockpit/carbon-c-relay:latest | 2003 | 指标路由分发 |
| carbon-cache1/2 | openitcockpit/carbon-cache:latest | — | Whisper 存储写入(双实例可横向扩) |
| victoria-metrics | openitcockpit/victoria-metrics:latest | 8428 | Prometheus 远端存储 |
| prometheus | openitcockpit/prometheus:latest | 9090 | 指标抓取(经 openITCOCKPIT prometheus_bridge 同步配置) |
| grafana | openitcockpit/grafana:latest | 3033 | 仪表盘(经 nginx 反代,网络别名 grafana.docker) |
| puppeteer | openitcockpit/puppeteer:latest | 8084 | 报表截图渲染 |
| checkmk | openitcockpit/checkmk:latest | 1234 | Checkmk 集成 API 包装 |
| postfix | boky/postfix | 587 | 邮件通知中继 |
实测组件版本(部署完成后在对应服务内核验):
# 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-data | mysql:/var/lib/mysql | 主数据库(配置对象+状态+事件) |
| graphite-data | carbon-cache1/2、graphite-web:/var/lib/graphite/whisper | Whisper 性能数据 |
| grafana-data | grafana:/var/lib/grafana | Grafana 仪表盘与用户 |
| naemon-var | openitcockpit、naemon、mod_gearman_worker、checkmk:/opt/openitc/nagios/var | status.dat、nagios.cmd、oitc.cmd 等引擎运行时交换数据 |
| naemon-var-local | naemon:/opt/openitc/nagios/var_local | 引擎日志/归档(可弃) |
| naemon-config | openitcockpit:/opt/openitc/nagios/etc/config(引擎侧 :ro) | openITCOCKPIT 生成的 Naemon 配置目录 |
| oitc-frontend-src | openitcockpit:/opt/openitc/src_sharing/frontend → worker:/opt/openitc/frontend:ro | 共享给 worker 的前端源码(EVC 插件/通知脚本) |
| oitc-webroot | openitcockpit、puppeteer:/opt/openitc/frontend/webroot | 上传图片、报表共享 |
| oitc-maps / oitc-styles | MapModule/DesignModule 目录 | 地图图片、自定义样式 |
| oitc-agent-cert / oitc-agent-etc | /opt/openitc/agent、/opt/openitc/receiver/etc | 监控 Agent TLS 证书与接收端配置 |
| oitc-var | openitcockpit:/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_PASSWORD | root_password | root 口令,务必修改 |
| MYSQL_DATABASE / MYSQL_USER | openitcockpit / openitcockpit | 官方建议不改 |
| MYSQL_PASSWORD | openitcockpit_password | 业务库口令 |
| MYSQL_HOST / MYSQL_PORT | mysql / 3306 | compose 网络内服务名 |
openITCOCKPIT 组
| 变量 | 默认值 | 说明 |
|---|---|---|
| OITC_ADMIN_EMAIL / OITC_ADMIN_PASSWORD | user@example.org / asdf12 | 初始管理员(首启前修改) |
| OITC_DEBUG | 0 | 置 1 开启 CakePHP debug |
| OITC_DB_BACKEND | Statusengine4 | 状态后端(可选 Nagios/Crate/Statusengine3) |
| OITC_PERFDATA_BACKEND | Whisper | 性能数据后端(可选 Rrdtool/Crate) |
| OITC_GEARMAN_ADDRESS / PORT | gearmand / 4730 | Gearman 任务服务器 |
| OITC_GRAPHITE_WEB_ADDRESS / PORT / PREFIX | graphite-web / 8080 / openitcockpit | 图表查询入口 |
| OITC_NAEMON_HOSTNAME | naemon | 引擎服务名 |
| OITC_MAIL_RELAYHOST / PORT | postfix / 587 | 邮件中继 |
| OITC_NGINX_SSL_CERTIFICATE / _KEY | snakeoil 自签 | 换正式证书路径(见第八节) |
| OITC_GRAFANA_ADMIN_PASSWORD + GF_SECURITY_ADMIN_PASSWORD | 同值 | Grafana 管理员(成对修改) |
| OITC_PHP_MEMORY_LIMIT / UPLOAD_MAX_FILESIZE / MAX_EXECUTION_TIME | 512M / 25M / 300 | PHP 运行时 |
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 配置参数详解》):
-
openitcockpit.env(可改):唯一推荐的手工入口。compose 将对应变量注入各服务容器,守护进程启动时渲染成自己的配置文件(naemon 的 nagios.cfg、mod_gearman 的 neb.conf/worker.cfg、statusengine 的 worker 配置、Grafana 的 GF_* 等)。
-
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)。手改会在下一分钟被覆盖。 -
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 客户端工具行为实测一致),导致等待循环永远失败。
修复尝试(两轮弯路,均有实测依据):
- 删掉 mysql.cnf 的
database行 → mysqladmin ping 通过,但安装推进到数据库迁移时报[RuntimeException] The 'default' connection has no 'database' key defined——CakePHP 的config/datasource.php用平台自带的MysqlConfigFileParser解析同一份 cnf,必须有database键。 - 把
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》。
十二、参考链接
- 官方 Docker 文档:docs.openitcockpit.io(Docker → Installation/Troubleshooting/Query Gearman status/Restarting services 章节,查询日期 2026-11-01)
- 编排仓库:github.com/openITCOCKPIT/openITCOCKPIT-ce-docker
- 镜像仓库:hub.docker.com/u/openitcockpit
- 本专栏:《openITCOCKPIT 介绍与选型指南》《openITCOCKPIT 5.9.0 配置参数详解》《openITCOCKPIT 5.9.0 常用 CLI 命令与工具详解》
- 引擎背景:《Naemon 介绍与选型指南》