openITCOCKPIT 5.9.0 常用 CLI 命令与工具详解
openITCOCKPIT 5.9.0 命令行工具体系实测详解：oitc（CakePHP console 封装）全命令组速览，nagios_export/config_generator/supervisor/cronjobs/reset_password/roles/acl.aco_sync/dump/system_health 等核心命令逐条实测回显，含 Docker 形态下 --verify 的落点差异与 gearadmin/naemon -v/monitoring-plugins 辅助工具验证。
openITCOCKPIT 5.9.0 常用 CLI 命令与工具详解
目标：系统实测 openITCOCKPIT 5.9.0 的 CLI 工具体系——平台主命令
oitc的核心命令组（配置导出、配置生成、进程管控、定时任务、账号权限、数据导出、健康检查）与周边工具（gearadmin、naemon 校验、monitoring-plugins 插件集），每条命令给出参数说明与真实回显，作为 Web UI 之外的自动化运维入口手册。部署背景见《openITCOCKPIT Docker Compose 部署指南》，配置体系见《openITCOCKPIT 5.9.0 配置参数详解》。
一、环境信息
- 被测版本：openITCOCKPIT Community Edition 5.9.0（Docker Compose 全栈，17 服务运行中；版本溯源见《openITCOCKPIT 介绍与选型指南》）
- CLI 入口：openitcockpit 服务容器内
/usr/bin/oitc（实测which oitc） - 引擎侧：naemon 服务容器（Naemon 1.5.1，实测 status.dat
info.version=1.5.1），检查插件位于 mod_gearman_worker 服务容器 - 执行方式：
docker compose exec openitcockpit bash进入平台容器后运行oitc <command>（官方排障章节「Execute commands in a container」）
oitc 本体是 CakePHP console 的封装脚本，实测关键逻辑（节选自 /usr/bin/oitc）：
# 保留全部环境变量（Docker 内配置生成所需，官方注释 ITC-2986）
export PATH="${PATH:+$PATH:}/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
WWW_GID="$(getent group www-data | cut -d: -f3)"
# 新建文件组可写，保证 Web 进程可覆写
umask 002
# 以 root + www-data 组执行 CakePHP console
exec setpriv --reuid 0 --regid "$WWW_GID" --keep-groups -- /opt/openitc/frontend/bin/cake "$@"
要点：
oitc即cake——帮助尾注原文To run a command, type cake command_name [args|options]；它只存在于 openitcockpit 服务容器（引擎容器内无此命令），所有平台级 CLI 操作都在这一侧完成。
二、工具概览
oitc --help 实测输出按组列出全部命令（60+ 项，节选核心）：
Available Commands:
acl:
- aco_sync
└─── Perform a full sync on the ACO table...
- aco_update
- recover
app:
- cmd
- config_generator
- cronjobs
- dump
- gearman_worker
- nagios_export
- reset_password
- roles
- setup
- supervisor
- system_health
- version_check
- wipe
cakephp:
- cache clear / cache clear_all / routes / version
migrations:
- migrations migrate / migrations seed / ...
checkmk_module: / grafana_module: / prometheus_module: / autoreport_module: ...
按用途归类，本文详解以下 9 组命令 + 3 个周边工具：
| 类别 | 命令 | 用途 |
|---|---|---|
| 配置导出 | oitc nagios_export | 数据库对象 → Naemon 配置文件 |
| 配置生成 | oitc config_generator | 环境变量 → config/*.php |
| 进程管控 | oitc supervisor | 跨容器启停引擎/服务进程 |
| 任务调度 | oitc cronjobs | 内置定时任务列表/强制执行 |
| 账号权限 | oitc reset_password / roles / acl.aco_sync | 口令重置、角色授权、权限树同步 |
| 数据导出 | oitc dump | 配置对象批量导出 PHP 文件 |
| 健康与版本 | oitc system_health / version_check / statusengine_version | 状态自检 |
| 外部命令 | oitc cmd | 向引擎命令管道投递 |
| 周边工具 | gearadmin / naemon -v / check_* -V / mysql --defaults-file | 队列、校验、插件、数据库 |
三、前置条件
# 全栈在跑（按《openITCOCKPIT Docker Compose 部署指南》一文部署完成后）
docker compose ps --format '{{.Name}}\t{{.Status}}' | grep -c Up
17
# 进入平台容器
docker compose exec openitcockpit bash
which oitc
/usr/bin/oitc
四、各工具详解
4.1 oitc nagios_export —— 监控配置导出
把数据库中的主机/服务/命令等对象渲染成 Naemon 配置目录。参数实测（oitc nagios_export --help）：
Usage:
cake nagios_export [-h] [-q] [--resource] [-v] [--verify]
--resource Only write the file /opt/openitc/nagios/etc/resource.cfg
--verify Verify Nagios/Naemon configuration files and exit.
执行导出（实测回显）：
oitc nagios_export -v
Generating new monitoring configuration. This could take awhile...
Monitoring configuration successfully generated.
Execute "systemctl reload naemon" to load the new configuration
产物目录结构（实测 ls /opt/openitc/nagios/etc/config/，15 个子目录）：
commands hostdependencies hostgroups servicetemplates
contactgroups hostescalations hosts timeperiods
contacts hosttemplates services
defaults servicedependencies serviceescalations servicegroups
对象文件示例（实测 cat config/hosts/hosts_minified.cfg 节选）——默认启用 minified 模式（nagios.php export.minified=true），全部主机压缩进单文件：
;#########################################################################
;# DO NOT EDIT THIS FILE BY HAND -- YOUR CHANGES WILL BE OVERWRITTEN #
;# File generated by openITCOCKPIT #
;#########################################################################
define host{
use efbee68c-cf48-4b78-83f5-c856c56177f0
host_name c36b8048-93ce-4385-ac19-ab5c90574b77
display_name default host
address 127.0.0.1
}
（对象名使用 UUID 是 openITCOCKPIT 的固有设计：Web 端改名不影响引擎对象标识，display_name 才是展示名。）
Docker 形态注意：--verify 在 openitcockpit 容器内不可用（实测回显）：
oitc nagios_export --verify
Verifying monitoring configuration files, please standby...
sudo: /opt/openitc/nagios/bin/nagios: command not found
2026-11-01 09:05:21 error: Error with Naemon / Nagios configuration! Verification failed!
原因：校验器调用引擎二进制，而引擎在独立服务容器。正确校验位置见 4.10 节 naemon -v。
4.2 oitc config_generator —— 平台配置再生成
环境变量 → config/*.php 的渲染器（模板在 src/config_templates/config/*.tpl，占位符 {{address}} 式替换）。参数实测（--help 仅 -h/-q/-v 三项）。执行回显：
oitc config_generator -v
Check for pending configuration files...
Ok
（Ok = 无待更新文件，幂等。）该命令由内置 cronjob 每 1 分钟自动执行，手工触发场景：改完 openitcockpit.env 重建服务后想立即确认渲染结果，或直接 cat /opt/openitc/frontend/config/gearman.php 核对。
4.3 oitc supervisor —— 跨容器进程管控
官方文档「Restarting services」指定的运维入口：从 openitcockpit 容器管控其他容器的 supervisor 进程。参数实测（oitc supervisor --help）：
Usage:
cake supervisor [-h] [-q] [-v] <start|stop|restart|status> <oitc_cmd|gearman_worker|event-collectd|openitcockpit-websocket|prometheus_bridge|customalert_worker|naemon|prometheus|nsta|statusengine|openitcockpit-node|nginx|php-fpm|snmptrapd|snmptt>
（可选服务名 14 个，覆盖引擎、worker、websocket、图表桥等。）实测：
oitc supervisor status naemon
Service naemon is running. pid 53, uptime 0:17:56
官方示例集：oitc supervisor restart nginx、oitc supervisor stop nginx、oitc supervisor start nginx。
4.4 oitc cronjobs —— 内置定时任务
参数实测（--help）：-f 全部强制执行、-l 列出、-t <Task> 单跑指定任务。列表实测（节选）：
oitc cronjobs -l
+---------------------------------+------------------+----------+---------------------+
| Task | Plugin | Interval | Last scheduled |
+---------------------------------+------------------+----------+---------------------+
| CleanupTemp | Core | 10 | 2026-11-01 09:04:01 |
| DatabaseCleanup | Core | 1440 | 2026-11-01 08:44:01 |
| RecurringDowntimes | Core | 10 | 2026-11-01 09:05:01 |
| CpuLoad | Core | 15 | 2026-11-01 09:00:01 |
| VersionCheck | Core | 1440 | 2026-11-01 08:44:02 |
| SystemHealth | Core | 1 | 2026-11-01 09:06:01 |
| SystemMetrics | Core | 240 | 2026-11-01 08:44:04 |
| ConfigGenerator | Core | 1 | 2026-11-01 09:06:01 |
| AgentSoftwareInventory | Core | 60 | 2026-11-01 08:44:04 |
| LdapUserImport | Core | 1440 | n/a |
| Autoreport | AutoreportModule | 720 | 2026-11-01 08:44:04 |
| GrafanaDashboard | GrafanaModule | 720 | 2026-11-01 08:44:04 |
+---------------------------------+------------------+----------+---------------------+
（Interval 单位分钟；LdapUserImport 未启用显示 ✗，模块任务以 Plugin 列区分。）
4.5 账号与权限：reset_password / roles / acl.aco_sync
oitc reset_password——管理员口令丢失的官方解法（实测用法）：
oitc reset_password 1 --print --no-mail --enable
（参数：用户 id=1、--print 直接打印新随机口令、--no-mail 不发邮件、--enable 顺带启用被锁账号。实测打印出 8 位随机口令后可立即登录 Web UI；《openITCOCKPIT Docker Compose 部署指南》第十一节问题 2 即用它解 OITC_ADMIN_PASSWORD 未生效困局。）
oitc roles——角色默认权限修复，参数实测（--help）：
Usage:
cake roles [--admin] [--enable-defaults] [-h] [-q] [-v]
--admin Restore all default user role permissions for "Administrator" role
--enable-defaults Re-Enables all default permissions of pre defined user groups
(Viewer) and keeps custom changes. (Excluding "Administrator")
平台升级脚本（UPGRADE.sh）初始化权限的正解即两连（实测源码行）：
oitc acl.aco_sync
oitc roles --enable-defaults --admin
oitc acl.aco_sync——全量同步 ACO 权限树（创建缺失 controller/action 节点、清除孤儿节点）。实测权限数据分布：acos 表 939 个节点（root=controllers）、aros 表用户组节点、aros_acos 表 1131 条授权——排障时若 API 大面积 403「Identity is not authorized」，先跑这两条命令修复角色授权，而不是误判 ACO 树丢失（实测 oitc aco_update 输出同样指向 acos 独立表，勿混淆）。
4.6 oitc dump —— 配置对象批量导出
参数实测（--help，13 个导出维度）：--all --commands --contacts --container --cronjobs --hosts --hosttemplates --macros --services --servicetemplates --systemsettings --timeperiods --usergroups。实测执行：
oitc dump --hosts
Dumping data to: /tmp/dump_hosts.php Done
（产物为 PHP 数组文件，可用于跨环境迁移比对或审计。）
4.7 健康与版本：system_health / version_check / statusengine_version
oitc system_health
Fetch system health information... Ok
oitc version_check
Checking for new openITCOCKPIT Version Ok
oitc statusengine_version
Statusengine4
（system_health 对应 Web UI「System health」页与 SYSTEM_HEALTH 设置段；version_check 即 VersionCheck cronjob 的手动触发；statusengine_version 打印当前状态后端实现。）
4.8 oitc cmd —— 引擎外部命令管道
向 Naemon 的 nagios.cmd/oitc.cmd 投递外部命令（禁用检查、排程 downtimes 等），参数实测（--help）：
Usage:
cake cmd [-h] [-p /opt/openitc/nagios/var/rw/oitc.cmd] [-q] [-v]
--pipe, -p Path of the oitc.cmd (default: /opt/openitc/nagios/var/rw/oitc.cmd)
（该命令即 supervisor 服务列表中的 oitc_cmd 常驻进程，负责消费管道。）
4.9 数据库入口：mysql --defaults-file
官方排障标准入口（免密进 openitcockpit 库）：
mysql --defaults-file=/opt/openitc/etc/mysql/mysql.cnf
凭据文件由服务启动脚本按环境变量生成（[client] 段 host/user/password/port/database），详见配置篇 §5.1；注意 mysqladmin 对该文件兼容性的坑（部署篇问题 1）。
4.10 周边工具实测
gearadmin（Gearman 队列）——官方「Query Gearman status」入口，在 openitcockpit 容器执行：
gearadmin --status -h gearmand
statusngin_cmd 0 0 1
oitc_gearman 0 0 5
eventhandler 0 0 5
notification 0 0 5
service 0 0 5
host 0 0 5
.
（列义：队列名 / 运行中 / 等待中 / worker 槽位数；自定义地址用 -h $OITC_GEARMAN_ADDRESS。）
naemon -v（引擎配置校验）——必须在 naemon 容器内以 nagios 用户执行（root 被拒：ERROR: do not start naemon as root user.）：
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
（引擎实际加载的主配置是 /opt/openitc/etc/nagios/nagios.cfg，其 cfg_dir=/opt/openitc/nagios/etc/config 引入 Web 导出对象。）
monitoring-plugins（检查插件集）——位于 mod_gearman_worker 容器 /opt/openitc/nagios/libexec/（实测 100+ 插件：check_apt/check_by_ssh/check_curl/check_disk/check_dns/check_http/check_icmp/check_ldap/check_load…），版本实测：
/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)
（注意 libexec 不在默认 PATH，须全路径调用；自研插件的容器化挂载方法见官方「Install your own monitoring plugins → Containerized method」。）
五、注意事项
- 执行位置分层：
oitc只在 openitcockpit 容器；naemon二进制只在 naemon 容器；check_*插件在 mod_gearman_worker 容器——跨层调用（如nagios_export --verify）必然失败，属形态差异而非故障。 - oitc 的权限模型：以 root + www-data 组、umask 002 执行，产物组可写，Web 进程才能覆写；用其他用户（如
docker exec -u指定）跑 oitc 生成的文件可能锁死 Web 覆写能力。 - 配置类命令幂等：config_generator/nagios_export 重复执行安全，可放外部 cron/CI；但导出后引擎不会自动 reload，需
oitc supervisor restart naemon或 Web UI 触发 rollout。 oitc wipe/cache clear_all等破坏性命令：wipe 清空监控数据、cache clear 影响响应速度，生产慎用，执行前先--help确认参数。
六、常见问题
Q1：naemon 容器里执行 oitc 报 command not found？
设计如此：oitc 属平台侧命令（CakePHP console），引擎容器无 PHP 应用。进 openitcockpit 容器执行（docker compose exec openitcockpit bash）。
Q2：naemon -v 报 ERROR: do not start naemon as root user.？
引擎二进制拒绝 root 校验，切 nagios 用户：su nagios -c '/opt/openitc/nagios/bin/naemon -v /opt/openitc/etc/nagios/nagios.cfg'（实测通过，见 4.10）。
Q3：check_http -V 报 not found？
插件目录 /opt/openitc/nagios/libexec 不在 PATH，用全路径调用；worker 执行检查时由 mod_gearman 以 $USER1$ 宏（resource.cfg 实测 $USER1$=/opt/openitc/nagios/libexec）解析，无需 PATH。
Q4：oitc nagios_export 成功但界面状态不更新？
导出只写配置文件，引擎加载需 reload：oitc supervisor restart naemon（实测 status 回显 uptime 归零即生效）；Web UI 上对应「Deploy」动作。
七、参考链接
- 官方文档 Troubleshooting/Query Gearman status/Restarting services/Install your own monitoring plugins 章节（docs.openitcockpit.io，查询日期 2026-11-01）
- Naemon 外部命令手册：naemon.org/documentation
- monitoring-plugins 插件清单：monitoring-plugins.org
- 本专栏：《openITCOCKPIT 介绍与选型指南》《openITCOCKPIT Docker Compose 部署指南》《openITCOCKPIT 5.9.0 配置参数详解》；引擎背景《Naemon 介绍与选型指南》