# FNHK

**Repository Path**: ypopenclaw/fnhk

## Basic Information

- **Project Name**: FNHK
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 13
- **Forks**: 0
- **Created**: 2026-09-22
- **Last Updated**: 2026-10-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 在 fnOS 平台搭建一套类似群晖 Surveillance Station 的监控管理套件-飞海监控（FNHK）

> 仓库名 **FNHK** ｜ 飞牛应用 ID（包名）：`fn-hiknvr`

**在 fnOS 平台搭建一套类似群晖 Surveillance Station 的监控管理套件。**

## 📌 项目简介

本项目参考 **群晖 Surveillance Station** 的设计思路进行开发。考虑到大量部署 fnOS 的用户存在将家庭监控设备接入飞牛 NAS 存储与管理的需求，由此发起本项目，旨在满足 fnOS 用户将家庭 IPC 摄像头接入飞牛 NAS 进行集中管理、录像存储的需求。

目前已适配 **海康威视 / 大华 / 宇视 / TP-LINK** 等主流品牌（内置 RTSP 地址模板），也支持**自定义 RTSP 地址**接入任意品牌；摄像头支持 ONVIF 的话，还能**一键扫描局域网**自动发现并取流。功能：实时预览、连续 + 事件双轨录像、网页回放、本地移动侦测。纯本地运行，**只读拉取 RTSP**，数据只存在你自己的 NAS 上；摄像机参数与录像目录都可在应用内配置，支持多台摄像机。

## 🔓 开源与可信（为什么可以放心用）

- **完全开源**：MIT 许可，全部源码都在仓库里，可逐行审计、可自行编译打包（`tools/build.sh`），不需要信任任何第三方
- **无后门、无遥测**：代码里不含统计上报、埋点、广告、云同步或第三方 SDK；**应用不会访问任何外部网络地址**
- **唯一对外连接 = 你自己填的摄像头**（RTSP 拉流）；除此之外它不主动连任何服务器
- **不越界**：只读摄像头 RTSP、只往**你指定的**录像目录写文件；不修改摄像头设置、不动 NAS 上其它应用/目录的数据
- **密码只存本机**：摄像头账号密码保存在 NAS 本机的 `config.json`，不上传、不外发
- **可自行验证**：不放心就 grep 代码；网络行为也可自行抓包核对
- **运行身份**：目前以 `root` 运行（原因与边界见下方「安全与隐私」）

---

## ✨ 功能

- 📹 **实时预览**：首页是以「当前画面快照」为入口的摄像机列表，点进去是单画面直播（同一时间只播一路，省资源）
- 🎬 **直播全屏**：支持全屏观看；竖屏手机会自动旋转画面，按钮按「横屏后你看到的方位」摆放
- 💾 **双轨录像**：主码流连续录像（默认 5 分钟一段）+ 移动侦测事件片，按 `日期 / 上午·下午 / 小时` 分目录
- 🔍 **网页回放**：按天 → 时段 → 小时折叠浏览，支持全屏播放（进度条随播放器）
- 🎯 **本地移动侦测**：拉一路子码流做逐帧差分（不是调摄像头的事件接口，不打扰摄像头）
- 🧩 **多摄像机**：最多 **16 台**，首页宫格自适应 **2×2 / 3×3 / 4×4**；各机独立管线、独立目录、状态互不影响
- 📁 **录像目录可选**：想放哪块盘/哪个子目录都行（在设置页里点选）
- 📱 **手机友好**：网页即用，可“添加到主屏幕”当 PWA
- ☁️ **零云端**：不发任何数据出去（不推送、不上传、不需要账号）

## 🖼 截图

| 首页（摄像机列表） | 单画面直播 |
| --- | --- |
| ![首页](screenshots/home.png) | ![直播](screenshots/live.png) |

| 设置页 | 回放 |
| --- | --- |
| ![设置](screenshots/settings.png) | ![回放](screenshots/playback.png) |

*(截图中的画面已打码，仅用于展示界面)*

---

## 📦 环境要求

- **飞牛 fnOS** ≥ 1.2.0（x86_64）
- **Node.js 运行时**：应用**不自带** Node，使用飞牛应用中心的「**Node.js v24**」（`nodejs_v24`）。
  - 本应用已在 manifest 声明依赖 `install_dep_apps = nodejs_v24`：安装/启用时会**自动装好并启用**它；
  - 如果没自动装上（或系统里没有这个应用），请到「**应用中心**」搜索安装 **Node.js v24**（v22 也可，启动脚本会自动探测 `nodejs_v24` / `nodejs_v22`），再启用本应用。
- **ffmpeg**：默认使用系统的 `ffmpeg`（P3 计划改为随包自带）
- **一台或多台摄像头**（海康 / 大华 / 宇视 / TP-LINK，或任意支持 RTSP 的品牌；也可以是 NVR 的某个通道），**最多 16 台**，且已开启 RTSP
- 想用「扫描局域网摄像头」自动取流：摄像头需支持并**开启 ONVIF**（见下方说明）

## 🚀 安装

### 方式一：下载 fpk 安装（推荐）

1. 到 **[Releases（发行版）](https://gitee.com/ypopenclaw/fnhk/releases)** 下载 `fn-hiknvr-x.y.z.fpk`（最新版：`fn-hiknvr-1.0.0.fpk`）
2. 飞牛「应用中心 → 手动安装」，选择该 fpk

### 方式二：自己打包

```bash
# 需要飞牛官方的 fnpack（fnOS 自带 /usr/local/bin/fnpack）
tools/build.sh          # 等价于：cd fn-hiknvr && fnpack build
# 产物：fn-hiknvr/fn-hiknvr-<version>.fpk
```

## ⚙️ 首次配置

打开「飞海监控 → 右上角 ⚙」，按卡片填：

1. **名称**：随便起（会作为录像目录名和文件名前缀，中文也行）
2. **IP / 端口**：摄像头地址（RTSP 端口默认 `554`）
3. **用户名 / 密码**：摄像头账号（建议单独建一个只读账号）
4. **品牌**：`海康威视`（默认）/ `大华` / `宇视` / `TP-LINK` / `自定义 RTSP` —— 按品牌自动拼 RTSP 地址；选「自定义 RTSP」则直接填主/子码流地址（子码流可留空 = 只拉主码流）
5. **通道号**（海康 / 大华需要）：普通摄像头填 `1`；接在 NVR 上的通道依次 `1、2、3…`（对应 `101/201/301`）
6. **预览码流**：`主码流`（默认，清晰）/ `子码流`（更省资源）
7. 点 **测试连接** → 显示「连接成功 / 分辨率 / 编码」后再 **保存**
8. 需要多台就点 **＋ 添加摄像机**（最多 16 台）
9. **录像保存目录**：点「选择目录」，选一块空间足够的盘/目录

> 🚫 **同一台摄像头不要重复添加**：应用会自动检测（重复时卡片会亮黄条、保存时会再确认一次），因为重复添加会重复占用会话上限，可能导致两边都黑屏。

> 🔍 **用 ONVIF 自动添加（懒人模式）**：先填好 **用户名 / 密码** → 点「**🔍 扫描局域网摄像头**」→ 点扫到的设备 → 应用会**自动选好主/子码流**并填好地址 → 保存。
> - 需先在**摄像头后台开启 ONVIF**：海康在「配置 → 网络 → 高级设置 → 集成协议」勾选启用，并**添加一个 ONVIF 用户**（ONVIF 用户与网页登录账号是分开的；用户名**区分大小写**）
> - 扫描依赖组播；若交换机/AP 做了隔离或拦截组播可能扫不到，此时用上面的品牌模板 / 自定义地址手动填

保存后自动开始预览和录像，无需重启。

> ⚠️ **注意摄像头的并发 RTSP 会话上限**（不同型号不同，常见 **3～6 路**，以实测为准）：
> - 本应用每台摄像机占 **2 路**（主码流 1 + 子码流 1）
> - **同一台摄像头不要重复添加** —— 重复添加会重复占用会话，超出上限就会黑屏
> - 如果这台摄像头同时还被 **群晖 Surveillance Station 等其它软件**拉流（例如群晖在录像 1 路），要把那些路数**一起算进总上限**

## 🗂 录像存储

```
<你选的录像目录>/<摄像机名>/<日期>/{上午,下午}/<HH:00-HH:59:59>/<摄像机名>-YYYYMMDD-HHMMSS.mp4
<你选的录像目录>/<摄像机名>/<日期>/事件/<摄像机名>-YYYYMMDD-HHMMSS-E.mp4
```

- 连续录像**按小时分目录**，跨小时会自动切目录；每段默认 **5 分钟**，**可在设置页自定义**
- **保留天数默认 3 天**（超过天数的旧录像自动删除），**天数可在设置页自定义** —— 想留 7 / 15 / 30 天都行
- 文件用普通 mp4（`+faststart`），手机直接可播
- 磁盘剩余不足 **500MB** 时会**自动暂停录像**并在界面提示；等清理掉过期录像、空间恢复后**自动继续**（不会删你的其它数据）

## ❓ 常见问题

**Q：安装后无法启用，提示「未找到 Node.js 运行时（需要 nodejs_v24）」？**
应用**不自带** Node 运行时（保持安装包很小），依赖飞牛应用中心的 **Node.js v24**。
到「**应用中心**」搜索安装 **Node.js v24** 并启用，再回来启用「飞海监控」即可（v0.3.0 起已声明依赖，正常会自动装好）。

**Q：画面黑屏 / 转圈不出画？**
多半是摄像头输出 **H.265(HEVC)**。浏览器不认 H.265，请到摄像头后台
`配置 → 视频/音频 → 视频 → 视频编码` 把 **主码流和子码流都改成 H.264**，保存后重启应用。

**Q：怎么把录像下载到手机？**
飞牛 App 内置浏览器不支持网页下载。请用 **飞牛 App → 文件**，进录像目录拷出来。

**Q：手机物理返回键会退出应用？**
这是飞牛 App 对第三方网页的机制（所有第三方应用都一样），请用页面内的「← 全部摄像机」「← 返回直播」返回。

**Q：加了 2 台以上后不显示 / 卡顿？**
先看**并发会话是不是超了**：① 同一台摄像头被加了两次；② 这台摄像头还有别的软件在拉流（群晖 Surveillance Station 等），路数要**合并计算**。另外把「预览码流」改成子码流会更省资源。

**Q：我想在局域网里直接用 `IP:8091` 打开？**
默认只监听本机（安全考虑）。要局域网访问：改 `config.json` 的 `http.host` 为 `0.0.0.0`，并设置 `http.user` / `http.pass`（**不设口令时局域网访问会被拒绝**）。

**Q：支持别的品牌摄像头吗？**
支持。内置 **海康 / 大华 / 宇视 / TP-LINK** 的 RTSP 地址模板，也有「**自定义 RTSP**」可以直接填地址（任意品牌、任意魔改路径都行）；摄像头支持 ONVIF 的话还能「扫描局域网摄像头」自动取流。
两个通用前提：① 摄像头必须**开放 RTSP**（部分互联网品牌——例如大多数**小米/米家**型号——不开放 RTSP，只能走官方 App/云，接不进来）；② 编码必须是 **H.264**（H.265 浏览器播不了）。

## 📝 更新日志

### v1.0.0（最新）—— 16 路版正式发布 🎉

**新增 / 升级**
- 🎥 **最多 16 台摄像机**：首页宫格自适应 **2×2 / 3×3 / 4×4**（窄屏自动 2 列）
- 🏷️ 首页角标「直播」→「**在线**」
- 🕘 回放顺序改为「**下午 → 上午 → 事件 → 连续**」，最近的排最上
- 🧭 新增 **H.265 引导**（教你把主码流改成 H.264 / 用子码流预览）

**修复**
- 首页角标误报「在线」（没画面就显示离线，角标不再跳动）
- 应用图标四角透明（桌面不再「蓝块套白框」）

**其它改进**
- 跨小时 / 跨天切换录像目录不再等 5 秒（切换空档 **5 秒 → 0.2 秒**）
- 设置页「选择保存目录」顶部新增「存储空间（硬盘）」列表，可**跨盘切换**（此前只能选到默认那块盘）
- 「测试连接」失败时返回 ffmpeg 原始报错，便于远程定位「为什么连不上」
- 深色主题下品牌下拉框白底白字 → 修好
- 启动日志打印**真实访问地址 + 当前访问口令**，方便找入口
- 新增 `/healthz` 健康检查接口（给反向代理 / 探活用）

### v0.3.0 —— 多品牌适配 + ONVIF 自动发现

**新增功能**
- 🧩 **多品牌支持**：内置 **海康威视 / 大华 / 宇视 / TP-LINK** 的 RTSP 地址模板，选品牌 + 通道号即可自动拼出主/子码流地址（不用自己查 RTSP 路径）；新增「**自定义 RTSP**」—— 直接填主/子码流地址（任意品牌、任意端口/路径都行；子码流可留空 = 只拉主码流）
- 🔍 **ONVIF 自动发现 + 自动取流**：点「扫描局域网摄像头」列出局域网内支持 ONVIF 的设备（WS-Discovery 多网卡组播 + 同网段单播兜底），选中后**自动获取主/子码流地址并回填**，名称也能自动填
- 🗑 **允许删除全部摄像机**（原来至少留一台）；删光后不会自动补回一台空白摄像机
- 🚫 **重复添加检测**：同一台摄像头被重复添加时，卡片亮黄条提醒，保存时再确认一次（重复添加会重复占用摄像头会话路数，可能导致黑屏）
- 🛡 **认证失败提示更清楚**：提示注意**大小写**；若密码确认无误，可能是相机因多次错误登录**临时锁定了账号**（连续错 7 次锁约 30 分钟，重启相机可立即解锁）
- 🛡 **认证失败长退避（防锁死）**：认证失败（401）不再每几秒重试，改为 **1 分钟 → 5 分钟 → 15 分钟 → 30 分钟** 长退避 —— 账号被相机锁定时，正确密码也会返回 401，快速重试等于继续累加失败次数、会把锁定越刷越长；其它错误（网络断、相机重启中、超时）仍保持原来的 **5→10→20→30 秒**快速重试
- 📦 **安装依赖自动化**：manifest 声明 `install_dep_apps = nodejs_v24` —— 安装/启用时由飞牛应用中心**自动装好并启用 Node.js 运行时**，不再出现「未找到 Node.js 运行时（需要 nodejs_v24）」

**文档**
- README 补充：多品牌 / 自定义 RTSP / ONVIF 扫描的使用说明、首次配置 9 步、常见问题（Node 依赖、H.265、米家类摄像头是否支持等）

### v0.2.4
- 回放列表改为**并发读取**（录像很多时列表加载更快）
- 拉流中断改为**指数退避重试**（5s→10s→20s，封顶 30s；进程存活满 30 秒即重置），并给重复告警降噪
- 日志超过 5MB 自动轮转；界面版本号改为自动读取安装版本

### v0.2.3
- **修复**：删除摄像机后其拉流进程未停止（会占满摄像头并发路数，导致新加摄像机连接失败）
- **安全加固**：日志脱敏（不再出现摄像头密码）、配置文件权限收紧、网关/本机鉴权收紧、录像清理与孤儿进程判据更精确、磁盘写满保护
- 首次安装的默认录像目录改为**用户可见目录**（原为系统隐藏目录）

### v0.1.0
- 首个版本：海康摄像头接入、实时预览、连续 + 事件双轨录像、网页回放、本地移动侦测

---

## 🔐 安全与隐私

- 只做 **RTSP 只读拉流**，不会修改摄像头的任何设置
- 账号密码只存在 NAS 本机（`config.json`），不加密传输到任何第三方；**注意该文件权限**
- 应用不做任何外发请求（无遥测、无推送、无云同步）
- 默认通过飞牛的**统一网关**访问（需飞牛登录态）；应用自己的 HTTP 端口**默认只监听本机 `127.0.0.1`**，不对外暴露
- 若要局域网直连（例：浏览器打开 `http://NAS:8091`）：需自行把 `config.json` 里的 `http.host` 改成 `0.0.0.0`，并**务必设置** `http.user` / `http.pass`（未设口令时服务只接受本机访问）
- **日志脱敏**：摄像头密码不会出现在运行日志里（写入前统一脱敏）
- ⚠️ 注意：ffmpeg 的**进程参数**里带有摄像头地址，NAS 上其它用户/进程理论上可查看 —— 建议给摄像头单独建一个**只读账号**，并限制 NAS 的登录用户
- **运行身份**：目前以 `root` 运行 —— 因为需要往**你自己选的任意目录**写录像、并读 `/proc` 采样资源占用
  - 它同时受上述约束：不连外网、不改摄像头、不读你指定目录之外的文件；所有行为都在开源代码里可见

## ⚠️ 免责声明

本项目与杭州海康威视数字技术股份有限公司无任何关系，非官方产品。请自行评估使用风险，作者不对录像丢失、设备异常等后果负责。

关于录像的合规性（涉及隐私的场所），请遵守当地法律法规。

## 🧱 项目结构

```
fn-hiknvr/                 # ← 飞牛应用 ID（包名）
  manifest                 # 飞牛应用清单（名称/版本/入口/端口）
  cmd/main                 # 生命周期脚本（start/stop/status）
  cmd/install_callback     # 安装后写入「空配置」
  config/privilege         # 运行用户
  app/ui/config            # 桌面入口（统一网关 /app/fn-hiknvr）
  app/server/server.mjs    # 服务端：RTSP 拉流、录像、移动侦测、HTTP API
  app/server/public/       # 前端（index.html / settings.html / app.js / style.css / sw.js）
```

技术栈：**Node.js（零依赖，只用标准库）** + 原生 HTML/CSS/JS + hls.js（随包） + ffmpeg（子进程）。

## 🛠 开发

```bash
# 语法检查
node --check fn-hiknvr/app/server/server.mjs
node --check fn-hiknvr/app/server/public/app.js

# 打包
tools/build.sh
```

改完前端记得升 `?v=` 参数与 `sw.js` 的缓存名，否则手机端会吃缓存。

## 📄 许可

[MIT](https://gitee.com/ypopenclaw/fnhk/blob/master/LICENSE)

随包或运行时若使用 **ffmpeg**，其版权归 FFmpeg 项目所有，遵循 LGPL/GPL（取决于编译选项），本项目通过**子进程调用**方式使用，不链接其库。