Zoneminder 1.38.6 配置参数详解

目标：摸清 ZoneMinder 1.38.6 全部 280 项配置参数「存放在哪里、怎么查看、怎么修改、改完如何生效」，对认证、日志、事件、图像、系统、Web 等核心分类的关键参数逐项给出实测值与出厂默认值，并给出按监控路数与磁盘规模组织的生产配置模板。全部命令与回显已在 Ubuntu 22.04 + ZoneMinder 1.38.6 环境逐条实测通过，参数值与分类统计直接取自本机 Config 表的 API 导出。

一、环境信息

本篇全部命令与回显在下列实测环境中逐条跑出（2026-10-30），部署过程见《Zoneminder 1.38.6 Docker Compose 部署指南》：

二、前置条件

1. 已按《Zoneminder 1.38.6 Docker Compose 部署指南》完成部署，Web 控制台可正常登录（ZoneMinder 的安装与选型背景见《Zoneminder 1.38.6 介绍与选型指南》）。
2. 一个具有 System 权限的账号（本篇用 admin，密码 q1w2e3r4）。Options 页与 configs API 均要求 System 权限，普通（View/Event）权限账号看不到这些入口。
3. API 处于开启状态。ZM_OPT_USE_API 出厂默认即开启（本机实测 Value=1），若被关闭，按 3.2 节在 Options → System 页签重新勾选。
4. 服务器已安装 curl 与 python3（Ubuntu 22.04 均内置），用于 3.3 节的 API 实操。
5. 涉及文件层（/etc/zm/）修改的操作需要 root 或 sudo 权限。

三、参数查看与修改方式

ZoneMinder 的配置参数分布在三个层面，动手前先分清一个参数属于哪一层，修改方式完全不同：文件层的路径与数据库连接参数（约 33 项）只能改文件；数据库层的行为参数（280 项中其余 247 项）通过 Web Options 页或 API 修改。本节先给出三层体系全景，再逐一实测 Web、API 两条通道，最后讲修改后的生效方式。

3.1 三层配置体系

先看基础文件层的真实内容（DO NOT EDIT 是文件自带的第一行声明，自定义修改一律走 conf.d）：

cat /etc/zm/zm.conf

# ==========================================================================
#
# ZoneMinder Base Configuration
#
# ==========================================================================
#
# *** DO NOT EDIT THIS FILE ***
#
# To make custom changes to the variables below, create a new configuration
# file, with an extension of .conf, under the /etc/zm/conf.d
# folder, containing your desired modifications.
#

# Path to installed data directory, used mostly for finding DB upgrade scripts
ZM_PATH_DATA=/usr/share/zoneminder

# Path to ZoneMinder binaries
ZM_PATH_BIN=/usr/bin

# Path to ZoneMinder libraries (none at present, for future use)
ZM_PATH_LIB=/usr/lib/x86_64-linux-gnu

# Path to ZoneMinder configuration (this file only at present)
ZM_PATH_CONF=/etc/zm

# Path to ZoneMinder web files
ZM_PATH_WEB=/usr/share/zoneminder/www

# Path to ZoneMinder cgi files
ZM_PATH_CGI=/usr/lib/zoneminder/cgi-bin

# Username and group that web daemon (httpd/apache) runs as
ZM_WEB_USER=www-data
ZM_WEB_GROUP=www-data

# ZoneMinder database type: so far only mysql is supported
ZM_DB_TYPE=mysql

# ZoneMinder database hostname or ip address and optionally port or unix socket
# Acceptable formats include hostname[:port], ip_address[:port], or
# localhost:/path/to/unix_socket
ZM_DB_HOST=localhost

# ZoneMinder database name
ZM_DB_NAME=zm

# ZoneMinder database user
ZM_DB_USER=zmuser

# ZoneMinder database password
ZM_DB_PASS=zmpass

# SSL CA certificate for ZoneMinder database
ZM_DB_SSL_CA_CERT=

# SSL client key for ZoneMinder database
ZM_DB_SSL_CLIENT_KEY=

# SSL client cert for ZoneMinder database
ZM_DB_SSL_CLIENT_CERT=

# Do NOT set ZM_SERVER_HOST if you are not using Multi-Server
# You have been warned
#
# The name specified here must have a corresponding entry
# in the Servers tab under Options
ZM_SERVER_HOST=

扩展文件层 conf.d 的官方包自带 01-system-paths.conf（原 Options → Paths 页签的路径参数）与 02-multiserver.conf（多服务器参数）两个文件。用 grep 可以确认事件目录在这一层定义：

grep ZM_DIR_EVENTS /etc/zm/conf.d/*.conf

/etc/zm/conf.d/01-system-paths.conf:ZM_DIR_EVENTS=/var/cache/zoneminder/events

01-system-paths.conf 开头同样带着 DO NOT EDIT 声明，节选（实测首部）如下：

# ==========================================================================
#
# ZoneMinder System Paths Configuration
#
# ==========================================================================
#
# This config file contains the variables previously found under Options -> Paths
#
# *** DO NOT EDIT THIS FILE ***
#
# To make custom changes to the variables below, create a new configuration
# file, with an extension of .conf, containing your desired modifications.
#

# Full path to the folder events are recorded to.
# The web account user must have full read/write permission to this folder.
ZM_DIR_EVENTS=/var/cache/zoneminder/events

# Foldername under the webroot where ZoneMinder looks for optional sound files
# to play when an alarm is detected.

⚠️ 注意：两层文件的修改规则一致——不编辑任何已存在的 conf 文件，在 /etc/zm/conf.d/ 下新建自己的 .conf（如 90-custom.conf）覆盖同名键。数据库层能管的参数（见 3.3 节的 280 项清单）优先走 Options 页或 API，文件层只兜底数据库层管不到的路径与连接类参数。

3.2 Web 控制台查看与修改

Options 页是数据库层参数的图形界面。操作路径：登录 Web 控制台 → 右上角导航栏的 Options 链接（即 ?view=options）→ 顶部页签分组成列（System、Web、Images、Logging、Network、Mail、Upload、X10、High/Medium/Low B/W、Version 等）→ 点开对应页签逐项修改 → 拉到页底点击 Save。

三个要点：

1. 权限：整个 Options 页要求 System 权限账号，普通账号访问会直接被拒。
2. 分类与页签并非严格一一对应：数据库层有 19 个分类（见第四章统计），页签只覆盖同名大类，auth/config/telemetry 等分类的参数大多收纳在 System 页签内；以 3.3 节 API 查到的分类与名称为准最可靠。
3. 保存后不会立即生效：Save 只是把新值写入 Config 表，多数参数要等守护进程重启后才生效，见 3.4 节。

修改是否真的落库，用 3.3 节的 viewByName 一条命令即可复核，不需要刷新页面反复确认。

3.3 API 查看与修改（逐条实测）

configs API 是 280 项参数最精确的查改通道，本小节命令全部在本机实测，可直接照抄。API 鉴权采用 JWT 令牌：

💡 技术拓展：ZoneMinder API 有三种鉴权形态——①JWT 令牌（host/login.json 签发，1.34.0 起的标准方式，放 ?token= 查询参数）；②legacy MD5 auth hash（credentials=auth=<hash>，老版第三方客户端如 zmNinja 旧版在用，由 ZM_OPT_USE_LEGACY_API_AUTH 控制）；③用户名密码直传（append_password 模式，明文走 URL，不建议）。本篇统一用 ①JWT：本机实测 ZM_OPT_USE_LEGACY_API_AUTH=1（默认 yes）兼容②，若确认无老客户端依赖可将其置 0 收紧。

第一步：登录拿 token。

curl -s -X POST 'http://127.0.0.1:8140/zm/api/host/login.json?username=admin&password=q1w2e3r4'

{"version":"1.38.6","apiversion":"2.0","access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJab25lTWluZGVyIiwiaWF0IjoxNzkzMzM3MTE3LCJleHAiOjE3OTMzNDQzMTcsInVzZXIiOiJhZG1pbiIsInR5cGUiOiJhY2Nlc3MifQ.Uf0a1N8_127lnsjM6foV7LnFz1ePLvdePb6x2nLnvOY","access_token_expires":7200,"refresh_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJab25lTWluZGVy……（JWT 全文略）","refresh_token_expires":86400,"credentials":"auth=5be35c685f6538fd6ac655fbe8b137c4","append_password":0}

输出节选说明：access_token 有效期 7200 秒（2 小时），refresh_token 有效期 86400 秒（1 天）可用于续签。把 token 提取进变量，后续命令直接引用：

TOK=$(curl -s -X POST 'http://127.0.0.1:8140/zm/api/host/login.json?username=admin&password=q1w2e3r4' | python3 -c 'import sys,json;print(json.load(sys.stdin)["access_token"])')
echo "token_len=${#TOK}"

token_len=195

第二步：拉全量参数清单并统计分类。 configs.json 一次返回全部条目，每条挂在 Config 键下：

curl -s "http://127.0.0.1:8140/zm/api/configs.json?token=$TOK" -o /tmp/configs.json
python3 - <<'EOF'
import json
from collections import Counter
d = json.load(open('/tmp/configs.json'))
items = d if isinstance(d, list) else d.get('configs', d.get('data', []))
rows = [x.get('Config', x) for x in items]
print('total:', len(rows))
c = Counter(str(r.get('Category')) for r in rows)
for k in sorted(c): print(f'{k}: {c[k]}')
EOF

total: 280
MQTT: 5
None: 33
auth: 13
config: 18
dynamic: 3
hidden: 2
highband: 17
images: 15
logging: 24
lowband: 17
mail: 11
medband: 17
network: 7
system: 42
telemetry: 4
upload: 15
version: 6
web: 27
x10: 4

实测 280 项：数据库层 19 个分类共 247 项，None 分类 33 项即文件层的路径与连接参数（它们也出现在 API 清单里，但值被隐藏，见第 5.12 节）。

第三步：按名称精确查看。 viewByName 端点返回单个参数的当前值：

curl -s "http://127.0.0.1:8140/zm/api/configs/viewByName/ZM_WEB_TITLE_PREFIX.json?token=$TOK" | python3 -m json.tool

{
    "config": {
        "Value": "ZM"
    }
}

要看全字段（默认值、提示语、校验正则等）改用 view 端点：

curl -s "http://127.0.0.1:8140/zm/api/configs/view/ZM_WEB_TITLE_PREFIX.json?token=$TOK" | python3 -m json.tool

{
    "config": {
        "Config": {
            "Id": 91,
            "Name": "ZM_WEB_TITLE_PREFIX",
            "Value": "ZM",
            "Type": "string",
            "DefaultValue": "ZM",
            "Hint": "string",
            "Pattern": "(?^:^(.+)$)",
            "Format": " $1 ",
            "Prompt": "The title prefix displayed on each window",
            "Help": "\n      If you have more than one installation of ZoneMinder it can be\n      helpful to display different titles for each one. Changing this\n      option allows you to customise the window titles to include\n      further information to aid identification.\n      ",
            "Category": "web",
            "Readonly": 0,
            "Private": false,
            "System": false,
            "Requires": null
        }
    }
}

字段含义逐项对照：

第四步：修改并复核。 edit 端点用 PUT 提交 Config[Value] 字段，成功时响应体为空（HTTP 200），必须再查一次确认：

curl -s -X PUT "http://127.0.0.1:8140/zm/api/configs/edit/ZM_WEB_TITLE_PREFIX.json?token=$TOK" -d 'Config[Value]=ZMDoc'

（无输出，HTTP 200。）

curl -s "http://127.0.0.1:8140/zm/api/configs/viewByName/ZM_WEB_TITLE_PREFIX.json?token=$TOK" | python3 -m json.tool

{
    "config": {
        "Value": "ZMDoc"
    }
}

改回原值并复核（本篇所有实测参数改完即还原，环境不留残余）：

curl -s -X PUT "http://127.0.0.1:8140/zm/api/configs/edit/ZM_WEB_TITLE_PREFIX.json?token=$TOK" -d 'Config[Value]=ZM'

（无输出，HTTP 200。）

curl -s "http://127.0.0.1:8140/zm/api/configs/viewByName/ZM_WEB_TITLE_PREFIX.json?token=$TOK" | python3 -m json.tool

{
    "config": {
        "Value": "ZM"
    }
}

第五步：分类清单端点。 categories 端点返回去重后的分类名列表：

curl -s "http://127.0.0.1:8140/zm/api/configs/categories.json?token=$TOK" | python3 -c "import sys,json; d=json.load(sys.stdin); print([x['Config']['Category'] for x in d['categories']])"

['images', 'system', 'auth', 'config', 'logging', 'version', 'dynamic', 'mail', 'web', 'network', 'MQTT', 'upload', 'x10', 'telemetry', 'highband', 'lowband', 'medband']

（该端点只列数据库层 17 个分类，文件层的 None 类不出现在此清单中。）

3.4 参数生效与重启

数据库层参数的新值要等守护进程重启才被读取。判断依据：zmdc.pl status 显示每个守护进程的 running since 时间，重启后全部刷新为重启时刻。全量重启用 zmpkg.pl restart（注意 zmdc.pl restart 不带守护进程名会报 usage，全量启停是 zmpkg 的职责）：

zmpkg.pl status

running

zmpkg.pl restart

（无输出，命令在守护进程全部重启后返回。）

zmdc.pl status

'zmc -m 1' running since 26/10/30 13:16:17, pid = 2992, valid
'zmfilter.pl --filter_id=1 --daemon' running since 26/10/30 13:16:17, pid = 2998, valid
'zmfilter.pl --filter_id=2 --daemon' running since 26/10/30 13:16:17, pid = 3004, valid
'zmwatch.pl' running since 26/10/30 13:16:17, pid = 3010, valid
'zmupdate.pl -c' running since 26/10/30 13:16:17, pid = 3016, valid
'zmtelemetry.pl' running since 26/10/30 13:16:17, pid = 3021, valid
'zmstats.pl' running since 26/10/30 13:16:17, pid = 3027, valid

全部守护进程的 running since 一致刷新为 13:16:17（重启时刻）、pid 全部更新，说明新配置已被加载。Web 控制台里对应的操作是首页顶部出现的「Restart ZoneMinder」提示条，点击效果相同。仅修改 ZM_WEB_* 一类纯界面参数时可不重启，保存即生效。

四、参数总览

280 项参数按「数据库层 247 项（17 分类）+ 文件层 33 项（None 分类）」组织。分类统计如下（3.3 节同源实测）：

两点口径说明：

1. highband/medband/lowband 是同一套参数的三份拷贝：键名中缀分别为 _H_/_M_/_L_，控制 Web 控制台的刷新频率、流画质与码率，由 ZM_BANDWIDTH_DEFAULT（system 分类，本机实测 high）决定实际套用哪一档。三档关键差异：

2. 文件层 33 项也在 API 清单里出现，但 Value 恒为空字符串（脱敏，见 5.12 节），真实值以 /etc/zm/ 文件内容为准。

后续第五章按分类详解，条目较多的分类（system/web/logging）挑关键参数成表，每张表的「实测值 / 默认值」两列均取自 3.3 节全量导出的真实数据。

五、核心参数分类详解

5.1 认证与安全（auth，13 项）

💡 技术拓展：ZM_AUTH_RELAY 的三个取值对比——hashed：传限时哈希串（默认 TTL 2 小时），不落明文账号密码，通用推荐；plain：明文传用户名密码，仅在系统完全隔离且无 md5 库时考虑；none：不传递身份，适合纯内网且另有访问控制的隔离环境。本环境取默认 hashed。开启认证后记得同步检查 ZM_AUTH_HASH_SECRET，沿用默认提示语等于没加盐。

5.2 日志（logging，24 项）

ZoneMinder 日志有五个独立通道，各自用 None=-5|Panic=-4|Fatal=-3|Error=-2|Warning=-1|Info=0|Debug=1 七级刻度（此映射逐字来自参数 Hint 字段）控制「记录该级别及更低严重度」：

日志目录的真实落点（实测 15 个文件，与五通道及各组件一一对应）：

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
zmstats.log
zmu.log
zmupdate.log
zmwatch.log

其余关键项：

⚠️ 注意：ZM_LOG_LEVEL_DATABASE 开到 Info 以上时，忙碌系统会让 Logs 表快速膨胀，务必保留 ZM_LOG_DATABASE_LIMIT（默认 7 day）兜底；生产环境推荐直接 -5 关闭入库，排障时临时打开。

5.3 事件与录像行为（config，18 项）

5.4 图像与视频（images，15 项）

5.5 系统与守护进程（system，42 项）

按功能组呈现（42 项全覆盖于三张表）：

巡检与自愈组——决定各后台进程的自检节奏：

功能开关组：

界面偏好组：

5.6 Web 界面（web，27 项）

5.7 版本检查、遥测与动态字段（version 6 + telemetry 4 + dynamic 3 + hidden 2）

version 分类全是运行期动态字段（ZM_DYN_*），由 zmupdate.pl -c 守护例行刷新：

telemetry 分类控制匿名使用数据上报（目标是 hidden 类的 ZM_TELEMETRY_SERVER_ENDPOINT=https://telemetry.zoneminder.com/index.php）：

dynamic 分类是运行期状态字段：ZM_DYN_SHOW_DONATE_REMINDER=1（捐赠提醒，默认 yes）、ZM_DYN_DONATE_REMINDER_TIME=1795925573（下次提醒时间戳）、ZM_SHOW_PRIVACY=0（隐私声明页开关，默认 yes；首启同意后置 0，对应部署篇 4.5 节的 privacy 同意页）。hidden 分类除遥测端点外还有 ZM_USE_DEEP_STORAGE=1（深度存储，见第七章 Q9 的禁改警告）。

5.8 消息总线与邮件通知（MQTT 5 项 + mail 11 项）

MQTT 分类是对接外部 MQTT 服务器的参数（本机均保持默认，未对接自建 broker）：

mail 分类控制告警邮件（默认全关，启用需配过滤器联动）：

主题/正文模板的占位符含义（改模板时照抄组合即可）：

5.9 远程上传与 X10（upload 15 项 + x10 4 项）

upload 分类把事件归档包上传到远端 FTP/SFTP 服务器，默认全部关闭（本机 15 项实测值与默认一致）。关键项：ZM_OPT_UPLOAD=0（总开关）、ZM_UPLOAD_PROTOCOL=ftp（可选 sftp）、ZM_UPLOAD_HOST/PORT/USER/PASS/REM_DIR（远端主机/端口/凭据/目录，出厂为空，启用时按自有环境填写）、ZM_UPLOAD_ARCH_FORMAT=tar（可选 zip）、ZM_UPLOAD_ARCH_COMPRESS=0（是否压缩归档）、ZM_UPLOAD_FTP_PASSIVE=1（被动模式）、ZM_UPLOAD_TIMEOUT=120（超时秒）、ZM_UPLOAD_LOC_DIR=/var/tmp/zm（本地暂存目录）、ZM_UPLOAD_ARCH_ANALYSE=0（上传后校验）、ZM_UPLOAD_DEBUG=0、ZM_UPLOAD_STRICT=0。启用时先填 HOST/USER/PASS/REM_DIR 四项再开总开关。

x10 分类是 X10 家电控制协议（通过串口收发，做「告警联动开灯」类自动化），默认关闭：ZM_OPT_X10=0、ZM_X10_DEVICE=/dev/ttyS0（串口设备）、ZM_X10_HOUSE_CODE=A（房码 A–P）、ZM_X10_DB_RELOAD_INTERVAL=60（配置重载间隔秒）。无对应硬件时保持关闭即可。

5.10 网络与流媒体（network，7 项）

5.11 带宽三档参数集（highband/medband/lowband，各 17 项）

三档共 51 项是同一套键的三份拷贝（中缀 _H_/_M_/_L_），控制 Web 端实时与回放的刷新率、缩放、码率。每套 17 键结构完全一致：AJAX_TIMEOUT（5000–10000 毫秒）、CAN_STREAM（auto/yes/no）、DEFAULT_RATE（回放速率 %，枚举 25–10000）、DEFAULT_SCALE（缩放 %，枚举 25–400）、EVENTS_VIEW（events/timeline）、REFRESH_CYCLE/REFRESH_EVENTS/REFRESH_IMAGE/REFRESH_MAIN/REFRESH_NAVBAR/REFRESH_STATUS（各页面刷新秒数）、SCALE_THUMBS、SHOW_PROGRESS、STREAM_METHOD（mpeg/jpeg）、VIDEO_BITRATE、VIDEO_MAXFPS、VIEWING_TIMEOUT。三档核心差异见第四章对比表。实际套用哪一档由 ZM_BANDWIDTH_DEFAULT 决定（本机 high）；该机制主要服务于 classic 皮肤与弱带宽客户端（如经窄带链路访问的远程客户端），桌面局域网场景保持默认即可。

5.12 文件层路径与连接参数（None 分类，33 项）

这 33 项定义于 /etc/zm/zm.conf 与 conf.d，API 清单中可见但值一律脱敏为空，且不可通过 API 修改（edit 返回 404，3.3 节同源实测）。按用途分组：

用一条 grep 即可对照出「文件层有真值、API 层空值」的脱敏现象：

grep ZM_DB_PASS /etc/zm/zm.conf

ZM_DB_PASS=zmpass

而 API 视角 viewByName/ZM_DB_HOST.json 返回 {"config":{"Name":"ZM_DB_HOST","Value":""}}（HTTP 200，值为空）——密码类与连接类信息不通过 API 外泄，是 ZoneMinder 的刻意设计。

六、生产配置模板

以下三套模板按「监控路数 × 磁盘规模」划分，均基于 5.x 节实测参数（值为推荐值，非出厂值处单独标注）。场景假设均为 H.264 1080p 主码流、开启认证、默认 Modect/Continuous 混合录制。

模板 A：家用 1–4 路（4GB 内存 / 256GB SSD，7×24 连录 + 移动侦测）

模板 B：中小商用 8–16 路（16GB 内存 / 2TB NVMe，Modect 为主）

模板 C：磁盘敏感 16–32 路（32GB 内存 / 8TB HDD，Continuous + Mocord）

落地方式（两步，命令形态即 3.3.4 节实测验证过的 edit + viewByName 模式）。第一步逐项修改，这里以模板 C 的两条为例完整实测（先改再验，最后还原，环境无残余）：

curl -s -X PUT "http://127.0.0.1:8140/zm/api/configs/edit/ZM_LOG_LEVEL_DATABASE.json?token=$TOK" -d 'Config[Value]=-5'

（无输出，HTTP 200。）

curl -s "http://127.0.0.1:8140/zm/api/configs/viewByName/ZM_LOG_LEVEL_DATABASE.json?token=$TOK"

{"config":{"Value":"-5"}}

curl -s -X PUT "http://127.0.0.1:8140/zm/api/configs/edit/ZM_JPEG_ALARM_FILE_QUALITY.json?token=$TOK" -d 'Config[Value]=85'

（无输出，HTTP 200。）

curl -s "http://127.0.0.1:8140/zm/api/configs/viewByName/ZM_JPEG_ALARM_FILE_QUALITY.json?token=$TOK"

{"config":{"Value":"85"}}

（实测后均已用同一命令形态还原为 0，复核 {"config":{"Value":"0"}}。）

第二步重启生效并验证，命令与回显见 3.4 节（zmpkg.pl restart → zmdc.pl status 全员时间戳刷新）。文件层仅当需要改 5.12 节路径/连接参数时才动 /etc/zm/conf.d/，行为参数一律走本节通道。

七、常见问题

Q1：configs API 用数字 ID 访问报 404？ Config 表虽有 Id 自增主键（如 ZM_WEB_TITLE_PREFIX 的 Id=91），但 configs 端点的路由主键是 Name 字符串。用数字访问会得到如下实测 404：

curl -s -o /tmp/r.txt -w 'HTTP %{http_code}\n' "http://127.0.0.1:8140/zm/api/configs/view/91.json?token=$TOK" && cat /tmp/r.txt

输出节选（省略 url 字段，其余照抄；url 内嵌 token）：

HTTP 404
{"success":false,"data":{"name":"Invalid config","message":"Invalid config","exception":{"class":"NotFoundException","code":404,"message":"Invalid config"}}}

定位参数一律用名称：view/ZM_WEB_TITLE_PREFIX.json。

Q2：ZM_DB_ 数据库连接参数为什么改不了、查不到值？* 它们属于文件层 None 分类（5.12 节）：viewByName 能返回但 Value 恒为空（脱敏）；edit 直接 404（实测回显见 3.3 节 Q1 同款结构，端点为 edit/ZM_DB_HOST.json 时返回同样 Invalid config）。修改只能走 /etc/zm/conf.d/ 新建 .conf 覆盖，改完重启。

Q3：ZM_AUTH_HASH_SECRET 通过 API 查是空值，是不是没配置？ 不是。ZM_AUTH_HASH_SECRET、ZM_OPT_GOOG_RECAPTCHA_SITEKEY/_SECRETKEY 三个参数带 Private=true 标志（3.3 节全量导出实测），API 返回时脱敏为空。文件层/数据库里有真实值，只是不通过 API 外露。检查是否仍为默认值，看 Options 页输入框或对比 5.1 节默认值提示语。

Q4：Options 页改完参数，行为没变？ 数据库层参数由守护进程在启动时读取，Save 只落库不重载。执行 zmpkg.pl restart 并用 zmdc.pl status 确认全员 running since 刷新为当前时刻（完整回显见 3.4 节）。仅 ZM_WEB_* 纯界面参数例外，保存即生效。

Q5：ZM_DYN_LAST_VERSION=1.38.4 比本机 1.38.6 旧，要不要处理？ 不用。该字段是官方更新检查端点回报的「最新版本」，其收录滞后于 GitHub Release（实测 2026-10-30 检查时刻仍回报 1.38.4）。只要 ZM_DYN_CURR_VERSION 与 ZM_DYN_DB_VERSION 一致（均 1.38.6），即无待执行升级。

Q6：日志级别数字怎么对应？ 七级刻度逐字来自参数 Hint：None=-5|Panic=-4|Fatal=-3|Error=-2|Warning=-1|Info=0|Debug=1。通道取值表示「记录该级别及更低严重度」，例如 ZM_LOG_LEVEL_DATABASE=0 即 Info 及以上入库，-5 即完全关闭该通道（各通道实测值见 5.2 节）。

Q7：highband/medband/lowband 三套参数怎么切换？ 不直接改这三类参数，改 ZM_BANDWIDTH_DEFAULT（system 分类，可选 high/med/low 对应档位，本机实测 high）。该机制主要作用于 classic 皮肤与弱带宽客户端；三档差异对照见第四章。

Q8：怎么把参数恢复默认值？ API 没有「一键还原」端点。用 view 端点读出 DefaultValue 字段，再用 edit 改回去（3.3.4 节命令形态）。判断「当前值=默认值」也用同一对照法：本篇 5.x 节各表已同时给出实测值与默认值。

Q9：ZM_USE_DEEP_STORAGE 可以改吗？ 不可以随意改。它是 hidden 分类参数，默认 1（深度存储，事件按 年/月/日/时/分/秒 目录组织）。官方 Help 明确警告：变更必须先停服务、改值、再执行 zmupdate.pl --migrate-events 迁移旧事件，跳步会丢数据。新装系统保持默认即可。

八、参考链接

• ZoneMinder 官方文档（Read the Docs）：https://zoneminder.readthedocs.io/en/stable/
• ZoneMinder 官方 Wiki：https://wiki.zoneminder.com/
• ZoneMinder GitHub 仓库：https://github.com/ZoneMinder/zoneminder
• 本机 API 自带调试页（登录后可见全部端点）：http://127.0.0.1:8140/zm/api
• 《Zoneminder 1.38.6 介绍与选型指南》
• 《Zoneminder 1.38.6 Docker Compose 部署指南》