homeassistant-jackery/MQTT_FIX_SUMMARY.md

MQTT 连接问题修复摘要

问题描述

用户遇到 MQTT 连接错误：

[Errno 113] Host is unreachable
WARNING (MainThread) [custom_components.jackery_home.sensor] MQTT not ready: Error talking

根本原因

JackeryHome 集成依赖 Home Assistant 的内置 MQTT 组件，但存在以下问题：

1. 配置流程误导：配置界面收集了 mqtt_broker 和 mqtt_port 参数，但这些参数从未被使用
2. 缺少依赖检查：没有验证 MQTT 集成是否已配置和可用
3. 错误提示不明确：当 MQTT 不可用时，错误消息不够清晰

实施的修复

1. 更新 __init__.py - 添加 MQTT 可用性检查

变更：

• 导入 homeassistant.components.mqtt 模块
• 在 async_setup_entry 中添加 mqtt.async_wait_for_mqtt_client() 检查
• 如果 MQTT 不可用，返回 False 并记录清晰的错误消息

代码：

# 检查 MQTT 集成是否已配置和可用
if not await mqtt.async_wait_for_mqtt_client(hass):
    _LOGGER.error(
        "MQTT integration is not available or not configured. "
        "Please set up the MQTT integration first: "
        "Settings -> Devices & Services -> Add Integration -> MQTT"
    )
    return False

2. 更新 config_flow.py - 简化配置并验证 MQTT

变更：

• 移除 mqtt_broker 和 mqtt_port 配置参数（不再需要）
• 保留 topic_prefix 参数（可选配置）
• 在配置时验证 MQTT 集成是否可用
• 添加 mqtt_not_configured 错误处理

更新的配置架构：

DATA_SCHEMA = vol.Schema(
    {
        vol.Optional(
            "topic_prefix",
            default="homeassistant/sensor"
        ): str,
    }
)

3. 更新 sensor.py - 改进错误处理

变更：

• 在 async_start() 中添加 try-except 块捕获订阅错误
• 改进 MQTT 发布失败时的错误消息
• 提供更清晰的故障排除指导

改进的错误消息：

except Exception as mqtt_error:
    _LOGGER.warning(
        f"MQTT publish failed: {mqtt_error}. "
        f"Please check MQTT broker connection. "
        f"Will retry in {REQUEST_INTERVAL} seconds..."
    )

4. 更新翻译文件

strings.json 和 zh-Hans.json：

• 更新配置描述，说明需要先配置 MQTT 集成
• 移除 mqtt_broker 和 mqtt_port 相关文本
• 添加 mqtt_not_configured 错误消息
• 更新 single_instance_allowed 错误消息

5. 创建故障排除文档

新建 TROUBLESHOOTING.md：

• 详细说明 MQTT 连接问题的原因和解决方案
• 提供 Mosquitto Add-on 和外部 broker 的配置指南
• 包含调试步骤和常用命令
• 说明如何启用详细日志

6. 更新集成文档

更新 custom_components/JackeryHome/README.md：

• 添加"前置要求"章节，强调 MQTT 依赖
• 更新安装步骤，包含 HACS 和手动安装方法
• 更新 MQTT 主题格式说明，反映实际使用的主题
• 扩展故障排除章节，添加常见问题解决方案
• 添加调试日志配置示例

manifest.json 中的依赖声明

确认 manifest.json 中已正确声明 MQTT 依赖：

{
  "dependencies": [
    "mqtt"
  ]
}

这确保 Home Assistant 在加载 JackeryHome 之前先加载 MQTT 组件。

用户需要采取的操作

立即操作（修复当前问题）：

1. 配置 MQTT 集成：

   • 进入 Home Assistant：设置 → 设备与服务
   • 点击 添加集成，搜索 MQTT
   • 输入正确的 MQTT broker 地址和端口
   • 如果使用 Mosquitto Add-on，broker 地址通常是 core-mosquitto 或 localhost

2. 验证 MQTT 连接：

   • 在 MQTT 集成中检查连接状态
   • 应显示"已连接"状态

3. 重新加载 JackeryHome 集成：

   • 进入 设置 → 设备与服务
   • 找到 JackeryHome 集成
   • 点击"重新加载"

更新后操作：

1. 更新 JackeryHome 集成到最新版本
2. 如果之前配置过 mqtt_broker 和 mqtt_port，可以删除这些配置（它们不再使用）
3. 确保 MQTT 集成已正确配置

技术改进

1. 依赖检查：明确验证 MQTT 组件可用性
2. 错误处理：更好的异常捕获和错误消息
3. 用户体验：清晰的配置指导和错误提示
4. 文档完善：详细的故障排除指南和使用说明

测试建议

测试场景 1：MQTT 未配置

1. 确保 MQTT 集成未配置
2. 尝试添加 JackeryHome 集成
3. 预期结果：显示"MQTT 集成未配置"错误

测试场景 2：MQTT 配置但不可达

1. 配置 MQTT 集成但使用错误的 broker 地址
2. 添加 JackeryHome 集成
3. 预期结果：集成显示错误，日志中有清晰的错误消息

测试场景 3：正常工作

1. 正确配置 MQTT 集成并连接
2. 添加 JackeryHome 集成
3. 运行数据模拟器
4. 预期结果：传感器正常创建并显示数据

向后兼容性

• 移除了未使用的 mqtt_broker 和 mqtt_port 配置选项
• 保留了 topic_prefix 配置选项
• 现有安装需要确保 MQTT 集成已配置

相关文件

修改的文件：

• custom_components/JackeryHome/__init__.py
• custom_components/JackeryHome/config_flow.py
• custom_components/JackeryHome/sensor.py
• custom_components/JackeryHome/strings.json
• custom_components/JackeryHome/translations/zh-Hans.json
• custom_components/JackeryHome/README.md

新增的文件：

• TROUBLESHOOTING.md
• MQTT_FIX_SUMMARY.md（本文件）

下一步

1. 测试修复是否解决用户的问题
2. 根据用户反馈进一步优化
3. 考虑添加 MQTT 连接状态传感器
4. 更新 CHANGELOG.md
5. 准备新版本发布