Feng's Blog

7.13 HA巴法云插件兼容修复

Properties1
tags网络基建

7分钟阅读

对话笔记直发：7.13 HA巴法云插件兼容修复。分类：网络基建。

HA 巴法云插件兼容修复（jp NAS Home Assistant 2026.7.1）

时间

  • 操作日期：2026-07-12（jp 服务器日志时间戳，中国时区）
  • 笔记记录日期：2026-07-13
  • 涉及服务器：jp（IP 局域网IP（已脱敏），hostname jp-tvbox-3566，aarch64，多服务 Docker host）

用户目标

jp NAS 上的 Home Assistant 把容器更新到最新版本（stable 标签，实际跑的是 2026.7.1）后，巴法云（bemfa）自定义集成无法加载（前端显示”未加载”）。要求排查并修复，参考 hassbian 论坛帖：https://bbs.hassbian.com/thread-30520-1-1.html

背景与上下文

  • HA 容器名 homeassistant，镜像 ghcr.io/home-assistant/home-assistant:stable，配置挂载：宿主机 /opt/ha/config → 容器内 /config
  • 巴法云插件位于 /config/custom_components/bemfa/，原始版本为 2024-07 的旧版（基于 larry-wong/bemfa）
  • jp 服务器是 multi-service Docker host；/mnt/vps/jp/ha 对应 homeassistant 容器
  • 论坛帖子结论：HA 25.03+ 后 bemfa 因 MQTT 库不兼容失效；9# 楼指出 ImportError: cannot import name 'STATE_IDLE' from 'homeassistant.components.camera'

过程摘要

  1. 读取论坛帖子，确认是已知兼容性问题（HA 高版本移除/重命名了多个旧 API）。
  2. SSH 进 jp，确认 HA 实际版本为 2026.7.1（极新），bemfa 文件日期 2024-07。
  3. 第一轮诊断：旧版 sync_switch.py 同时导入 STATE_IDLE（camera）和 STATE_LOCKED（const），均已被新版 HA 删除 → ImportError，集成无法加载。做了最小化补丁（本地定义常量），重启后 loader 仅报”未测试”警告，无 ImportError。
  4. 用户确认切换到维护版：从 https://github.com/FightTogether/bemfa.git 拉取 v1.4.0（git clone HTTPS 因 GnuTLS TLS 中断失败，改用 tarball 下载），覆盖 custom_components/bemfa/，旧版整体备份为 bemfa.old.bak。
  5. 重启后用户仍报”未加载”。第二轮诊断：维护版 v1.4.0 在 2026.7.1 上仍有 7 处失效导入，最关键报错： cannot import name 'area_entities' from 'homeassistant.helpers.template'（sync_sensor.py:17）。
  6. 写 Python 脚本扫描整个 bemfa 包对所有 homeassistant 导入的兼容性（AST 解析 + importlib.import_module 逐个校验），定位全部 7 个问题符号：
    • sync_sensor.py：area_entities（已从 homeassistant.helpers.template 移除，现为 template extension 类的方法，签名也变了）
    • sync_switch.py：STATE_IDLE（camera 移除）、STATE_CLEANING（vacuum 移除，现为 mqtt/vacuum.py 内部私有 "cleaning"）、STATE_LOCKED（const 移除）
    • sync_light.py：ATTR_COLOR_TEMP / ATTR_MAX_MIREDS / ATTR_MIN_MIREDS（light 移除，现为组件内部私有字面量）
  7. 修复方式：
    • sync_sensor.py：把 from homeassistant.helpers.template import area_entities 换成导入 area_registry, entity_registry as er, device_registry as dr，并在文件末尾追加本地 area_entities(hass, area_id_or_name) 函数，用 er.async_entries_for_area / dr.async_entries_for_area / er.async_entries_for_device 重建等价逻辑（已确认这些 API 在 2026.7.1 存在）。
    • sync_switch.py / sync_light.py：从导入语句删除失效符号，并在文件末尾追加本地常量定义（稳定字符串值："idle" / "cleaning" / "locked" / "color_temp" / "max_mireds" / "min_mireds"）。
  8. 重新跑兼容性扫描 → ALL_OK。重启 HA。
  9. 验证：最近一次启动（23:58）日志仅出现 custom integration bemfa which has not been tested（导入成功标志），无 Unable to import / Setup failed / Error setting up entry bemfa；配置项 bemfa 存在且 disabled_by: None；bemfa 云 broker bemfa.com:9501 从 jp 服务器可达。

关键结论

  • 根因：bemfa 自定义集成（无论旧版还是维护版 v1.4.0）与 HA 2026.7.1 不兼容，多个公共常量/函数已被移除或改为私有字面量。
  • 修复有效：全部 7 处失效导入已通过本地常量/函数替代解决，集成现在能正常加载。
  • 维护版 v1.4.0 的 mqtt.py 已使用 paho 2.x API（mqtt.Client(mqtt.CallbackAPIVersion.VERSION1, client_id=uid, protocol=mqtt.MQTTv311)），容器已自带 paho-mqtt 2.1.0，无需额外安装；巴法云走独立 paho 连接，不依赖 HA 自带 mqtt 集成。

执行动作

  • 备份：旧版 bemfa 整体备份到 custom_components/bemfa.old.bak；每个被改文件备份为 *.py.bak（sync_switch.py.bak、sync_light.py.bak、sync_sensor.py.bak）。
  • 替换：用 FightTogether/bemfa v1.4.0 覆盖 custom_components/bemfa/。
  • 补丁：在 3 个文件中删除失效导入行并追加本地兼容定义。
  • 多次 docker restart homeassistant 验证加载结果。

执行命令记录

（重要命令，保留原始形式）

  1. 确认 HA 版本与 bemfa 目录：
ssh root@`局域网IP（已脱敏）` 'docker exec homeassistant python -c "import homeassistant; print(homeassistant.const.__version__)"'
# 结果：2026.7.1
  1. 下载维护版（git clone HTTPS 因 TLS 失败，改用 curl tarball）：
curl -sL https://github.com/FightTogether/bemfa/archive/refs/heads/main.tar.gz -o /tmp/bemfa-main.tar.gz
tar -xzf /tmp/bemfa-main.tar.gz -C /tmp/bemfa-fixed --strip-components=1

  1. 全量导入兼容性扫描（容器内运行 /tmp/scan.py，BASE=/config/custom_components/bemfa）—— 发现 7 个 NAME_MISSING。

  2. 删除失效导入行（示例）：

sed -i "/^    STATE_CLEANING,$/d" /opt/ha/config/custom_components/bemfa/sync_switch.py
sed -i "/^    STATE_LOCKED,$/d"    /opt/ha/config/custom_components/bemfa/sync_switch.py
sed -i "s#from homeassistant.components.camera import DOMAIN as CAMERA_DOMAIN, STATE_IDLE#from homeassistant.components.camera import DOMAIN as CAMERA_DOMAIN#" /opt/ha/config/custom_components/bemfa/sync_switch.py
sed -i "/^    ATTR_COLOR_TEMP,$/d" /opt/ha/config/custom_components/bemfa/sync_light.py
sed -i "/^    ATTR_MAX_MIREDS,$/d" /opt/ha/config/custom_components/bemfa/sync_light.py
sed -i "/^    ATTR_MIN_MIREDS,$/d" /opt/ha/config/custom_components/bemfa/sync_light.py
sed -i "s#from homeassistant.helpers.template import area_entities#from homeassistant.helpers import area_registry, entity_registry as er, device_registry as dr#" /opt/ha/config/custom_components/bemfa/sync_sensor.py
  1. 验证 bemfa 云 broker 可达：
docker exec homeassistant bash -c "getent hosts bemfa.com"   # `你的服务器IP（已脱敏）`
# 宿主机 /dev/tcp/bemfa.com/9501 可达
  1. 重启并扫描 bemfa 错误：
docker restart homeassistant
docker logs homeassistant 2>&1 | grep -iE "bemfa|Unable to import|Error setting up"
# 最新启动仅 loader 警告，无错误

关键输出与结果

  • 扫描结果（修复前，7 个 NAME_MISSING）：
('/config/custom_components/bemfa/sync_sensor.py', 'NAME_MISSING area_entities from homeassistant.helpers.template', '')
('/config/custom_components/bemfa/sync_switch.py', 'NAME_MISSING STATE_IDLE from homeassistant.components.camera', '')
('/config/custom_components/bemfa/sync_switch.py', 'NAME_MISSING STATE_CLEANING from homeassistant.components.vacuum', '')
('/config/custom_components/bemfa/sync_switch.py', 'NAME_MISSING STATE_LOCKED from homeassistant.const', '')
('/config/custom_components/bemfa/sync_light.py', 'NAME_MISSING ATTR_COLOR_TEMP from homeassistant.components.light', '')
('/config/custom_components/bemfa/sync_light.py', 'NAME_MISSING ATTR_MAX_MIREDS from homeassistant.components.light', '')
('/config/custom_components/bemfa/sync_light.py', 'NAME_MISSING ATTR_MIN_MIREDS from homeassistant.components.light', '')
  • 修复后扫描结果：ALL_OK
  • 启动日志关键行（23:58 启动）：
2026-07-12 23:58:02 WARNING We found a custom integration bemfa which has not be

---

> 注：本文涉及的服务器公网 IP / Tailnet / 局域网 IP 已脱敏，请替换为你自己的地址。

---
**相关**： [[00-索引-玩机NAS索引]] [[5.8 JP NAS 本地部署 Kimi GLM 统一网关]]

关系图谱

反向链接