HomeAssistant连接科沃斯失败如何排查？

Question

当Home Assistant无法连接科沃斯扫地机器人时，常见问题之一是设备认证失败。这通常源于科沃斯云API密钥（ECOVACS_IOT_TOKEN）过期或区域配置错误。用户在集成配置中输入的邮箱、密码及服务器区域（如中国区cn、北美区na）必须与科沃斯账户完全匹配。此外，频繁登录尝试可能触发账号安全锁定，导致连接超时。建议检查网络连通性，确认Home Assistant可访问外网，并使用最新版“Ecovacs Integration”插件。若仍失败，可通过抓包工具或日志查看具体错误码，如“Invalid credentials”或“Device not found”，进一步定位认证或设备注册问题。

Answer 1

Home Assistant连接科沃斯扫地机器人认证失败的深度排查与解决方案

1. 问题背景与表层现象分析

在使用Home Assistant集成科沃斯扫地机器人时，用户常遇到“设备认证失败”这一典型问题。最直观的表现是：添加集成后提示登录错误、设备未发现或连接超时。这些现象往往归因于ECOVACS_IOT_TOKEN失效或区域配置不匹配。

• 常见错误码包括：Invalid credentials
• Device not found
• Authentication failed due to region mismatch

初步判断应从账户凭证和网络连通性入手。

2. 认证机制解析：ECOVACS IOT API 工作原理

科沃斯通过其私有云平台提供IOT服务，所有第三方接入（如Home Assistant）均需通过OAuth-like流程获取ECOVACS_IOT_TOKEN。该token通常具有时效性（约7天），过期后需重新认证。

认证流程如下：

1. 客户端提交邮箱、密码及区域标识（如cn/na/eu）
2. 服务器验证凭据并返回用户UID与临时token
3. 通过UID+token请求设备列表
4. 建立WebSocket长连接控制设备

若任一环节信息错配，将导致链路中断。

3. 区域配置错误的深层影响

科沃斯采用多区域云架构，不同区域间数据隔离。例如中国区账户（server: cn）无法在北美区（na）API端点完成认证。

区域标识	API域名	适用国家
cn	api.ecovacs.cn	中国大陆
na	api-us.ecovacs.com	北美、南美
eu	api-eu.ecovacs.com	欧洲
ru	api-ru.ecovacs.com	俄罗斯

用户若在Home Assistant中误选区域，即使账号密码正确也会返回“Invalid credentials”。

4. 安全策略与频繁尝试引发的锁定机制

科沃斯后端具备防暴力破解机制。连续5次以上失败登录将在IP或账户维度触发临时封禁（持续数分钟至数小时）。

Logger: custom_components.ecovacs
Source: custom_components/ecovacs/__init__.py:123
Error: Failed to connect - response code 401, message: "Too many login attempts"

此情况下即使修正配置也无法立即恢复，需等待冷却周期结束或更换公网IP出口。

5. 网络与插件版本依赖检查清单

确保环境基础条件满足：

• Home Assistant可访问外网（测试命令：ping api.ecovacs.cn）
• 防火墙/NAT规则未阻断HTTPS出站请求
• DNS解析正常（避免污染）
• 已安装最新版“Ecovacs Integration”（GitHub仓库更新频繁）
• 确认插件支持当前固件版本机器人型号

6. 日志分析与抓包诊断流程图

graph TD A[开始排查] --> B{查看HA日志} B -->|含'Invalid credentials'| C[核对邮箱/密码/区域] B -->|'Device not found'| D[确认设备已在App绑定] C --> E[清除缓存并重试] D --> F[重启Ecovacs服务] E --> G{是否成功?} F --> G G -->|否| H[启用Debug模式] H --> I[使用Wireshark抓包分析HTTPS交互] I --> J[提取实际请求Host与Payload] J --> K[比对官方API文档参数格式]

7. 高级调试手段：手动获取Token验证

可通过Python脚本模拟认证过程，绕过集成层定位问题：

import requests

url = "https://api.ecovacs.cn/v1/user/login"
payload = {
    "account": "[e-mail]",
    "password": "your_hashed_password",
    "country": "CN",
    "lang": "zh-CN"
}
headers = {"User-Agent": "Ecovacs/App"}
response = requests.post(url, json=payload, headers=headers)
print(response.json())

注意：密码需经SHA256加密后再Base64编码，具体算法可在开源项目ozmartians/pyecovacs中参考。