更新与使用问题排查

先记录 HA Bridge 显示的版本、Docker 或 Add-on 安装方式，以及通过局域网 IP 还是域名访问。这几项通常能帮助区分版本、网络和控件配置问题。

本轮更新的适用范围

本文涉及的反向代理模型加载修复、空调横排规则、3D 预览优化和账号独立文件重置，均属于 v0.4.5 之后的待发布更新。本文编写时正式版仍为 v0.4.5，请在包含相应改动的版本发布后更新验证。

更新后没有看到新功能

1. 检查容器或 Add-on 的运行版本，确认新版本已经在自己的发布渠道提供。
2. 独立 Docker 容器需要完成拉取镜像和重新创建；只下载镜像不会替换已运行的程序。
3. 保存正在编辑的内容，再刷新页面。若仍显示旧界面，尝试强制刷新，或用无痕窗口重新登录对比；使用反向代理缓存时也检查是否缓存了旧 HTML 或脚本。
4. 如果仍缺少对应入口，带上版本和安装方式反馈。

beta、latest、固定版本标签和 Add-on 是不同更新入口。beta 不会因为正式版发布而自动变成 latest；固定版本标签也不会自动跳到下一版本。日常更新方法见使用 DockerCopilot 更新或HAOS（冬瓜）部署。

域名访问时3D模型一直加载

先在可信局域网中，用同一浏览器通过设备 IP 和实际 HA Bridge 端口打开相同户型，再与域名访问对比。无需为了排查额外开放公网端口。

• IP 正常，域名一直加载：重点检查反向代理、缓存、资源路径和浏览器安全策略。
• 两种方式都异常：继续检查应用日志、模型资源是否能加载，以及浏览器是否支持当前 3D 渲染；不能仅凭这一现象判断为反向代理问题。

本轮更新改进了压缩模型的加载方式，可兼容只允许同源 Worker 的反向代理安全策略；加载器启动失败时也会及时进入模型回退。它不能替代所有反向代理配置，网络错误或资源被拦截仍需要处理。

熟悉代理配置的用户可在浏览器开发者工具中查看失败请求和控制台错误，重点核对：

• /bridge-static/ 下的模型、解码脚本和 WASM 请求是否返回正确文件，而非 404、登录页或代理错误页；
• 代理添加的 Content-Security-Policy（CSP）是否允许同源 Worker、脚本以及所需的 WASM 执行；
• 是否仍缓存旧版本页面或脚本。

遇到明确的拦截错误时，按对应策略项调整，不需要直接关闭整套安全策略。

空调选项为什么有的横排、有的下拉

本轮更新后，运行模式、风速、摆风、预设模式等各自判断所需宽度：能放下一行的保留横向按钮，超出的那一组才使用下拉；不会因为摆风选项多，就把其他功能组一并改成下拉。

常见模式优先显示中文，已知英文名称会转换为对应中文；未知模式保留 Home Assistant 提供的名称。功能取决于实体实际提供的能力，不按品牌限定，详见空调 / 浴霸。

点击控件没有弹窗

先切换到「仪表盘」模式，确认使用了配置的点按、双击或长按动作，再检查关联实体和弹窗目标。如果按钮被上层透明图片或其他控件挡住，请从图层列表检查覆盖关系，再调整该区域的控件顺序。

这类遮挡不一定是空调适配问题。反馈时说明哪个页面、哪个控件、使用什么手势，以及是否只在中控设备出现。

3D旋转中心偏移或第一次开灯停顿

本轮更新后，「重置视角」会按墙体、地面、门窗等户型结构重新计算中心。远处的家具、电器、汽车、灯具和铭牌不再把中心拉偏；已有保存视角和手动平移仍保留各自的中心，需要重新居中时先点击「重置视角」。

户型绘制工作室会在浏览器空闲时提前准备灯光渲染，减少第一次开灯的等待。刚进入就立即开灯、户型很大或设备性能有限时仍可能出现短暂停顿。若持续卡顿，请反馈浏览器、设备型号、楼层和灯具数量，以及是否只发生在第一次开灯；详细操作见3D 预览与视角。

忘记账号密码或更新后出现设置页

• 忘记本地管理员凭据时，按重置本地账号与密码处理。
• 主动删除了独立账号文件并重启后，进入设置页是正常现象。
• 普通更新后意外进入设置页，应先检查数据挂载和账号文件是否遗漏；不要立刻新建账号、清空目录或覆盖备份。

反馈问题时提供什么

提供版本、安装方式、浏览器或中控设备型号、复现步骤、是否能通过局域网 IP 正常访问，以及相关报错截图或脱敏日志即可。分享前移除密码、HA 令牌、激活码、Cookie、账号文件和密钥等敏感信息。