openITCOCKPIT 5.9.0 配置参数详解

目标：讲清 openITCOCKPIT 5.9.0 在官方 Docker Compose 形态下的三层配置体系——openitcockpit.env 环境变量、平台自动生成的 config/*.php、数据库 systemsettings 系统设置——并逐组实测各守护进程（Naemon、ModGearman、Statusengine4、Graphite、Grafana、Postfix）的参数落点，让读者知道「改哪里、何时生效、被谁覆盖」。选型背景见《openITCOCKPIT 介绍与选型指南》，从零部署过程见《openITCOCKPIT Docker Compose 部署指南》。

一、环境信息

本文基于已部署并运行的 openITCOCKPIT 5.9.0 全栈实测（Ubuntu 24.04，Docker Compose 形态，17 服务，版本溯源见《openITCOCKPIT 介绍与选型指南》）。配置体系取证环境：

环境变量文件：编排目录下 openitcockpit.env（实测 311 行），经 compose 的 env_file: 注入 8 个服务
平台配置文件目录：openitcockpit 服务内 /opt/openitc/frontend/config/（实测 15 个 .php + Migrations/Seeds/schema 子目录）
数据库系统设置：MySQL openitcockpit 库 systemsettings 表（实测 115 个键值、10 个 section）
守护进程配置：naemon 服务 /opt/openitc/etc/nagios/nagios.cfg、/opt/openitc/etc/mod_gearman/mod_gearman_neb.conf；mod_gearman_worker 服务 /opt/openitc/mod_gearman/etc/worker.cfg；statusengine-worker 由 STATUSENGINE_* 环境变量直接驱动

三层配置体系总览（数据流向实测确认）：

层	载体	修改方式	生效路径
1. 环境变量	openitcockpit.env	编辑文件 + `docker compose up -d <服务>` 重建	注入容器环境 → 各守护进程启动时渲染成自身配置文件
2. 生成的 PHP 配置	/opt/openitc/frontend/config/*.php	禁止手改，由 env 变量驱动生成	`oitc config_generator`（内置 cronjob 每 1 分钟）比对模板重渲染
3. 数据库设置	systemsettings 表（Web UI System → Settings）	界面修改，即时入库	平台运行时读取，优先级最高

💡 技术拓展：配置来源的常见三选一——「文件静态配置 / 环境变量注入 / 数据库动态配置」。openITCOCKPIT 三层并用：env 是 Docker 形态的单一事实来源，PHP 文件是 env 的渲染产物（模板占位符 {{address}} 式替换），数据库承载运行期可改的业务设置。同类系统对比：Zabbix 用 server 配置文件 + 前端管理页两层；Icinga2 纯文件 + API 对象；Prometheus 纯文件 + 热加载。

二、前置条件

已按《openITCOCKPIT Docker Compose 部署指南》完成全栈部署，docker compose ps 17 服务 Up、Web UI 可登录
进入配置现场的命令（实测可用）：

docker compose exec openitcockpit bash     # 平台层：config/*.php、mysql.cnf、oitc CLI
docker compose exec naemon sh              # 引擎层：nagios.cfg、mod_gearman NEB
docker compose exec statusengine-worker sh # 状态层：worker 进程

三、参数查看与修改方式

3.1 第一层：openitcockpit.env（推荐入口）

全部跨服务共享参数集中于此。修改后需重建对应服务容器生效：

vim openitcockpit.env
docker compose up -d openitcockpit naemon   # 只重建受影响服务

实测生效示例——OITC_ADMIN_EMAIL/OITC_ADMIN_PASSWORD、MYSQL_* 四要素、GF_SECURITY_ADMIN_PASSWORD 等均在此定义（完整分组见第四、五节）。

3.2 第二层：config/*.php（只读观察）

平台配置目录实测清单（ls /opt/openitc/frontend/config/，节选）：

after_export.php   dbbackend.php    graphite.php      perfdatabackend.php
app.php            email.php        nagios.php        datasource.php
gearman.php        bootstrap.php    paths.php         routes.php

由环境变量生成的文件（gearman/dbbackend/perfdatabackend/graphite/after_export）头部固定标注（实测 cat）：

//////////////////////////////////////////////////////////////////////////
//    DO NOT EDIT THIS FILE BY HAND -- YOUR CHANGES WILL BE OVERWRITTEN  //
//                   File generated by openITCOCKPIT                     //
//                        Created: 01.11.2026 08:48                      //
//////////////////////////////////////////////////////////////////////////

生成器实测——oitc config_generator 幂等执行（无待更新时）：

oitc config_generator -v
Check for pending configuration files...
Ok

该命令由内置 cronjob 每分钟调度（oitc cronjobs -l 实测行：ConfigGenerator | Core | Interval 1），因此手改这些文件最多存活 1 分钟。

3.3 第三层：systemsettings 数据库设置

Web UI「System → Settings」的持久化后端。表结构与样例实测：

SHOW COLUMNS FROM systemsettings;
+----------+---------------+------+-----+---------+----------------+
| Field    | Type          | Null | Key | Default | Extra          |
+----------+---------------+------+-----+---------+----------------+
| id       | int           | NO   | PRI | NULL    | auto_increment |
| key      | varchar(255)  | NO   |     | NULL    |                |
| value    | varchar(255)  | NO   |     | NULL    |                |
| info     | varchar(1500) | NO   |     | NULL    |                |
| section  | varchar(255)  | NO   |     | NULL    |                |
+----------+---------------+------+-----+---------+----------------+
SELECT COUNT(*) FROM systemsettings;   -- 实测 115
SELECT DISTINCT section FROM systemsettings;
-- SUDO_SERVER / WEBSERVER / MONITORING / SYSTEM / FRONTEND / CHECK_MK
-- ARCHIVE / INIT / TICKET_SYSTEM / SYSTEM_HEALTH

免密进入 MySQL 的官方方式（凭据文件由服务启动脚本按 env 生成）：

mysql --defaults-file=/opt/openitc/etc/mysql/mysql.cnf

样例键值实测（节选）：

key                        value                                    section
WEBSERVER.USER             www-data                                 WEBSERVER
MONITORING.USER            nagios                                   MONITORING
MONITORING.FROM_ADDRESS    openitcockpit@example.org                MONITORING
MONITORING.CMD             /opt/openitc/nagios/var/rw/nagios.cmd    MONITORING
MONITORING.CORECONFIG      /opt/openitc/etc/nagios/nagios.cfg       MONITORING
MONITORING.STATUS_DAT      /opt/openitc/nagios/var/status.dat       MONITORING

要点：MONITORING.CMD/CORECONFIG/STATUS_DAT 这类「平台 ↔ 引擎」路径对接参数在数据库层维护，与 env 层互不覆盖；改引擎路径属于高危操作，一般保持默认。

四、参数总览（按消费方分组）

openitcockpit.env 311 行的分组结构（官方注释即标明 Used by）：

组前缀	消费服务	落点文件/机制
MYSQL_*	mysql、openitcockpit、statusengine-worker、mod_gearman_worker	生成 mysql.cnf / DSN
SUPERVISOR_*	naemon、openitcockpit 等（进程管控）	supervisord.conf（envsubst 渲染，实测 `/tmp/supervisord.conf`）
OITC_*	openitcockpit	config/*.php、nginx、php-fpm
NAEMON_*	naemon	nagios.cfg 同名指令
MOD_GEARMAN_* / MOD_GEARMAN_WORKER_*	naemon(NEB) / mod_gearman_worker	neb.conf / worker.cfg
STATUSENGINE_*	statusengine-worker	Go worker 进程环境直读
VICTORIA_METRICS_* / PROMETHEUS_* / GF_* / CCR_* / CC_* / GW_*	各图表组件	各组件原生配置
CHECKMK_API_URL	checkmk 集成	—

五、核心参数分类详解

5.1 数据库连接（MYSQL_*）

MYSQL_ROOT_PASSWORD=root_password      # 务必修改
MYSQL_DATABASE=openitcockpit           # 官方建议不改
MYSQL_USER=openitcockpit               # 官方建议不改
MYSQL_PASSWORD=openitcockpit_password  # 务必修改
#MYSQL_PORT=3306 / #MYSQL_HOST=mysql   # 注释态即默认

openitcockpit 服务启动时把四要素渲染为 /opt/openitc/etc/mysql/mysql.cnf（[client] 段 host/user/password/port/database），供 mysql 客户端、CakePHP 解析器（MysqlConfigFileParser 只认 [client]/[mysql] 段）、Go websocket 进程三方共用——同一份文件、三种解析器，是《openITCOCKPIT Docker Compose 部署指南》mysqladmin 死锁问题的根源，参数本身无需改动，但理解此机制对排障至关重要。

5.2 平台初始化与安全（OITC_ADMIN_* / OITC_DEBUG / Session）

OITC_ADMIN_EMAIL=admin@example.org     # 初始管理员（官方默认 user@example.org/asdf12）
OITC_ADMIN_PASSWORD=q1w2e3r4
OITC_ADMIN_FIRSTNAME=Admin / OITC_ADMIN_LASTNAME=User
#OITC_DEBUG=0                          # 置 1 开 CakePHP 调试（app.php: env('OITC_DEBUG', false)）
#OITC_SECURITY_SALT=cf45...            # 应用加盐，不设置则安装时随机生成
#OITC_SESSION_DEFAULTS=php             # app.php Session.defaults；cookie 强制 httponly/secure/samesite=Lax/use_strict_mode

实测 app.php 会话段（grep -A8 "'Session'" config/app.php）：

'Session'   => [
    'defaults' => env('OITC_SESSION_DEFAULTS', 'php'),
    'ini'      => [
        'session.cookie_httponly' => 1,
        'session.cookie_secure'   => 1,
        'session.cookie_samesite' => 'Lax',
        'session.use_strict_mode' => 1
    ]
],

会话后端可选 redis（#OITC_REDIS_HOST=redis / #OITC_REDIS_PORT=6379，compose 已带 redis 服务）。

5.3 状态与性能数据后端选择

两个「架构开关」型参数，实测生成物：

#OITC_DB_BACKEND=Statusengine4        # 状态后端：Nagios/Crate/Statusengine3/Statusengine4
#OITC_PERFDATA_BACKEND=Whisper        # 性能数据后端：Rrdtool/Crate/Whisper

// config/dbbackend.php（实测）
return ['dbbackend' => 'Statusengine4'];
// config/perfdatabackend.php（实测）
return ['perfdatabackend' => 'Whisper'];

默认组合 Statusengine4 + Whisper 即「Go worker 写 MySQL 状态表 + carbon-cache 写 Whisper 时序文件」，与全栈其余服务（graphite-web/carbon-c-relay/carbon-cache1/2）配套；改这两项需同步增删 compose 服务，一般保持默认。

5.4 Gearman 分布式检查

#OITC_GEARMAN_ADDRESS=gearmand        # 任务服务器
#OITC_GEARMAN_PORT=4730
#OITC_GEARMAM_WORKER=5                # 官方变量名即此拼写（GEARMAM），平台内一致

渲染产物 config/gearman.php 实测：

'gearman' => ['address' => 'gearmand', 'port' => 4730,
              'pidfile' => '/var/run/oitc_gearmanworker.pid', 'worker' => 5, 'timeout' => 1000]

引擎侧 NEB 模块（MOD_GEARMAN_* → naemon 服务 /opt/openitc/etc/mod_gearman/mod_gearman_neb.conf，实测节选）：

server=gearmand:4730
eventhandler=yes / notifications=yes / services=yes / hosts=yes
do_hostchecks=yes
orphan_host_checks=yes / orphan_service_checks=yes
encryption=no / key=should_be_changed

执行器侧（MOD_GEARMAN_WORKER_* → mod_gearman_worker 服务 /opt/openitc/mod_gearman/etc/worker.cfg，实测节选）：

server=gearmand:4730
job_timeout=60 / min-worker=5 / max-worker=50
idle-timeout=30 / spawn-rate=3 / sink-rate=1
load_cpu_multi=2.5 / mem_limit=70
enable_embedded_perl=on / use_embedded_perl_implicitly=off

跨信任边界部署必须 MOD_GEARMAN_ENCRYPTION=yes 并更换 KEY（两侧成对修改）。队列实况用 gearadmin --status -h gearmand 验证（《openITCOCKPIT Docker Compose 部署指南》第十节实测回显：host/service 队列 max=5 即 worker 槽位数）。

5.5 Naemon 引擎参数（NAEMON_* → nagios.cfg）

NAEMON_* 与 nagios.cfg 指令一一对应，env 实测注释与引擎配置回显对照（grep -v '^#' /opt/openitc/etc/nagios/nagios.cfg 节选）：

env	默认	nagios.cfg 实测
NAEMON_SERVICE_CHECK_TIMEOUT	60	`service_check_timeout=60`
NAEMON_HOST_CHECK_TIMEOUT	30	`host_check_timeout=30`
NAEMON_MAX_CONCURRENT_CHECKS	0	`max_concurrent_checks=0`
NAEMON_LOG_NOTIFICATIONS	1	`log_notifications=1`
NAEMON_LOG_EXTERNAL_COMMANDS	0	`log_external_commands=0`
NAEMON_RETENTION_UPDATE_INTERVAL	3600	`retention_update_interval=3600`
NAEMON_LOW/HIGH_SERVICE_FLAP_THRESHOLD	5.0/20.0	`low_service_flap_threshold=5.0`

引擎主配置另有平台固定项（非 env 控制）：cfg_dir=/opt/openitc/nagios/etc/config（接收 Web 导出的配置）、status_file=/opt/openitc/nagios/var/status.dat、command_file=/opt/openitc/nagios/var/rw/nagios.cmd、query_socket=/opt/openitc/nagios/var/rw/nagios.qh、event_broker_options=-1（全量事件走 broker 模块）。修改 NAEMON_* 后重建 naemon 服务即生效。

5.6 Statusengine4 worker（STATUSENGINE_*）

Go worker 直读环境变量（无中间文件），关键项与实测默认：

#STATUSENGINE_CONSUMER=gearman
#STATUSENGINE_GEARMAN_ADDR="gearmand:4730"
#STATUSENGINE_MYSQL_DSN="openitcockpit:openitcockpit_password@tcp(mysql:3306)/openitcockpit?parseTime=true"
#STATUSENGINE_MYSQL_BATCH_SIZE=500          # 状态批量入库
#STATUSENGINE_GRAPHITE_BATCH_SIZE=100
#STATUSENGINE_GRAPHITE_ADDR="carbon-c-relay:2003"
#STATUSENGINE_PERFDATA_ROUTE=graphite
#STATUSENGINE_LISTEN_ADDR=":8091"           # WebSocket 事件流
#STATUSENGINE_COMMAND_LISTEN_ADDR=":8092"   # 外部命令 HTTP API
#STATUSENGINE_METRICS_LISTEN_ADDR=":9105"   # Prometheus exporter
#STATUSENGINE_STATUS_MAX_AGE="5m"
#ENABLE_OPENITCOCKPIT_TWEAKS=true

worker 启动脚本同样依据 MYSQL_* 生成自己的 mysql.cnf（含 database 行于 [client] 段——与平台层一致的机制）。三个监听端口在 compose 中默认注释未发布到宿主机，需要事件流/命令 API 时按需打开。

5.7 图表与指标存储

Graphite 查询入口（OITC_GRAPHITE_* → config/graphite.php 实测）：graphite_web_host=graphite-web、port=8080、prefix=openitcockpit、use_https/use_proxy=false
Whisper 保留策略：CC_CARBON_STORAGE_SCHEMA=60s:365d（60 秒分辨率存 1 年，直接决定磁盘占用曲线）；CC_WHISPER_FALLOCATE_CREATE=1 可加速文件创建
relay 分发：CCR_CARBON_CACHE_1/2=carbon-cache1/2:2003，扩容 carbon-cache 实例需同步改 compose 与该项
VictoriaMetrics：VICTORIA_METRICS_RETENTION_PERIOD=1（单位是月，默认仅 1 个月，生产建议按磁盘预算调大）
Grafana：GF_* 全量遵循 Grafana 官方环境变量规范；成对项 OITC_GRAFANA_ADMIN_PASSWORD = GF_SECURITY_ADMIN_PASSWORD；反代路由依赖网络别名 grafana.docker（compose 中 grafana 服务的 networks alias），OITC_GRAFANA_HOSTNAME 保持该值时流量走 openITCOCKPIT 的 nginx，改为直连地址则要求所有客户端可达 Grafana
Prometheus 桥：#OITC_PROMETHEUS_BRIDGE_LOOP_INTERVAL=15（秒，平台监控对象同步为 Prometheus targets 的周期，由 openitcockpit 容器内 prometheus_bridge 进程执行）

5.8 邮件通知（email.php / postfix）

平台 CakePHP 邮件传输实测配置（cat config/email.php）：

'EmailTransport' => ['default' => [
    'className' => \Cake\Mailer\Transport\SmtpTransport::class,
    'host'      => 'postfix',   // ← OITC_MAIL_RELAYHOST
    'port'      => 587,         // ← OITC_MAIL_RELAYHOST_PORT
    'timeout'   => 30, ...
]]

postfix 服务用社区镜像 boky/postfix，compose 内环境变量：HOSTNAME、RELAYHOST=mailrelay.example.org（上游真实 SMTP）、RELAYHOST_USERNAME/PASSWORD（可选）、ALLOW_EMPTY_SENDER_DOMAINS=true。生产落地需改 RELAYHOST 指向自有中继并配 SPF/DKIM。

5.9 Web 服务器与 PHP 运行时

#OITC_NGINX_SSL_CERTIFICATE=/etc/ssl/certs/ssl-cert-snakeoil.pem      # 默认自签
#OITC_NGINX_SSL_CERTIFICATE_KEY=/etc/ssl/private/ssl-cert-snakeoil.key
#OITC_PHP_MEMORY_LIMIT=512M / OITC_PHP_UPLOAD_MAX_FILESIZE=25M
#OITC_PHP_POST_MAX_SIZE=25M / OITC_PHP_MAX_EXECUTION_TIME=300
#OITC_PHP_FPM_PM_MAX_CHILDREN=10 / PM_START_SERVERS=4

nginx 行为固定为 80 → 301 → 443（实测），SPA 前端挂 /a/ 路径（alias /opt/openitc/frontend-angular/browser/）。PHP-FPM 池参数（pm.max_children 等）由模板 config_templates/PhpFpmOitc/oitc.conf.tpl 渲染，大规模实例（数千 host/service）应上调 OITC_PHP_FPM_PM_MAX_CHILDREN 并同步 OITC_PHP_MEMORY_LIMIT。

六、生产配置模板

按「4 GB 内存 / 60 GB 磁盘 / ≤500 监控对象」基线，openitcockpit.env 生产最小修改集（值均为建议演示值）：

# ── 必改：凭据 ──
MYSQL_ROOT_PASSWORD=<pwgen -s -1 16 生成>
MYSQL_PASSWORD=<pwgen -s -1 16 生成>
OITC_ADMIN_EMAIL=ops@your.example.org
OITC_ADMIN_PASSWORD=<强口令>
OITC_GRAFANA_ADMIN_PASSWORD=<与下行同值>
GF_SECURITY_ADMIN_PASSWORD=<强口令>

# ── 建议：数据保留 ──
VICTORIA_METRICS_RETENTION_PERIOD=12     # 默认 1 个月太短
CC_CARBON_STORAGE_SCHEMA=60s:365d        # 磁盘紧张可降为 60s:180d

# ── 跨信任边界时：Gearman 加密 ──
MOD_GEARMAN_ENCRYPTION=yes
MOD_GEARMAN_KEY=<32 字符随机密钥>
MOD_GEARMAN_WORKER_ENCRYPTION=yes
MOD_GEARMAN_WORKER_KEY=<与上同值>

# ── 邮件落地 ──
# postfix 服务 RELAYHOST 在 compose.yml 中指向真实 SMTP 中继

要点：改完 docker compose up -d（受影响服务自动重建）；MySQL 口令改动需 mysql 卷初始化前完成，已建库后需同步改库内账号，属高危操作。

七、常见问题

Q1：改了 config/gearman.php 不生效？ 设计行为。该文件头部标注 DO NOT EDIT THIS FILE BY HAND，由 oitc config_generator 每分钟从 env 重渲染（实测 1 分钟周期见 oitc cronjobs -l）。正确做法：改 openitcockpit.env 的 OITC_GEARMAN_ADDRESS 后重建 openitcockpit 服务。

Q2：改了 openitcockpit.env 但容器里还是旧值？ env_file 只在容器创建时注入，docker compose restart 不会重读文件，必须 docker compose up -d <服务名> 触发重建（官方 compose 语义）。

Q3：Web UI 的 System Settings 和 env 同名参数以哪个为准？ 两层作用域不同：systemsettings（115 键实测）管平台↔引擎路径、通知署名等业务项；env 管连接、超时、阈值等启动参数。不存在同名覆盖关系，改错层「不生效」是第一信号。

Q4：mysql.cnf 里为什么有一行 database？删掉会怎样？ 它是 CakePHP datasource.php 与 Go websocket 进程的必需键（删掉分别报 The 'default' connection has no 'database' key defined 与 Error 1046: No database selected），但 mysqladmin 不认识它——该矛盾导致全新安装可能卡死在 Waiting for MySQL to become available...，完整排障实录与补丁见《openITCOCKPIT Docker Compose 部署指南》第十一节问题 1。

Q5：OITC_ADMIN_PASSWORD 设了但登录失败？ 实测存在初始口令注入未生效的情况；用 oitc reset_password 1 --print --no-mail --enable 重置（打印新随机口令），登录后在 Web UI 用户设置中改为目标口令。

八、参考链接

官方文档 Docker → Settings / Default values 与「Container」配置章节（docs.openitcockpit.io，查询日期 2026-11-01）
Statusengine worker 配置文档：github.com/statusengine/statusengine-worker
Grafana 环境变量规范：grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/#configure-with-environment-variables
Mod-Gearman 参数手册：mod-gearman.org
本专栏：《openITCOCKPIT 介绍与选型指南》《openITCOCKPIT Docker Compose 部署指南》《openITCOCKPIT 5.9.0 常用 CLI 命令与工具详解》