Bluecherry 配置参数详解

目标：系统讲解 Bluecherry 3.1.14 的三层配置体系——/etc/bluecherry.conf 服务端配置文件、MySQL GlobalSettings/Devices/Storage 配置表（Web 后台读写的数据源头）、nginx 站点配置，逐参数给出实测含义、取值格式与修改方法，并给出生产配置模板与排障沉淀。全部参数取值来自本机实测环境（Ubuntu 22.04 + Bluecherry 3.1.14，部署过程见《Bluecherry .deb 裸机部署实战》）。

一、环境信息

二、前置条件

1. 已按《Bluecherry .deb 裸机部署实战》完成安装，systemctl is-active bluecherry 为 active；
2. 具备 MySQL 访问能力（mysql -u<用户> -p bluecherry，包配置默认建了 root/bluecherry 两个账号）；
3. 能访问 Web 后台 https://<服务器IP>:7001（示例账号 Admin/q1w2e3r4）；
4. ⚠️ 动配置前先理解修改生效机制：Web 后台改的是数据库，bc-server 每 5 秒轮询配置表自动生效，无需重启；/etc/bluecherry.conf 只存数据库连接与健康令牌，改它才需要重启 bc-server。

三、配置查看与修改方式总览

Bluecherry 的配置分散在四处，按"改动频率"排列：

三个配置表的分工（实测）：

• GlobalSettings：全局键值对（22 项），键名以 G_ 前缀命名；
• Devices：每路摄像头一行，40 个字段，覆盖接入、编码、侦测、计划、通知五类参数；
• Storage：存储路径表，支持多行（多磁盘）。

四、GlobalSettings 全局参数详解（实测全量）

select * from GlobalSettings 实测 dump（安装默认值，3.1.14）：

💡 技术拓展：G_ 前缀键不是固定封闭集合——bc-server 兼容在 GlobalSettings 表里动态增行。升级版本时新参数以新行出现，旧版本会忽略未知键，这让 GlobalSettings 成为"前向兼容"的配置面。生产变更时建议只改已有键，不擅自发明新键。

五、/etc/bluecherry.conf 服务端配置文件详解

实测全文（19 行）：

# Bluecherry configuration file

# Used to be sure we don't use configurations not suitable for us
version = "1.0";

bluecherry:
{
  db:
  {
    # 0 = sqlite, 1 = pgsql, 2 = mysql
    type = 2;
    dbname = "bluecherry";
    user = "bluecherry";
    password = "bluecherry";
    host = "localhost";
    userhost = "localhost";
  };
};

追加参数（本层还可追加 bc-server 启动参数，3.1.14 实测有效的一项）：

修改本文件必须重启：systemctl restart bluecherry（Web 端 PHP 也会随之读取新值，无需重启 nginx）。

六、Devices 表逐摄像头参数详解（实测字段全量）

select * from Devices 实测字段（按功能分组讲解，id=1 LabCam 持续录像 + id=2 MotionCam 移动侦测两路实测值）：

6.1 接入参数

6.2 录像计划参数（schedule 语法）

实测把 MotionCam 切到移动侦测计划的完整命令（可在维护窗口执行）：

mysql -u root -p bluecherry -e \
  "update Devices set schedule=repeat('M',168), schedule_override_global=1 where id=2;"
systemctl restart bluecherry
journalctl -u bluecherry --no-pager --since "1 min ago" | grep MotionCam

实测回显：

I(2/MotionCam): Device 2: Starting schedule transition to 'motion'
I(2/MotionCam): Device 2: Successfully completed schedule transition to 'motion'

6.3 移动侦测参数

实测触发效果（testsrc2 动态画面 + 上述默认参数）：日志连续输出 Motion event: area=16.244140%，事件落 EventsCam 表（type_id=motion），并按预录/后录参数生成 *-motion.mp4 录像段（文件名实测如 09-41-30-motion.mp4）。

6.4 编码与流参数

6.5 通知参数

6.6 其他

七、Storage 表与存储参数

实测表结构与默认行：

mysql -u root -p bluecherry -e "select * from Storage\G"

实测回显：

         id: 1
       path: /var/lib/bluecherry/recordings
 max_thresh: 95
 min_thresh: 90
    priority: 1
  free_space: 133704138752

运行期自检日志（每 5 分钟）：

I(): Storage path /var/lib/bluecherry/recordings below threshold: 41.3% <= 95.0%

⚠️ 清理逻辑只删"已归档"或超期媒体索引对应的文件并同步 Media 表（3.1.14 的 DB/文件系统同步修复就是针对此），不要手工 rm 录像文件——会造成索引"孤儿"，正确做法走归档 + 官方清理机制（见《Bluecherry 常用命令与运维实战（核心篇）》）。

八、参数修改实测与验证方法

8.1 实测：录像文件轮转时长（G_MAX_RECORD_TIME）

需求：短文件快速轮转（如演示环境），验证全局参数热生效。

mysql -u root -p bluecherry -e \
  'update GlobalSettings set value=60 where parameter="G_MAX_RECORD_TIME";'

无需重启。等待约 90 秒后查看录像目录：

-rw-rw---- 1 bluecherry bluecherry 29597698 Oct 28 09:40 09-26-21.mp4   ← 改前旧段（补齐到轮转点）
-rw-rw---- 1 bluecherry bluecherry  2167103 Oct 28 09:41 09-40-28.mp4   ← 新参数生效段（62 秒）
-rw-rw---- 1 bluecherry bluecherry   524336 Oct 28 09:41 09-41-30.mp4   ← 62 秒后再次轮转

实测结论：GlobalSettings 修改即热生效（bc-server 5 秒轮询），旧段在当前轮转点收尾，之后严格按新时长切片。验证后恢复 value=900。

8.2 实测：设备级计划覆盖（schedule_override_global）

见 6.2 节完整实录。两个易踩坑点复述：

1. 只改 schedule 不置 schedule_override_global=1 → 永远跟随全局计划（这是"改了计划不生效"的头号原因）；
2. 置位后需 systemctl restart bluecherry 才触发计划切换（比 GlobalSettings 的热轮询多一步，属计划引擎的重估时点设计）。

8.3 实测：健康检查令牌（access_token）

# 未配置时：
curl -sk https://127.0.0.1:7001/ajax/health.php/ping

实测回显：

{
    "status": 401,
    "error": "Unauthorized",
    "code": 401,
    "message": "Authorization token is missing or invalid",
    "timestamp": "2026-10-28T09:28:20+00:00"
}

在 /etc/bluecherry.conf 的 bluecherry: 块内追加 access_token = "bluecherry-health-token"; 后 systemctl restart bluecherry：

curl -sk -H "Authorization: Bearer bluecherry-health-token" https://127.0.0.1:7001/ajax/health.php/ping

实测回显：

{
    "status": 200,
    "message": "Service is healthy"
}

8.4 参数验证的通用三板斧

1. 看日志：journalctl -u bluecherry --no-pager --since "5 min ago" 或 tail -f /var/log/bluecherry.log，设备级日志前缀 I(<设备ID>/<设备名>)；
2. 查表确认：mysql -u root -p bluecherry -e "select …"，Web 界面改的任何东西最终都在这三张表里；
3. 看接口：/ajax/stats.php（JSON 系统统计：CPU/内存/磁盘/设备状态）与 /ajax/health.php/ping（需 access_token）。

九、生产配置模板

9.1 8 路 1080p 中小规模（单机单盘）

-- 全局：改文件 15 分钟轮转，预/后录各 5 秒
update GlobalSettings set value=900 where parameter='G_MAX_RECORD_TIME';
update GlobalSettings set value=5  where parameter='G_BUFFER_PRERECORDING';
update GlobalSettings set value=5  where parameter='G_BUFFER_POSTRECORDING';
-- 全局周计划：工作日 7-19 点移动侦测、其余持续录像（字符位 = 周×24+小时）
update GlobalSettings set value=concat(repeat('C',31),repeat('M',12),repeat('C',77),repeat('C',31),repeat('M',12),repeat('C',17)) where parameter='G_DEV_SCED';
-- 摄像头：内网 TCP 拉流 + 信号丢失通知
update Devices set rtsp_rtp_prefer_tcp=1, signal_loss_notification=1, motion_notification=1;
-- 存储：90% 触发清理到 85%（给系统留余量）
update Storage set max_thresh=90, min_thresh=85;

# /etc/bluecherry.conf 追加（健康监控接入）
access_token = "生成一个强随机串";

9.2 分场景推荐值速查

十、常见问题（FAQ，含排障实录）

Q1：改了 Devices.schedule 移动侦测不生效？ 实录：直接 UPDATE schedule=repeat('M',168) 后日志无任何 transition 记录。原因：schedule_override_global=0 时逐设备计划被全局计划覆盖（bc-server 读的是全局串）。修复：update Devices set schedule_override_global=1 where id=N; systemctl restart bluecherry，日志出现 Schedule transition to 'motion' 即生效。

Q2：改 GlobalSettings 需要重启吗？ 不需要（实测 8.1 热生效）。需要重启的是 /etc/bluecherry.conf（access_token/db 连接）与 systemd 单元级改动。

Q3：日志刷 Failed to open VAAPI device /dev/dri/card0 ... falling back to software decoding？ 实测复现：无核显的纯 CPU 服务器上 G_VAAPI_DEVICE 指向不存在的 DRI 设备，bc-server 自动回退软解，不影响功能。有 Intel 核显时可把核显用于解码以降 CPU（ls /dev/dri/ 确认设备存在），纯 CPU 环境可忽略该日志。

Q4：Web 后台改的配置在哪个文件？ 不在文件里——Web 后台读写 MySQL 三张配置表（GlobalSettings/Devices/Storage）。"导出配置"的实质是备份这三张表（mysqldump 指定表即可，见运维篇）。

Q5：移动事件文件名为何带 -motion 后缀？命名规则？ 实测：持续录像段 HH-MM-SS.mp4，移动侦测段 HH-MM-SS-motion.mp4，同目录同设备，缩略图同名 .jpg。按后缀即可批量区分两类录像。

Q6：Media 表里 end=1970-01-01、size=NULL 的行是什么？ 实测：当前正在写入的录像段（未收尾，结束时间用 epoch 0 占位），段关闭（轮转/事件结束）后自动补全 start/end/size。监控脚本判断"活动段"即查 end=0。

Q7：motion_algorithm 能选多帧分析法吗？ 3.1.14 实测只能 framebuffer（mmotion 已废弃，升级迁移时自动映射）。侦测调优走 motion_map + min/max_motion_area + 降采样组合。

Q8：G_ENABLE_TELNET 开了有什么风险？ 调试用 telnet 接口（明文、无认证），等于把 NVR 控制权暴露在端口上。生产永远 0；即便内网调试，用完立即关闭。

十一、参考链接

1. 服务端源码仓库（配置结构权威来源）：https://github.com/bluecherrydvr/bluecherry-apps
2. 服务端 3.1.14 发布公告（监控/稳定性相关参数背景）：https://forums.bluecherrydvr.com/t/server-release-3-1-14/1050
3. 官方论坛：https://forums.bluecherrydvr.com
4. 站内配套阅读：《Bluecherry .deb 裸机部署实战》（安装实战）、《Bluecherry 常用命令与运维实战（核心篇）》（运维命令与排障）