SentryShot v0.3.11 配置参数详解

本文以 v0.3.11 首次启动自动生成的默认配置为基准，逐项讲解 SentryShot 的配置体系，关键参数均附实测验证（Debian 12 + Docker Compose 部署，2026-10-30）。

一、配置体系总览

SentryShot 的持久化分为四个位置（本文部署目录为 /opt/sentryshot/stack/，服务端内对应路径见全局配置的 config_dir/storage_dir）：

位置	内容	修改方式
`configs/sentryshot.toml`	全局配置 + 插件开关	手工编辑后 `docker compose restart sentryshot`
`configs/monitors/<id>.json`	每个摄像头的配置	API `PUT /api/monitor` 保存时自动落盘
`configs/accounts.json`	账号（argon2id 哈希）	API 建号/改密时自动落盘
`storage/`	录像（`recordings/年/月/日/<id>/`）、事件库（`eventdb/`）、日志库（`logs/`）	运行时写入，不手工改

v0.3.4 起官方文档将配置说明移入了设置页面，本文按实测补充。修改 sentryshot.toml 后需要重启服务；修改摄像头配置后需要调用 POST /api/monitor/restart?id=<id>（细节见《SentryShot v0.3.11 HTTP API 使用详解》）。

二、全局配置 sentryshot.toml

首次启动自动生成的默认配置全文（实测，docker logs 可见 Generating '/app/configs/sentryshot.toml' and exiting..，生成即退出）：

# Port app will be served on.
port = 2020

# Directory where recordings will be stored.
storage_dir = "/app/storage"

# Directory where configs will be stored.
config_dir = "/app/configs"

# Directory where the plugins are located.
plugin_dir = "/app/plugins"


# Maximum allowed storage space in GigaBytes.
# Recordings are delete automatically before this limit is exceeded.
max_disk_usage = 100

# Write debug logs to stdout. Still available from the logs page.
debug_log_stdout = true


# PLUGINS

# Authentication. One must be enabled.

# Basic Auth.
[[plugin]]
name = "auth_basic"
enable = true

# No authentication.
[[plugin]]
name = "auth_none"
enable = false



# Motion detection.
# Unreliable in most situations.
[[plugin]]
name = "motion"
enable = true

# Object detection.
# Enabling will generate a `object_detction.toml` file.
[[plugin]]
name = "object_detection"
enable = false


# Thumbnail downscaling.
# Downscale video thumbnails to improve page load times and data usage.
[[plugin]]
name = "thumb_scale"
enable = true


# MQTT API.
# Documentation: ./docs/4_API.md
[[plugin]]
name = "mqtt"
enable = false
host = "127.0.0.1"
port = 1883
#username = ""
#password = ""

顶层参数

参数	默认值	说明
`port`	`2020`	服务端固定监听端口（宿主映射端口由部署编排决定，本文为 8247→2020）
`storage_dir`	`"/app/storage"`	录像/事件/日志存储根目录（编排放射到 `./storage`）
`config_dir`	`"/app/configs"`	配置根目录（编排放射到 `./configs`）
`plugin_dir`	`"/app/plugins"`	插件目录，一般不动
`max_disk_usage`	`100`	存储上限（GB），超限自动删除最旧录像段
`debug_log_stdout`	`true`	是否把 DEBUG 级日志写 stdout

插件段（`[[plugin]]`）

TOML 的 [[plugin]] 是数组写法：每个 [[plugin]] 块描述一个插件，靠 name 区分、enable 控制开关。认证插件必须启用一个，否则启动失败，实测日志（默认配置两个认证插件都未启用时反复重启）：

Please enable one of the authentication plugins in the generated sentryshot.toml file. See docs for more info

插件	默认	说明
`auth_basic`	`false`	HTTP Basic 认证，账号存 `accounts.json`（推荐）
`auth_none`	`false`	免认证，仅建议首次引导建号时临时开启
`motion`	`true`	移动侦测（官方注释明确提示 "Unreliable in most situations"，可靠性有限）
`object_detection`	`false`	目标检测，启用后会生成 `object_detction.toml`（官方注释原文拼写即如此）
`thumb_scale`	`true`	缩略图降采样，降低页面加载与流量
`mqtt`	`false`	MQTT API（127.0.0.1:1883，可配用户名/密码）

debug_log_stdout 实测

改为 false 并重启后，stdout 里不再出现 [DEBUG] 行（docker logs --since 30s 仅剩 INFO 级启动行）：

[INFO] App: loading plugin auth_basic
[INFO] App: loading plugin motion
[INFO] App: loading plugin thumb_scale
[INFO] App: Serving app on port 2020

恢复 true 后 DEBUG 行（如 [DEBUG] cam2: Monitor: recorder: starting recording session）重新出现。注意注释原文 "Still available from the logs page"：无论开关如何，日志页（Web 界面 /logs）始终可查全量日志。

三、摄像头配置（monitor JSON）

通过 PUT /api/monitor 保存的摄像头配置会落盘为 configs/monitors/<id>.json。实测 cam2 的完整内容：

{
  "alwaysRecord": true,
  "enable": true,
  "id": "cam2",
  "motion": {
    "duration": 10,
    "enable": true,
    "feedRate": 2,
    "zones": [
      {
        "area": [[0,0],[1,0],[1,1],[0,1]],
        "enable": true,
        "sensitivity": 3,
        "thresholdMax": 99,
        "thresholdMin": 1
      }
    ]
  },
  "name": "cam2",
  "source": "rtsp",
  "sourcertsp": {
    "mainStream": "rtsp://mediamtx:8554/cam1",
    "protocol": "tcp"
  },
  "videoLength": 1
}

字段说明

字段	默认值	说明
`id`	必填	摄像头唯一标识（同时是录像目录名、URL 参数里的 monitor-id）
`name`	必填	显示名
`enable`	`true`	是否启用取流
`alwaysRecord`	`false`	`true` 持续录像；`false` 仅在移动侦测触发时录像
`videoLength`	`1`	单段录像时长（分钟）。最小 1；分段入库粒度
`source`	`"rtsp"`	取流方式，当前仅 rtsp
`sourcertsp.protocol`	`"tcp"`	RTSP 传输协议（`tcp`/`udp`）
`sourcertsp.mainStream`	必填	RTSP 地址，仅接受 H.264 视频轨
`motion.enable`	`false`	移动侦测总开关
`motion.feedRate`	`2`	帧采样率（每秒采样帧数，数值越大越灵敏越耗 CPU）
`motion.duration`	`10`	触发后的延续录像秒数
`motion.zones[]`	全屏默认区	侦测区域，`area` 为 0~1 归一化坐标四边形
`motion.zones[].sensitivity`	`3`	灵敏度（1~10）
`motion.zones[].thresholdMin/Max`	`1` / `99`	触发像素变化百分比下限/上限，滤除全局光照突变

videoLength 实测：改动必须 restart 才生效

PUT /api/monitor 把 videoLength 从 1 改成 2 后，不重启摄像头时分段粒度不变（实测 60 秒间隔的段落照常产生）；调用 POST /api/monitor/restart?id=cam2 后新段落按新时长生成，两个相邻段落文件名间隔 122 秒：

2026-10-30_01-18-38_cam2.mdat
2026-10-30_01-20-40_cam2.mdat

（01:18:38 → 01:20:40，即 2 分钟 + 2 秒的起录间隙。）

PUT 是全量覆盖：motion 段丢失实测

PUT /api/monitor 用请求体整体替换摄像头配置。实测把 cam2 的请求体去掉 motion 段再 PUT（返回 200），随后 GET /api/monitors 显示 motion.enable 已回落为 false、其余字段回到默认值——已配置的移动侦测被静默清空。因此：

修改摄像头参数时，应先 GET /api/monitors 取全量 JSON，改其中字段后整体 PUT 回去；
再调用 POST /api/monitor/restart?id=<id> 使新配置生效。

四、账号文件 accounts.json

首个账号通过 API 创建时生成 configs/accounts.json，密码只存 argon2id 哈希（实测）：

{
  "a2b3c4d5e6f7g8h9": {
    "id": "a2b3c4d5e6f7g8h9",
    "username": "admin",
    "password": "$argon2id$v=19$m=19456,t=2,p=1$yd8y1jQGF76oIp+7PP7Reg$p67eVK09hd2P4mNm5IBDmq11LBEiHFFLrS0DcMmzxFo",
    "isAdmin": true
  }
}

账号 ID 为 16 位字符串，字符集为小写字母与数字 2-9（0/1/i/l/o 不可用），不符合返回 422。建号流程与负样本回显见《SentryShot v0.3.11 Docker Compose 部署指南》。

五、参数误区速查（均实测）

误区	实测结论
首次启动直接可用	不行：生成默认配置即退出，且默认认证插件全关，需手工启用一个认证插件再启动
`debug_log_stdout=false` 关闭全部调试日志	只是不写 stdout，日志页仍可查全量日志
改 `videoLength` 保存即生效	`PUT /api/monitor` 保存后需 `POST /api/monitor/restart?id=<id>`，否则分段粒度不变
`PUT /api/monitor` 改单个字段	全量覆盖：请求体漏 `motion` 段会清空移动侦测配置
`max_disk_usage` 超限后报错	不报错，自动删除最旧录像段腾出空间
摄像头输出 H.265 也能接	不能：日志无 `using h264 video stream` 行，仅接受 H.264

SentryShot v0.3.11 配置参数详解

SentryShot v0.3.11 配置参数详解

一、配置体系总览

二、全局配置 sentryshot.toml

顶层参数

插件段（[[plugin]]）

debug_log_stdout 实测

三、摄像头配置（monitor JSON）

字段说明

videoLength 实测：改动必须 restart 才生效

PUT 是全量覆盖：motion 段丢失实测

四、账号文件 accounts.json

五、参数误区速查（均实测）

六、参考链接

插件段（`[[plugin]]`）