motionEye 0.44.0 常用 CLI 命令与配置文件管理详解

目标：给 motionEye 0.44.0 的日常运维提供一份命令与配置文件管理手册——服务进程的启动停止、motion 守护进程与 HTTP 控制接口、事件处理子命令、配置备份恢复与直接编辑生效链路。全部命令与回显均在 Ubuntu 22.04 服务器（motionEye 0.44.0 + motion 4.7.1）实测取得。

篇型说明：motionEye 没有对外承诺稳定、有文档的 REST API（Web 界面背后的接口未公开文档），其运维面由「meyectl 命令行 + motion 命令行 + motion webcontrol HTTP 接口 + 三层配置文件」构成，故本文按命令与配置文件管理组织。

一、命令体系总览

1.1 三个命令面

motionEye 的运维命令分三个层面，各管一段：

命令面	归属	典型用途
`meyectl`	motionEye 服务	服务启动/停止、版本查看、事件通知与回调处理
`motion`	motion 守护进程	版本查看、裸用 motion 引擎（motionEye 托管下一般不直接操作）
motion webcontrol	motion HTTP 接口	运行时查参、侦测启停、手动抓拍等即时动作

三者关系：motionEye（meyectl startserver）按 motioneye.conf 的 motion_control_port（默认 7999）与 motion 通信，webcontrol 是这条管理通道的 HTTP 面。

1.2 命令速查表

meyectl -v                      # 服务版本
meyectl startserver [-c 配置文件] [-b] # 启动服务（-b 后台）
meyectl stopserver              # 停止服务
meyectl sendmail/sendtelegram/webhook/shell  # 事件处理子命令
motion -h                       # motion 版本与用法
curl http://127.0.0.1:7999/0/... # webcontrol 运行时控制

二、meyectl：服务管理命令

2.1 版本与总帮助

meyectl -v

实测回显：

motionEye 0.44.0

meyectl --help

实测回显：

unknown command "--help"

usage: meyectl [command] [-c CONFIG_FILE] [-d] [-h] [-l] [-v] [command options...]

available commands:
  startserver
  stopserver
  sendmail
  sendtelegram
  webhook
  shell

options:
  -c CONFIG_FILE  use a config file instead of built-in defaults
  -d              enable debugging, overriding log level from config file
  -h              print this help and exit
  -l              log to file instead of standard error
  -v              print program version and exit

type "meyectl [command] -h" for help on a specific command

解说：总帮助必须用 -h（--help 会被当作命令名拒绝），子命令六个：两个服务管理 + 四个事件处理。

2.2 startserver：启动服务

meyectl startserver -h

实测回显：

usage: meyectl startserver [-c CONFIG_FILE] [-d] [-h] [-l] [-v] [-b]

options:
  -c CONFIG_FILE  use a config file instead of built-in defaults
  -d              enable debugging, overriding log level from config file
  -h              print this help and exit
  -l              log to file instead of standard error
  -v              print program version and exit
  -b              start the server in background (daemonize)

前台启动与正常日志（-c 显式指定配置文件是官方推荐的启动姿势）：

meyectl startserver -c /etc/motioneye/motioneye.conf

实测回显：

[meyectl] 20:46:41 INFO: server: starting motioneye server 0.44.0
[meyectl] 20:46:41 INFO: motion: not running, trying to start it
[meyectl] 20:46:42 INFO: motion: started
[meyectl] 20:46:42 INFO: server: listening on http://0.0.0.0:8765

解说：启动序列值得注意——motionEye 先自检 motion 未运行则代为拉起 motion（日志 motion: started），再监听 8765。这就是为何永远不需要单独启动 motion：它是 motionEye 的受管子进程。裸机部署长期运行时用 -b 后台化并配合 systemd 托管（见 2.5）。

2.3 stopserver：停止服务

meyectl stopserver

实测回显：

configure_logging cmd motioneye: False
configure logging to file: None
server is not running

解说：stopserver 通过 /run/motioneye/ 下的 pid 文件定位进程。实测在本机以 motion 用户身份运行服务、root 身份执行 stopserver 时出现 "server is not running"——多数是 pid 文件权限/运行身份不一致所致，先用 ps -ef | grep meyectl 确认实际运行用户，再用同一身份执行 stopserver。长期托管场景更建议 systemctl stop motioneye 走 systemd 生命周期。

2.4 事件处理子命令

这四个子命令是 C1 篇 4.6 事件回调机制的下游：relayevent.sh 收到 motion 事件后，按界面里配置的渠道选择对应子命令完成通知。

webhook（向任意 URL 发 HTTP 请求）：

meyectl webhook -h

实测回显：

usage: meyectl webhook [-c CONFIG_FILE] [-d] [-h] [-l] [-v] method url

positional arguments:
  method          the HTTP method to use
  url             the URL for the request

options:
  -c CONFIG_FILE  use a config file instead of built-in defaults
  -d              enable debugging, overriding log level from config file
  -h              print this help and exit

实测一次真实调用（GET 一个本机地址，目标服务按安全策略拒绝未认证请求）：

meyectl webhook GET http://127.0.0.1:8765/login/ 2>&1 | tail -3

实测回显：

configure_logging cmd webhook: False
configure logging to file: None
2026-10-29 21:03:50: [webhook]    ERROR: failed to call webhook: HTTP Error 403: Forbidden

解说：webhook 子命令确实发出了请求并记录了失败原因——排障时（界面里 Webhook 通知不工作）可以先用它手工复现，快速区分「网络/URL 问题」与「接收方拒绝」。

sendtelegram（Bot API 推送）：

meyectl sendtelegram -h

实测回显：

usage: meyectl sendtelegram [-c CONFIG_FILE] [-d] [-h] [-l] [-v]
                            api chatid motion_camera_id moment timespan

Send Telegram using bot api

positional arguments:
  api               telegram api key
  chatid            telegram chat room id
  motion_camera_id  the id of the motion camera
  moment            the moment in ISO-8601 format

sendmail（邮件通知）：实测 meyectl sendmail -h 直接抛 Python Traceback（IndexError，参数不足未做友好处理），是 0.44.0 的已知粗糙点；其完整用法应通过界面「邮件通知」配置并保存，由事件回调带参调用，手工排障时建议直接看 motionEye 日志中的邮件发送记录。

shell（执行界面配置的任意命令通知）：meyectl shell -h 仅显示通用 options，无专属参数——它按配置文件里的通知定义执行外部命令，实际参数由 relayevent.sh 注入。

2.5 systemd 托管（pip/系统包部署）

pip 安装或系统包部署时，推荐用 systemd 托管实现开机自启与崩溃拉起。单位文件要点（标准 systemd 写法，路径按实际安装位置调整）：

[Unit]
Description=motionEye NVR
After=network.target

[Service]
Type=simple
User=motion
ExecStart=/usr/local/bin/meyectl startserver -c /etc/motioneye/motioneye.conf
Restart=on-failure

[Install]
WantedBy=multi-user.target

常用操作：systemctl daemon-reload && systemctl enable --now motioneye 启用自启；systemctl restart motioneye 在直接改配置文件后重载（对应配置篇 6.2 的生效链路）。

三、motion：守护进程命令

3.1 版本与用法

motion -h | head -2

实测回显：

motion Version 4.7.1, Copyright 2000-2024 Jeroen Vreeken/Folkert van Heusden/Kenneth Lavrsen/Motion-Project maintainers

Home page :	 https://motion-project.github.io/

3.2 motionEye 托管下的运行形态

motionEye 托管时 motion 以前台模式运行。实测进程（精简环境无 ps 时可直接读内核进程表）：

for p in /proc/[0-9]*/cmdline; do tr "\0" " " < $p; echo; done | grep '/usr/bin/motion'

实测回显：

/usr/bin/motion -n -c /etc/motioneye/motion.conf -d 5

参数解读：-n 前台运行（不 fork），-c 指定 motionEye 生成的 motion.conf，-d 5 日志级别 NTC。运维要点：不要手工 kill motion——motionEye 有 motion_check_interval（默认 10 秒）巡检并按需重启它；误杀只会造成短暂摄像头离线，不会损坏状态。

四、motion webcontrol：运行时 HTTP 控制接口

4.1 侦测状态与启停

curl -s "http://127.0.0.1:7999/0/detection/status"

实测回显：

Camera 1 Detection status ACTIVE

启停操作（界面上每摄像头的「运动检测」开关即走此通道）：

curl -s "http://127.0.0.1:7999/0/detection/pause"; echo; curl -s "http://127.0.0.1:7999/0/detection/status"; echo; curl -s "http://127.0.0.1:7999/0/detection/start"; echo; curl -s "http://127.0.0.1:7999/0/detection/status"

实测回显：

Camera 0 Detection paused
Done

Camera 1 Detection status PAUSE

Camera 0 Detection resumed
Done

Camera 1 Detection status ACTIVE

解说：暂停后 status 返回 PAUSE（注意词形），恢复后回到 ACTIVE；同时可见同一动作的执行响应自报 Camera 0、状态查询自报 Camera 1——webcontrol 各端点间编号语境不统一的又一实证，排障时以动作产生的实际效果为准。

4.2 运行时参数查询

curl -s "http://127.0.0.1:7999/0/config/get?query=threshold"

实测回显：

Camera 0
threshold = 1500
Done

查询全局参数清单（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

⚠️ 实测注意（编号语境）：webcontrol 的线程编号（/0/、/1/…）与 motionEye 界面的摄像头 ID（1 起）不保证一一对应，实测 /0/config/get?query=threshold 返回 1500（motion 主线程默认值）而 camera-2.conf 落盘值为 1999（界面百分比按分辨率换算）。用 webcontrol 改参排障前，先用 detection/status 或修改一个可观测参数验证编号映射，再动手；正式变更一律以界面或配置文件为准。

4.3 即时动作

curl -s -X GET -o /dev/null -w '%{http_code}\n' "http://127.0.0.1:7999/0/action/snapshot"

实测回显：

常用动作端点：/0/action/snapshot（抓拍）、/0/action/makemovie（开始录像）、/0/action/snapshot 与 %t 占位符配合可做脚本化巡检。界面上的「抓拍/录制」按钮最终也落到这些动作（motionEye 侧封装为 POST /action/<id>/snapshot，实测返回 OK 并在媒体目录落盘 jpg）。

五、配置文件管理实操

5.1 配置备份与恢复

内装备份接口（界面：设置 → 常规 → 下载配置文件）：

curl -s -b cookies.txt -o backup.tar.gz -w 'http_code=%{http_code} type=%{content_type} bytes=%{size_download}\n' http://127.0.0.1:8765/config/backup/ && tar tzf backup.tar.gz

实测回显：

http_code=200 type=application/x-compressed bytes=1528
motion.conf
camera-2.conf
camera-1.conf

文件级备份（补齐内装备份不含的 motioneye.conf）：

tar czf motioneye-conf-$(date +%F).tar.gz -C /etc/motioneye motioneye.conf motion.conf camera-1.conf camera-2.conf && ls -la motioneye-conf-*.tar.gz

实测回显：

-rw-r--r-- 1 root root 2473 Oct 29 21:05 motioneye-conf-2026-10-29.tar.gz

解说：两份备份建议都做——内装备份便于在界面上传恢复（POST /config/restore/），文件级备份覆盖服务端参数；摄像头多时可改为整目录打包（tar czf ... -C / etc/motioneye）。恢复配置后需重启服务或等 motion 线程重载。

5.2 直接编辑与生效验证

以调整画面文本叠加字号为例的完整链路（实测记录）：

sed -i 's/^text_scale 1$/text_scale 2/' /etc/motioneye/camera-2.conf && 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

注意两条红线：管理区（# @ 行）手工改动会被界面保存覆盖；直接编辑后必须重启（见 2.5），否则 motion 线程不感知。

5.3 配置迁移

迁移到新服务器/新路径时的核对清单（按序）：

整体拷贝 /etc/motioneye/ 与 /var/lib/motioneye/；
核对新机 motioneye.conf 的四个路径（conf_path/run_path/log_path/media_path）与新布局一致，media_path 不一致会导致界面看不到旧媒体（媒体索引按摄像头 target_dir 定位，camera-N.conf 里的 target_dir 也要一并核对）；
启动服务后用 meyectl -v、界面登录、媒体列表三项做迁移验收；
摄像头流地址含主机名的（如本文 http://motioneye-0.44.0-camsrc:8090/cam-a）检查 DNS/hosts 解析是否可达。

六、参考链接

motionEye 官方仓库与 Wiki（部署/FAQ）：https://github.com/motioneye-project/motioneye
motion 官方文档（motion 命令与配置权威出处）：https://motion-project.github.io/
本专栏入门篇：《motionEye 0.44.0 介绍与选型指南》
本专栏部署篇：《motionEye 0.44.0 Docker Compose 部署指南》
本专栏配置篇：《motionEye 0.44.0 配置参数详解》