ViCare 认证机制大改版：OAuth2 + Client ID 三步搞定，告别 401 报错
【免费下载链接】core:house_with_garden: Open source home automation that puts local control and privacy first.项目地址: https://gitcode.com/GitHub_Trending/co/core
Home Assistant 的 Viessmann ViCare 集成把认证机制从"配置里存明文密码"改为 OAuth2 令牌流程。存量配置会自动迁移，升级后设备照常在线，认证失败不再反复出现。
新旧方案对比：从明文密码到 OAuth2 令牌
旧方案：用户名、密码、Client ID 直接写在集成配置里，每次靠它们调威仕曼云。新方案：集成走 OAuth2 + PKCE，HA 只保存访问令牌，密码不再落盘。
左侧是旧数据流：凭证跟着每个请求走；右侧是新数据流：令牌先找认证服务器要，再带着令牌访问业务 API。
核心原理：令牌怎么拿、旧配置怎么迁
迁移逻辑在homeassistant/components/vicare/__init__.py的async_migrate_entry中：
# 旧配置 1.2 -> 2.1 的关键步骤 await async_import_client_credential(hass, DOMAIN, ClientCredential(client_id, "", username)) token = await hass.async_add_executor_job( obtain_token_via_basic_auth_pkce, client_id, username, password) data.pop(CONF_USERNAME) data.pop(CONF_PASSWORD) # 明文凭证从配置中移除白话说：系统把你原来填的 Client ID 导入到 HA 的应用凭证框架（application_credentials），再用一次性的"用户名密码 + PKCE"换回令牌存进配置，随后把密码从配置里删掉。令牌文件名定义在homeassistant/components/vicare/const.py的VICARE_TOKEN_FILENAME，迁移完成即删除旧文件。
动手配置：三步完成 Client ID 申请与集成接入
- 申请 Client ID：登录威仕曼开发者门户（
application_credentials提示页会给出入口），创建新应用，勾选 IoT 与 Offline Access 权限。 - 填写重定向 URI：填
/auth/external/callback（必须与 HA 实际回调路径完全一致），复制生成的 Client ID 与 Client Secret。 - 在 HA 接入：
设置 → 设备与服务 → 添加集成 → Viessmann ViCare- 按提示粘贴 Client ID / Client Secret
- 跳转威仕曼登录页授权，浏览器回到 HA 后集成自动加载
⚠️ 重定向 URI 写错一个字符，令牌就换不回来，表现为"重定向 URI 不匹配"，需要回门户改完再来。
踩坑速查：三个高频问题
现象：日志出现OAuth2 token is invalid, please re-authenticate。原因：令牌过期且刷新失败，或 Client Secret 被轮换。解法：面板会弹出重新认证通知，点一下走一遍授权即可，设备列表不需要重建。
现象：vicare_token.save文件找不到。原因：新版不再使用这个文件，迁移时 HA 会主动删掉它。解法：无需处理；如果手动升级后集成掉线，重新触发一次重新认证就能恢复。
现象：日志出现Vicare API rate limit exceeded，设备状态刷新变慢。原因：轮询频率超过威仕曼云端限流阈值。解法：降低自动化里的轮询间隔。HA 也会按设备数量自动拉长缓存时长（默认 60 秒 × 设备数），多设备家庭属正常行为。
收尾
用 OAuth 令牌取代明文密码，是云集成认证的正确方向。存量用户无需手动操作：升级后按配置问题面板的通知把重定向 URI 更新一下即可，其余交给自动迁移。
【免费下载链接】core:house_with_garden: Open source home automation that puts local control and privacy first.项目地址: https://gitcode.com/GitHub_Trending/co/core
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
