企业官网建设流程全解析

Home-Assistant-Matter-Hub 是一个开源的 Matter 桥接项目，能把你的 Home Assistant 设备发布到 Apple Home、Google Home、Alexa 等 Matter 平台。由于原版 t0bst4r 项目已于 2026 年 3 月归档停更，本文介绍如何把 t0bst4r 版本平滑迁移到持续维护的 Home-Assistant-Matter-Hub，核心结论先说清楚：两个版本的存储格式完全兼容，迁移全程不会丢失 Matter Fabric 连接，所有已配对的设备都无需重新配网。

Home-Assistant-Matter-Hub 迁移后的 Web 仪表盘，展示 Bridge 运行状态、设备数量与 Matter Fabric 连接数

为什么要把 t0bst4r 迁移到新版 Home-Assistant-Matter-Hub

在动手之前，先看看两个版本的现状对比：

最后一行是迁移安全感的来源：Matter 存储格式逐字节一致，Fabric 数据（即与 Apple Home、Google Home、Alexa 的连接凭证）在两个版本间通用，迁移后自动重连。更详细的对比见 fork-comparison.md。

迁移前准备：2 分钟备份 + 记录配置

迁移动作本身很轻，但备份是保险：

1. 备份存储目录（Fabric 数据都在这里）；
2. 记录当前 Bridge 的设置（端口、实体过滤规则等），方便迁移后核对。

完成迁移后，新版 Web 界面还内置了备份与恢复页面，支持导出包含 Matter 身份文件（密钥、Fabric 凭证）的完整备份，后续再迁移或重装都不用担心：

Home-Assistant-Matter-Hub 备份与恢复页面，可下载含 Matter 身份的完整备份，保障 Fabric 连接不丢失

方法一：Home Assistant 插件（Add-on）迁移步骤（推荐）

适合使用 Home Assistant OS 的用户，步骤如下：

第 1 步：备份存储数据

通过 SSH 或终端登录 Home Assistant，把插件数据目录复制出来：

cp -r /addon_configs/*_hamh /config/hamh-backup ls /config/hamh-backup # 确认备份成功

第 2 步：卸载旧插件

进入设置 → 插件 → Home Assistant Matter Hub，点击卸载，并确认旧数据目录已删除：

rm -rf /addon_configs/*_hamh

第 3 步：添加插件仓库

进入设置 → 插件 → 插件商店，点击右上角三个点（⋮）→Repositories，添加官方插件仓库地址riddix/home-assistant-addons（完整地址见 installation.md），点击添加。

第 4 步：安装并恢复数据

找到维护分支的Home-Assistant-Matter-Hub插件并安装。先启动一次（让它创建数据目录）再停止，然后清空新目录并恢复备份：

rm -r /addon_configs/*_hamh/* cp -r /config/hamh-backup/* /addon_configs/*_hamh/

第 5 步：配置并启动

把之前记录的插件配置填回设置页，点击启动。几分钟后，你的 Matter Fabric 会自动重连。

方法二：Docker 容器迁移步骤

如果你是用 Docker 直接运行的，流程更简单——只需要换镜像，数据卷不动：

docker stop home-assistant-matter-hub # 备份存储目录（默认位置） cp -r ~/.home-assistant-matter-hub ~/.home-assistant-matter-hub-backup

然后删除旧容器、拉取新镜像，用和原来相同的参数启动（HA 地址、Access Token、端口、数据卷挂载路径保持不变）：

docker rm home-assistant-matter-hub docker pull ghcr.io/riddix/home-assistant-matter-hub:latest docker run -d \ --name home-assistant-matter-hub \ --network host \ -v ~/.home-assistant-matter-hub:/data \ -e HAMH_HOME_ASSISTANT_URL="http://homeassistant.local:8123" \ -e HAMH_HOME_ASSISTANT_ACCESS_TOKEN="your-token" \ ghcr.io/riddix/home-assistant-matter-hub:latest

启动后 Matter 连接应立即恢复，无需重新配网。

方法三：Docker Compose 一键更新镜像

如果用的是docker-compose.yml，改动只有一行——把image从 t0bst4r 的镜像换成维护分支的镜像：

image: ghcr.io/riddix/home-assistant-matter-hub:latest

然后重启即可：

docker compose down docker compose pull docker compose up -d

这是最省心的迁移方式：Compose 文件里的数据卷和环境变量全部保留。

验证 Matter Fabric 是否成功重连

启动插件/容器后，打开 Web 界面进入 Bridge 详情页，重点看Connected Fabrics卡片：原来连接的 Apple Home、Google Home 等 Fabric 图标应该都在列表中，状态显示 Running。如果迁移后一切正常，这里显示的 Fabric 数量和迁移前完全一致。

Home-Assistant-Matter-Hub 桥接详情页 Connected Fabrics 卡片，用于验证 Matter Fabric 连接在迁移后成功重连

如果设备没有立刻出现，按下面顺序排查（详见 migration-from-t0bst4r.md 的故障排查章节）：

1. 等待 2~3 分钟：Matter 设备重连需要时间，这是最常见的“假故障”；
2. 查看日志：插件用ha addon logs hamh，Docker 用docker logs home-assistant-matter-hub；
3. 重启 Matter 控制器：打开 Apple Home / Google Home 应用触发重连；
4. 遇到网络层问题（mDNS / IPv6）时，参考 connectivity-issues.md。

另外，如果日志里出现存储权限报错，调整一下数据目录的属主即可：

sudo chown -R $(whoami):$(whoami) ~/.home-assistant-matter-hub

随时回滚：迁移后悔了怎么办

因为存储格式双向兼容，回滚同样无损：

1. 停止维护分支的插件/容器；
2. 用迁移前做的备份恢复数据；
3. 重新安装 t0bst4r 原版插件或拉取旧镜像。

Fabric 依然可用，来回切换都不需要重新配网。

迁移后你能获得什么新功能

换版本不只是"续命"，维护分支新增了大量原版没有的设备类型和能力（完整清单见 supported-device-types.md）：

Home-Assistant-Matter-Hub 全部设备列表页面，展示迁移后支持的新设备类型与端点管理

💡 需要说明的是：新增设备类型都是可选开启的覆盖项，不会改变默认行为——已配对的设备在升级后不会被重新组合，现有 Fabric 连接保持原样。

总结：一条命令式的迁移心法

把整个方案浓缩成一句话：备份存储目录 → 换装新版 → 恢复数据 → 等待重连。

• 存储格式双向兼容，Matter Fabric 凭证原样保留；
• 三种部署方式（Add-on / Docker / Compose）都有对应步骤；
• 出问题可等待重连、查日志、重启控制器，极端情况可无损回滚。

迁移完成后，建议顺手在新版 Web 界面里下载一次含身份的完整备份，作为下一次折腾的保险。祝迁移顺利，你的 Matter 设备们会"无感"地跟着你一起搬家 🏠