赵府智家 · 视觉系统

运行在自有小电脑上的视频管理程序。Python 标准库负责对象、空间、配置与登录；MediaMTX 负责 RTSP 接入、HLS 实时预览、本机录像及回放；浏览器使用本地打包的 hls.js。

对象与空间

• 空间档案：家庭 / 公司 / 其他，所属家庭或单位，省、市、区县、街道、小区或园区、楼栋、单元、楼层、门牌和详细地址。
• 摄像头对象：实体设备的稳定 ID、品牌、型号、序列号、镜头数、安装位置和空间引用。
• 镜头通道：每个物理镜头一个通道，关联摄像头对象，配置主、子码流。双镜头摄像头的主、子码流不能当作两个物理镜头。
• 录像机：独立的设备与凭据档案，通道可以引用录像机获取画面。也可以直接连接摄像头。
• 录像来源：明确区分录像机原有录像与小电脑新保存的录像。

当前功能与边界

源码包括空间 / 摄像头 / 录像机 / 镜头档案，局域网 RTSP 探测、ONVIF 设备信息与独立镜头媒体配置读取、同源 HLS 播放、本机可选持续录像、日期查询、录像时间轴、定位回放和片段下载、存储保护、管理员初始化与登录。

录像机原有历史录像回放尚未实现。 需要取得具体型号及合法设备账号，接入其录像检索和回放接口；实时 RTSP 地址不能代替录像检索接口。驱动选项目前仅表示路径模板与接入类型，不能视为某个品牌全系列已经兼容。实际通道号需要由设备确认，不能根据三台双镜头直接猜成通道 1–6。

本机录像默认关闭，用户逐通道开启。默认保留 7 天、容量 40 GB、磁盘预留 8 GB，界面可调整。保留期限到达后 MediaMTX 自动删除本机录像；配额达到后暂停录制，不删除录像机中的数据。配额每 20 秒观察一次，允许少量超出。文件路径及录像索引使用 UTC，界面按浏览器时区显示。

HLS 会有数秒延迟。网页清晰度仅提供“主码流”和“子码流”两个选项，默认主码流。主码流预览使用实际主码流，通过 Intel VAAPI 硬件解码、缩放及 H.264 Main 编码，最高 1920×1080、15 帧/秒。子码流预览使用实际子码流，由 FFmpeg 按需生成 H.264 Baseline / AAC 兼容画面，最高 768×432、10 帧/秒。高清预览需要可用的 Intel 核显、驱动及 render 设备权限，不自动退回高负载的软件高清转码。首开需要等待取流与缓冲。没有观看者后会停止转码；同一镜头的观看者共享一路转码。网页不提供原始编码直出的预览选项。本机录像保留原始主码流编码，兼容预览不改变录像及摄像头设置。网页回放按需转换为 H.264/AAC，最多同时两个会话，每段最多一小时；使用时间轴或定位时间跳转。关闭回放或切换页面后终止转换，不生成额外缓存文件。有可用 VAAPI 时回放最高 1080p/15 帧，否则使用 768×432/10 帧软件转换。下载保留原始录像编码，需支持该编码的播放器。设备状态基于 MediaMTX 实际码流状态；“正在录像”还要求观察到近期写入的本机录像文件。离线不会生成假画面或假录像。

实时预览按镜头独立恢复连接：普通状态轮询只更新标签，不重建播放器；断流后按 2–30 秒退避重连，画面长时间不前进时也会自动恢复。用户主动暂停会保留暂停状态，离开页面会清理播放器和重试任务。

Ubuntu x86_64 部署

先将源文件提交、公开发布，再部署同一 Git 提交的归档。建议放在 /opt/zhaovision/releases/<commit>/。Python 3.11 以上，无 pip 运行依赖。

sudo VISION_BIND=<本机的Tailscale-IPv4> bash deploy/install.sh

安装脚本从系统软件源安装 FFmpeg；检测到 Intel renderD128 时安装 Intel 媒体驱动，授予服务用户 render 组权限，并校验安装固定版本 MediaMTX v1.21.1，创建无登录权限的服务用户，数据写入 /var/lib/zhaovision，应用入口为 http://<Tailscale-IP>:8790/。可用逗号分隔的 VISION_BIND 同时指定本机局域网与 Tailscale 地址；已安装系统在 /etc/zhaovision.env 中修改并重启服务。视频服务的 HTTP、RTSP 与管理 API 全部仅监听回环地址，由应用进行登录鉴权并代理。

首次打开页面，读取服务器上的 /var/lib/zhaovision/setup-code.txt，输入初始化码，设置至少 8 位管理密码（初始用户名为 admin）。初始化后码文件删除。摄像头与录像机密码在自己的界面填写。

systemctl status zhaovision zhaovision-media
journalctl -u zhaovision -u zhaovision-media --since '10 minutes ago'

程序不自动修改网络、防火墙、Tailscale 子网路由或设备密码。录像机仍按其原有设置运行。

开发

python3 app.py
# 在另一个终端运行 MediaMTX，使用首次启动生成的配置
mediamtx ./data/mediamtx.yml

回归测试：python3 -m unittest -v test_app 和 node --test test_live_player.js test_kinship.js。测试使用临时数据库和模拟播放器，不连接真实设备。

访问 http://127.0.0.1:8790/。后端配置变量：VISION_BIND、VISION_PORT、VISION_DATA、VISION_RECORDINGS；高清转码可用 VISION_VAAPI_DEVICE 指定渲染设备（默认 /dev/dri/renderD128）。HTTPS 反向代理场景可设 VISION_SECURE_COOKIE=1。当前管理 API 是单管理员模型。

数据与恢复

数据库和生成的 MediaMTX 配置含设备连接凭据，存于权限受限的本机目录，不进入 Git。系统管理员可以读取这些凭据；当前版本未提供硬盘加密。备份时停止两个服务并一并备份整个 /var/lib/zhaovision。恢复到同一路径、修正服务用户所有权后启动服务。升级时保留数据目录，发布目录按提交留存，回滚 current 符号链接并重启服务；后续涉及数据库版本变更时需遵循对应迁移说明。

本仓库不包含真实家庭地址、设备凭据、视频文件或部署主机凭据。

第三方软件

• MediaMTX v1.21.1，MIT，部署时独立安装。
• FFmpeg，通过系统软件源安装为独立进程，用于按需兼容预览。
• hls.js v1.7.3，Apache-2.0，浏览器构建与许可证位于 web/vendor/。
• 官方接口参考：录像、回放、配置。

系统架构与对象关系。

本项目源码以 MIT 许可证发布。v0.1.x 为初始版本，真实录像机的历史回放兼容性需完成型号适配后另行验证。

账号与家谱（v0.1.11）

• 管理员维护设备、空间、账号和权限。个人账号只可观看授权空间内的实时画面与本机回放，设备配置、网络发现和审计接口仅管理员可用。媒体播放请求逐次检查空间权限。
• 每个账号具有独立用户名和密码，密码使用 scrypt 散列存储；更新密码、角色、空间范围、家谱权限或停用状态会撤销该账号会话。亲属关系不自动授予权限。
• 管理员在“账号与关系”中设置显示名称、相对于哪个账号的称呼，以及关联的家谱人物。支持常用称呼与自定义称呼。默认新个人账号没有空间或家谱权限。
• 家谱是本部署内的一份家庭档案，具有独立的不可访问、查看、编辑权限。一个编辑账号可录入任意数量的祖先、亲属与后辈，无需为每位人物开户。未实现跨家庭租户隔离。
• 人物记录姓名/称呼、别名、性别、生卒日期、在世情况、籍贯、生平和信息来源。公历日期不确定时留空，将农历或口述信息写入备注。
• 亲子关系按“父母一方 → 子女”逐条连接，支持亲生、收养、继亲和未注明；配偶关系为双向。禁止自我关系、重复关系、祖先循环、直系祖先与配偶冲突。关系可以停用后恢复，人物可归档后恢复。
• 支持关系参照人物、搜索、祖先树、后裔树、配偶列表和 JSON 导出。孙辈、曾孙辈、玄孙辈等直系辈分由路径推算；旁系复杂称谓显示明确路径，缺少出生日期时不猜测兄弟姐妹的长幼。称谓用于辅助阅读，以录入关系为准。
• 并发编辑使用家谱修订号，旧表单提交会被拒绝，避免覆盖他人的更新。导出包含人物和关系，不含密码和设备凭据。当前导出用于保存副本，尚未提供 JSON 导入界面。

从 v0.1.10 升级

部署前用 SQLite backup API 保存 /var/lib/zhaovision/vision.db。首次启动 v0.1.11 会将原有单密码账户迁移为 admin，保留原密码散列，并把既有会话关联到管理员；没有固定出厂密码。新增 users、people、family_links 表和 sessions.user_id 列。以后可以直接升级；若回退到 v0.1.10，必须同时恢复升级前数据库副本，因为旧版本使用旧账户模型。人物和实际账号数据仅在受限数据目录中，不包含在公开源码内。