开始使用 QiHome

01第 1 步

选一种用法。

只装 App

现已提供

家里已经有 Home Assistant：App 会自动发现它，用 Home Assistant 账号登录就能用房间、设备、自动化、小组件和 3D 的家。也可以先打开演示模式看看。

直接到第 3 步

加上 QiHome OS

现已提供

问家里、值得一看、家庭守护、改动历史、插件、家人和访客账号、网页版和断网时的本地兜底，都需要 QiHome OS。装好后用 App 扫码连上。

去第 2 步

02第 2 步 · 稳定版 1.1

选一种装法。

家里一台常开的电脑

本地版 · 全部在家里

Home Assistant 和 QiHome 都装在这台电脑上，不需要云服务器。Ubuntu 22.04 / 24.04、Debian 12 或 64 位 Raspberry Pi OS；树莓派 4 / 5、迷你主机、旧笔记本都行，内存 4 GB 起，8 GB 以上更从容。

在那台电脑上打开终端，运行：

终端

curl -fsSL https://123457.shop/qihome/os/install.sh | sudo bash -s -- --home

装好后，在家里的手机或电脑上打开 qihome.local，跟着向导完成设置。

本地版默认只在家里的网络里能用；在外面用需要你自己的 VPN。

一台云服务器，加家里的轻代理

服务器版 · 在外面也能用

QiHome 装在云服务器上，家里一台常开的设备装 QiHome Edge（轻代理），把家里的 Home Assistant 连过去。外网断了时，家里会自动启用本地版继续工作。

在云控制台放行 80 和 443 端口，登录服务器，运行：

终端

curl -fsSL https://123457.shop/qihome/os/install.sh | sudo bash

打开终端显示的网址，跟着向导走三步。

在家里的设备上装轻代理，再在它的设置页里连上服务器和 Home Assistant：

终端

curl -fsSL https://123457.shop/qihome/os/edge.sh | sudo bash

本地版和服务器版

	本地版 · 全部在家里	服务器版 · 在外面也能用
装在哪	家里一台常开的 Linux 电脑：Ubuntu 22.04 / 24.04、Debian 12 或 64 位 Raspberry Pi OS，内存 4 GB 起	一台 Linux 云服务器（内存 2 GB 起，放行 80 和 443），家里再放一个 QiHome Edge
Home Assistant	和 QiHome 一起装在这台电脑上	留在家里（用你已有的），由 QiHome Edge 接到服务器
在外面用	需要你自己的 VPN	打开网址就能用：HTTPS 证书自动申请，不用公网 IP、端口映射或 VPN
断网时	全部在家里，照常使用	约 1 分钟后 Edge 在家里启用本地兜底；可选备用的 Home Assistant（QiHome Lite）接管设备和自动化
数据在哪	全部在你家里	在你自己的云服务器上，以及家里
需要什么	一台闲置电脑	一台云服务器（按月付费），加家里一台常开的设备
升级	`sudo qihome update`，先自动备份	同左；家里的 Edge 自己更新
适合	只在家里用，想把一切都放在家里	经常在外面用，家里不想开端口

QiHome Edge · 家里的轻代理

服务器版需要

QiHome 装在云服务器上时，家里要放一个很小的 QiHome Edge：它从家里主动连到服务器，把家里的 Home Assistant 安全地接上去，家里不用开端口、不需要公网 IP，也不用 VPN。平时只占约 10 MB 内存；服务器连不上时，它在家里顶上。本地版不需要它。

怎么安装

Mac、树莓派、Debian、Ubuntu：在那台设备的终端里运行（会自动选择安装包；Mac 第一次打开要在“隐私与安全性”里点“仍要打开”）：

macOS / Linux

curl -fsSL https://123457.shop/qihome/os/edge.sh | sudo bash

NAS 或其他装了 Docker 的设备：

Docker

curl -fsSL https://123457.shop/qihome/os/edge.sh | sudo bash -s -- --docker

Windows 10 / 11（预览）：用“以管理员身份运行”打开 PowerShell。第一次可能需要重启一次（开启 WSL），重启后再运行一次同一行：

PowerShell

irm https://123457.shop/qihome/os/edge.ps1 | iex

装好后怎么连

打开 Edge 的设置页浏览器打开 http://这台设备:8765（Mac 会自己打开）。
粘贴配对链接服务器的设置向导会给出配对链接；没有链接，就在 QiHome 网页的“系统 → 配对新设备”里拿一个配对码，连同服务器地址填进“没有链接？”。
登录 Home Assistant 授权Edge 会自动找到家里的 Home Assistant，用它的账号登录。
完成页面显示“已连接”，服务器向导里也会显示“家里的 QiHome Edge 已连接 · Home Assistant 已连接”。之后它开机自动运行，本地兜底待命。

03第 3 步

装上 App，连上你的家。

装了 QiHome OS：在它的网页里打开“配对新设备”，用 App 扫码，在家里 App 也会自动发现它。只有 Home Assistant：App 自动发现，用 Home Assistant 账号登录。

iPhone · iPad · Mac

当前版本

iPhone 与 iPad2.0.0 · iOS 18 起 · 安装包（.ipa）
下载
Mac · Apple 芯片2.0.0 · macOS 15 起
下载
Mac · Intel2.0.0 · macOS 15 起
下载

怎么装到 iPhone 和 iPad

QiHome 还没有上架 App Store。苹果不允许直接点链接安装未上架的 App，下载的安装包要用你自己的 Apple ID 签名后才能装到手机上。免费 Apple ID 签名的 App 每 7 天续签一次，数据不会丢。

下载安装包和 Sideloadly在上面下载 .ipa；在电脑上安装免费的签名工具 Sideloadly（Windows 和 Mac 都有）。Windows 电脑还要装苹果官网版的 iTunes 和 iCloud。
连上手机用数据线连接，手机上点“信任此电脑”。
拖入安装包，填 Apple IDApple ID 密码只发给苹果用于签名；开了双重认证，填手机上收到的验证码。看到 “Done.” 就装好了。
信任你的 Apple ID设置 → 通用 → VPN 与设备管理 → 点你的 Apple ID → 信任。首次使用还要在设置 → 隐私与安全性里打开“开发者模式”。

不想每周连电脑：用 AltStore，电脑上的 AltServer 开着就会在后台自动续签。在 AltStore 里添加源 https://123457.shop/qihome/altstore.json。

怎么装到 Mac

解压，拖进“应用程序”Apple 芯片和 Intel 各有一个安装包。
第一次打开Mac 版还没有苹果签名和公证，macOS 会提示“无法验证开发者”。点“完成”，到系统设置 → 隐私与安全性，点“仍要打开”。只需要一次。

Android

当前版本

Android1.1.0 · Android 8.0 起 · APK，含家庭屏
下载

怎么安装

下载 APK在手机浏览器里点上面的下载。
允许安装系统会问是否允许这个浏览器安装应用，选“允许”，再点安装。
从 1.0.0 升级1.1.0 换了签名，先卸载旧版“栖家”再安装，然后重新连接；家里的设备和自动化不受影响。

网页

装好 QiHome OS 就有，不用安装：在浏览器里打开你的 QiHome 地址，用管理员或家人的账号登录，也可以“添加到主屏幕”。基础设施总览、家庭守护的完整页面和完整的自动化编辑器都在网页上。

像连蓝牙耳机一样，连上你的家。

在家里，App 自己找到
还没连接任何家的 App，在家里的 Wi-Fi 上会自动找到 QiHome（本地版本身，或者服务器版家里的 QiHome Edge），弹出这张卡片，用主人或家庭成员的账号登录就好。
配对码或扫码
QiHome 网页“系统 → 配对新设备”里有二维码和 6 位配对码：App 扫码一步完成，也可以手动输入。配对码 5 分钟内有效，输错 5 次作废。
用账号登录
主人或家庭成员用和网页同一个账号登录，不用配对码。家庭成员的 App 只有成员的权限，成员被移除后就连不上了。
随时收回
QiHome 网页“系统 → 已配对设备”列出每台设备、怎么配对的、最近什么时候在线。点“移除”，它的令牌立刻失效。

3.0公开测试版

QiHome 3.0 测试版，可以下载了。

网页桌面、文件、房间自动化、新的栖家智能和 MCP 都在 3.0 里。它是测试版：大部分功能已经能用，但还会变，也可能有问题。想要稳定，就装上面的 1.1。

QiHome OS 3.0.0-beta.1

测试版

新装（本地版，家里一台常开的 Linux 电脑）：

终端

curl -fsSL https://123457.shop/qihome/os/install.sh | sudo bash -s -- --home --version 3.0.0-beta.1

从 1.1 或 2.0 升级（本地版和服务器版都用这一行，升级前会先自动备份）：

终端

curl -fsSL https://123457.shop/qihome/os/install.sh | sudo bash -s -- --update --version 3.0.0-beta.1

Home Assistant OS 加载项版还没有更新到 3.0。

App 3.0.0（测试版）

测试版

iPhone 与 iPad3.0.0-beta.1 · iOS 18 起 · 安装包（.ipa），装法同下
下载
Mac · Apple 芯片3.0.0-beta.1
下载
Mac · Intel3.0.0-beta.1
下载
Android3.0.0-beta.1 · Android 8.0 起 · 和 1.1 同一个签名，直接覆盖升级
下载

3.0 的 App 搭配 QiHome OS 3.0 才有桌面以外的新功能（文件、房间自动化等）。

04系统要求

需要什么。

本地版Ubuntu 22.04 / 24.04、Debian 12 或 64 位 Raspberry Pi OS；树莓派 4 / 5、迷你主机、旧笔记本都行；内存 4 GB 起，8 GB 以上更从容。目前只支持 Linux。
服务器版一台 Linux 云服务器，内存 2 GB 起，放行 TCP 80 和 443；家里再放一台常开的设备装 QiHome Edge。
QiHome EdgeMac、树莓派或 Linux 电脑、能跑 Docker 的 NAS；Windows 10 / 11 也可以（预览）。最好和 Home Assistant 在同一个网络里。
iPhone · iPadiOS 18 起。扫描户型需要带激光雷达的机型。
MacmacOS 15 起，Apple 芯片或 Intel。
AndroidAndroid 8.0 起。
网页现代浏览器。宽屏打开是桌面，手机浏览器里是经典布局。

05升级与备份

升级之前，先备份；出了问题，能放回去。

在装 QiHome 的电脑上运行这些命令。升级和卸载都会保留你的设置、设备和数据。

升级（先自动备份）

sudo qihome update

手动备份

sudo qihome backup

恢复（不带文件名时列出所有备份；恢复前会先保存当前状态）

sudo qihome restore

异地备份到你自己的存储：sudo qihome offsite --now。
卸载时数据默认保留：sudo qihome uninstall；加 --purge 会在最后备份一次后删除数据。
插件更新坏了会自动退回上一版；QiHome 里的改动可以在“改动历史”里退回。

06遇到问题

装的时候卡住了？

云服务器上打不开 QiHome 网页

先在云控制台的“安全组”（轻量服务器叫“防火墙”）放行 TCP 80 和 443，来源 0.0.0.0/0。服务器自己开了 ufw 的话，也要放行这两个端口。80 和 443 也是自动申请 HTTPS 证书要用的。

网址里带着 :8443，浏览器提示“不安全”

说明服务器的 443 端口已经被别的程序占用，QiHome 用了自己的证书。第一次点“高级 → 继续前往”即可，同时记得在安全组里放行 8443。想和已有的 nginx、Home Assistant 共存，可以用高级安装。

本地版安装时提示端口 80 被占用

这台电脑上已经有别的网页服务。QiHome 会自动换一个端口，终端最后显示的地址里带着端口号，照那个地址打开就行。

qihome.local 打不开

有些安卓手机不认 .local 名字，用终端里显示的 IP 地址打开就行；也可以扫终端里的二维码。手机要和那台电脑在同一个 Wi-Fi 里。

我的电脑是 Windows 或 Mac，能装本地版吗

本地版目前只支持 Linux（Ubuntu 22.04 / 24.04、Debian 12、64 位 Raspberry Pi OS）。可以把旧电脑装成 Ubuntu，或者改用服务器版：Mac 和 Windows 可以当家里的 QiHome Edge。

QiHome Box 是以后的家用硬件，现在还没有开卖。

三步，用上 QiHome。