米家远程摄像头：独立 Homebridge 插件

插件：@linanw/homebridge-mijia-remote-camera，平台：MijiaRemoteCamera。

登录、家庭选择、远程摄像头连接、快照、HomeKit 视频、声音与双向对讲由插件管理，无需独立的 viewer / relay 容器或另一个摄像头插件。摄像头可以位于其他网络。

目前后端仅实现 CS2/vendor 4。已在一台小米智能摄像机 3 Pro 云台版上验证跨网络远程取流，以及真实 Apple“家庭”的配对、预览和直播。具体测试环境见下文“验证范围”；其他型号、地区和网络环境尚未逐一验证。

要求 Linux x86_64、Node.js 22.13.1+（22.x）或 24.x、Homebridge 1.11.4+（1.x）或 2.x，以及支持自定义插件设置页的 Homebridge UI。适用 Synology DS1618+ 上以 host 网络运行的 Homebridge Docker。运行组件提供 glibc 和 musl 版本；ARM、macOS 和 Windows 不支持。

这是独立开发的插件，与小米、Apple 和 Homebridge 项目没有隶属关系。0.4.1 已公开发布；Homebridge 认证申请 #1296 已提交，正在等待官方审核。当前尚未获得 Homebridge Verified 或 Matter 认证。

安装和首次导入

公开 npm 包包含插件代码和由这些源码编译的自有 Java 适配器，首次需要从已有的本地运行包导入组件。运行组件不随 npm 分发，也不会自动从网上下载；详情见 THIRD_PARTY_NOTICES.md。目前支持指定版本的本地包 homebridge-mijia-remote-camera-0.1.0.tgz，已有该包的用户可按以下步骤迁移。没有该本地包时，npm 包本身不能提供视频功能。

1. 在 Homebridge UI 的“插件”页搜索完整包名 @linanw/homebridge-mijia-remote-camera 并安装。迁移时先停用此前连接同一摄像头的 viewer／relay 或旧插件，避免重复占用运行目录。
2. 将你已持有的 homebridge-mijia-remote-camera-0.1.0.tgz 放入 Homebridge 持久化存储目录，容器内通常为 /homebridge。也支持放在该目录内的匹配版本 assets 目录。插件不会提供或下载这些组件。
3. 打开插件设置页的“导入已有的运行包”，填写存储目录内的相对路径，例如 homebridge-mijia-remote-camera-0.1.0.tgz，点击“导入并校验组件”，等待结果。此过程无需终端，也无需让 Homebridge 在 TTY 中启动。绝对路径也必须位于同一配置存储目录内；Homebridge 指定的根目录可以是别名链接，但用户选择的子路径中的符号链接、越界路径与不匹配的组件会被拒绝。
4. 点击“启用并保存配置”，按界面提示从 Homebridge 首页重新启动，再回到设置页登录。

导入只读取运行文件、核验固定 SHA-256，并保留组件的 legal 目录；目标为 <Homebridge storage>/mijia-remote-camera/runtime。它不导入旧包的插件代码、凭据或配置。已有有效组件会保留；目录正被运行中的插件占用时返回 runtime_in_use。此时先停用平台并正常重启，待旧进程退出后再导入。损坏的已有目录也不会被覆盖，请先备份后处理。

也可向现有 platforms 数组加入基本配置：

{
  "platform": "MijiaRemoteCamera",
  "name": "米家远程摄像头",
  "region": "cn"
}

保留现有 Bridge、配对 PIN、其他平台和配件配置。组件导入后无需系统 Java、Python 或新 Docker 服务。npm 升级会保留存储目录中的组件、会话、设备选择和配件身份。

可选的命令行迁移工具仍可使用，但首次配置优先使用上述设置页：

mijia-camera-setup --from /homebridge/homebridge-mijia-remote-camera-0.1.0.tgz --storage /homebridge

--storage 必须是当前 Homebridge 的真实存储目录。公开 npm 包单独安装成功不表示具备完整视频运行条件；没有匹配且有权使用的本地组件时，请勿把本插件视为可直接工作的摄像头方案。

登录、选择家庭和配对

在插件设置页选择与米家 App 相同的地区，生成小米官方登录链接，在浏览器中打开并按小米页面提示确认。授权后先选择自有或共享家庭，再选择摄像头并保存。插件会连接远程中继并保持连接。

已有有效插件会话时可点击“使用已有登录，读取家庭”。取消或失败的授权保留原凭据。更换已发布的摄像头需要重启 Homebridge。连接停止时可点击“重新连接摄像头”，无需重新登录、选择设备或配对；已连接和自动重试期间不会重复启动连接。

摄像头作为独立配件发布。在 iPhone“家庭 → 添加配件 → 更多选项”中选择它，使用该摄像头启动日志中 Please add [...] manually in Home app. Setup Code: 后面的配对码。插件运行在子桥时，这个码可能与 Homebridge 首页的主桥配对码不同。

默认最高 640×360、12 fps、700 kbps。HomeKit 播放能力维持原状；Matter 默认允许两个播放窗口同时观看。0.1.2 起接入摄像头实际返回的 PCMA 或 Opus 音频，经 AAC-ELD 16 kHz 发送到 Apple“家庭”；双向对讲会将“家庭”回传的声音转换为摄像头协议，并通过同一远程会话发送。没有收到真实音频时不会生成替代声音，视频可独立播放。0.3.0 增加支持型号的上下左右单步控制；尚未接入运动事件、录像回放及 HomeKit Secure Video。

米家名称与房间同步（0.4.0）

0.4.1 修复群晖默认存储目录别名下的首次组件导入，已有视频和同步功能继续运行。

插件默认每 60 秒读取所选摄像头在米家中的名称、家庭及所属房间，也可在设置页立即刷新或暂停自动同步。米家 App 中的修改会更新插件资料、同一 HomeKit 配件的名称信息和 Matter 的厂商资料接口，无需重建配件或重启视频。Apple“家庭”可能保留它自己保存的显示名称和房间，插件不会自动重排 Apple 家庭。

设置页及支持本插件厂商接口的 Matter 客户端可修改所选摄像头的米家设备名，或将它移到同一米家家庭中已存在的房间。写回仅对当前登录账号拥有的家庭开放；共享家庭保持只读。账号无写回权限或当前运行版本未启用写回能力时，编辑按钮保持禁用。当前不创建／重命名房间，不跨家庭移动，也不把摄像头移到“未分房”。

每次修改会先刷新米家资料并检查你编辑时的版本，再发送一次写请求，随后独立回读确认。资料已经变化时保留草稿并提示冲突；超时或回读失败会显示“结果尚未确认”，请先刷新核对，避免重复提交。自动轮询只读取资料。账号、地区或设备选择改变后，旧请求和旧草稿不能写入新的选择。

米家名称最多 160 个 UTF-16 代码单元；本地传输和校验完整保留有效 Unicode，拒绝首尾空白与控制字符，不自动截短。米家云端还有自己的名称规则，可能改写或去除字符，只有按原目标权威回读一致才算确认；目标与回读名称不一致时返回 metadata_not_applied，不会冒称成功。实机中文改名／恢复已通过，emoji 曾被云端去除并触发上述保护。发生这种情况请先刷新核对实际名称，插件不会自动重试或回滚。Matter 厂商资料接口的字符串另受 160 个 UTF-8 字节限制；超出时该投影标记为资料不完整，不截断后继续写入。普通 Matter 控制器可能不显示此接口。

Apple“家庭”内改名／移动房间再写回米家暂未开放。 双向资料同步目前指米家 App 与插件设置页／支持的 Matter 厂商接口之间的读写；Apple 的房间分配属于另一套家庭资料。

声音、对讲与夜视

默认开启现场声音、双向对讲和夜视开关。升级后重启摄像头子桥即可，保留已有 HomeKit 配对。在“家庭”直播页面使用对讲按钮，并允许 iPhone 访问麦克风；松开或结束对讲后会停止向摄像头发送声音。声音静音和音量控制会作用于实际音频转发。插件设置页显示是否已收到真实摄像头声音，以及当前协议是否支持对讲。

设置页可修改“收听摄像头现场声音”“允许双向对讲”“在家庭中显示手动／自动夜视开关”；保存后需重启摄像头子桥。对应配置项为 enableAudio、enableTalkback、enableNightVision，默认均为 true。关闭现场声音也会禁用对讲。

夜视目前仅支持已核对 MIOT 定义的 chuangmi.camera.061a01／chuangmi.camera.061a03。插件设置页先读取设备实际状态，再选择“自动／开启／关闭”并应用；写入后会回读确认。

0.4.3 起 Apple“家庭”提供两个互斥开关：“手动夜视”开启时设置为始终开启；“自动夜视”开启时由摄像头按环境光自动决定是否启用红外。关闭当前开启的开关会关闭夜视，两者均显示关。重复关闭已经关闭的开关会保留另一个模式。两个开关反映夜视策略，不表示红外灯此刻是否点亮；米家 App、插件设置或 Matter 修改模式后，它们会同步更新。启动和轮询只读状态，不更改策略。

原夜视开关保留配对和服务编号，名称改为“手动夜视”；自动模式下它现在显示关，“自动夜视”显示开。已有自动化中打开原开关表示强制开启夜视；需要自动模式的场景请使用新增开关。

云台方向控制（0.3.0）

插件设置页提供上下左右按钮，一次点击只发送一次有限步进，不自动重复或启动巡航。只有经过实机核对的具体型号才会启用；当前验证目标为 chuangmi.camera.061a01。摄像头的远程连接就绪后即可控制，不要求摄像头与 NAS 处于同一局域网。按钮提示“已接受”表示收到电机请求的回复，不表示读取到了最终位置。单步幅度由摄像头决定，成对反向操作也不保证精确返回原角度。当前不提供绝对角度、位置反馈或镜头变焦。

需要在 Apple“家庭”中操作时，在插件设置页勾选“在 Apple家庭中显示四个云台方向开关”，保存并重启摄像头子桥。对应 enablePtzSwitches: true，默认关闭。每个开关打开后只发一次方向指令，随后自动回到关闭状态；关闭开关不会再次移动摄像头。无需重新配对。

0.4.2 为四个方向补充 Apple“家庭”使用的独立配置名称：“云台向上”“云台向下”“云台向左”“云台向右”。已有配对和方向服务标识不变。升级并重启摄像头子桥后，重新打开“家庭”查看；Apple 已保存的自定义别名可能需要在该开关设置中手动调整，无需移除摄像头。

MatterDesk 使用摄像头端点上的厂商方向步进接口 MijiaPtzStep（cluster 0xFFF1FC01）。客户端需要先读取型号支持与当前可用状态；方向命令仅接受上、下、左、右，不提供任意设备指令入口。它没有将固定步进冒充为标准 Matter 机械角度控制；其他 Matter 客户端可能只显示视频功能。

Matter 摄像头（实验性）

可在保留现有 HomeKit 配对的同时启用独立的 Matter Camera（设备类型 0x0142，端点 1）。它实现 Camera AV Stream Management 与 WebRTC Transport Provider，包含 H.264 视频、Opus 现场声音、双向对讲、JPEG 快照、音量／静音和支持型号的夜视模式。当前使用 matter.js 0.18.0 的 Matter 1.6.1 模型，已与 matter-server 1.5.3 控制器进行协议对接。MatterDesk Qt 客户端是当前目标客户端；客户端需要实现摄像头播放。Apple“家庭”仍使用本插件原有的 HomeKit 配件。

在插件设置页勾选“启用 Matter 摄像头”，选定 NAS 的局域网接口（群晖 host 容器通常为 eth0），保存并重启摄像头子桥。默认端口为 5540，需可用且允许同一局域网的 TCP／UDP；mDNS 与 IPv6 也需可用。高级配置示例：

{
  "platform": "MijiaRemoteCamera",
  "enableMatter": true,
  "matterInterface": "eth0",
  "matterPort": 5540
}

0.2.1 修复了仅视频／仅音频会话的资源清理，并支持浏览器早到的 ICE 候选、重复启动，以及 Chromium 多 H264 profile 的正常协商。升级默认不开启 Matter。启用后，从受保护的插件设置页点击显示 Matter 配对信息，将手动配对码或 MT: 内容输入控制器。它与 HomeKit Setup Code 不同。已配对后增加其他控制器时可在设置页重新打开配对窗口，操作完成后可以关闭窗口。配对码和 Matter 私钥不会写入脱敏报告。Matter fabric／设备身份保存在插件私有存储的 matter/ 内，升级和正常重启保留身份；删除该目录会使已有配对失效。

这是未认证的开发设备，使用 SDK 的测试 VID／开发证书。matter-server 默认会拒绝这种证书；只在明确信任此开发设备时，使用它的 --enable-test-net-dcl（或 ENABLE_TEST_NET_DCL=true）选项。插件不冒充通过认证的产品，客户端普通启动应保留严格验证。

Matter 信令及 WebRTC 播放目前面向同一局域网，无外部 STUN／TURN，不能据此承诺跨网 Matter 播放。远端摄像头与 NAS 可以继续处于不同网络，由原有小米远程连接取流。0.2.2 起默认允许两路 Matter 实时会话，可用 matterMaxStreams 设置 1–4 路。相同编码配置的视频与音频共享转码和上游取流，连接分别使用独立的 WebRTC/SRTP；关闭一个窗口不会停止另一个，最后一路关闭后才释放共享编码资源。不同画质需要额外编码器，会增加 CPU 用量。对讲同一时刻保留一路，先发声的窗口持有对讲，停止发送或退出后释放；多个窗口都可独立收听。默认视频上限 640×360、12 fps、700 kbps，可使用已有 maxWidth／maxHeight／maxFPS／maxBitrate 配置调整。没有声明录像、标准机械角度／数字变焦、运动事件或云存储能力；方向步进使用上文的厂商接口。Matter 和 HomeKit 共享同一个远程源，分别编码；群晖上同时播放会增加 CPU 使用。

打开直播时客户端会唤起插件取流；小米中继仍可能间歇连接失败，与是否先打开米家 App 无关。连接失败时会结束当前 Matter 会话，待源恢复后在客户端重新打开。当前未完成长时间稳定性验证。

数据和运行管理

会话、设备选择和导入的组件保存在：

<Homebridge storage>/mijia-remote-camera/
  .micam/credentials.json
  selection.json
  region.json
  runtime/
  matter/

私有目录权限为 0700，凭据和选择文件为 0600。小米 Token 不写入 Homebridge config.json。设置页通过 Homebridge 的受保护接口和本机 Unix socket 通信；原始视频和音频仅监听临时的本机回环端口，不保存录音。对讲与电机控制接口也仅允许本机访问；电机控制使用每次连接独立的私有令牌，令牌不进入设置页或诊断报告。Homebridge 启动后恢复所选摄像头，关闭时清理 Java、FFmpeg 和 UDP 会话，临时网络故障会自动重连。

插件按单个账号、单个摄像头设计，按所选家庭及实际所有者查询完整设备分页。迁移前请备份 Homebridge 存储目录。

验证范围

实际设备验证使用一台小米智能摄像机 3 Pro 云台版，摄像头与 NAS 位于不同网络。Synology DS1618+ 上的 Homebridge Docker 使用 host 网络，Homebridge 2.0.2 / HAP 2.1.6；远程源为 HEVC，由 NAS 解码并转换为 HomeKit 视频。用户已确认 iOS 26.6.2 的 Apple“家庭”预览和直播正常。0.1.2 在同一台摄像头上确认收到真实 Opus 48 kHz 双声道音频并成功独立解码；HomeKit 音频发送和手机回传的对讲音频也已在实机日志中确认，摄像头扬声器的可听效果仍需现场确认。夜视已在实机通过读取、关闭、回读确认、恢复原模式的往返验证，操作约需 0.6–2.2 秒。

开发测试使用 Homebridge 1.11.4／2.x，当前开发依赖为 2.4.0。本地测试另覆盖 Homebridge 1／2 的原生 HAP CameraController、加密快照、视频与双向音频的 SRTP 发送／独立接收解码、夜视读取与写后回读、进程清理、授权取消与原子保存、家庭作用域、真实 Homebridge 设置页 IPC 和本地 Java 启动。

0.4.0 在所选自有家庭完成真实云端往返：中文临时名称写入、独立读取并恢复原名；移到同家庭另一个现有房间、独立读取并恢复原房间。最终名称／房间和原凭据均保持原值。云端去除 emoji 的案例未被误报为确认成功。该验证不覆盖所有名称字符、家庭权限或摄像头型号。

2026-10-24，0.4.1 的完整本地测试在 Node 22.22.1 和 Node 24.19.0、Homebridge 2.4.0 下分别为 328 项：327 通过、1 项仅 root 用户适用的所有权测试跳过、0 失败；包含已持有的运行组件和独立 Matter 控制器集成。公开 CI 的 Node 22.13.1／22.x／24.x × Homebridge 1.11.4／2.4.0 六个组合全部通过；公开 CI 不含私有组件，依赖这些组件的测试会明确跳过。

0.4.1 已通过从公开 npm 匿名全新安装到非 root 用户环境、无平台配置启动 Homebridge 和生产依赖审计（0 个漏洞）。这些检查不表示新用户无需本地运行组件即可播放视频。详细验证范围见 验证记录。

远程中继仍可能间歇断开并自动重连，重连期间预览和直播可能暂不可用。目前尚未完成长时间稳定性验证。

连接诊断

设置页可展开“连接诊断”，查看连接阶段、重试次数、上次失败原因及 HomeKit 快照／直播／音频／对讲请求计数。“已收到摄像头视频”表示米家视频源已就绪；快照和直播计数则显示 HomeKit 是否已请求媒体。也可在 Homebridge 终端运行：

mijia-camera-diagnose --storage /var/lib/homebridge

--storage 必须是实例真实的存储目录，也可能是 /homebridge。输出不包含小米凭据、设备 ID 或视频地址。HomeKit 快照请求不会跳过连接重试间隔。

能在插件中收到视频、但 Apple“家庭”添加失败时，请检查摄像头日志中的独立 HomeKit 端口及 Setup Code；摄像头端口与主桥／子桥端口不同。

相关的 homebridge-xiaomi-camera-native 已提出认证申请 #1289，截至 2026-10-24 尚待最终审核。它的 README 描述直接局域网 MISS/CS2 视频、快照与云台，不含音频／双向对讲。本插件针对已验证的跨网络摄像头传输、音频／对讲和米家／Matter 资料接口；存在功能重叠，不代表整体功能优于其他项目。

公开发布与认证审核状态、兼容性矩阵、同类项目对照及已知限制见 verification.md，组件权利说明见 THIRD_PARTY_NOTICES.md。