Zoneminder 1.38.6 常用 CLI 命令与工具详解
ZoneMinder 1.38.6 全部 24 个 CLI 命令行工具详解:zmu/zmpkg/zmdc/zmaudit/zmupdate/zmvideo 等核心工具逐参数实测(强制告警、服务级启停链、守护进程管理),zmdc 分参语法三态对照、zmu double-free quirk、zmupdate 常驻行为等踩坑实录,24 工具分组全景与守护进程族职责表(2026-10-30 实测)。
Zoneminder 1.38.6 常用 CLI 命令与工具详解
目标:盘点 ZoneMinder 1.38.6 安装后落在 /usr/bin 下的全部 24 个命令行工具,讲清每个工具「管什么、怎么调、什么场景用」,对日常运维必用的 zmu、zmpkg.pl、zmdc.pl、zmaudit.pl、zmupdate.pl、zmvideo.pl 等逐参数给出实测命令与回显,并沉淀 zmdc 分参语法、zmu 崩溃 quirk、zmupdate 常驻行为等实测踩坑记录。全部命令与回显已在 Ubuntu 22.04 + ZoneMinder 1.38.6 环境逐条实测通过。
一、环境信息
本篇全部命令与回显在下列实测环境中逐条跑出(2026-10-30),部署过程见《Zoneminder 1.38.6 Docker Compose 部署指南》,参数体系见《Zoneminder 1.38.6 配置参数详解》:
| 项目 | 值 |
|---|---|
| 操作系统 | Ubuntu 22.04(Linux x86_64,6 核 CPU / 19GB 内存) |
| ZoneMinder | 1.38.6(Web 控制台与守护进程同机) |
| 数据库 | MariaDB 11.8(库名 zm) |
| Web 控制台端口 | 8140 |
| 工具目录 | /usr/bin(均在 PATH 内) |
| 配置文件 | /etc/zm/zm.conf + /etc/zm/conf.d/*.conf |
| 日志目录 | /var/log/zm/ |
| Web 账号 | admin / q1w2e3r4(System 权限,已开启认证) |
| 实测监控 | Monitor 1「Cam1」(Ffmpeg 源 rtsp://…:8554/cam1,768x432,Modect) |
说明:本篇各小节回显来自多次实测会话,守护进程的
running since、pid、事件编号等时间性字段各自对应当时的真实现场,读者复现时数值不同属正常。
二、工具概览
ZoneMinder 1.38.6 安装后共 24 个命令行工具。命名有两类约定:.pl 结尾是 Perl 脚本;无后缀(zmu、zmc、zms、zm_rtsp_server)或短横线命名(zm-version、zm-healthcheck)为编译二进制。按用途分七组:
| 分组 | 工具 | 用途 |
|---|---|---|
| 服务总控 | zmpkg.pl | 全部守护进程的 start/stop/restart/status(服务级开关) |
| 服务总控 | zmdc.pl | 单个守护进程的 start/stop/restart/status(守护级细控) |
| 服务总控 | zmsystemctl.pl | 在 systemd 系统上包装 systemctl 管理 zoneminder 服务 |
| 服务总控 | zm-version、zm-healthcheck | 打印版本信息 / 输出健康状态词(healthy) |
| 状态与控制 | zmu | 单个监控的状态查询与控制(查帧率/索引、强制告警/取消) |
| 状态与对账 | zmaudit.pl | 数据库与磁盘文件一致性对账清理 |
| 状态与对账 | zmrecover.pl | 从崩溃残留中恢复事件记录 |
| 状态与对账 | zmeventtool.pl | 单事件维护(补关闭记录、删帧图) |
| 版本与升级 | zmupdate.pl | 版本检查、数据库结构升级、事件迁移 |
| 事件处理 | zmfilter.pl | 执行已保存的过滤器(邮件/删除/上传联动) |
| 事件处理 | zmvideo.pl | 把事件帧图合成为视频文件 |
| 事件处理 | zmtrigger.pl | 外部事件触发接入(socket/文件/串口) |
| 云台与硬件 | zmcontrol.pl | 向云台控制模块下发指令 |
| 云台与硬件 | zmtrack.pl | 命令监控跟踪运动目标 |
| 云台与硬件 | zmcamtool.pl | 摄像头控制与预置位的导入/导出 |
| 云台与硬件 | zmx10.pl | X10 家电控制联动 |
| 流与协议 | zmc | 采集守护(每监控一个实例,从摄像头拉流取帧) |
| 流与协议 | zms | Web 实时流输出(nph-zms CGI 由它承载) |
| 流与协议 | zm_rtsp_server | 把监控流重新以 RTSP 对外发布 |
| 流与协议 | zmonvif-probe.pl、zmonvif-trigger.pl | ONVIF 设备探测(profiles/metadata/move/events)与事件触发 |
| 后台守护 | zmwatch.pl | 巡检采集守护是否卡死并自动重启 |
| 后台守护 | zmstats.pl | 周期性落库运行统计 |
| 后台守护 | zmtelemetry.pl | 匿名使用数据上报(受 ZM_TELEMETRY_DATA 控制) |
| 后台守护 | zmfilter.pl --daemon、zmupdate.pl -c | 同一工具的常驻形态(见 4.6、4.5 节) |
后台守护(zmc/zms/zmwatch.pl 等)由 zmdc.pl 托管、不手工直跑(见 4.13 节);日常运维真正高频敲的是 zmu、zmpkg.pl、zmdc.pl、zmaudit.pl 四件套。
三、前置条件
- ZoneMinder 1.38.6 已部署且守护进程在跑(
zmpkg.pl status返回running,见 4.2 节)。 - 以服务器上的系统用户执行(root 或具备读取 /etc/zm 权限的用户)。工具都在 /usr/bin 下,无需额外配 PATH。
- 认证已开启时 zmu 必须带凭据:
-U admin -P q1w2e3r4,或改传-T <JWT>/-A <auth hash>(见 4.1 节认证参数表)。凭据错误时 zmu 查询无输出。 - 涉及数据库结构变更的命令(zmupdate.pl 升级形态)执行前先备份(
zmaudit.pl -r先做一次对账确认基线)。
四、各工具详解
4.1 zmu —— 监控状态查询与控制
zmu 是单监控粒度的「瑞士军刀」:只读查询(状态/帧率/索引/完整配置)与主动控制(强制告警/挂起/恢复)都从这里进。帮助全文如下:
zmu -h
zmu <-d device_path> [-v] [function] [-U<username> -P<password>]
zmu <-m monitor_id> [-v] [function] [-U<username> -P<password>]
General options:
-h, --help : This screen
-v, --verbose : Produce more verbose output
-l, --list : List the current status of active (or all with -v) monitors
Options for use with devices:
-d, --device [device_path] : Get the current video device settings for [device_path] or all devices
-V, --version <V4L version> : Set the Video 4 Linux API version to use for the query, use 1 or 2
-q, --query : Query the current settings for the device
Options for use with monitors:
-m, --monitor <monitor_id> : Specify which monitor to address, default 1 if absent
-q, --query : Query the current settings for the monitor
-s, --state : Output the current monitor state, 0 = idle, 1 = prealarm, 2 = alarm,
3 = alert, 4 = tape
-j, --janus-pin : Output the pin, if set, used to secure Janus for this monitor
-B, --brightness [value] : Output the current brightness, set to value if given
-C, --contrast [value] : Output the current contrast, set to value if given
-H, --hue [value] : Output the current hue, set to value if given
-O, --colour [value] : Output the current colour, set to value if given
-i, --image [image_index] : Write captured image to disk as <monitor_name>.jpg, last image captured
or specified ring buffer index if given.
-S, --scale <scale_%%ge> : With --image specify any scaling (in %%) to be applied to the image
-t, --timestamp [image_index] : Output captured image timestamp, last image captured or specified
ring buffer index if given
-R, --read_index : Output ring buffer read index
-W, --write_index : Output ring buffer write index
-e, --event : Output last event index
-f, --fps : Output last Frames Per Second captured reading
-z, --zones : Write last captured image overlaid with zones to <monitor_name>-Zones.jpg
-a, --alarm : Force alarm in monitor, this will trigger recording until cancelled with -c
-n, --noalarm : Force no alarms in monitor, this will prevent alarms until cancelled with -c
-c, --cancel : Cancel a forced alarm/noalarm in monitor, required after being enabled with -a or -n
-L, --reload : Signal monitor to reload settings
-E, --enable : Enable capture, wake monitor up
-D, --disable : Disable capture, put monitor to sleep
-u, --suspend : Suspend motion detection, useful to prevent bogus alarms when panning etc
-r, --resume : Resume motion detection after a suspend
-U, --username <username> : When running in authenticated mode the username and
-P, --password <password> : password combination of the given user
-A, --auth <authentication> : Pass authentication hash string instead of user details
-T, --token <token> : Pass JWT token string instead of user details
-x, --xtrigger : Output the current monitor trigger state, 0 = not triggered, 1 = triggered
认证参数三种形态(开启认证后 -U/-P 必带):
| 参数 | 形态 | 说明 |
|---|---|---|
| -U / -P | zmu … -U admin -P q1w2e3r4 | 用户名密码(本篇统一用此形态) |
| -T | zmu … -T <JWT> | 传 API 登录签发的 JWT 令牌 |
| -A | zmu … -A <auth hash> | 传 API 返回的 credentials auth 哈希串 |
清单与状态查询(实测)。 一次连续实测会话的完整回显(当时监控处于告警收尾态):
zmu -l -U admin -P q1w2e3r4
Id Capturing Analysing Recording State TrgState LastImageTime RdIdx WrIdx LastEvent FrameRate
1 3 2 2 3 0 1793330143.22 711 0 9 9.99
| 列 | 含义 |
|---|---|
| Id / State / TrgState | 监控 ID / 运行状态(0=idle 1=prealarm 2=alarm 3=alert 4=tape)/ 外部触发态 |
| Capturing / Analysing / Recording | 三项功能编码(1=None 2=Always 3=OnMotion) |
| LastImageTime | 最近一帧的 Unix 时间戳 |
| RdIdx / WrIdx | 环形缓冲读/写索引 |
| LastEvent | 最近事件 ID |
| FrameRate | 最近帧率读数 |
逐项查询同一监控(-m 1 指定监控,可省略则默认 1):
zmu -m 1 -s -U admin -P q1w2e3r4
3
zmu -m 1 -f -U admin -P q1w2e3r4
capture: 9.99, analysis: 9.99
zmu -m 1 -e -U admin -P q1w2e3r4
9
zmu -m 1 -t -U admin -P q1w2e3r4
1793330147.42
zmu -m 1 -R -U admin -P q1w2e3r4
720
zmu -m 1 -W -U admin -P q1w2e3r4
0
zmu -m 1 -x -U admin -P q1w2e3r4
0
(-s 状态 3=alert、-f 采集/分析双帧率 9.99、-e 最近事件 9、-t 最近帧时间戳、-R 读索引 720、-W 写索引 0、-x 未触发 0,全部与 -l 清单行互为印证。)
完整配置查询(实测,输出较长,全文照抄)。 -q 打印监控与全部 Zone 配置,是核对 API 建库结果最快的手段:
zmu -m 1 -q -U admin -P q1w2e3r4
Id : 1
Name : Cam1
Type : File
Path : rtsp://mediamtx:8554/cam1
Width : 768
Height : 432
Colours : 3
Subpixel Order : 6
Event Prefix : Event-
Label Format :
Label Coord : 0,0
Label Size : 1
Image Buffer Count : 3
Warmup Count : 0
Pre Event Count : 10
Post Event Count : 10
Stream Replay Buffer : 0
Alarm Frame Count : 1
Section Length : 600
Min Section Length : 10
Maximum FPS : 10.00
Alarm Maximum FPS : 10.00
Reference Blend %ge : 6
Alarm Reference Blend %ge : 6
Track Motion : 0
Capturing 3 - Always
Analysing 2 - Always
Recording 2 - On motion
Zones : 1
Id : 1
Label : All
Type: 1 - Active
Shape : 4 points
0: 0,0
1: 767,0
2: 767,431
3: 0,431
Alarm RGB : 000000
Check Method: 1 - Alarmed Pixels
Min Pixel Threshold : 10
Max Pixel Threshold : 180
Min Alarm Pixels : 1
Max Alarm Pixels : 75
Filter Box : 3,3
Min Filter Pixels : 0
Max Filter Pixels : 0
Min Blob Pixels : 10
Max Blob Pixels : 0
Min Blobs : 1
Max Blobs : 0
Capturing Enabled? enabled
Motion Detection Enabled? enabled
Recording Enabled? enabled
Events Enabled (!TRIGGER_OFF)? enabled
⚠️ 注意:
Type : File一行是 zmu 对 Ffmpeg 源监控的显示 quirk(Path 实为 rtsp://),以 Web 控制台或 API 查到的 Type=Ffmpeg 为准;Recording 2 - On motion则如实反映该监控已按部署篇修正为移动侦测录像。
主动控制(实测)。 强制告警 -a 触发一次告警录制并返回事件号,-c 取消:
zmu -m 1 -a -U admin -P q1w2e3r4
Alarmed event id: 9
zmu -m 1 -c -U admin -P q1w2e3r4
(无输出,exit 0。取消后状态会以 alert 短暂收尾,-s 由 2 逐渐回到 1/0。若调用时监控尚未开出事件,-a 会返回 Alarmed event id: 0,事件在随后一两秒内落库,属正常时序。)
云台操作前的防误报挂起 -u 与恢复 -r(实测均无输出、exit 0,-s 状态保持 1=idle):
zmu -m 1 -u -U admin -P q1w2e3r4
(无输出,exit 0。)
zmu -m 1 -r -U admin -P q1w2e3r4
(无输出,exit 0。挂起最长受 ZM_MAX_SUSPEND_TIME(默认 30 秒)保护自动恢复,见《Zoneminder 1.38.6 配置参数详解》5.3 节。)
其余参数速查(语义来自 -h 原文):-B/-C/-H/-O [值] 读取或设置亮度/对比度/色调/色彩;-i [索引] 把环形缓冲帧写成 <监控名>.jpg(可配 -S 缩放百分比);-z 输出带 Zone 框叠加的截图;-L 通知监控重载配置;-E/-D 唤醒/休眠采集;-n 强制无告警(同 -a 需 -c 解除);-d [设备路径] 查询 V4L 设备参数(配 -V 1|2 指定 V4L 版本,本篇 Ffmpeg 源不适用);-j 输出 Janus 鉴权 pin;-v 是 verbose 增输出而非打印版本。
4.2 zmpkg.pl —— 服务级总控
zmpkg 管「整套守护进程」的启停,等价于 Web 控制台的 start/stop/restart 按钮。无参数时打印用法:
zmpkg.pl
Usage:
zmpkg.pl {start|stop|restart|status|logrot|state|version}
子命令逐个实测:
zmpkg.pl status
running
zmpkg.pl version
1.38.6
stop/start 全链路(实测)。 stop 无输出,停掉后 zmdc 通信 socket 一并消失:
zmpkg.pl stop
(无输出,exit 0。)
zmdc.pl status
Unable to connect to server using socket at /run/zm/zmdc.sock
(exit 255——zmdc 的管理套接字随守护全停而关闭,此报错即「已全停」的确证。Web 控制台此时仍可打开,但监控流与事件分析全部停止。)
zmpkg.pl start
(无输出,exit 0。)
zmdc.pl status
'zmc -m 1' running since 26/10/30 13:30:07, pid = 3580, valid
'zmfilter.pl --filter_id=1 --daemon' running since 26/10/30 13:30:07, pid = 3586, valid
'zmfilter.pl --filter_id=2 --daemon' running since 26/10/30 13:30:07, pid = 3592, valid
'zmwatch.pl' running since 26/10/30 13:30:07, pid = 3598, valid
'zmupdate.pl -c' running since 26/10/30 13:30:07, pid = 3604, valid
'zmtelemetry.pl' running since 26/10/30 13:30:07, pid = 3609, valid
'zmstats.pl' running since 26/10/30 13:30:07, pid = 3615, valid
zmpkg.pl restart
(无输出,exit 0——等效于 stop+start,重启后 zmdc.pl status 的 running since 整体刷新为重启时刻,验证方式同上。)
子命令速查:logrot 轮转日志(通常由系统 cron 调用);state 子命令需带状态参数,不带参数只回显 usage(实测即上文 usage 原文)。
4.3 zmdc.pl —— 守护级控制(分参语法是第一坑)
zmdc 是 zmpkg 背后的守护控制器,管单个进程。无参数打印用法:
zmdc.pl
No command given
Usage:
zmdc.pl {command} [daemon [options]]
Options:
{command} - One of 'startup|shutdown|status|check|logrot' or
'start|stop|restart|reload|version'. [daemon [options]] - Daemon name
and options, required for second group of commands
status 全景(实测)。
zmdc.pl status
'zmc -m 1' running since 26/10/30 13:30:07, pid = 3580, valid
'zmfilter.pl --filter_id=1 --daemon' running since 26/10/30 13:30:07, pid = 3586, valid
'zmfilter.pl --filter_id=2 --daemon' running since 26/10/30 13:30:07, pid = 3592, valid
'zmwatch.pl' running since 26/10/30 13:30:07, pid = 3598, valid
'zmupdate.pl -c' running since 26/10/30 13:30:07, pid = 3604, valid
'zmtelemetry.pl' running since 26/10/30 13:30:07, pid = 3609, valid
'zmstats.pl' running since 26/10/30 13:30:07, pid = 3615, valid
单查某个守护时守护名与参数必须拆开传——zmc -m 1 是「守护名 zmc + 参数 -m 1」两个词:
zmdc.pl status zmc -m 1
'zmc -m 1' running since 26/10/30 12:33:44, pid = 1502
zmdc.pl version
1.38.6
restart 的三种写法(三种结果,全部实测)。
写法一:不指定守护——报 usage:
zmdc.pl restart
No daemon given
Usage:
zmdc.pl {command} [daemon [options]]
Options:
{command} - One of 'startup|shutdown|status|check|logrot' or
'start|stop|restart|reload|version'. [daemon [options]] - Daemon name
and options, required for second group of commands
写法二:把「zmc -m 1」整串加引号当成一个词——判定为非法守护名:
zmdc.pl restart "zmc -m 1"
Invalid daemon 'zmc -m 1' specifiedUsage:
zmdc.pl {command} [daemon [options]]
Options:
{command} - One of 'startup|shutdown|status|check|logrot' or
'start|stop|restart|reload|version'. [daemon [options]] - Daemon name
and options, required for second group of commands
(exit 255;Invalid daemon 'zmc -m 1' specified 与 Usage 之间无换行,原样照抄。)
写法三(正确):守护名与参数分参——输出重启动作并自动拉起新实例:
zmdc.pl restart zmc -m 1
Restarting zmc -m 1
'zmc -m 1' sending stop to pid 3580 at 26/10/30 13:30:08
(exit 0。随后 zmdc 日志完整记录了「stop → 正常退出 → 重新拉起」生命周期,见 4.13 节 zmdc.log 节选。)
其余子命令:start|stop <守护> [参数] 单启单停,用法与 restart 相同的分参规则;startup|shutdown 由 zmpkg 内部调用(整组拉起/收回);check 校验守护配置一致性;logrot 通知守护重开日志文件;reload 让守护重载配置。
4.4 zmaudit.pl —— 数据库与磁盘对账
zmaudit 核对 Config 外的 Events/Frames 记录与磁盘文件是否一致,清理孤儿。--help 不被识别但仍给出用法(Unknown option: help 是该工具族的固定行为):
zmaudit.pl --help
Unknown option: help
Usage:
zmaudit.pl [-r,-report|-i,-interactive]
Options:
-c, --continuous - Run continuously
-f, --force - Run even if pid file exists
-i, --interactive - Ask before applying any changes
-m, --monitor_id - Only consider the given monitor
-r, --report - Just report don't actually do anything
-s, --storage_id - Specify a storage area to audit instead of all
-v, --version - Print the installed version of ZoneMinder
报告模式(只读统计,不动数据)与无参直接执行(按守护默认间隔也会自动跑,这里手工触发)的实测回显一致:
zmaudit.pl -r
Deleted 0 log table entries by time
Finished updating TotalEvents, ArchivedEvents
Finished updating HourEvents
Finished updating DayEvents
Finished updating WeekEvents
Finished updating MonthEvents
Finished updating Storage DiskSpace
(7 行统计全部 0/Finished——库与磁盘一致,Storage 磁盘占用已刷新。交互模式 -i 会在每次改动前询问,适合人工核对后清理。)
4.5 zmupdate.pl —— 版本检查与升级
版本检查与数据库结构升级的统一入口。--help 同样回 Unknown option: help + 用法:
zmupdate.pl --help
Unknown option: help
Usage:
zmupdate.pl -c,--check | -f,--freshen | -v<version>,--version=<version>
[-u <dbuser> -p <dbpass>]
Options:
-c, --check - Check for updated versions of ZoneMinder.
If not interactive zmupdate.pl will stay running, checking every hour.
If interactive will try once, print out result and quit.
-f, --freshen - Freshen the configuration in the database. Equivalent of old zmconfig.pl -noi
--migrate-events - Update database structures as per USE_DEEP_STORAGE setting.
-v <version>, --version=<version> - Force upgrade to the current version from <version>
-u <dbuser>, --user=<dbuser> - Alternate DB user with privileges to alter DB
-p <dbpass>, --pass=<dbpass> - Password of alternate DB user with privileges to alter DB
-s, --super - Use system maintenance account on debian based systems instead of unprivileged account
-d <dir>, --dir=<dir> - Directory containing update files if not in default build location
-interactive - interact with the user
-nointeractive - do not interact with the user
两个实测行为务必记牢:
-c在非交互(无终端)环境下会常驻不退出——按 Help 原文「stay running, checking every hour」每小时检查一次。本篇采集时用管道方式调用-c,命令长时间不返回,Ctrl+C 结束。日常手工检查请直接在交互终端跑zmupdate.pl -c(跑一次即退出),或让守护常驻形态干这活(zmdc.pl status里的'zmupdate.pl -c'进程就是它)。-v是「从指定版本升级」的参数,不是打印版本。zmupdate.pl --version会报错(实测回显):
zmupdate.pl --version
Option version requires an argument
Usage:
zmupdate.pl -c,--check | -f,--freshen | -v<version>,--version=<version>
[-u <dbuser> -p <dbpass>]
打印版本用 zm-version(4.11 节)。升级场景(如从 1.38.5 升 1.38.6)才用 -v 1.38.5,执行前务必先做数据库备份;--migrate-events 专门服务于 ZM_USE_DEEP_STORAGE 迁移(该参数严禁随意执行,见《Zoneminder 1.38.6 配置参数详解》Q9)。
4.6 zmfilter.pl —— 过滤器执行
过滤器(Web 端 Filter 页定义,可做自动删除/邮件/上传)的命令行执行器:
zmfilter.pl --help
Unknown option: help
Usage:
zmfilter.pl [-f <filter name>,--filter=<filter name>]
[--filter_id=<filter id>] [--daemon] | -v, --version
Options:
-f{filter name}, --filter={filter name} - The name of a specific filter to run
--filter_id={filter id} - The id of a specific filter to run
--daemon - Causes zmfilter.pl to stay running endlessly repeating the filter(s).
-v, --version - Print ZoneMinder version
zmfilter.pl -v
1.38.6
-f <名称> 立即执行一次指定过滤器;--filter_id=<id> 按数据库 ID 执行;--daemon 是常驻形态——zmdc.pl status 里按过滤器数量拉起的 'zmfilter.pl --filter_id=1 --daemon'、'zmfilter.pl --filter_id=2 --daemon' 两个进程即由它而来(执行节奏受 ZM_FILTER_EXECUTE_INTERVAL 控制,默认 60 秒)。
4.7 zmvideo.pl —— 事件视频生成
把事件帧图用 ffmpeg 合成视频文件(格式受 ZM_FFMPEG_FORMATS 白名单约束):
zmvideo.pl --help
Unknown option: help
Usage:
zmvideo.pl [ -e <event_id>,--event=<event_id> | --filter_name=<filter name> | --filter_id=<filter id> ]
[--concat=filename]
[--format <format>]
[--rate=<rate>]
[--scale=<scale>]
[--fps=<fps>]
[--size=<size>]
[--overwrite]
对部署篇创建的 3 号事件(Forced Web,64 帧)实际生成 mp4 的实测回显:
zmvideo.pl -e 3 --format mp4 --overwrite
Use of uninitialized value $transforms in split at /usr/share/perl5/ZoneMinder/Event.pm line 305.
/var/cache/zoneminder/events/1/2026-10-30/3/Event-3-r1-s1.mp4
(第一行是 Perl 对空置变换字段的提示性警告,不影响产物;第二行即生成文件在事件目录中的落盘路径,--overwrite 允许覆盖同名文件。不带 --overwrite 且文件已存在时会跳过生成。)
4.8 zmeventtool.pl 与 zmrecover.pl —— 事件维护与恢复
zmeventtool.pl 面向单个事件做修复性操作,帮助全文(自带 --help 支持):
zmeventtool.pl --help
Usage:
zmeventtool.pl [--user=<dbuser> --pass=<dbpass>] command [list of event ids]
Options:
close - Update event record after a crash
deletejpegs - Deletes all jpegs from the event directory
deleteanalysisjpegs - Deletes the analysis jpegs from the event directory
--help - Print usage information.
--user=<dbuser> - Alternate dB user with privileges to alter dB.
--pass=<dbpass> - Password of alternate DB user with privileges to alter DB.
--version - Print version.
典型场景:监控进程崩溃导致事件没有正常关闭记录时,zmeventtool.pl close <事件ID> 补写记录;磁盘紧张时 deletejpegs 只删帧图保留 mp4。
zmrecover.pl 从崩溃残留中恢复丢失的事件记录。它的 --help 也回 Unknown option + 用法:
zmrecover.pl --help
Unknown option: help
Usage:
zmrecover.pl [-r,-report|-i,-interactive]
Options:
-i, --interactive - Ask before applying any changes
-m, --monitor_id - Only consider the given monitor
-r, --report - Just report don't actually do anything
-s, --storage_id - Specify a storage area to recover instead of all
-v, --version - Print the installed version of ZoneMinder
实测一个 quirk:按 usage 只传 -r 单参数,本版本会报「只允许一个选项」并把 usage 打出来(exit 0):
zmrecover.pl -r
Error, only one option may be specified
Usage:
zmrecover.pl [-r,-report|-i,-interactive]
Options:
-i, --interactive - Ask before applying any changes
-m, --monitor_id - Only consider the given monitor
-r, --report - Just report don't actually do anything
-s, --storage_id - Specify a storage area to recover instead of all
-v, --version - Print the installed version of ZoneMinder
(不影响常规使用:日常对账交给 zmaudit.pl,zmrecover 留给「事件记录缺失」的定向恢复场景,配合 -m <监控ID> 限定范围。)
4.9 云台与摄像头工具(zmcontrol.pl / zmtrack.pl / zmcamtool.pl)
三者服务于「可控摄像头」(PTZ 云台):zmcontrol 下发单条控制指令、zmtrack 驱动监控跟随运动目标、zmcamtool 管理控制能力与预置位数据库。帮助全文实测:
zmcontrol.pl --help
Unknown option: help
Usage:
zmcontrol.pl --id {monitor_id} [--command={command}] [various options]
zmcontrol.pl --protocol {module} --address {addr} [--device {dev}] --command {cmd}
Options:
--id [ monitor_id ] - Monitor ID (monitor mode)
--protocol [ name ] - Control module name, e.g. ONVIF (direct mode)
--address [ addr ] - ControlAddress, e.g. user:pass@host:port (direct mode)
--device [ dev ] - ControlDevice / profile token (direct mode)
--command [ cmd ] - Command to execute (e.g. moveConUp, get_config)
--autostop -
--xcoord [ arg ] - X-coord
--ycoord [ arg ] - Y-coord
zmtrack.pl --help
Unknown option: help
Usage:
zmtrack.pl -m <monitor>
zmtrack.pl --monitor=<monitor>
Options:
-m<monitor>, --monitor=<monitor> - Id of the monitor to track
zmcamtool.pl --help
Usage:
zmcamtool.pl [--user=<dbuser> --pass=<dbpass>]
[--import [file.sql] [--overwrite]]
[--export [name]]
[--topreset id [--noregex]]
Options:
--export - Export all camera controls and presets to STDOUT.
Optionally specify a control or preset name.
--import [file.sql] - Import new camera controls and presets found in
zm_create.sql into the ZoneMinder dB.
Optionally specify an alternate sql file to read from.
--overwrite - Overwrite any existing controls or presets.
with the same name as the new controls or presets.
--topreset id - Copy a monitor to a Camera Preset given the monitor id.
--noregex - Do not try to find and replace fields such as usernames,
passwords, IP addresses, etc with generic placeholders
when converting a monitor to a preset.
--help - Print usage information.
--user=<dbuser> - Alternate dB user with privileges to alter dB.
--pass=<dbpass> - Password of alternate DB user with privileges to alter dB.
--version - Print version.
⚠️ 注意:本篇实测环境无云台硬件,三者的用法已实测照抄,
--command moveConUp一类的操作指令未实际执行。zmcamtool.pl 不依赖硬件,--export/--import随时可用,是换机迁移摄像头预置位的正规通道。
4.10 流服务与 ONVIF 工具(zm_rtsp_server / zmonvif-probe.pl / zmonvif-trigger.pl)
zm_rtsp_server 把监控流重新以 RTSP 对外发布(给第三方播放器/分析器消费),zmonvif-probe 探测局域网 ONVIF 设备能力:
zm_rtsp_server --help
zm_rtsp_server -m <monitor_id>
Options:
-m, --monitor <monitor_id> : We default to all monitors use this to specify just one
-h, --help : This screen
-v, --version : Report the installed version of ZoneMinder
zm_rtsp_server -v
1.38.6
zmonvif-probe.pl --help
/usr/bin/zmonvif-probe.pl version [unknown] calling Getopt::Std::getopts (version 1.14),
running under Perl version 5.40.1.
Usage: /usr/bin/zmonvif-probe.pl [-v] probe <soap versions> <network interface>
/usr/bin/zmonvif-probe.pl [-v] <command> <device URI> <soap version> <user> <password>
Commands are:
probe - scan for devices on the local network and list them
profiles - print the device's supported stream configurations
metadata - print some of the device's configuration settings
move - move the device (only ptz cameras)
events - check if the device supports ONVIF events
Common parameters:
-v - increase verbosity
Device access parameters (for all commands but 'probe'):
device URL - the ONVIF Device service URL
soap versions - SOAP versions (1.1 or 1.2 or 1.1,1.2)
user - username of a user with access to the device
password - password for the user
(probe <soap版本> <网卡> 子命令可在不接设备的情况下扫全网段;profiles/metadata/move/events 需要提供 ONVIF Device 服务 URL 与凭据。zmonvif-trigger.pl 与 zmtrigger.pl 配合做 ONVIF 事件转触发,本篇未接设备故仅列用途。)
4.11 版本与健康检查(zm-version / zm-healthcheck)
两个无参数小工具,适合塞进巡检脚本:
zm-version
ZM_CHANNEL=release-1.38
ZM_VERSION=1.38.6+trixie1
ZM_PIN=1.38.6+trixie1
zm-healthcheck
healthy
(zm-version 的 ZM_VERSION=1.38.6+trixie1 比裸版本号多发行版后缀;zm-healthcheck 输出 healthy/异常词,可作健康探针。)
4.12 zmsystemctl.pl —— systemd 包装
在带 systemd 的 Linux 真机上,该工具把 zmdc 的管理动作包装为 systemctl 对 zoneminder 服务的操作(deb/rpm 安装形态的标准托管路径)。其调用链经 polkit/pkexec 授权,无 systemd/polkit 的环境下执行会直接崩溃(实测回显,exit 134):
zmsystemctl.pl --help
**
ERROR:../src/programs/pkexec.c:784:main: assertion failed: (polkit_unix_process_get_start_time (POLKIT_UNIX_PROCESS (subject)) > 0)
Bail out! ERROR:../src/programs/pkexec.c:784:main: assertion failed: (polkit_unix_process_get_start_time (POLKIT_UNIX_PROCESS (subject)) > 0)
⚠️ 注意:本篇实测环境无 systemd/polkit,故只有这条崩溃回显可考。在 systemd 真机上使用前先确认
systemctl status zoneminder存在该服务单元;zmsystemctl.pl 的子命令以真机zmsystemctl.pl --help输出为准。
4.13 后台守护进程族(由 zmdc 托管,不手工直跑)
下表守护由 zmdc 在 zmpkg.pl start 时按需拉起,手工直跑会绕过托管(端口/共享内存冲突或重复实例):
| 进程(zmdc status 原文) | 职责 |
|---|---|
| zmc -m 1 | 采集守护:按 Monitor 1 的源拉流解码入环形缓冲,每监控一个实例 |
| zms | 流输出:Web 页面实时流的 CGI(nph-zms)后端 |
| zmwatch.pl | 巡检采集守护帧延迟,卡死自动重启(节奏见 ZM_WATCH_CHECK_INTERVAL) |
| zmfilter.pl --filter_id=N --daemon | 按过滤器数量常驻,周期执行各过滤器 |
| zmupdate.pl -c | 每小时版本检查常驻形态(4.5 节) |
| zmtelemetry.pl | 匿名使用数据上报(ZM_TELEMETRY_DATA=1 时运行) |
| zmstats.pl | 周期落库运行统计(Monitor/Event 表的状态字段) |
| zmtrigger.pl / zmx10.pl | 外部触发接入 / X10 联动(启用对应功能才出现) |
zmdc 对守护的完整生命周期会落到 /var/log/zm/zmdc.log,一次 zmdc.pl restart zmc -m 1 的日志节选(实测):
10/30/26 13:30:07.660049 zmdc[3549].INF [ZMServer:445] ['zmtelemetry.pl' starting at 26/10/30 13:30:07, pid = 3609]
10/30/26 13:30:07.726291 zmdc[3549].INF [ZMServer:445] ['zmstats.pl' starting at 26/10/30 13:30:07, pid = 3615]
10/30/26 13:30:07.726309 zmdc[3615].INF [ZMServer:445] ['zmstats.pl' started at 26/10/30 13:30:07]
10/30/26 13:30:08.007908 zmdc[3549].INF [ZMServer:445] ['zmc -m 1' sending stop to pid 3580 at 26/10/30 13:30:08]
10/30/26 13:30:08.016103 zmdc[3549].INF [ZMServer:761] ['zmc -m 1' exited normally]
10/30/26 13:30:09.018976 zmdc[3549].INF [ZMServer:445] [Starting pending process, zmc -m 1]
10/30/26 13:30:09.021922 zmdc[3549].INF [ZMServer:445] ['zmc -m 1' starting at 26/10/30 13:30:09, pid = 3642]
10/30/26 13:30:09.021943 zmdc[3642].INF [ZMServer:445] ['zmc -m 1' started at 26/10/30 13:30:09]
日志目录的全集(实测 18 个文件,各守护一一对应):
ls /var/log/zm/
cake_debug.log
cake_error.log
debug.log
error.log
web_php.log
zmaudit.log
zmc_m1.log
zmdc.log
zmfilter_1.log
zmfilter_2.log
zmpkg.log
zmrecover.log
zmstats.log
zmtelemetry.log
zmu.log
zmupdate.log
zmvideo.log
zmwatch.log
五、注意事项
- zmdc 分参语法是第一坑:守护名与参数必须拆成独立单词(
zmdc.pl restart zmc -m 1),整串引号"zmc -m 1"会被当非法守护名拒绝。三条路径的实测对照见 4.3 节。 - zmu 存在 glibc double-free 崩溃 quirk:同一环境连续复跑
zmu -l、zmu -m 1 -t时出现过free(): double free detected in tcache 2进程崩溃(实测记录)。规避:单次调用取值即停、避免脚本里高频循环调用;崩溃不影响其他工具与服务本身,重启后再观察。若复现频繁,优先升级到更新的 1.38.x 修正版本。 - zmu
-v是 verbose 不是 version,打印版本用zm-version;zmupdate.pl 的-v更是「从指定版本升级」的参数(4.5 节)。 - zmupdate.pl
-c在无终端环境常驻不退出(每小时检查),cron/管道场景要么交互终端单跑,要么接受常驻形态。 - zmrecover.pl 单传
-r会报「only one option may be specified」(4.8 节实测),本版本以无参默认行为或-i交互模式使用为宜。 - 多数
.pl工具不认识--help(回Unknown option: help后仍给出 usage),这是工具族统一行为,不是故障。 - 认证开启后 zmu 不带凭据则查询无输出;凭据错误同样静默,先核对
-U/-P。 - 不要手工直跑 zmc/zms 等后台守护(4.13 节),一律经 zmpkg/zmdc 管理。
六、常见问题
Q1:zmu 查询没有任何输出?
认证开启后 zmu 静默失败的最常见原因是凭据缺失或错误——必须带 -U admin -P q1w2e3r4(或等效 -T/-A),并确认账号 Enabled 且权限不低于 Monitor 维度。先跑 zmu -l -U admin -P q1w2e3r4 确认能列出监控,再排单监控参数。
Q2:zmu 复跑时报 free(): double free detected in tcache 2 崩溃? 已录得的环境 quirk(详见五、2),单次调用即可取到正确结果(崩溃前的输出有效)。作为对照,同环境的 zmpkg/zmdc/zmaudit 全程无恙,崩溃仅限 zmu 个别参数路径的高频复跑。
Q3:zmdc.pl restart "zmc -m 1" 报 Invalid daemon?
守护名与参数是一个词组时不能整体加引号。正确写法把 -m 1 作为独立参数跟在守护名后(4.3 节写法三);同理 zmdc.pl status zmc -m 1 也是分参形态。
Q4:zmupdate.pl --version 报 Option version requires an argument?
-v/--version 在 zmupdate.pl 里是「从指定版本强制升级」的参数。查版本用 zm-version 或 zmaudit.pl -v、zmfilter.pl -v。
Q5:zmvideo.pl 生成视频时输出 Use of uninitialized value 警告? Perl 对事件元数据中空变换字段的提示,不阻断生成——警告行之后给出的路径即产物文件(4.7 节实测为 /var/cache/zoneminder/events/1/2026-10-30/3/Event-3-r1-s1.mp4),回放确认即可。
Q6:各守护的日志在哪、怎么对应?
统一在 /var/log/zm/ 下按进程命名(zmc_m1.log 对应 zmc -m 1、zmfilter_1.log/2.log 对应两个 filter 实例,全集见 4.13 节 ls 回显)。排查守护启停优先看 zmdc.log(生命周期 INF 级序列),排查采集/检测看 zmc_m1.log。
Q7:zmpkg.pl stop 之后 Web 页面还能打开?
stop 只停守护进程族(采集/分析/流),Web 控制台与 API 由 Web 服务承载、不随 zmpkg 停止——此时页面可访问但监控列表无实时流。确证手段是 zmdc.pl status 返回 socket 断连报错(4.2 节实测),zmpkg.pl start 恢复。
七、参考链接
- ZoneMinder 官方文档(Read the Docs):https://zoneminder.readthedocs.io/en/stable/
- ZoneMinder 官方 Wiki:https://wiki.zoneminder.com/
- ZoneMinder GitHub 仓库:https://github.com/ZoneMinder/zoneminder
- 《Zoneminder 1.38.6 介绍与选型指南》
- 《Zoneminder 1.38.6 Docker Compose 部署指南》
- 《Zoneminder 1.38.6 配置参数详解》