HomeAssistant (HA) 2025.12.2 +版本接入海康威视（Hikvision）摄像头的最佳方式其实不是用那个名字带“Hikvision”的老集成（那个主要只能看报警状态，看不了画面），而是用 ONVIF 协议。
通俗解释一下：你可以把 ONVIF 想象成是摄像头界的“普通话”。海康威视有自己的“方言”（私有协议），HomeAssistant 不一定能完全听懂。但是只要你让摄像头讲“普通话”（开启 ONVIF），HomeAssistant 就能立刻听懂，不仅能直接看到画面，还能自动发现你在摄像头里设置的那些动作检测报警。
下面是基于 2025.12.2 版本的详细小白教程。最重要的步骤其实是在摄像头那一端，请务必仔细看第一步。
第一步：在海康威视摄像头后台“考个普通话证书” (开启 ONVIF)
很多小白卡在这一步，因为海康威视默认是关闭 ONVIF 的，而且ONVIF 的账号密码和登陆摄像头的账号密码是分开的！
- 电脑浏览器登录摄像头： 在电脑浏览器地址栏输入摄像头的 IP 地址（比如 192.168.1.64），输入管理员账号密码登录。
- 找到设置入口： 点击顶部菜单的 配置 (Configuration) -> 左侧菜单 网络 (Network) ->高级配置 (Advanced Settings) ->集成协议 (Integration Protocol)。
- 开启 ONVIF：
- 勾选 启用 ONVIF (Enable ONVIF)。
- 关键点来了：点击下方的 添加 (Add) 按钮，创建一个专门给 HA 用的 ONVIF 用户。
- 用户名：建议填 ha_admin (不要和摄像头登陆账号 admin 混淆)。
- 密码：设置一个只有你知道的密码（建议纯数字+字母，别搞太复杂符号）。
- 权限：也就是用户类型，选择 管理员 (Media User/Operator/Admin)，建议选管理员以防权限不足。
点击 确定 保存。
同步时间 (防坑)：去 系统 (System) ->系统设置 (System Settings) ->时间设置 (Time Settings)。确保摄像头的时间和你的 HA 时间是一致的（最好都开启 NTP 校时），时间对不上会导致认证失败。
第二步：在 HomeAssistant 中“认领”摄像头
做完第一步，你的摄像头已经会讲“普通话”了，现在回 HA 里添加它。
打开集成页面：在 HA 左侧菜单点击 设置 (Settings) ->设备与服务 (Devices & Services)。
添加集成：点击右下角的 + 添加集成 (+ ADD INTEGRATION) 按钮。
搜索 ONVIF：在搜索框输入 ONVIF，点击出现的图标。
填写信息：这时候会弹出一个框，运气好的话 HA 已经自动发现你的摄像头了，你直接点“提交”就行。如果没自动发现，手动填一下：
主机 (Host): 填摄像头的 IP 地址 (例如 192.168.1.64)。
端口 (Port): 默认 80，如果不管用且你没改过，有些海康旧机型可能是 8000 或 8080，但绝大多数情况留空或填 80。
名称 (Name): 给摄像头起个名，比如“大门口”。
用户名:
注意！
这里填你在第一步里专门创建的那个 ONVIF 用户名（比如 ha_admin），不是你登陆摄像头的 admin。
密码: 第一步里设置的那个 ONVIF 密码。
完成：点击提交。如果没有报错，HA 会让你把发现的设备（主码流、子码流、各种传感器）分配到房间。直接点完成即可。
第三步：把画面放到桌面上 (Dashboard)
- 回到 HA 的 概览 (Overview) 页面。
- 点击右上角的 笔形图标 (编辑仪表盘)。
- 点击右下角 + 添加卡片 (Add Card)。
- 搜索 图片概览 (Picture Glance) 或 图片实体 (Picture Entity)。
- 在“实体 (Entity)”一栏，选择刚才添加的摄像头实体（通常叫 camera.damenkou_main_stream 之类的）。
- 这时候你应该能看到画面了（通常是静态图，几秒刷一次，点进去是直播流）。
- 注：如果你想要低延迟的实时画面，建议在卡片设置里把“查看方式”设为
常见翻车现场及急救 (Troubleshooting)
- 问题 A：一直提示“认证失败”或“无法连接”。
- 原因 1：你用的是登陆摄像头的密码，而不是 ONVIF 用户的密码。再去检查第一步。
- 原因 2：海康威视的安全设置里，把“非法登录锁定”开了。去摄像头后台 -> 系统 -> 安全 -> 安全服务，把“启用非法登录锁定”暂时关掉，或者重启摄像头解封。
- 原因 3：认证类型问题。在摄像头后台的 集成协议 页面，如果你看到有 ONVIF 认证 (ONVIF Authentication) 或 Web认证 (Web Authentication) 选项，请确保选为 Digest/Basic 或者 Digest（尽量兼容 Basic）。
问题 B：能看到画面，但是很卡，延迟十几秒。
- 这是正常的。HA 原生的流媒体有延迟。
- 优化办法：在 HA 的集成里，找到这个设备，确保勾选使用 Substream (子码流) 作为默认预览，因为主码流 4K 画质太大，WIFI 撑不住。
- 或者勾选卡片里的“预加载流 (Preload stream)”。
问题 C：ONVIF 死活添加不上。
- 备用方案：使用 Generic Camera (通用摄像头) 集成。
- 在添加集成时搜 Generic Camera。
- 静态图像 URL: http://admin:密码@IP地址:80/ISAPI/Streaming/channels/101/picture
- 流式传输源 URL (RTSP): rtsp://admin:密码@IP地址:554/Streaming/Channels/101
- (注意：这里用的就是你登陆摄像头的那个 admin 和密码了，不是 ONVIF 的)。
按照这个教程，99% 的海康威视摄像头都能在 5 分钟内接入 Home Assistant 2025.12。祝你成功！
