Frigate 贡献者开发指南从本地环境搭建到提交 PR 的完整实践【免费下载链接】frigateNVR with realtime local object detection for IP cameras项目地址: https://gitcode.com/GitHub_Trending/fr/frigateFrigate 是一套面向 IP 摄像头的实时本地目标检测 NVR 系统其代码库横跨 Python 后端、Web 前端Preact/Vite与 Docker 多架构构建体系。本文基于仓库内 docs/docs/development/contributing.md 开发贡献文档系统讲解如何获取源码、搭建与核心/Web/文档三个子项目匹配的开发环境、运行测试、执行硬件加速验证、通过格式化与静态类型检查直至提交 Pull Request 并参与官方多架构构建的完整流程。读完本文你将具备在本仓库内独立开展 Frigate 后端、前端或文档开发并顺利通过 CI 检查的实战能力。一、获取源码分清三个独立仓库Frigate 的开发工作分散在三个仓库中本文档所指向的主仓库只包含核心应用本体及其依赖。核心、Web、Docker 与文档本仓库本仓库持有 Frigate 主应用及全部依赖Python 后端、Web UI、Dockerfile、文档站点。开发流程为先 fork 上游的blakeblackshear/frigate仓库到自己的 GitHub 账户再将 fork 后的仓库 clone 到本地。此后按下面三个方向分别阅读对应小节核心后端CoreWeb 界面文档Frigate Home Assistant App独立仓库该仓库承载 Home Assistant App用于在 Home Assistant OS 及兼容安装环境中让你能够从 Home Assistant Supervisor 选项卡直接运行 Frigate。需要 fork 并 cloneblakeblackshear/frigate-hass-addons仓库。Frigate Home Assistant Integration独立仓库该仓库保存自定义集成无论 Frigate 是作为独立 Docker 容器运行还是作为上述 Home Assistant App 运行它都能让 Home Assistant 自动为你的 Frigate 实例创建实体。需 fork 并 cloneblakeblackshear/frigate-hass-integration仓库。二、核心后端开发环境搭建前置条件GNU make用于调用 Makefile 中的构建目标Docker含 buildx 插件可选的额外检测器Coral、OpenVINO 等建议配备以模拟真实运行性能。需要注意一个 Coral 设备同一时刻只能被单个进程使用因此如果开发过程中需要使用 Coral建议准备额外的 Coral 设备避免与正在运行的 Frigate 实例冲突。第 1 步用 Visual Studio Code 打开仓库打开仓库后VS Code 会提示你“在远程容器中重新打开”项目。这一步会基于 Frigate 基础容器构建一个包含全部开发依赖的开发容器从而保证所有贡献者使用一致的开发环境无需在宿主机上安装任何依赖。该开发容器在 docker/main/Dockerfile 中有清晰定义它从deps阶段派生devcontainer目标安装 Node 20 与 make将工作区挂载到/workspace/frigate并把源码符号链接到/opt/frigate/frigatego2rtc 的create_config.sh会引用该路径。值得留意的是开发容器默认不会启动真正的 Frigate 服务而是由 docker/main/fake_frigate_run 脚本模拟一个空转服务每 5 秒打印一条[INFO] The fake Frigate service is running...用于模拟日志输出真正的后端由你手动启动。第 2 步编写本地测试配置在仓库根目录创建config/config.yml。文档给出的示例配置如下可按需修改mqtt: host: mqtt cameras: test: ffmpeg: inputs: - path: /media/frigate/car-stopping.mp4 input_args: -re -stream_loop -1 -fflags genpts roles: - detectinput_args中-re按原始帧率读取、-stream_loop -1无限循环播放 mp4 文件-fflags genpts用于修正时间戳。这里的输入可以是任何合法的 ffmpeg 输入源。第 3 步准备测试用的 mp4 文件在仓库根目录创建debug文件夹并放入测试视频。这个目录同时是你在测试配置中开启录像功能后录像文件的落盘位置。修改第 2 步的配置指向正确的视频文件并查看仓库根目录的 docker-compose.yml 了解卷映射关系——其中./config:/config与./debug:/media/frigate两条映射正是让配置文件与视频文件进入容器的关键。第 4 步从命令行运行 FrigateVS Code 会自动为你启动 Docker Compose 文件并打开一个连接到frigate-dev容器的终端根据开发所用硬件你可能需要修改根目录的 docker-compose.yml 来透传 USB Coral 或 GPU 以实现硬件加速。该文件已预置了相关注释group_add需要与宿主机render/video/plugdev组 ID 一致否则 OpenVINO GPU 加速会失败并给出了 NVIDIA GPUdeploy.resources.reservations与设备透传/dev/bus/usb、/dev/dri的示例在容器终端执行python3 -m frigate启动后端另开一个终端进入web目录执行npm install npm run dev启动前端。第 5 步清理Teardown关闭 VS Code 后容器可能仍在运行。执行docker-compose down -v即可彻底关闭并清理全部容器。补充Makefile 中的常用构建目标仓库根目录 Makefile 提供了一系列可直接复用的目标适合不依赖 VS Code 的开发方式make local构建frigate:latest本地镜像--targetfrigate且--loadmake debug以DEBUGtrue构建附带开发依赖make amd64/make arm64/make build按平台构建镜像make run构建后直接以-p 5000:5000 -p 8971:8971运行并挂载./configmake run_tests在容器内依次执行python3 -u -m unittest与 mypy 类型检查与下文测试、检查命令一一对应。三、测试单元测试与硬件加速验证单元测试GitHub 会在新 PR 上执行单元测试因此在提交前必须确保全部测试通过python3 -u -m unittest仓库的单元测试集中在 frigate/test 目录下覆盖 HTTP API、MQTT、PTZ 自动追踪、运动检测、录像保留策略、WebSocket 鉴权、sqlite-vec 嵌入等多个模块例如 test_ptz_autotrack.py、test_detection_runners.py、test_http_media.py 等可作为编写新测试时的参考模板。FFmpeg 硬件加速验证以下命令在容器内执行用于确认硬件加速正常工作文档特别提醒Raspberry Pi 场景下应观察到 top 中 CPU 占用低于 50%去掉-c:v h264_v4l2m2m后约 80% CPURaspberry Pi64 位ffmpeg -c:v h264_v4l2m2m -re -stream_loop -1 -i https://streams.videolan.org/ffmpeg/incoming/720p60.mp4 -f rawvideo -pix_fmt yuv420p pipe: /dev/nullNVIDIA GPUffmpeg -c:v h264_cuvid -re -stream_loop -1 -i https://streams.videolan.org/ffmpeg/incoming/720p60.mp4 -f rawvideo -pix_fmt yuv420p pipe: /dev/nullNVIDIA Jetsonffmpeg -c:v h264_nvmpi -re -stream_loop -1 -i https://streams.videolan.org/ffmpeg/incoming/720p60.mp4 -f rawvideo -pix_fmt yuv420p pipe: /dev/nullVAAPIIntel 核显等ffmpeg -hwaccel vaapi -hwaccel_device /dev/dri/renderD128 -hwaccel_output_format yuv420p -re -stream_loop -1 -i https://streams.videolan.org/ffmpeg/incoming/720p60.mp4 -f rawvideo -pix_fmt yuv420p pipe: /dev/nullQSVIntel 快速同步视频ffmpeg -c:v h264_qsv -re -stream_loop -1 -i https://streams.videolan.org/ffmpeg/incoming/720p60.mp4 -f rawvideo -pix_fmt yuv420p pipe: /dev/null这些解码器参数与 Frigate 官方镜像内置的 ffmpeg 构建保持一致可用作排查硬件加速是否生效的快速基准。四、提交 Pull Request 前的三道检查代码必须通过格式化、Lint 与类型检查GitHub 会在 PR 上自动执行这些检查因此强烈建议在提交前本地先行运行。格式化ruff formatruff format frigate migrations docker *.pyLintruff checkruff check frigate migrations docker *.pyRuff 的规则配置位于 pyproject.tomltarget-version py311忽略E501行长等规则并额外启用了I导入排序、UPpyupgrade、G日志格式、ASYNC210、B904等检查族。MyPy 静态类型检查python3 -u -m mypy --config-file frigate/mypy.ini frigatepyproject.toml 中针对 Python 后端的 mypy 配置相当严格位于 frigate/mypy.inipython_version 3.11、disallow_untyped_defs true、warn_unreachable true、strict_equality true、check_untyped_defs true等。同时为逐步推进类型覆盖配置对frigate.api.*、frigate.detectors.*、frigate.util.*、frigate.video.*等若干模块暂设ignore_errors true注释中标注为 TODO待后续补充类型注解后移除。五、Web 前端开发前置条件全部核心后端前置条件或者本机已有另一个可访问的 Frigate 实例Node.js 20开发容器镜像中已通过nsolid_setup_deb.sh 20安装。修改流程第 1 步准备一个 Frigate 实例Web UI 需要连接一个 Frigate 实例才能获取全部数据。可以本地运行一个实例推荐也可以连接网络上独立的实例。本地实例的搭建方式见核心后端开发环境搭建。如果你不会改动 Frigate 的 HTTP API则可以跳过本步直接按“第 3a 步”将开发服务器指向网络上的任意 Frigate 实例。第 2 步安装依赖cd web npm install第 3 步启动开发服务器cd web npm run dev第 3a 步连接非本机实例将 web/vite.config.ts 中的代理目标localhost:5000替换为远端后端服务器的 IP。该文件通过server.proxy将/api、/vod、/clips、/exportsHTTP以及/ws、/liveWebSocket统一代理到后端因此前端开发时无需处理跨域。其默认值来自process.env.PROXY_HOST || localhost:5000也可以直接用环境变量PROXY_HOST指定目标地址。第 4 步修改代码Web UI 基于 Vite、Preact 与 Tailwind CSS 构建。以下是官方给出的轻量原则与建议避免新增依赖。Web UI 追求轻量与快速加载不要做大范围改动。任何大型或架构级想法都应先在讨论区发起讨论确保lint通过该命令会尽可能自动修复风格问题含 Prettier 格式化npm run lint补充单元测试并确保通过。应尽量在每次改动时提高测试覆盖率防止功能在未来被意外破坏npm run test在不同浏览器Firefox、Chrome、Safari中测试——它们各有独特的行为差异。前端测试脚本定义在 web/package.jsontest使用 vitest配置见 web/vite.config.ts 的test段基于 jsdom、mockReset/restoreMocks、全局模式lint还会额外检查 e2e 规范node e2e/scripts/lint-specs.mjse2e 测试则基于 Playwrightweb/e2e/playwright.config.ts。如果运行测试时遇到形如TypeError: Cannot read properties of undefined (reading context)的错误可能是 vitest 的已知问题相关 issuevitest#1910、vitest#1652官方文档也坦承尚未完全解决。六、文档站点开发前置条件Node.js 20。修改流程第 1 步安装依赖cd docs npm install第 2 步本地开发npm run start该命令会启动本地开发服务器并打开浏览器窗口大部分改动可即时热更新无需重启服务器。文档基于 Docusaurus v3 构建参见 docs/package.json依赖docusaurus/core、docusaurus/preset-classic、docusaurus-plugin-openapi-docs等修改 Frigate 文档前建议先熟悉 Docusaurus 官方文档。值得注意的是start脚本会先执行npm run build:config与npm run regen-docs重新生成 API 文档因此首次启动会稍慢。第 3 步构建可选npm run build该命令将静态内容生成到build目录可部署到任意静态内容托管服务。文档站点的导航、侧边栏配置位于 docs/sidebars.ts 与 docs/docusaurus.config.ts。七、官方多架构镜像构建若需构建并推送官方多架构镜像先在宿主机配置 buildx 多架构支持docker buildx stop builder docker buildx rm builder # ---- 如果已存在 docker run --privileged --rm tonistiigi/binfmt --install all docker buildx create --name builder --driver docker-container --driver-opt networkhost --use docker buildx inspect builder --bootstrap make push其中make push对应 Makefile 中的push目标它会针对linux/arm64/v8,linux/amd64双平台构建--targetfrigate的镜像并推送标签为${GITHUB_REF_NAME}-$(COMMIT_HASH)。仓库还通过docker/*/*.mk将各硬件平台的构建目标如 RPi、Rockchip、TensorRT、ROCM 等注入主 Makefile。若要为新的单板计算机/检测器添加社区支持可参考 docs/docs/development/contributing-boards.md其中说明了board.hclBake 文件、board.mk、Dockerfile以deps为基底 COPY --fromrootfs / /以及 CI 与CODEOWNERS的必改项。八、开发容器内的 Nginx 配置调试在开发容器中测试 nginx 配置改动时无需重建容器即可复制并重载配置sudo cp docker/main/rootfs/usr/local/nginx/conf/* /usr/local/nginx/conf/ sudo /usr/local/nginx/sbin/nginx -s reload该命令将仓库中的 nginx 配置位于 docker/main/rootfs/usr/local/nginx/conf复制进容器内的 nginx 配置目录并执行热重载适用于验证代理、鉴权等 nginx 层改动的场景。九、参与 Web UI 翻译Frigate 使用 Weblate 管理 Web UI 的多语言翻译。参与方式在 Weblate 注册账户后进入 Frigate NVR 项目。翻译时需保持既有 key 结构不变只翻译 value同时确保翻译保留正确的格式包括占位符变量如{{example}}。本仓库的翻译产物即web/public/locales/下的各语言 JSON 文件可作为理解 key 结构的参考。结语从 fork 源码、启动 VS Code 开发容器、编写config/config.yml与debug测试视频到运行python3 -m frigate起后端、npm run dev起前端再到用ruff、mypy、unittest完成 PR 前的自检——本文已覆盖 Frigate 核心、Web、文档三大子项目的完整开发闭环。无论是修复后端 bug、为 Web UI 增加功能还是补充文档与翻译遵循上述流程都能确保你的改动与官方 CI 检查及多架构发布体系无缝衔接。【免费下载链接】frigateNVR with realtime local object detection for IP cameras项目地址: https://gitcode.com/GitHub_Trending/fr/frigate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考