核心亮点
- 登录、设置、单摄像头、四宫格、回放、事件页一体
- 面向长时间值守的暗色界面与信息层级
- 兼容老旧的 32 位录制环境
技术栈
开发成果 22/26
- 七层架构方案定稿(前端 / 网关 / 媒体 / AI / 存储 / LLM / 设备)
- Vue3 前端 7 页面 + Dark First Pro 暗色设计系统
- Go API 网关(REST + WebSocket + JWT)+ C++ ZLMediaKit 媒体核心
- ONVIF 全链路:自动发现 / 云台 PTZ / 事件订阅(5 台实机验证)
- macOS 原生客户端:RTSP + 硬解 + 多路宫格 + 全屏 + 语音唤醒 + 录像回放
- Android TV 客户端(Compose + ExoPlayer)
- Android 手机客户端(Compose + ExoPlayer,竖屏单列 + 语音输入)
- 智能录制引擎:person-only 门禁 + 64G 循环覆盖 + 灰帧拦截
- AI M0 · 修网关静默降级(落库曾假成功 2 天)+ 健康探针 /api/health
- AI M1 · 事件契约 nvr.event.v1 + 文件 spool(录制器顺便产出结构化事件)
- AI M2 · 理解消费者 ai_understand.py(spool → DeepSeek → 落库 → done/)
- AI M3 · 检索闭环:查询意图解析 + 分级召回 + 结果直达录像回放
- AI M4 · 产品化:成本看板 + 灵敏度三档(热重载约 1 秒生效)+ AI 面板
- 官网 nvr.filebreeze.cn 上线并按实测口径更新(成本 / 三级闸门 / AI 面板)
- 消费者挂定时任务(launchd 每 5 分钟 --once),让欠账自动清零
- 录制器周期性断流重连的根因治理(ZLM 代理「补建后不等就绪」→ 读帧死循环)
- AI 事件分析页自动更新(时间轴 30s 轮询;简报花钱只给显式按钮)
- 事件详情「左录像 + 右文字」对话框 + ASR 转写落盘修复
- 服务托管补齐:录制器/消费者脱离会话常驻 + 两个 service 管理脚本
- 产品化成熟度盘点与三期路线图(15 维度评分 + 缺口清单)
- Android TV 产品化:服务器地址可配置 + 实时宫格预览 + 遥控器全键盘 + 语音交互
- 三端播放链路补「帧看门狗」:以「最近一帧时刻」为判据,修掉画面静默冻结(含错误归因纠正)
- iOS 手机端 / Windows 桌面端
- 人脸识别 P5(先跑 face_probe.py 过闸门再立项)
- TV / 手机正式 keystore 签名 + ICP 备案
- 端到端验收 + 打包发布
项目简介
从纯前端原型演进为 Vue + Go + C++ + Python 全栈智能 NVR。
主链路:Vue3 前端 → Go API 网关 → C++ ZLMediaKit 媒体核心,WebRTC / FLV / HLS 三种出流协议按场景分工(单路低延迟 / 多路并发 / 回放)。
客户端四端并行:Vue Web、macOS 原生(SwiftUI,RTSP 直连 + H.264/H.265 硬解 + 录像回放 + 语音唤醒)、Android TV(Compose)、Android 手机(Compose)。
设备侧:ONVIF 全链路(组播+单播+端口扫描三通道自动发现、云台 PTZ、事件订阅),已在 6 台实机验证出画面(全 TP-Link TL-IPC44K-4,含车库与地下室)。
AI 两级推理(2026-10-10 全线打通):
一级·本地门禁 —— macOS Vision + OpenCV + vDSP,5 级过滤(帧差/去重/画质/人体/噪声),7~35ms/帧,零上传零磁盘;判据为「画面里真的有人」(person-only),实测挡掉 99.6% 的静态误录。
价值判据 —— 停留时长 ≥5s 或跨区移动 ≥0.25 才入队,被挡的只记本地 audit。这一层决定月成本是几块还是上百。
二级·云端理解 —— DeepSeek 视觉(768px 关键帧,json_object)。实测(10 月账本 3311 次 / ¥17.52):单次低谷 ¥0.0037、高峰 ¥0.0075、综合 ≈¥0.005;6 路日均约 330 次 ≈ ¥50/月;周末全天按低谷价。
管道 —— 文件 spool(不用 MQ:未消费即欠账,一眼可见),事件契约 nvr.event.v1,原子写 + 幂等。
闭环 —— 一句话检索(查询意图解析:时间/设备/关键词)→ 事件落库(含 clipUrl)→ 点击直达录像回放。
可观测 —— AI 面板:今日调用/费用/被本地挡掉数/放行率/欠账;灵敏度三档切换,热重载约 1 秒生效,不重启任何服务。
架构硬约束:摄像头对 H.265 2K 每台只稳供 1 路主码流、并发会话 ≤3 ⇒ 不新建抽帧链路,复用录制器已解出的帧。
开发历程 61 条
官网 5 处事实错误:全部「看起来正常」,没有一处会报错
- 起因:飞哥问「有新增功能吗,官网是不是该更新」。查下去发现不是「该不该更新」,而是官网已经错了 5 处,其中 2 处点开就失败。线上首页/product/about 的
Last-Modified停在 10-10,下载页 10-13,这 21 天恰好是功能最密集的一段。 - 错处一(硬伤):4 个页面顶栏「Web 版」都链到
(内网地址):3000,而本机已在(内网地址)网段。对外站放局域网 IP 本身就是错的设计 —— 任何公网访客点了必然失败。已直接去掉该入口,下载页留「访问同一网络下的系统地址」说明。 - 错处二(数字):原写「¥0.003/次、日均 50 次、¥4.7/月」。10 月账本实测 3311 次 / ¥17.52,其中低谷 75%、高峰 25%:低谷中位 ¥0.0037、高峰 ¥0.0075、综合 ≈¥0.005;有活动的 10 天日均 326 次 ⇒ 月约 ¥50。把 ¥4.7 改成 ¥50 看起来是「把自己写贵了 10 倍」,但那是真实账单。
- 错处三:「4 品牌 5 设备」→ 实际 6 台(新增地下室 .20,车库换 .76)。错处四:下载页版本号与 SHA。错处五:about.html 正文有 Markdown 星号泄漏(
带价值判据的事件管道),页面会真显示**。 - 为什么这些能活 21 天:它们都是「看起来正常」的东西 —— 链接是蓝色的、数字是像模像样的、版本号也有。没有一处会报错,只会默默指向错的地方。
- 验收:4 页本地与线上字节逐一相等;从线上拉回 dmg 算 SHA-256 与页面标注一致;并给下载页做了强制显示副本截图,实测四张卡片底边与按钮对齐(macOS 描述原来多一行把按钮顶高 5px,已缩到同宽)。
- 起因:飞哥问「有新增功能吗,官网是不是该更新」。查下去发现不是「该不该更新」,而是官网已经错了 5 处,其中 2 处点开就失败。线上首页/product/about 的
macOS 客户端 0.2.0 发版:打包脚本补上 .dmg 产出
- 为什么发:官网下载的 dmg 是 9-27 的 0.1.0,而源码已到 10-16。下载版缺:帧看门狗、AI 事件分析页、事件详情对话框、回放页、语音唤醒。用户下到的是个残缺品,页面却写着「最新版本」。
- 根因不是忘了发版,是打包脚本从来就不产 dmg:9-27 那个是手工
hdiutil做的,于是「源码天天改、下载包一动不动」。 - 修正:
build-app.sh补 release 模式自动hdiutil出 dmg 并打印 SHA-256;版本号从写死的0.1.0改为NVR_VERSION可覆盖(默认 0.2.0)—— 同上一个「部署脚本硬编码 apk 版本号」的坑是同一类。 - 产物:
NVRStation-0.2.0.dmg2.0M,SHAcd937893…c448。挂载校验:CFBundleShortVersionString=0.2.0、CFBundleName=悦居智能NVR、codesign --verifyvalid on disk + satisfies its Designated Requirement。 - 签名不是 ad-hoc:钥匙串里有「NVRStation Local Signing」(
security find-identity -v会过滤掉它,因为不被系统信任;不带-v才能看到)。用固定证书才能让 macOS 记住「本地网络」授权,否则每次重编译都重弹窗。 - 官网同步:v0.2.0 + 新 SHA + 描述补上 AI 事件分析页;并如实写明「本地签名、未走 Apple 公证,首次需右键打开」—— 不写这一句,用户会以为装坏了。
- 上线验收:从线上拉回 dmg 算 SHA-256,与页面标注逐字符一致(不是只看 HTTP 200)。
AI 事件落库断了 5 天:真因是登录 401,却被记成「网关 503」
- 现象:
events最后一条停在 10-30 22:36,spool/dead/积了 542 个事件(书房 227 / 客厅 219 / 玄关 96),而成本账本 10-31 19:55 还在正常扣费 —— 理解在跑、钱在花、结果被丢掉。 - 真因:
ai_understand用默认密码admin123登录,而 10-30 安全加固已把密码改掉 ⇒ 每轮 401。日志里全历史 1635 次「登录网关失败 HTTP 401」,零次 503。 - 为什么排查会被带偏:
_save_to_db只返回 True/False,上层把一切失败写成「落库未确认(网关 503/降级或返回 id=0)」。错误归因比没有归因更贵,它会让人去网关里查一天。 - 三处修正:①凭据改读
(本机路径)(600),改密码不用重装 launchd 服务(改 plist 后bootstrap在受限终端恒 EIO);②新增_LAST_DB_ERROR/last_db_error(),dead 备注写真实原因;③补 flock 单实例锁。 - 为什么必须加锁:launchd 每 120s 起一轮
--once,积压大时一轮跑不完 ⇒ 两个消费者同时读写同一 spool,互相os.remove、同一条事件重复理解重复扣费、run_once抛 FileNotFoundError 整轮中断。重放 500 条时第一次必然撞车,平时事件量小看不出来。 - 重放:新增
scripts/replay_dead_events.py,必须清掉_consume.attempts否则移回 spool 会被立刻再判死。514 条重放,按 ¥0.0043/次约 ¥2.2。 - 验收:小批 3 条全部落库(id 1702~1704)、死信 0、超 300s 的旧事件只落库不播报;并发第二个进程干净退出(退出码 0,不是失败)。
- 现象:
官网重新部署:修掉部署脚本两个失效点
官网 nvr.filebreeze.cn 重新部署(远端停在 9 月 27 日版,落后半个月)。
部署脚本两个真失效点(直接跑会挂或漏更)
- 硬编码
nvr-tv-0.1.0.apk,而磁盘已是 0.2.0 ⇒ scp 阶段失败。改为按后缀取最新(版本升级不用改脚本) - 只上传
index.html⇒ download / product / about 永远停在旧版。改为整站打包上传,解包后 chown 回 ubuntu - 又踩一次「全角括号紧跟变量」:
$REMOTE_NGINX(报 unbound variable,必须${VAR}
验收(不只 curl 200,要比字节数)
- 首页 200 / 12389B,与本地 index.html 字节数完全一致(旧版只有 9.6K)
- 下载页 7271B,引用
NVRStation-0.1.0.dmg与nvr-tv-0.2.0.apk - 两个安装包 Range 请求均 206(支持断点续传)
- product / about 均 200;nginx -t 通过后 reload
- 硬编码
车库子码流 H.265→H.264:406 拒绝才是重启的真凶
背景:6 台主码流全 H.265,子码流里只有车库(id=11,海康白牌 800x448)也是 H.265。flv.js 只认 codecId=7、ExoPlayer FlvExtractor 只认 AVC ⇒ 仅这一路在 Web/TV 黑屏。设备无配置入口,只能转码。
链路:cam_11_sub → h264_videotoolbox → cam_11_sub_h264;网关自动发现
_h264变体,三端零改动。实测 5.5% 单核(libx264 speed 0.855x 跟不上)、拉 10 秒得 151 帧且 time=10.11s。四个坑
- ffmpeg 8.1.1 没有
-rw_timeout(rc=8 秒退)⇒ rtsp demuxer 用-timeout(微秒) - 不加
-fps_mode passthrough⇒ ZLM 声明 fps=22(源 15)快放 1.47× stderr=PIPE只在退出时读 ⇒ 警告写满 64KB 阻塞转码(进程活、画面不动)- ffmpeg 被 kill 后 ZLM 不立刻释放发布者 ⇒ 重推同名流必吃
ANNOUNCE 406(rc=8)。正常退出不触发、像「随机偶发」。推流前close_streams force=1,黑屏 10~20s → 3s
两个假阴性:
launchctl list恒空 ≠ 未注册;grep -E "^\s+(state|pid) ="在 BSD grep 下\s不匹配,会误报「未注册」。自省:曾把 aliveSecond 很大当成僵尸源,踢了一个正出数据的流(speed 34KB/s)。判据应是
bytesSpeed>0。- ffmpeg 8.1.1 没有
暴露面收敛:7 个端口收回本机 + JWT_SECRET 改必填
接上网线后发现局域网内任一设备可直接连数据库与 Redis(实测 Redis 无密码直接回 +PONG),遂做收敛。
做了什么
- 5432 / 6379 / 1883 / 9091 / 8082 / 80 从 0.0.0.0 收窄到 127.0.0.1(网关用容器名访问 redis、mosquitto,本来就不需要宿主端口)
- Redis 加 requirepass;admin 密码重置为 18 位强口令(旧 admin123 实测返 401)
比弱口令严重得多的一条
docker-compose.yml写着JWT_SECRET: change-me-in-production,Go 代码读不到环变量时的默认值也是同一个串。知道这串就能自己签发任意用户令牌,跳过密码调用所有 API,admin 密码多强都没用。已改为
${JWT_SECRET:?...}必填、值放deploy/.env(600);缺变量则网关拒绝启动,宁可不起也不静默回落。代价:三端已登录 token 全部失效,mac / 手机 / TV 需重新登录。
遗留:ZLM secret 仍为可猜字符串且在 git 历史里(与 PG 密码同),真正解药是轮换而非改文本;554 端口因 Lima 残留监听未能关闭(实测不响应 RTSP、拉不到流,重启即消失)。
App 端媒体接口上线 + 对外集成 API 落地
- 新增
/api/client三接口(JWT 保护,DTO 不含任何凭据字段):逐个:清单 / 起流并返回四协议地址 / JPEG 截图 - 失败码语义分开:502 起流失败、504 流建好但 N 秒无数据(仍给地址)、503 截图取不到真实帧
mediaBase由请求 Host 推导 ⇒ 同一份代码在 127.0.0.1 与 (内网地址) 下各自返回可用地址- 对外集成(ADR-013/014):服务令牌 + 中间件、Webhook+HMAC、订阅调度、migration-013
- 双向令牌隔离:用户 JWT 打 /api/v1 返 401、服务令牌打 /api/* 返 401
- 修
zlm.Stream缺Schema字段:同一路流按 rtsp/rtmp/hls/ts/fmp4 各一条,原遍历会算成 5 路 - 实测:清单 6 台全在线、play readyMs=12、FLV 与 HLS 均 200
- 新增
三端补「帧看门狗」:修掉画面静默冻结,并纠正一个错误归因
- 画面冻在 12:34,源端 OSD 正常、日志六小时无重连与拉流错误:三端只做首帧超时,没有中途停帧检测。
- 判据改为「最近一次收到新帧的时间」:mac 10 秒无新帧重建并加 120 秒内 3 次的刹车,Web 四路径三档信号,TV 看 currentPosition。
- 纠正错误归因:ZLM 按需拉流 0 路,摄像头只有 mac 的 5 条直连、每台 1 条已是最小,改走 ZLM 不做。
- 三端编译通过,看门狗自测 13/13;提交 f1a98e7 已推。