motionEye 0.44.0 配置参数详解
motionEye 0.44.0 配置参数详解
目标：把 motionEye 0.44.0 的三层配置文件（motioneye.conf / motion.conf / camera-N.conf）逐层讲透，给出每一域参数的实测文件样例、界面键与文件键的对应关系、以及修改生效与验证的实操方法。全部配置内容与回显均取自一台已部署并完成摄像头接入的 Ubuntu 22.04 服务器（motionEye 0.44.0 + motion 4.7.1，实测接入一路模拟网络摄像头）。
一、配置体系总览
1.1 三层配置文件
motionEye 的配置按「服务端 → motion 全局 → 单摄像头」分为三层，全部落在配置目录（默认 /etc/motioneye/）下。实测目录内容：
ls -la /etc/motioneye/
实测回显：
-rw-r--r-- 1 root root 257 10月29日 20:52 camera-1.conf
-rw-r--r-- 1 root root 3089 10月29日 21:07 camera-2.conf
-rw-r--r-- 1 root root 631 10月29日 21:04 motion.conf
-rw-r--r-- 1 root root 2522 10月29日 20:46 motioneye.conf
| 文件 | 读取者 | 职责 | 修改后生效方式 |
|---|---|---|---|
motioneye.conf | motionEye 服务 | Web 监听、日志、媒体路径、motion 进程管理等服务端参数 | 重启 motionEye 服务 |
motion.conf | motion 主进程 | motion 全局参数 + 摄像头配置文件清单 + 界面管理账号凭据 | 随 motion 线程重载/重启 |
camera-N.conf | motion 各摄像头线程 | 单路摄像头的接入、侦测、录像、抓图、实时流参数 | 随 motion 线程重载/重启 |
1.2 管理区与有效区
motion.conf 与 camera-N.conf 都由两个区域组成，这是理解 motionEye 配置的关键：
- 管理区：以
# @key value形式出现的注释行，是 motionEye 自己管理的界面层状态（账号、开关、摄像头元数据）。保存界面配置时 motionEye 会整体重写这些行，手工修改会在下次界面保存时被覆盖； - 有效区：不带 @ 前缀的普通键，会被 motion 守护进程直接读取，遵循 motion 原生语法。
实测 motion.conf 全文（一个只有全局、尚未挂全局参数的典型状态）：
# @relay_secret 9a4f91fc20901cdcd67fdbbd432bdc2392b0975b3ac1fbe766e58c5e849a8438
# @client_secret 86f6950a81cb35b043d37d7b530966a971e36b381a256230816a06850aa57d7c
# @admin_username admin
# @normal_username user
# @admin_password $argon2id$v=19$m=65536,t=3,p=4$E3Xs/FuOAq5shnfgZRkRdg$7GI2DL7sjnwpdqJJpTibKEKMO9g1shoxLhaKLc+bV1c
# @normal_password $argon2id$v=19$m=65536,t=3,p=4$nBvFA9SdBauWhJXTnexyaQ$7nYB1Ccb82c5Q61eggAC66l7UuqnmE71c6lEXsLSPY4
# @enabled on
# @lang en
setup_mode off
webcontrol_port 7999
webcontrol_interface 1
webcontrol_localhost on
webcontrol_parms 2
camera camera-2.conf
要点解读：账号密码只存 argon2id 哈希（$argon2id$v=19$m=65536,t=3,p=4$...，无法还原明文）；relay_secret/client_secret 是 motionEye 与 motion 之间事件中继的内部令牌，随部署自动生成；最后一行 camera camera-2.conf 把摄像头配置文件挂进 motion，每添加一路摄像头就多一行。
1.3 三种查看与修改途径
| 途径 | 操作方式 | 适用场景 |
|---|---|---|
| Web 界面 | 浏览器打开设置面板逐项调整 | 日常管理，保存即生效 |
| HTTP 配置接口 | GET /config/<id>/get/、全量 POST /config/<id>/set/ | 自动化脚本（注意 set 是全量覆盖，见第六节） |
| 直接编辑文件 | 改 /etc/motioneye/*.conf 后重启服务 | 批量调整、迁移、界面覆盖不到的底层参数 |
二、motioneye.conf：服务端参数
该文件在首次启动时生成，实测全文（含注释）约 120 行，按功能域分组解读如下。
2.1 路径类参数
# path to the configuration directory (must be writable by motionEye)
conf_path /etc/motioneye
# path to the directory where pid files go (must be writable by motionEye)
run_path /run/motioneye
# path to the directory where log files go (must be writable by motionEye)
log_path /var/log/motioneye
# default output path for media files (must be writable by motionEye)
media_path /var/lib/motioneye
解说：四个路径决定 motionEye 的数据布局。media_path 是新摄像头媒体目录的默认父目录（每路摄像头在其下按名称建子目录）；conf_path 必须与实际挂载的配置目录一致，迁移部署时最容易出错的就是它。
2.2 服务监听与日志
# the log level (use quiet, error, warning, info or debug)
log_level info
# the IP address to listen on
# (0.0.0.0 for all interfaces, 127.0.0.1 for localhost)
listen 0.0.0.0
# the TCP port to listen on
port 8765
解说：listen 0.0.0.0 + port 8765 是 Web 服务监听。内网部署建议保持 8765 并在防火墙/反代层收敛；log_level 排障时可临时改 debug，motionEye 日志会细化到每个 HTTP 请求（改后需重启服务生效）。
2.3 motion 进程管理参数
# whether motion HTTP control interface listens on
# localhost or on all interfaces
motion_control_localhost true
# the TCP port that motion HTTP control interface listens on
motion_control_port 7999
# interval in seconds at which motionEye checks if motion is running
motion_check_interval 10
# whether to restart the motion daemon when an error occurs while communicating with it
motion_restart_on_errors false
解说：motionEye 通过 motion 的 HTTP 控制接口（motion_control_port 7999）下发侦测启停、手动抓拍等指令，motion_control_localhost true 把该接口限制在本机访问（安全默认值，不建议改）。motion_check_interval 10 是 motionEye 每 10 秒对 motion 的存活巡检周期。实测在服务器上直接验证该控制接口的可达性：
curl -s http://127.0.0.1:7999/0/detection/status
实测回显：
Camera 1 Detection status ACTIVE
2.4 清理与超时参数
# interval in seconds at which the janitor is called
# to remove old pictures and movies
cleanup_interval 43200
# timeout in seconds to wait for media files list
list_media_timeout 120
# timeout in seconds to wait for zip file creation
zip_timeout 500
# timeout in seconds to wait for timelapse creation
timelapse_timeout 500
解说：cleanup_interval 43200（12 小时）是内置清理任务周期，配合界面里每摄像头设置的「保留天数/占用百分比」删除过期媒体；三个 timeout 与媒体量直接相关——媒体目录文件数过大时，zip 打包与延时摄影合成容易顶到上限，此时调大对应值并注意磁盘读放大。
2.5 功能开关参数
# enable add and remove cameras from UI
add_remove_cameras true
# enable SMB shares (requires motionEye to run as root and cifs-utils installed)
smb_shares false
# enables shutdown and rebooting after changing system settings
# (such as wifi settings or time zone)
enable_reboot false
# overrides the hostname (useful if motionEye runs behind a reverse proxy)
#server_name motionEye
解说：add_remove_cameras true 控制界面能否增删摄像头（锁死摄像头清单的场合可关）；smb_shares/enable_reboot 依赖 root 权限与系统组件，容器化部署通常保持默认关闭；server_name 在反向代理后面域名显示不正确时启用。
三、motion.conf：motion 全局参数
3.1 有效区逐项解读
| 键 | 实测值 | 作用 |
|---|---|---|
setup_mode | off | 界面调试模式（on 时 motionEye 会显示更多底层状态），生产保持 off |
webcontrol_port | 7999 | motion HTTP 控制接口端口，与 motioneye.conf 的 motion_control_port 对应 |
webcontrol_interface | 1 | 控制接口返回格式（0 纯文本，1 为 motionEye 期望的增强格式） |
webcontrol_localhost | on | 控制接口仅监听本机 |
webcontrol_parms | 2 | 允许通过控制接口读写参数的级别（0/1 只读基础集，2 可写全量） |
camera camera-2.conf | — | 挂载单摄像头配置文件，一行一路 |
3.2 实测：webcontrol 参数只读验证
webcontrol_parms 2 打开了全量参数读写能力，实测查询 motion 全局段：
curl -s "http://127.0.0.1:7999/0/config/list?query=threshold" | head -12
实测回显：
daemon = off
setup_mode = off
pid_file = (null)
log_file = (null)
log_level = 5
log_type = ALL
quiet = on
native_language = on
watchdog_tmo = 30
watchdog_kill = 10
解说：这是 motion 主线程（全局段）的运行时快照，排障时用它核对 motion 实际生效的参数比翻文件更可靠。
四、camera-N.conf：摄像头参数矩阵（核心）
以实测的 camera-2.conf（一路 motion 本地摄像头，接入 HTTP MJPEG 模拟网络摄像头）为样本，按功能域展开。先看文件管理区：
# @enabled on
# @proto netcam
# @url http://motioneye-0.44.0-camsrc:8090/cam-a
# @id 2
# @admin_only off
camera_name Camera2
解说：@proto netcam 与 @url 记录了接入形态与流地址——这正是「网络摄像头」与「简单 MJPEG 摄像头」两种形态在文件层的分界（简单 MJPEG 的配置文件实测只有 5 行，见 4.8）。
4.1 视频源与画面参数
| 键 | 实测值 | 说明 |
|---|---|---|
netcam_url | http://motioneye-0.44.0-camsrc:8090/cam-a | 摄像头流地址（RTSP 摄像头则为 rtsp://...） |
netcam_params | keepalive = off,tolerant_check = on | 连接保活与兼容性开关，motionEye 按流类型自动生成 |
framerate | 2 | 处理帧率（侦测/录像的最大帧率），越大越耗 CPU |
auto_brightness | off | 自动亮度调节 |
rotate | 0 | 画面旋转角度（0/90/180/270） |
mask_privacy | （空） | 隐私遮挡区（永久涂黑区域），界面可框选 |
camera_name | Camera2 | 摄像头名，同时是媒体子目录名 |
💡 技术拓展：
framerate 2看似很低，实为 motion 系 NVR 的性能核心——侦测/录像帧率与实时流帧率是解耦的（实时流由 stream_maxrate 单独控制）。把处理帧率压在 2-5fps 可让低端服务器稳定跑多路，代价是录像回放偏"幻灯片"；需要流畅录像时调到 10-15fps 并同步评估 CPU。
4.2 运动侦测参数
| 键 | 实测值 | 说明 |
|---|---|---|
threshold | 1999 | 帧差分判定阈值：单帧变化像素数超过该值判为运动 |
threshold_maximum | 0 | 阈值上限（0 不限制），配合阈值自动调优防漂移 |
threshold_tune | off | 阈值自动调优 |
noise_tune | on | 噪声水平自动调优 |
noise_level | 33 | 噪声阈值基准（noise_tune off 时生效） |
lightswitch_percent | 0 | 光线突变忽略百分比（0 关闭） |
despeckle_filter | （空） | 去噪组合滤波（如 EedDl） |
minimum_motion_frames | 20 | 连续多少帧判定为运动才触发事件（防瞬态误报） |
event_gap | 30 | 事件间隔秒数（持续运动合并为同一事件） |
smart_mask_speed | 0 | 智能遮罩学习速度（0 关闭） |
mask_file | （空） | 静态侦测遮罩图（PGM） |
locate_motion_mode | off | 画面上标记运动区域（redbox 样式，仅展示） |
实测核验文件值与运行值：
grep -E '^(threshold|minimum_motion_frames|event_gap)' /etc/motioneye/camera-2.conf
实测回显：
threshold 1999
minimum_motion_frames 20
event_gap 30
⚠️ 实测注意（阈值单位换算）：界面上「画面变化阈值」显示的是百分比（实测
frame_change_threshold = 0.6507161458333334），落盘文件是换算后的像素数：640x480 = 307200 像素，307200 × 0.6507% ≈ 1999，与文件值吻合。排查"侦测不触发/太灵敏"时，先在文件层确认像素阈值，再回界面改百分比。另实测发现 motion webcontrol 对/0/config/get?query=threshold返回threshold = 1500（motion 主线程默认值），与 camera-2.conf 的 1999 不一致——webcontrol 编号语境与 motionEye 界面编号不一一对应，排查时以 camera-N.conf 与界面设置为准。
4.3 录像参数
| 键 | 实测值 | 说明 |
|---|---|---|
movie_output | on | 运动触发录像总开关 |
movie_output_motion | off | 额外输出侦测区域可视化影片 |
movie_codec | mp4:libx264 | 封装:编码（mp4:h264_hw 等硬件编码视镜像支持） |
movie_quality | 75 | 编码质量（1-100） |
movie_filename | %Y-%m-%d/%H-%M-%S | 录像文件名模板（自带日期分层） |
movie_max_time | 0 | 单文件最大秒数（0 不限制） |
movie_passthrough | off | H.264 源直通录制（不转码，需源支持） |
pre_capture / post_capture | 1 / 1 | 事件前/后缓冲帧数 |
实测录像产物与元数据（testsrc 画面连续变化触发的事件）：
find /var/lib/motioneye -name '*.mp4' -exec ls -la {} \;
实测回显：
-rw-r--r-- 1 1000 1000 786011 10月29日 20:49 /var/lib/motioneye/Camera2/2026-10-29/20-49-29.mp4
ffmpeg -hide_banner -i /var/lib/motioneye/Camera2/2026-10-29/20-49-29.mp4 2>&1 | grep -E 'Duration|Stream #'
实测回显：
Duration: 00:00:37.51, start: 0.000000, bitrate: 454 kb/s
Stream #0:0[0x1](und): Video: h264 (Constrained Baseline) (avc1 / 0x31637661), yuv420p(progressive), 640x480, 454 kb/s, 2.03 fps, 2 tbr, 16384 tbn (default)
解说：37.51 秒的事件时长与 event_gap 30 直接相关——运动持续 + 30 秒无新触发才收尾文件；2.03 fps 的低帧率即 framerate 2 的体现。
4.4 抓图参数
| 键 | 实测值 | 说明 |
|---|---|---|
picture_output | on | 运动触发抓图 |
picture_output_motion | off | 侦测区域可视化抓图 |
picture_filename | %Y-%m-%d/%H-%M-%S | 抓图文件名模板 |
picture_quality | 85 | JPEG 质量 |
snapshot_interval | 0 | 定时快照间隔秒（0 关闭） |
snapshot_filename | %Y-%m-%d/%H-%M-%S | 快照文件名模板 |
emulate_motion | off | 定时快照的另一种实现（模拟运动事件），与 snapshot_interval 二选一 |
实测手动快照（界面「抓拍」按钮，HTTP 侧 POST /action/2/snapshot 返回 OK）后的产物：
find /var/lib/motioneye -name '*.jpg' -exec ls -la {} \;
实测回显：
-rw-r--r-- 1 1000 1000 26140 10月29日 20:50 /var/lib/motioneye/Camera2/2026-10-29/20-50-05.jpg
-rw-r--r-- 1 1000 1000 25657 10月29日 20:50 /var/lib/motioneye/Camera2/2026-10-29/20-50-31.jpg
4.5 实时流参数
| 键 | 实测值 | 说明 |
|---|---|---|
stream_localhost | on | 实时流仅本机可看（远程查看走 motionEye 转发/反代） |
stream_port | 9082 | motion 每路摄像头的 MJPEG 实时流端口（每路递增） |
stream_maxrate | 5 | 实时流最大帧率 |
stream_quality | 85 | 实时流 JPEG 质量 |
stream_motion | 0 | 1 时实时流在无查看者时降帧省资源 |
stream_auth_method | 0 | 流认证方式（0 无，1/2 Basic/Digest） |
stream_authentication | （空） | 流认证凭据 |
解说：motionEye 界面的实时画面并非直连 motion 的 9082 端口，而是由 motionEye 服务转发（受界面权限控制）；stream_localhost on 保证了 motion 原始流不暴露到外部网络。需要外部直连时改 stream_localhost off 并配 stream_auth_method。
4.6 事件回调参数
实测 camera-2.conf 尾部的四条回调：
on_event_start /usr/local/lib/python3.13/dist-packages/motioneye/scripts/relayevent.sh "/etc/motioneye/motioneye.conf" start %t
on_event_end /usr/local/lib/python3.13/dist-packages/motioneye/scripts/relayevent.sh "/etc/motioneye/motioneye.conf" stop %t
on_movie_end /usr/local/lib/python3.13/dist-packages/motioneye/scripts/relayevent.sh "/etc/motioneye/motioneye.conf" movie_end %t %f
on_picture_save /usr/local/lib/python3.13/dist-packages/motioneye/scripts/relayevent.sh "/etc/motioneye/motioneye.conf" picture_save %t %f
解说：motionEye 把界面上的通知/上传动作（邮件、Telegram、Webhook、上传网盘、自定义命令）翻译成这四条 motion 原生钩子，relayevent.sh 再把事件（携带 %t 摄像头号、%f 文件路径）经 relay_secret 鉴权回传给 motionEye 服务统一分发。这就是「界面里勾选通知 = 自动改写回调行」的机制，理解这一点就能解释：界面删除通知配置时，对应回调行也会被移除。
4.7 简单 MJPEG 摄像头的配置文件对照
同为接入但形态不同，camera-1.conf（简单 MJPEG）实测全文：
# @enabled on
# @proto mjpeg
# @url http://motioneye-0.44.0-camsrc:8090/cam-a
# @id 1
# @admin_only off
camera_name Camera1
解说：有效区只有 camera_name 一行——这种形态不占用 motion 摄像头线程，motionEye 仅在服务层转发画面，因此 4.1-4.6 的全部能力（侦测/录像/抓图/事件回调）均不可用，也不会生成 stream_port 实时流。选型接入时务必按需求选对形态。
五、界面键与文件键映射总表
motionEye 界面（HTTP 配置接口）键名与 motion 文件键名并非一一对应，以下为实测核对的高频映射（来源：GET /config/2/get/ 与 camera-2.conf 对照）：
| 界面键（UI） | 文件键（motion） | 实测对照 |
|---|---|---|
enabled | # @enabled + 文件区 | on |
framerate | framerate | 2 |
rotation | rotate | 0 |
motion_detection | # @enabled / webcontrol | 侦测启停 |
frame_change_threshold | threshold | 0.6507% → 1999 像素（按分辨率换算） |
auto_threshold_tuning | threshold_tune | off |
noise_level | noise_level | 界面 13 / 文件 33（noise_tune 自适应所致，文件值以提交时为准） |
minimum_motion_frames | minimum_motion_frames | 20 |
event_gap | event_gap | 30 |
movies | movie_output | true / on |
movie_format | movie_codec | "mp4:libx264" |
movie_quality | movie_quality | 75 |
movie_file_name | movie_filename | %Y-%m-%d/%H-%M-%S |
max_movie_length | movie_max_time | 0 |
pre_capture/post_capture | 同名 | 1 / 1 |
still_images | picture_output | true / on |
image_file_name | picture_filename | %Y-%m-%d/%H-%M-%S |
image_quality | picture_quality | 85 |
snapshot_interval | snapshot_interval | 0 |
video_streaming | stream_* 族 | 界面开关组 |
streaming_port | stream_port | 9082 |
streaming_framerate | stream_maxrate | 5 |
streaming_quality | stream_quality | 85 |
left_text/right_text | text_left/text_right | Camera2 / %Y-%m-%d\n%T |
text_scale | text_scale | 2（实测直接编辑后界面回读一致） |
working_schedule 族 | （存管理区/调度段） | 周一至周日时段 |
email_notifications_* / telegram_notifications_* / web_hook_notifications_* | on_event_* 回调行 | 由 relayevent.sh 中转 |
解读：界面键以「用户语义」命名（movie vs picture、frame_change_threshold 百分比），文件键沿 motion 术语。写自动化脚本时应以 GET /config/<id>/get/ 返回的界面键为准，不要按 motion 文档猜键名。
六、修改生效与验证
6.1 界面保存即重载
界面（或 HTTP set）保存后，motionEye 会改写配置文件并重载 motion 对应线程，无需手工重启。实测全量提交 Camera2 配置开启录像后，文件即时变化：
grep -E '^(movie_output|movie_codec)' /etc/motioneye/camera-2.conf
实测回显：
movie_codec mp4:libx264
movie_output on
6.2 直接编辑文件必须重启服务
绕过界面直接改文件时，motion 不会感知变化，必须重启 motionEye（或其托管的 motion）。实测过程：把 camera-2.conf 的 text_scale 由 1 改为 2：
grep '^text_scale' /etc/motioneye/camera-2.conf
实测回显：
text_scale 2
重启服务后通过界面接口回读验证生效：
curl -s -b cookies.txt http://127.0.0.1:8765/config/2/get/ | python3 -c "import json,sys; print('UI text_scale =', json.load(sys.stdin)['text_scale'])"
实测回显：
UI text_scale = 2
重启方式小结：pip/系统包部署用 systemctl restart motioneye（或 meyectl stopserver && meyectl startserver -c /etc/motioneye/motioneye.conf）；容器部署直接重启对应容器/服务本体。
6.3 生效验证三件套
- 文件层：
grep <键> /etc/motioneye/camera-N.conf确认落盘； - 运行层：webcontrol
curl http://127.0.0.1:7999/0/config/get?query=<motion键>（注意 4.2 的编号语境差异，以文件与界面为准）； - 界面层：
GET /config/<id>/get/回读界面键值。
三层一致才算生效，任一层不一致即指向 6.2 类的"改了没重启"或 4.2 类的单位换算误区。
七、配置备份与恢复
7.1 内装备份接口
curl -s -b cookies.txt -o backup.tar.gz -w 'http_code=%{http_code} bytes=%{size_download}\n' http://127.0.0.1:8765/config/backup/ && tar tzf backup.tar.gz
实测回显：
http_code=200 bytes=1528
motion.conf
camera-2.conf
camera-1.conf
解说：备份包即配置目录下的 motion.conf 与全部 camera-N.conf（不含 motioneye.conf），界面入口为「设置 → 常规 → 下载配置文件」；恢复用同页上传（POST /config/restore/），恢复后 motion 线程自动重载。
7.2 文件级备份
直接定时打包 /etc/motioneye/ 全目录即可覆盖内装备份未包含的 motioneye.conf；媒体数据独立于配置，按 /var/lib/motioneye/<摄像头名>/<日期>/ 结构做目录级备份。两份数据 + 一份备份策略（建议至少保留媒体 7 天滚动 + 配置每周全量）即可满足小型 NVR 的容灾需要。
八、参考链接
- motion 官方配置文档（文件键权威出处）：https://motion-project.github.io/motion_config.html
- motionEye 官方仓库与 Wiki：https://github.com/motioneye-project/motioneye
- 本专栏入门篇：《motionEye 0.44.0 介绍与选型指南》
- 本专栏部署篇：《motionEye 0.44.0 Docker Compose 部署指南》
- 本专栏命令篇：《motionEye 0.44.0 常用 CLI 命令与配置文件管理详解》