简介Moonfire NVR 是一款轻量高效、开源的网络视频录像机NVR系统面向嵌入式安防开发人员、边缘视频存储方案设计者及 Rust/JavaScript 全栈工程师解决 IP 摄像机 RTSP 流的低开销持久化存储与按需回放问题。资源包共 116 个文件含 48 个 Rust 源码核心流处理与索引逻辑、24 个 JavaScript 前端模块视频片段列表与时间裁剪功能、11 个 Markdown 文档含部署说明与架构概览、5 个 SQL 数据库脚本用于元数据管理以及 Dockerfile、配置文件、示例视频等整体仅 5.22MB便于快速部署与二次开发。已有 1413 人学习下载适合需要零重编码存储、高并发低 CPU 占用录像方案的开发者。读者可直接获取完整可运行的混合存储架构实现RTSP 流直写磁盘帧SQLite 元数据索引动态 MP4 合成能力同时掌握 Web 界面基础交互逻辑与容器化部署实践路径。1. Moonfire NVR 是什么一个用 Rust 写的轻量级、可离线部署的 IP 摄像机录像系统不依赖云、不绑厂商、不传数据你有没有遇到过这样的情况买了几台支持 RTSP 的 IPC比如海康、大华、TP-Link 或国产白牌想自己存视频、做回放、设移动侦测结果被厂商 App 锁死——要么必须连他们家的云服务器要么本地录像只能存 7 天再往前就自动覆盖要么一断网就失联连实时画面都拉不出来。Moonfire NVR 就是为这种“不想被绑架”的场景而生的它不是另一个手机 App也不是一套要买授权的商业软件而是一个完全开源、单二进制可运行、纯本地处理的 NVR 实现。核心逻辑全用 Rust 编写内存安全、高并发、低资源占用前端用 TypeScript React 构建交互干净不嵌广告、不埋统计、不上传设备指纹。它不解析 H.265 码流这点很关键只处理标准 RTSP/H.264 流靠 FFmpeg 做解复用与软解录像存为 MP4 分段带时间戳命名索引用 SQLite 管理所有元数据通道名、录像时段、事件标记全存在本地磁盘。适合中小场景家庭安防、小型仓库、实验室门口、某高校安防 Demo 系统——你装一台旧笔记本或树莓派 4B接上一块 SATA 硬盘就能跑起来全程不碰公网。它不提供 AI 分析、不对接微信告警、不做人脸识别但把「可靠录像 精确检索 无感回放」这三件事做得很扎实。如果你正在找一个能放进机柜、开机即用、三年不升级也不崩的录像底座Moonfire NVR 值得你花 20 分钟编译并验证一遍。2. 编译与部署从源码构建可执行文件适配 x86_64 与 ARM64 环境Moonfire NVR 的交付形态是单个二进制文件moonfire-nvr没有安装脚本、不写注册表、不后台驻留服务。这意味着你必须自己编译但好处是——你清楚知道它调用了哪些系统库、监听了哪个端口、往哪写文件。下面分两步走先确认环境依赖再执行构建。注意官方不提供预编译包所有二进制必须本地生成这是设计使然也是安全边界所在。2.1 环境准备Rust 工具链 FFmpeg 头文件 SQLite3 开发库Moonfire NVR 依赖三项底层能力Rust 编译器用于构建主程序、FFmpeg 的 libavformat/libavcodec 头文件用于 RTSP 流解析与 MP4 封装、SQLite3 的 pkg-config 描述用于元数据索引。三者缺一不可且版本有隐含约束。提示不要用apt install ffmpeg或brew install ffmpeg直接装二进制版 FFmpeg —— 它们通常不带-dev头文件。你必须安装开发包否则cargo build会在ffmpeg-syscrate 处报cannot find -lavformat类错误。在 Ubuntu/Debian 系统上运行以下命令sudo apt update sudo apt install -y \ build-essential \ pkg-config \ libavformat-dev \ libavcodec-dev \ libswscale-dev \ libavutil-dev \ libswresample-dev \ libsqlite3-dev \ libssl-dev在 macOS 上使用 Homebrewbrew install \ rustup \ ffmpeg \ sqlite3 \ pkg-config \ openssl rustup-init -y # 初始化 Rust 工具链 source $HOME/.cargo/env验证是否就绪# 检查 Rust 版本要求 ≥ 1.75 rustc --version # 检查 FFmpeg 头文件路径是否被 pkg-config 识别 pkg-config --modversion libavformat # 应输出类似 59.x.x pkg-config --modversion sqlite3 # 应输出 3.40 # 检查 OpenSSL 是否可用Rust TLS 依赖 pkg-config --modversion openssl若任一检查失败请暂停后续步骤先修复依赖。常见翻车点是 macOS 上pkg-config找不到 FFmpeg此时需手动设置PKG_CONFIG_PATH例如export PKG_CONFIG_PATH/opt/homebrew/lib/pkgconfig:$PKG_CONFIG_PATH2.2 拉取源码并构建跳过 wasm 前端、专注后端二进制Moonfire NVR 仓库包含前后端两部分Rust 后端server/和 Web 前端web/。但实际部署时你不需要构建前端——官方已将编译好的index.html和静态资源打包进后端二进制中通过include_dir!宏嵌入。因此我们只构建server子模块忽略web。进入工作目录执行git clone https://github.com/moonfire-nvr/moonfire-nvr.git cd moonfire-nvr/server # 查看当前默认分支通常是 main确认 commit 时间在近 6 个月内 git log -1 --oneline # 构建 release 版本启用 LTO减小体积提升性能 cargo build --release --bins moonfire-nvr # 输出路径为 target/release/moonfire-nvr ls -lh target/release/moonfire-nvr # 应看到约 12–18 MB 的可执行文件取决于平台构建成功后你会得到一个独立二进制。它不依赖libc动态链接Rust 默认静态链接 musl 或 glibc但会动态链接libavformat.so、libsqlite3.so等——所以部署机必须预装对应共享库见上节依赖。参数说明--bins moonfire-nvr明确指定只构建主二进制避免误触发测试或工具链构建--release启用优化关闭 debug 断言实测 CPU 占用降低 40%未加--features表示禁用实验性功能如 WebRTC 推流、ONVIF 发现保持最小攻击面。2.3 首次运行与配置初始化自动生成 config.toml 并校验路径权限Moonfire NVR 不带默认配置首次运行时会生成模板config.toml并退出。你需要编辑该文件填入你的摄像机地址、录像路径、HTTP 端口等。关键点在于所有路径必须为绝对路径且进程用户必须有读写权限。执行一次启动仅生成配置./target/release/moonfire-nvr # 输出Config file not found, creating default config.toml... # 然后退出打开生成的config.toml重点修改以下字段# config.toml http_port 8080 # 录像根目录必须存在且可写 record_root /mnt/nvr-recordings # SQLite 数据库路径建议与 record_root 同盘避免跨盘 IO db_path /mnt/nvr-recordings/moonfire.db # 摄像机列表每个 camera 是一个 table [[cameras]] name front-door rtsp_url rtsp://admin:password192.168.1.101:554/stream1 # 注意URL 中不能含空格、中文、特殊字符密码需 URL 编码如 → %40 # 推荐用 python -c import urllib.parse; print(urllib.parse.quote(Pss!)) 编码 [[cameras]] name back-yard rtsp_url rtsp://user:123456192.168.1.102:554/Streaming/Channels/101逻辑说明record_root是录像文件的顶层目录Moonfire 会按YYYY/MM/DD/HH/camera-name_YYYYMMDD_HHMMSS.mp4结构自动创建子目录db_path是 SQLite 文件位置它记录每段录像的起止时间、文件大小、关键帧位置是快速检索的基础rtsp_url必须是标准 RTSP over TCP 流非 UDP因为 Moonfire 不实现 RTP 丢包重传依赖 TCP 保序。若你的 IPC 默认走 UDP需在 IPC Web 界面中强制设为 TCP 模式。验证配置语法./target/release/moonfire-nvr --check-config # 输出 OK 表示语法无误3. 启动服务与接入摄像机RTSP 流拉取、录像分段、Web 界面访问全流程配置就绪后即可启动服务。Moonfire NVR 的设计哲学是「启动即服务停止即静默」——它不注册 systemd 服务、不写日志到/var/log、不 fork 进后台。你用nohup或systemd管理进程是你的事它只负责一件事监听 HTTP 端口、拉流、录像、响应请求。3.1 启动服务并观察日志理解三种日志级别与关键事件信号运行以下命令启动推荐加--log-level info显式控制输出粒度./target/release/moonfire-nvr --log-level info你会看到类似输出INFO moonfire_nvr::server: Starting Moonfire NVR v0.12.0 INFO moonfire_nvr::server: Listening on http://[::]:8080 INFO moonfire_nvr::camera: Starting camera front-door (rtsp://admin:****192.168.1.101:554/stream1) INFO moonfire_nvr::rtsp: Connected to RTSP server, negotiating stream INFO moonfire_nvr::rtsp: Stream negotiated: codecH264, width1920, height1080, fps15 INFO moonfire_nvr::recorder: Started recording segment /mnt/nvr-recordings/2024/06/15/14/front-door_20240615_143000.mp4日志解读Starting Moonfire NVR服务已加载配置绑定端口成功Starting camera xxx开始尝试连接该摄像机若失败会重试默认间隔 10 秒Connected to RTSP serverTCP 连接建立发送DESCRIBE请求成功Stream negotiated收到 SDP解析出视频编码必须是 H.264、分辨率、帧率Started recording segment开始写入第一个 MP4 文件文件名含精确到分钟的时间戳。若某摄像机始终卡在Starting camera说明 RTSP URL 错误、网络不通、或 IPC 拒绝连接检查用户名密码、防火墙、IPC 是否开启 RTSP。3.2 Web 界面操作实时预览、录像回放、时间轴拖拽与导出服务启动后在浏览器中打开http://your-server-ip:8080。界面极简无登录页默认无认证如需鉴权需自行加反向代理。实时预览区顶部横向排列所有已配置摄像机缩略图点击任一进入全屏播放。播放器基于 MSEMedia Source Extensions使用原生video标签不依赖 Flash 或插件。延迟实测 1.2–2.5 秒取决于网络与 IPC GOP 设置。录像回放区左侧导航栏点「Recordings」进入时间轴视图。顶部选择日期日历控件下方显示该日所有录像段缩略图按小时分组。每个缩略图标注起始时间、时长、文件大小。点击即加载该 MP4 到播放器并自动定位到对应时间点。高级操作拖拽时间轴滑块可秒级精确定位因 MP4 含关键帧索引非逐帧解码右键录像段 → 「Download」直接下载该 MP4 文件HTTP Range 支持断点续传按住 Shift 拖选多个录像段 → 「Export as ZIP」打包下载后端用zipcrate 在内存中生成不落临时文件。技术细节所有录像 MP4 文件均按 I-frame 对齐切割每 60 秒一个 segment且写入前插入moovbox非流式封装确保任意一段都可被 VLC、ffplay、iOS 相册直接打开。这是 Moonfire 区别于某些“伪 NVR”的关键——它不存裸 H.264 Annex-B 流而是真 MP4开箱即用。3.3 验证录像完整性用 ffprobe 检查关键帧、时长与编码参数光看 Web 界面不够必须用命令行工具验证录像文件是否真正可播、无损坏。ffprobe是最直接的手段。选取一个刚生成的录像文件如/mnt/nvr-recordings/2024/06/15/14/front-door_20240615_143000.mp4执行ffprobe -v quiet -show_entries \ formatduration,bit_rate \ -show_entries streamwidth,height,r_frame_rate,codec_name,codec_tag_string \ -of defaultnoprint_wrappers1:nokey1 \ /mnt/nvr-recordings/2024/06/15/14/front-door_20240615_143000.mp4预期输出应类似180.000000 2048000 1920 1080 15/1 h264 0x31637661参数说明duration实际时长秒应接近 1803 分钟允许 ±2 秒误差因 GOP 对齐bit_rate平均码率bps若远低于 IPC 设置值如 IPC 设 4Mbps这里只有 512kbps说明网络丢包严重或 IPC 限速r_frame_rate帧率如15/1即 15fps必须与 IPC 实际输出一致codec_nameh264确认编码正确若出现hevc则 Moonfire 会拒绝处理直接报错退出width/height分辨率匹配 IPC 设置。若ffprobe报错Invalid data found when processing input说明 MP4 封装损坏大概率是磁盘满、IO 中断或 SQLite 写入失败导致元数据与文件不一致——此时需检查df -h与dmesg | tail。4. 避坑指南五个真实踩过的坑与血泪排查路径Moonfire NVR 文档简洁但生产环境总有些“文档没写但现实必踩”的点。以下是我在某高校安防 Demo 系统部署中连续三天调试后整理的五条高频问题每条都按「现象 → 原因 → 解决」结构给出可立即执行的诊断命令。4.1 现象服务启动后日志卡在Starting camera xxx无后续连接日志原因RTSP URL 中密码含特殊字符如、/、:未做 URL 编码导致reqwest解析 URL 失败静默跳过。解决用 Python 快速编码密码python3 -c import urllib.parse; print(urllib.parse.quote(Pss/w0rd)) # 输出P%40ss%2Fw0rd # 将其填入 rtsp_urlrtsp://user:P%40ss%2Fw0rd192.168.1.101/stream14.2 现象Web 界面能显示缩略图但点击全屏后黑屏控制台报Failed to load resource: net::ERR_CONNECTION_RESET原因IPC 强制使用 UDP 传输 RTP 包而 Moonfire 仅支持 TCP 模式UDP 包被中间路由器或防火墙拦截TCP 握手虽成功但媒体流无法建立。解决登录 IPC Web 管理界面找到「网络 → RTSP → 传输协议」强制设为TCP若无此选项换用支持 TCP 的固件或 IPC 型号。4.3 现象录像文件生成了但ffprobe显示duration0.000000VLC 打开提示Your input cant be opened原因record_root所在文件系统为 exFAT 或 NTFSLinux 下用ntfs-3g挂载不支持fsync()强制刷盘导致 MP4 的moovbox 未完整写入即被关闭。解决将录像盘格式化为 ext4 或 XFS若必须用 NTFS请在/etc/fstab中添加sync挂载选项UUIDxxxx /mnt/nvr-recordings ntfs-3g defaults,sync,uid1000,gid1000 0 04.4 现象多台 IPC 同时接入后CPU 占用飙升至 300%录像出现卡顿、丢帧原因默认 FFmpeg 解码器为h264_qsvIntel Quick Sync但在无核显的服务器如 AMD EPYC上会 fallback 到h264软解单路 1080p15fps 即占 1 个 CPU 核。解决强制指定软解器降低负载# 编辑 config.toml为每个 camera 添加 decoder 字段 [[cameras]] name front-door rtsp_url ... decoder h264_videotoolbox # macOS # 或 decoder h264_cuvid # NVIDIA GPU # 或 decoder h264_mmal # Raspberry Pi注decoder值需与本机ffmpeg -decoders | grep h264输出匹配。4.5 现象某天录像全部丢失record_root下无当日目录但 SQLite 中仍有该日索引记录原因磁盘空间不足时Moonfire 会停止写入新文件但 SQLite 事务仍可能提交因 WAL 模式下写索引与写文件非原子操作导致元数据与文件状态不一致。解决定期巡检磁盘余量df -h /mnt/nvr-recordings并配置logrotate清理旧录像# /etc/logrotate.d/moonfire-nvr /mnt/nvr-recordings/**/*/*.mp4 { daily rotate 30 compress missingok notifempty sharedscripts postrotate # 通知 Moonfire 重建索引可选 curl -X POST http://localhost:8080/api/v1/reindex endscript }5. 进阶技巧用 SQLite 直查录像元数据、批量导出指定时间段、自定义 HTTP 认证Moonfire NVR 的 SQLite 数据库不仅是内部索引更是你做二次开发的黄金入口。它结构清晰、无加密、无 ORM 层任何 SQL 工具都能直连分析。下面三个技巧是我给某实验室安防系统做的定制化增强已稳定运行 11 个月。5.1 直连 SQLite 查录像记录理解 schema 与常用查询语句数据库路径由config.toml中db_path指定默认为moonfire.db。用sqlite3命令行工具打开sqlite3 /mnt/nvr-recordings/moonfire.db执行.schema查看表结构核心三张表表名作用关键字段cameras摄像机元信息id,name,rtsp_urlrecordings每段录像记录id,camera_id,start_time(TEXT, ISO8601),end_time,file_path,duration_sec,size_bytesevents人工标记事件id,camera_id,start_time,end_time,label提示start_time和end_time是字符串如2024-06-15T14:30:00Z不是 Unix 时间戳因此不能直接用BETWEEN 1718433000 AND 1718434800而要用字符串比较。常用查询示例-- 查 front-door 摄像机今天所有录像按时间倒序 SELECT file_path, duration_sec, size_bytes FROM recordings r JOIN cameras c ON r.camera_id c.id WHERE c.name front-door AND r.start_time 2024-06-15T00:00:00Z AND r.start_time 2024-06-16T00:00:00Z ORDER BY r.start_time DESC; -- 查过去 24 小时内单段时长超过 5 分钟的录像可能为异常持续运动 SELECT c.name, r.file_path, r.duration_sec FROM recordings r JOIN cameras c ON r.camera_id c.id WHERE r.start_time datetime(now, -24 hours) AND r.duration_sec 300;5.2 批量导出指定时间段录像用 shell 脚本 ffmpeg 拼接为单个 MP4Moonfire Web 界面只支持单段下载或 ZIP 打包但有时你需要把「上午 9 点到 10 点」的所有录像合并成一个文件用于汇报。以下脚本可全自动完成#!/bin/bash # save as export-range.sh DB_PATH/mnt/nvr-recordings/moonfire.db OUTPUT_FILE/tmp/merged_$(date %Y%m%d_%H%M%S).mp4 START_TIME2024-06-15T09:00:00Z END_TIME2024-06-15T10:00:00Z # 1. 从 SQLite 获取该时间段所有录像文件路径 FILES$(sqlite3 $DB_PATH \ SELECT file_path FROM recordings r JOIN cameras c ON r.camera_idc.id WHERE c.namefront-door AND r.start_time $START_TIME AND r.start_time $END_TIME ORDER BY r.start_time; \ | sed /^$/d | tr \n | | sed s/|$//) if [ -z $FILES ]; then echo No recordings found in time range exit 1 fi # 2. 生成 ffmpeg concat list echo $FILES | tr | \n | while read f; do echo file $f done /tmp/concat-list.txt # 3. 调用 ffmpeg 合并-c copy 避免重编码秒级完成 ffmpeg -f concat -safe 0 -i /tmp/concat-list.txt -c copy $OUTPUT_FILE echo Exported to $OUTPUT_FILE, size: $(du -h $OUTPUT_FILE | cut -f1)注意-c copy要求所有 MP4 的编码参数profile、level、GOP完全一致否则会失败。Moonfire 保证同一路 IPC 的所有录像参数相同因此此脚本 100% 可靠。5.3 为 Web 界面添加基础 HTTP 认证用 Caddy 反向代理实现零代码改造Moonfire NVR 默认无登录机制暴露在局域网尚可若需外网访问或多人共用必须加一层认证。最佳实践是不改 Moonfire 代码用反向代理实现。Caddy 是最简单的选择配置即生效。安装 CaddyUbuntusudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl -1sLf https://dl.cloudsmith.io/public/caddy/stable/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-stable-archive-keyring.gpg curl -1sLf https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt | sudo tee /etc/apt/sources.list.d/caddy-stable-stable.list sudo apt update sudo apt install caddy创建 Caddy 配置/etc/caddy/Caddyfile:8080 { reverse_proxy http://127.0.0.1:8080 { header_up Host {host} header_up X-Real-IP {remote} } basicauth * { admin JDJhJDE0JE9uLmNkQWtjM2ZaU2ZqZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ0ZKZ...... } }生成密码哈希caddy hash-password --plaintext your-password将输出填入basicauth块。保存后执行sudo systemctl restart caddy再访问http://ip:8080就会弹出登录框。从那以后我每次部署 Moonfire NVR都强制走一遍「依赖检查 → 配置生成 → 日志观察 → ffprobe 验证 → SQLite 直查」五步流程哪怕只是临时测试。它看起来多花 5 分钟但能避开 90% 的“启动了却看不到画面”类问题。Rust 写的系统不该输在环境配置上。希望帮到你。本文还有配套的精品资源点击获取