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视频监控Perl2026/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 内存)
ZoneMinder1.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.plX10 家电控制联动
流与协议zmc采集守护(每监控一个实例,从摄像头拉流取帧)
流与协议zmsWeb 实时流输出(nph-zms CGI 由它承载)
流与协议zm_rtsp_server把监控流重新以 RTSP 对外发布
流与协议zmonvif-probe.pl、zmonvif-trigger.plONVIF 设备探测(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 四件套。

三、前置条件

  1. ZoneMinder 1.38.6 已部署且守护进程在跑(zmpkg.pl status 返回 running,见 4.2 节)。
  2. 以服务器上的系统用户执行(root 或具备读取 /etc/zm 权限的用户)。工具都在 /usr/bin 下,无需额外配 PATH。
  3. 认证已开启时 zmu 必须带凭据:-U admin -P q1w2e3r4,或改传 -T <JWT> / -A <auth hash>(见 4.1 节认证参数表)。凭据错误时 zmu 查询无输出。
  4. 涉及数据库结构变更的命令(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 / -Pzmu … -U admin -P q1w2e3r4用户名密码(本篇统一用此形态)
-Tzmu … -T <JWT>传 API 登录签发的 JWT 令牌
-Azmu … -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

两个实测行为务必记牢:

  1. -c 在非交互(无终端)环境下会常驻不退出——按 Help 原文「stay running, checking every hour」每小时检查一次。本篇采集时用管道方式调用 -c,命令长时间不返回,Ctrl+C 结束。日常手工检查请直接在交互终端跑 zmupdate.pl -c(跑一次即退出),或让守护常驻形态干这活(zmdc.pl status 里的 'zmupdate.pl -c' 进程就是它)。
  2. -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

五、注意事项

  1. zmdc 分参语法是第一坑:守护名与参数必须拆成独立单词(zmdc.pl restart zmc -m 1),整串引号 "zmc -m 1" 会被当非法守护名拒绝。三条路径的实测对照见 4.3 节。
  2. zmu 存在 glibc double-free 崩溃 quirk:同一环境连续复跑 zmu -l、zmu -m 1 -t 时出现过 free(): double free detected in tcache 2 进程崩溃(实测记录)。规避:单次调用取值即停、避免脚本里高频循环调用;崩溃不影响其他工具与服务本身,重启后再观察。若复现频繁,优先升级到更新的 1.38.x 修正版本。
  3. zmu -v 是 verbose 不是 version,打印版本用 zm-version;zmupdate.pl 的 -v 更是「从指定版本升级」的参数(4.5 节)。
  4. zmupdate.pl -c 在无终端环境常驻不退出(每小时检查),cron/管道场景要么交互终端单跑,要么接受常驻形态。
  5. zmrecover.pl 单传 -r 会报「only one option may be specified」(4.8 节实测),本版本以无参默认行为或 -i 交互模式使用为宜。
  6. 多数 .pl 工具不认识 --help(回 Unknown option: help 后仍给出 usage),这是工具族统一行为,不是故障。
  7. 认证开启后 zmu 不带凭据则查询无输出;凭据错误同样静默,先核对 -U/-P。
  8. 不要手工直跑 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 恢复。

七、参考链接