VPS 搭建 Home Assistant Container 教程：Docker、MQTT、HTTPS 与备份 | 2026

Home Assistant 是开源的家庭自动化平台，可以把灯光、传感器、摄像头、空调、能源计量和自动化规则集中到一个控制台。把 Home Assistant 放在 VPS 上，适合管理远程设备、云端服务和跨地点的自动化；但它并不等于“把整个智能家居都搬到云端”，局域网设备仍需要稳定的网络、网关或 VPN。

本文使用 Ubuntu 24.04、Docker Compose 和 Home Assistant Container 部署。先说明一个容易踩坑的区别：

Home Assistant Container：最适合 VPS，升级和备份简单，但没有 Supervisor，也不能直接使用 HAOS Add-on 商店；
Home Assistant OS：适合树莓派、NUC 或虚拟机，包含 Supervisor 和 Add-ons，但不适合普通 VPS 上直接用 Docker 套 Docker；
Home Assistant Supervised：对宿主机和系统环境要求严格，不建议在随意购买的 VPS 上强行安装。

如果你依赖 USB Zigbee、Z-Wave 或蓝牙适配器，优先把 Home Assistant 放在家里的主机，再用 VPS 做远程访问、备份或辅助服务。若设备本身支持 Matter、MQTT、Tasmota 或云 API，Container 在 VPS 上更合适。

VPS 配置与网络规划

Home Assistant Core 不算重，但数据库历史记录、图表、摄像头快照和大量实体会增加磁盘与内存消耗。建议：

项目	轻量测试	稳定运行
CPU	2 vCPU	2-4 vCPU
内存	2 GB	4 GB 起
磁盘	30 GB SSD	60 GB SSD 起
系统	Ubuntu 22.04/24.04	Ubuntu 24.04 LTS
域名	ha.example.com	独立家庭自动化子域名

先规划网络路径：

家庭设备通过 MQTT、Matter Bridge 或厂商 API 与 VPS 通信；
管理员通过 HTTPS 或 WireGuard/Tailscale 访问 Home Assistant；
只有确实需要时才开放 MQTT 端口，默认不要让 1883 暴露公网；
摄像头视频尽量走家庭局域网或专用 VPN，避免把公网 VPS 当视频中转站。

多应用共用 VPS 时先用 free -h、df -h 和 docker stats 查看余量。VPS 配置选择可以参考 VPS 配置怎么选。

安装 Docker 和创建目录

sudo apt update
sudo apt install -y ca-certificates curl openssl
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker "$USER"
newgrp docker

sudo mkdir -p /opt/homeassistant/config
sudo chown -R "$USER":"$USER" /opt/homeassistant
cd /opt/homeassistant

Home Assistant 配置目录必须持久化。不要把配置放在容器临时层，也不要让多个容器同时直接修改 configuration.yaml。

Docker Compose 部署 Container

创建 compose.yml：

services:
  homeassistant:
    image: ghcr.io/home-assistant/home-assistant:stable
    container_name: homeassistant
    restart: unless-stopped
    network_mode: host
    environment:
      TZ: Asia/Shanghai
    volumes:
      - /opt/homeassistant/config:/config
      - /etc/localtime:/etc/localtime:ro
    healthcheck:
      test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:8123/ || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 5

这里使用 host 网络，是因为 Home Assistant 的部分局域网发现依赖 mDNS、SSDP 或广播。VPS 上并不一定能发现家庭设备，所以不要把“启动成功”误认为“所有设备会自动出现”。如果你不需要自动发现，也可以改成 bridge 网络并显式映射 8123 端口。

启动并查看日志：

docker compose config
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=150 homeassistant

第一次启动后，Home Assistant 通常监听 8123。先通过 SSH 隧道访问：

ssh -L 8123:127.0.0.1:8123 root@SERVER_IP

浏览器打开 http://127.0.0.1:8123，创建管理员账号、设置家庭位置和时区。

Caddy 配置 HTTPS

安装 Caddy：

sudo apt install -y caddy
sudo nano /etc/caddy/Caddyfile

配置反向代理：

ha.example.com {
    encode gzip zstd
    reverse_proxy 127.0.0.1:8123
    header {
        Strict-Transport-Security "max-age=31536000; includeSubDomains"
        X-Content-Type-Options "nosniff"
        X-Frame-Options "SAMEORIGIN"
    }
}

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
curl -I https://ha.example.com

如果使用反向代理，Home Assistant 需要在 configuration.yaml 中配置受信任代理。示例：

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 127.0.0.1

实际代理地址必须以你的网络结构为准，不要把 0.0.0.0/0 填进 trusted_proxies。反向代理和 HTTPS 排错可以参考 VPS 用 Caddy 反向代理完全指南。

MQTT 和远程设备接入

如果设备通过 MQTT 接入，建议单独部署 Mosquitto，并只允许 Home Assistant、家庭 VPN 或指定网段访问：

  mosquitto:
    image: eclipse-mosquitto:2
    container_name: mosquitto
    restart: unless-stopped
    ports:
      - "127.0.0.1:1883:1883"
    volumes:
      - /opt/mosquitto/config:/mosquitto/config
      - /opt/mosquitto/data:/mosquitto/data
      - /opt/mosquitto/log:/mosquitto/log

生产环境必须启用用户名、密码和 ACL。不要把匿名 MQTT 放在公网：

listener 1883 127.0.0.1
allow_anonymous false
password_file /mosquitto/config/passwd
acl_file /mosquitto/config/acl
persistence true
persistence_location /mosquitto/data/

Home Assistant 中添加 MQTT 集成时，使用服务名、内网地址或 VPN 地址。远程设备连接失败时，依次检查 DNS、VPN 路由、TCP 端口、MQTT 用户权限和主题名称，不要先修改成匿名访问。

设备发现与局域网限制

VPS 上的 Home Assistant 无法天然看到家庭局域网中的广播包。以下方案按稳定性排序：

设备支持云 API：使用官方集成，通过 HTTPS 出站连接；
家庭路由器或另一台主机运行 MQTT、Zigbee2MQTT、Matter Bridge，再让 VPS 连接；
用 WireGuard 或 Tailscale 把家庭网络和 VPS 放入同一私网；
通过子网路由转发 mDNS/SSDP，但要仔细限制广播范围。

如果只是管理远程服务器、智能插座的云端 API 和 MQTT 设备，VPS 版 Container 足够。若要直接接 USB Zigbee 棒、蓝牙温度计或本地摄像头，家庭主机通常比 VPS 更合适。

自动化、实体和历史数据

首次部署不要马上导入几百个实体。建议先接入一个传感器和一盏灯，验证：

状态更新时间是否正常；
自动化触发条件是否符合时区；
VPS 与设备断网后是否会恢复；
日志中是否出现认证失败或重复重连；
历史数据是否持续增长。

Home Assistant 默认使用 SQLite。实体数量和历史保留时间较大时，可以切换到 PostgreSQL 或 MariaDB，但数据库不是越重越好。先通过 recorder 配置减少无用实体，再决定是否外置数据库。摄像头录像不要存进 Home Assistant 配置目录，应该使用专门的 NVR 或对象存储。

安全加固

Home Assistant 是家庭控制入口，安全边界要比普通博客严格：

管理员启用 MFA，普通用户按最小权限创建；
关闭不需要的公网端口，只开放 80/443；
MQTT 禁止匿名，账号按设备拆分；
不在自动化脚本中硬编码长期有效的云 API Key；
通过 VPN 访问管理后台时，公网只保留 Caddy；
定期查看登录日志和异常 IP；
对第三方自定义集成先审查来源和权限；
不把家庭地址、摄像头 URL 和 Token 提交到公开仓库。

如果使用 Cloudflare 代理，确认 WebSocket、长连接和缓存规则不会破坏 Home Assistant 前端。管理后台也可以只允许 VPN 网段访问。

备份、恢复和升级

Home Assistant 的核心数据在 config 目录，其中包括 automations、用户、集成、实体历史和密钥。每天打包配置：

mkdir -p /opt/homeassistant/backups
tar -czf /opt/homeassistant/backups/homeassistant-$(date +%F).tgz -C /opt/homeassistant config

备份前可以暂时停止容器，避免写入不完整：

docker compose stop
tar -czf /opt/homeassistant/backups/homeassistant-safe-$(date +%F).tgz -C /opt/homeassistant config
docker compose start

备份至少保留一份异地副本并加密。恢复时在干净 VPS 使用相同镜像大版本，解压 config 后验证管理员登录、集成凭据、自动化、MQTT 和历史数据。更完整的恢复思路可参考 VPS 备份恢复演练。

升级前保存当前镜像版本和 Compose：

docker image inspect ghcr.io/home-assistant/home-assistant:stable --format '{{.Id}}' > /opt/homeassistant/backups/image-id.txt
cp compose.yml /opt/homeassistant/backups/compose-$(date +%F).yml
docker compose pull
docker compose up -d
docker compose logs --tail=200 homeassistant

不要在自动化生产环境里无条件跟随 latest。先查看发布说明，在测试配置验证集成，再安排升级窗口。

常见故障排查

页面 502 或打不开

docker compose ps
docker compose logs --tail=200 homeassistant
sudo journalctl -u caddy -n 100 --no-pager
ss -lntp | grep -E ':8123|:80|:443'

确认 Home Assistant 监听 8123，Caddy 指向正确地址，容器没有因权限或内存不足退出。

设备自动发现不到

先确认这是 VPS 的网络限制，而不是集成本身故障。检查 VPN 路由、mDNS/SSDP、家庭网关和设备云账号。对于广播依赖强的设备，改用家庭侧桥接服务通常比在公网 VPS 上转发广播更稳定。

自动化延迟或重复触发

查看系统日志和实体更新时间，确认时区正确、触发条件没有重复注册，并检查 MQTT 是否重复发布 retained 消息。不要通过把轮询间隔设成 1 秒来掩盖设备离线问题。

上线前清单

域名、HTTPS、管理员 MFA 和反代配置正常；
Container、HAOS 和 Supervised 的能力差异已确认；
MQTT 禁止匿名，管理端口未暴露公网；
家庭设备接入路径（云 API、VPN 或桥接）明确；
config、Compose 和密钥都有异地备份；
完成过一次恢复演练；
已固定镜像策略并记录升级回滚步骤。

Home Assistant Container 很适合把云端自动化、MQTT 和远程设备管理放到 VPS 上，但它不会自动替代家庭局域网主机。先把网络路径和设备能力边界规划清楚，再部署 HTTPS、权限和备份，后续维护会稳定很多。

项目

轻量测试

稳定运行

CPU

2 vCPU

2-4 vCPU

内存

2 GB

4 GB 起

磁盘

30 GB SSD

60 GB SSD 起

系统

Ubuntu 22.04/24.04

Ubuntu 24.04 LTS

域名

ha.example.com

独立家庭自动化子域名

sudo apt update sudo apt install -y ca-certificates curl openssl curl -fsSL https://get.docker.com | sudo sh sudo usermod -aG docker "$USER" newgrp docker sudo mkdir -p /opt/homeassistant/config sudo chown -R "$USER":"$USER" /opt/homeassistant cd /opt/homeassistant

services: homeassistant: image: ghcr.io/home-assistant/home-assistant:stable container_name: homeassistant restart: unless-stopped network_mode: host environment: TZ: Asia/Shanghai volumes: - /opt/homeassistant/config:/config - /etc/localtime:/etc/localtime:ro healthcheck: test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:8123/ || exit 1"] interval: 30s timeout: 10s retries: 5

ha.example.com { encode gzip zstd reverse_proxy 127.0.0.1:8123 header { Strict-Transport-Security "max-age=31536000; includeSubDomains" X-Content-Type-Options "nosniff" X-Frame-Options "SAMEORIGIN" } }

mosquitto: image: eclipse-mosquitto:2 container_name: mosquitto restart: unless-stopped ports: - "127.0.0.1:1883:1883" volumes: - /opt/mosquitto/config:/mosquitto/config - /opt/mosquitto/data:/mosquitto/data - /opt/mosquitto/log:/mosquitto/log

docker image inspect ghcr.io/home-assistant/home-assistant:stable --format '{{.Id}}' > /opt/homeassistant/backups/image-id.txt cp compose.yml /opt/homeassistant/backups/compose-$(date +%F).yml docker compose pull docker compose up -d docker compose logs --tail=200 homeassistant

VPS 搭建 Home Assistant Container（2026）：Docker、MQTT、HTTPS、设备接入与备份

VPS 配置与网络规划

安装 Docker 和创建目录

Docker Compose 部署 Container

Caddy 配置 HTTPS

MQTT 和远程设备接入

设备发现与局域网限制

自动化、实体和历史数据

安全加固

备份、恢复和升级

常见故障排查

页面 502 或打不开

设备自动发现不到

自动化延迟或重复触发

上线前清单

Loading...

VPS 搭建 Home Assistant Container（2026）：Docker、MQTT、HTTPS、设备接入与备份

VPS 配置与网络规划

安装 Docker 和创建目录

Docker Compose 部署 Container

Caddy 配置 HTTPS

MQTT 和远程设备接入

设备发现与局域网限制

自动化、实体和历史数据

安全加固

备份、恢复和升级

常见故障排查

页面 502 或打不开

设备自动发现不到

自动化延迟或重复触发

上线前清单