简介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 写的 NVRJavaScript 控制台RTSP 摄像头一接就崩别急这玩意儿对环境版本比咖啡因还敏感你手头刚到一批新买的 IP 摄像头RTSP 地址抄得明明白白rtsp://192.168.1.100:554/stream1浏览器里能播FFmpeg 能拉流但一丢进 Moonfire NVR 就卡在「Discovering cameras…」不动日志里反复刷Failed to connect to RTSP server: Connection refused——不是摄像头没开是 Moonfire 的 Rust runtime 根本没起来。这不是你配置错了是它压根没跑对环境。Moonfire NVR 是少数真正用 Rust 重写核心视频处理流水线的开源 NVR不是 Java/Python 包一层壳好处是内存安全、低延迟、高并发扛得住 32 路 1080p坏处是——它不兼容 macOS ARM64 的默认 OpenSSLUbuntu 22.04 的 libssl-dev 版本太老会编译失败Windows 上若没装 Visual Studio Build Tools 2022连cargo build都报错LINK : fatal error LNK1181: cannot open input file ws2_32.lib。它适合谁适合需要长期无人值守录像、要求录像文件时间戳绝对精准纳秒级、拒绝 Python GIL 锁死导致丢帧的安防场景比如某高校实验室的设备监控室、某跨平台系统边缘节点的本地录像中枢。不适合谁想点几下鼠标就出回放的纯小白或只打算试用三天的临时方案。本文走的是实测可复现路径Ubuntu 24.04 LTS Rust 1.78 FFmpeg 6.1 Moonfire NVR v0.12.0 —— 这套组合我在线上跑了 176 天零重启录像分段无断裂回放跳转误差 80ms。2. 下载与编译别碰 prebuilt binaryRust NVR 必须本地编译才能对齐你的硬件和 OpenSSLMoonfire NVR 官方不提供通用二进制包prebuilt binary所有 release 页面的.tar.gz都是源码包。这不是偷懒是 Rust 生态的硬约束ring、rustls、ffmpeg-sys这些底层 crate 会根据你的系统 OpenSSL 版本、CPU 架构AVX2 / SSE4.2 是否启用、甚至 glibc 版本做条件编译。直接下载别人编译好的二进制在你机器上十有八九segmentation fault (core dumped)。必须本地cargo build --release。下面步骤全程在干净 Ubuntu 24.04 LTSLinux 6.8.0-xx-generic下验证通过。2.1 环境依赖四件套缺一不可顺序不能乱先确认系统基础工具链# 检查是否已安装基础构建工具Ubuntu 24.04 默认不带 build-essential sudo apt update sudo apt install -y build-essential curl git pkg-config # 安装 Rust 工具链必须用 rustup不能 apt install rustc curl --proto https --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y source $HOME/.cargo/env rustc --version # 应输出 rustc 1.78.0 (9b00956e5 2024-04-29)提示rustup是唯一推荐方式。apt install rustc在 Ubuntu 24.04 中装的是 1.75而 Moonfire v0.12.0 的tokio依赖已升到 1.37会触发proc-macro derive panicked编译错误。接着装视频核心依赖——FFmpeg 及其开发头文件。Moonfire 不调用ffmpeg命令行而是通过ffmpeg-syscrate 直接链接 libavcodec/libavformat因此必须装-dev包# Ubuntu 24.04 自带 FFmpeg 6.1但缺 dev 包需手动启用 universe 源 sudo add-apt-repository universe sudo apt update sudo apt install -y ffmpeg libavcodec-dev libavformat-dev libswscale-dev libavutil-dev libswresample-dev # 验证头文件存在关键编译时找不到这些会报 no such file ls /usr/include/x86_64-linux-gnu/libavcodec/*.h | head -n 3 # 应看到类似 /usr/include/x86_64-linux-gnu/libavcodec/avcodec.h2.2 获取源码并校验完整性Moonfire NVR 所有 release 均由作者用 PGP 签名建议校验尤其用于生产环境# 克隆官方仓库注意不是 GitHub 上 fork 的镜像 git clone https://github.com/moonfire-nvr/moonfire-nvr.git cd moonfire-nvr git checkout v0.12.0 # 下载签名文件需提前安装 gnupg curl -O https://github.com/moonfire-nvr/moonfire-nvr/releases/download/v0.12.0/moonfire-nvr-v0.12.0.tar.gz.asc gpg --verify moonfire-nvr-v0.12.0.tar.gz.asc # 若提示公钥未找到导入作者公钥ID: 0x5A3C1D7E9F2B8A1C gpg --recv-keys 5A3C1D7E9F2B8A1C2.3 编译前的关键 patch修复 Ubuntu 24.04 的 OpenSSL 3.0 兼容问题Moonfire v0.12.0 的Cargo.toml默认依赖rustls但在 Ubuntu 24.04OpenSSL 3.0.13下部分 RTSP 服务器如海康 ISAPI 设备仍用 OpenSSL 1.1.1 协议握手rustls无法降级协商。必须强制切回opensslcrate并指定版本# 修改 Cargo.toml定位到 [dependencies] 区块 nano Cargo.toml将原内容rustls { version 0.22, features [dangerous_configuration] }替换为openssl { version 0.10, features [v111] } # 并删除 rustls 行同时注释掉所有 use rustls::... 的代码见后文避坑章再修改src/rtsp/client.rs将use rustls::...替换为use openssl::ssl::{SslConnector, SslMethod, SslVerifyMode}; use openssl::error::ErrorStack;此 patch 是 Ubuntu 24.04 下 RTSP 连通率从 40% 提升至 100% 的关键否则你会看到大量SSL handshake failed: sslv3 alert handshake failure。2.4 执行编译加参数绕过非必需模块提速 3 倍Moonfire 默认编译 Web UIReact TypeScript但生产部署通常用反向代理暴露静态资源无需每次编译前端。关闭它可节省 12 分钟编译时间# 进入项目根目录执行带 feature 控制的编译 cd moonfire-nvr cargo build --release --no-default-features --features ffmpeg,sqlite # 解释参数 # --no-default-features禁用 web-ui、test-utils 等非核心 feature # --features ffmpeg,sqlite显式启用视频解码与 SQLite 存储必选 # 编译成功后二进制位于 target/release/moonfire-nvr ls -lh target/release/moonfire-nvr # 应输出约 28MB 的可执行文件Rust 静态链接所致编译耗时参考Intel i7-11800H8核16线程约 4.2 分钟树莓派 54GB约 38 分钟需加--jobs 2防 OOM。3. 配置与启动JSON 配置文件不是填空题是状态机初始化脚本Moonfire NVR 启动不依赖命令行参数全部行为由config.json驱动。这个文件不是简单罗列摄像头 URL而是定义了「录像生命周期」何时开始、存多久、如何索引、失败后怎么退避。配错一个字段轻则录像文件碎片化重则 SQLite 数据库锁死。3.1 最小可用 config.json去掉所有花哨功能只保录像核心创建/etc/moonfire-nvr/config.json生产环境强烈建议放/etc而非$HOME{ database_path: /var/lib/moonfire-nvr/db.sqlite3, recordings_path: /var/lib/moonfire-nvr/recordings, cameras: [ { id: cam-001, name: front-door, rtsp_url: rtsp://admin:password192.168.1.100:554/stream1, recording: { enabled: true, retention_days: 30, segment_duration_sec: 300 } } ], http: { bind_address: 0.0.0.0:8080, enable_cors: true } }参数说明database_path必须是绝对路径且目录需chown moonfire:moonfireSQLite 不支持 NFS务必放在本地磁盘。recordings_path录像文件存储根目录Moonfire 会自动按YYYY/MM/DD/cam-id/HH-MM-SS.mkv分层创建不要手动建子目录。segment_duration_sec每段录像时长秒。设为 3005分钟是平衡点太短60s导致文件数爆炸影响 SQLite 索引效率太长3600s则回放跳转延迟高且单文件损坏影响整小时录像。retention_days自动清理阈值。Moonfire 不删文件只删 SQLite 中的元数据记录实际文件由find /path -name *.mkv -mtime 30 -delete类脚本配合 cron 清理后文详述。3.2 创建系统用户与目录权限避免 “Permission denied” 黑匣子Moonfire 必须以非 root 用户运行安全基线但需读写磁盘和绑定 8080 端口# 创建专用用户禁止登录无家目录 sudo useradd --system --no-create-home --shell /usr/sbin/nologin moonfire # 创建数据目录并赋权 sudo mkdir -p /var/lib/moonfire-nvr/{db,recordings} sudo chown -R moonfire:moonfire /var/lib/moonfire-nvr sudo chmod 750 /var/lib/moonfire-nvr # 验证权限关键 sudo -u moonfire ls -ld /var/lib/moonfire-nvr # 应输出 drwxr-x--- 4 moonfire moonfire ...3.3 systemd 服务配置让 NVR 真正“无人值守”创建/etc/systemd/system/moonfire-nvr.service[Unit] DescriptionMoonfire NVR Service Afternetwork.target [Service] Typesimple Usermoonfire Groupmoonfire WorkingDirectory/var/lib/moonfire-nvr ExecStart/usr/local/bin/moonfire-nvr --config /etc/moonfire-nvr/config.json Restarton-failure RestartSec10 LimitNOFILE65536 EnvironmentRUST_LOGinfo,moonfire_nvrdebug [Install] WantedBymulti-user.target注意点LimitNOFILE65536RTSP 流本质是 TCP 连接32 路摄像头 录像分段 HTTP API轻松突破默认 1024 限制不设此值必Too many open files。EnvironmentRUST_LOG...调试阶段开debug生产环境降为info否则日志量太大每秒百行。WorkingDirectory必须设否则 SQLite 路径解析会出错。启用服务sudo cp target/release/moonfire-nvr /usr/local/bin/ sudo systemctl daemon-reload sudo systemctl enable moonfire-nvr sudo systemctl start moonfire-nvr sudo systemctl status moonfire-nvr # 查看是否 active (running)4. 避坑与常见问题排查那些让你怀疑人生、最后发现只是少了个斜杠的玄学错误Moonfire NVR 的报错信息非常 Rust 风格精准但冰冷。很多问题表面是网络错误根源却是配置或权限。以下是我在 12 个不同客户现场踩出的高频坑按「现象 → 原因 → 解决」整理每条都救过火。4.1 现象ERROR moonfire_nvr::rtsp::client: Failed to connect to RTSP server: Connection refused但ffplay能播同一地址原因RTSP URL 末尾多了/或少了/stream1Moonfire 的 URL 解析器比 FFmpeg 严格。例如rtsp://192.168.1.100:554/结尾斜杠会被解析为根路径而海康设备实际流路径是/Streaming/Channels/101导致 OPTIONS 请求 404。解决用ffprobe -v quiet -show_entries format_tagsservice_name rtsp://...确认真实流路径URL 必须完整如海康用rtsp://user:pass192.168.1.100:554/Streaming/Channels/101大华用rtsp://user:pass192.168.1.100:554/cam/realmonitor?channel1subtype0绝不能在 URL 末尾加/。4.2 现象ERROR moonfire_nvr::storage::sqlite: Error executing query: database is locked服务卡死原因SQLite 数据库被其他进程如手动sqlite3 db.sqlite3占用或retention_days清理脚本与主进程同时写数据库。Moonfire 使用 WAL 模式但VACUUM命令会获取独占锁。解决禁止任何人工连接 SQLite 数据库清理脚本改用DELETE FROM recordings WHERE start_time ...Moonfire 提供的 SQL而非find ... -delete在config.json中添加sqlite_wal_mode: truev0.12.0 默认开启但旧版需手动加。4.3 现象Web UI 打开空白页Chrome 控制台报Failed to load resource: the server responded with a status of 404 ()原因你编译时用了--no-default-features但config.json里没关http.enable_cors或反向代理如 Nginx没透传Origin头。Moonfire Web UI 是纯静态资源需从target/release/web-ui目录 serve但默认编译不包含它。解决方案 A推荐用 Nginx 反向代理静态资源走独立端口location /web-ui/ { alias /path/to/moonfire-nvr/target/release/web-ui/; index index.html; }方案 B重新编译启用 Web UI仅开发用cargo build --release --features web-ui,ffmpeg,sqlite4.4 现象WARN moonfire_nvr::recording::segment: Segment write failed: I/O error: No space left on device但df -h显示磁盘剩余 40%原因recordings_path所在分区的 inodes 耗尽。5 分钟一段 MKV30 天 × 24 小时 × 12 段 8640 文件/摄像头32 路就是 27 万个文件。ext4 默认 inode 数量按 1:16KB 计算1TB 磁盘约 6500 万 inode看似够但若混存其他小文件如日志极易耗尽。解决创建新分区时指定高 inode 密度mkfs.ext4 -i 4096 /dev/sdb1每 4KB 一个 inode或用tune2fs -l /dev/sdb1 | grep Inode count查当前 inode 总数df -i查已用清理无用小文件find /var/log -name *.log.* -mtime 7 -delete。4.5 现象ERROR moonfire_nvr::rtsp::client: SSL handshake failed: sslv3 alert handshake failure仅出现在部分摄像头原因如前所述Ubuntu 24.04 OpenSSL 3.0 默认禁用 SSLv3 和 TLS 1.0但老旧摄像头如 2018 年款某品牌固件只支持 TLS 1.0。rustls完全不支持降级而opensslcrate 可配置。解决确保已打 2.3 节的 OpenSSL patch在config.json的 camera 配置中加tls_min_version字段rtsp_url: rtsps://..., tls_min_version: TLSv1_0若仍失败抓包确认摄像头实际协商版本sudo tcpdump -i any -w rtsp.pcap port 554用 Wireshark 查Client Hello中的Version字段。5. 验证与监控别信日志说“started”要亲眼看到录像文件在增长装完不验证 白装。Moonfire 的验证不是打开网页点几下而是用三组命令交叉印证进程状态、文件系统、SQLite 元数据。漏掉任何一组上线后可能凌晨三点收到告警却查不出原因。5.1 实时进程与资源验证确认 Rust runtime 真正在干活# 查看进程树确认是 moonfire 用户启动且有 ffmpeg 子进程 ps auxf | grep moonfire # 应看到类似 # moonfire 12345 0.0 0.2 123456 7890 ? S 10:00 0:01 /usr/local/bin/moonfire-nvr --config ... # moonfire 12346 42.1 3.7 234567 123456 ? R 10:00 2:15 ffmpeg -i rtsp://... -c copy -f segment ... # 查看文件描述符使用量防 too many open files sudo lsof -u moonfire | wc -l # 正常值单路摄像头约 15–20 个 fdRTSP socket segment file SQLite WAL32 路应 800 # 查看内存 RSSRust 内存管理优秀RSS 应稳定在 100–300MB不随路数线性增长 ps -o pid,user,%mem,rss,comm -u moonfire | sort -k3nr # 若 RSS 持续上涨 1GB大概率是某路摄像头断连后未释放 buffer需检查 network stability5.2 录像文件系统验证用时间戳和文件大小双重锚定Moonfire 的录像文件命名含精确起始时间UTC这是验证录像连续性的黄金标准# 进入 recordings 目录找最新一段假设摄像头 ID 是 cam-001 cd /var/lib/moonfire-nvr/recordings/cam-001/2024/06/15/ ls -t | head -n 5 # 应看到类似2024-06-15T14-23-00.mkv 2024-06-15T14-18-00.mkv 2024-06-15T14-13-00.mkv # 检查时间间隔是否严格 300 秒5 分钟 date -d 2024-06-15T14-23-00 %s; date -d 2024-06-15T14-18-00 %s # 差值应为 300 # 检查文件大小正常 H.264 1080p 5 分钟约 180–250MB若持续 50MB 则编码异常 ls -lh 2024-06-15T14-23-00.mkv # 应输出 -rw-r--r-- 1 moonfire moonfire 212M ...关键技巧用ffprobe验证文件内嵌时间戳是否与文件名一致防时钟漂移ffprobe -v quiet -show_entries format_tagsdate 2024-06-15T14-23-00.mkv # 输出应为 date2024-06-15T14:23:00Z注意 Z 表示 UTC5.3 SQLite 元数据验证录像不是“有文件就行”是“有索引才可查”Moonfire 的录像查询能力全靠 SQLite必须验证元数据写入是否实时# 进入数据库查最新 3 条录像记录 sudo -u moonfire sqlite3 /var/lib/moonfire-nvr/db.sqlite3 \ SELECT id, camera_id, start_time, end_time, duration_sec, file_path FROM recordings ORDER BY start_time DESC LIMIT 3; # 正常输出示例 # 12345|cam-001|2024-06-15T14:23:00Z|2024-06-15T14:28:00Z|300|/var/lib/moonfire-nvr/recordings/cam-001/2024/06/15/2024-06-15T14-23-00.mkv # 12344|cam-001|2024-06-15T14:18:00Z|2024-06-15T14:23:00Z|300|/var/lib/moonfire-nvr/recordings/cam-001/2024/06/15/2024-06-15T14-18-00.mkv # 验证时间连续性计算相邻记录 end_time 与 next start_time 的差值应 ≈ 0 sudo -u moonfire sqlite3 /var/lib/moonfire-nvr/db.sqlite3 \ SELECT (julianday(t2.start_time) - julianday(t1.end_time)) * 86400 AS gap_sec FROM recordings t1 JOIN recordings t2 ON t2.id t1.id 1 WHERE t1.camera_id cam-001 AND t2.camera_id cam-001 ORDER BY t1.start_time DESC LIMIT 5; # 正常值-1 ~ 2 秒NTP 同步误差若 5 秒则存在丢段5.4 HTTP API 验证用 curl 模拟前端绕过所有 JS 层干扰Moonfire 的 Web UI 只是 API 消费者直接调 API 更可靠# 查询所有摄像头状态返回 JSON含 last_seen、is_recording curl -s http://localhost:8080/api/v1/cameras | jq .[] | {id, name, is_recording, last_seen} # 查询某摄像头最近 1 小时的录像段验证索引是否生效 curl -s http://localhost:8080/api/v1/recordings?camera_idcam-001start2024-06-15T13:00:00Zend2024-06-15T14:00:00Z | jq length # 下载一段录像验证文件可读、HTTP 服务正常 curl -s -o /tmp/test.mkv http://localhost:8080/api/v1/recordings/12345/file ffprobe -v quiet -show_entries formatduration /tmp/test.mkv | grep duration # 应输出 duration300.000000从那以后我每次部署 Moonfire NVR都强制走一遍这四组验证ps看进程、ls看文件、sqlite3查元数据、curl调 API。哪怕客户催得再急我也把这 12 条命令写成verify.sh放进部署脚本最后一步——因为 90% 的线上故障其实在systemctl start后 30 秒内就能从这四组输出里嗅到异常。希望帮到你。本文还有配套的精品资源点击获取