NanoPi R5C + Armbian Debian 13 部署 Home Assistant Container 全记录

发表于 分类于 本文字数： 5.1k 阅读时长 ≈ 18 分钟
RK3568 小主机上的 Home Assistant Container 实战：netplan 静态 IP + WiFi 备用通道、清华源装 Docker、南大 ghcr 镜像拉 HA、蓝牙 NET_ADMIN 权限、每周自动备份与内核 hold，含 14 条故障速查。

本文基于 2026-10-17 的一次真实安装整理，所有命令均在实际设备上验证通过。
目标板：FriendlyElec NanoPi R5C（RK3568 / 4GB LPDDR4X / 32GB eMMC / 2.5G 双网口 / RTL8822CE）
系统：Armbian_community 26.11.0-trunk.95 trixie（Debian 13）· 内核 6.18.56-current-rockchip64
成果：Home Assistant 2026.10.2 Container 版跑在 192.168.5.30:8123，带蓝牙与每周自动备份
前置：本文接着 NanoPi R5C 安装 Armbian Debian 13 并迁移到 eMMC 全记录 往下做，系统需已能从 eMMC 启动

目录

1. 背景与结论

为什么不是 HAOS / Supervised

Home Assistant 官方在 2025-05 宣布废弃 Core 与 Supervised 安装方式，自 2025.12 版本起不再提供支持，长期只保留两种方式：

方式 说明 R5C 可行性
HAOS 官方整机镜像，带附加组件商店 ❌ 无 RK3568/R5C 官方镜像
HA Container 官方 Docker 镜像，附加组件自行用容器替代 ✅ 本文采用
Supervised 自建系统 + Supervisor ⚠️ 已废弃，Debian 13 上坑多，不建议
Core (venv) Python 虚拟环境直跑 ⚠️ 已废弃，不建议

最终成果

项目 结果
Home Assistant 2026.10.2，Container 版，http://192.168.5.30:8123
网络 有线静态 IP + WiFi 静态 IP 双通道（互为备份管理入口）
蓝牙 RTL8822CE，BLE 被动扫描可用
备份 每周日 04:00 自动打包 /config，保留 14 天
内核 已 apt-mark hold，避免滚动升级变砖

2. 环境基线

硬件

项目 规格
板卡 FriendlyElec NanoPi R5C
SoC Rockchip RK3568（4×Cortex-A55）
内存 4 GB LPDDR4X（2 GB 版本也能跑，紧张些）
存储 eMMC 32 GB（/dev/mmcblk1，根分区 29 G）
网口 2 × RJ45，其中 WAN 口为 RTL8125 2.5GbE
无线 RTL8822CE（WiFi 5 + BT 5.0 组合模块）
其它 无 HDMI，SSH 是唯一管理入口，务必先配好备用通道

软件

1
2
3
4
5
6
Armbian_community 26.11.0-trunk.95 trixie
Debian GNU/Linux 13 (trixie)
Kernel 6.18.56-current-rockchip64
aarch64 / PAGESIZE=4096
Docker 29.9.1 / Docker Compose v5.6.0
Home Assistant 2026.10.2 (ghcr.io/home-assistant/home-assistant:stable)

⚠️ 26.11.0-trunk 是 Armbian 滚动开发版，内核更新频繁。完成部署后务必锁内核（见第 11 节）。

前置检查

1
2
3
4
5
6
uname -m                        # 期望 aarch64
cat /etc/os-release             # 期望 VERSION_ID="13"
free -h                         # 建议 ≥2 GB
df -h /                         # 建议 ≥8 GB 可用
getconf PAGESIZE                # 期望 4096
timedatectl                     # 时间必须已同步

PAGESIZE 若为 16384/65536，HA 容器需要额外加 DISABLE_JEMALLOC=true（见 7.3）。

3. 目录与端口规划

1
2
3
4
5
6
7
/opt/homeassistant/
├── compose.yaml          # 容器编排
└── config/               # HA 配置、数据库、.storage（备份对象）

/usr/local/sbin/ha-backup.sh        # 备份脚本
/var/backups/homeassistant/         # 备份归档（建议改到外部存储）
/etc/netplan/10-dhcp-all-interfaces.yaml   # 网络配置（含 WiFi）
端口 用途
8123/tcp Home Assistant Web
22/tcp SSH 管理

4. 系统基础设置

1
2
3
4
5
6
7
8
9
10
# 更新系统
apt update && apt full-upgrade -y

# 时区与时间同步（HA 的证书、定时任务都依赖正确时间）
timedatectl set-timezone Asia/Shanghai
systemctl enable --now systemd-timesyncd
timedatectl                      # 确认 "System clock synchronized: yes"

# 主机名
hostnamectl set-hostname ha

精简（可选，省内存）：

1
systemctl disable --now bluetooth    # 若确定不用蓝牙；本文后面会用到，故先别关

减少对 eMMC 的写入：

1
systemctl status armbian-ramlog      # Armbian 默认把日志放内存，确认 active

5. 网络配置（systemd-networkd + netplan）

5.1 先搞清楚是谁在管网络

新版 Armbian 没有 NetworkManager（nmcli: command not found），实际链路是：

1
netplan  →  生成 /run/systemd/network/*.network  →  systemd-networkd 执行

确认方法：

1
2
3
4
cat /etc/systemd/network/00-armbian.network.readme
# 输出含 "The systemd-networkd configuration is managed by Netplan"
ls /etc/netplan/
cat /etc/netplan/*.yaml

5.2 关键坑：不要新建 netplan 文件

Armbian 默认文件用 match: name: "e*" 一把抓所有以太网口。如果另建一个 enP1p17s0 的 yaml，netplan 会生成两个 .network，而 networkd 只认字典序第一个匹配文件（all-eth-interfaces 排在前面），结果是”改了不生效”。

✅ 正确做法：直接改原来那个文件，把通配 match 换成显式网口。

5.3 修改为静态 IP

1
sudo cp /etc/netplan/10-dhcp-all-interfaces.yaml /root/netplan.bak

文件内容（先只做有线，WiFi 见 5.5）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
network:
  version: 2
  renderer: networkd
  ethernets:
    enP1p17s0:
      dhcp4: false
      dhcp6: false
      accept-ra: true
      addresses:
        - 192.168.5.30/24
      routes:
        - to: default
          via: 192.168.5.1
      nameservers:
        addresses: [192.168.5.1, 223.5.5.5]
    enP2p33s0:
      dhcp4: yes
      dhcp6: yes
      ipv6-privacy: yes
    all-lan-interfaces:
      match:
        name: "lan*"
      dhcp4: yes
      dhcp6: yes
      ipv6-privacy: yes
    all-wan-interfaces:
      match:
        name: "wan*"
      dhcp4: yes
      dhcp6: yes
      ipv6-privacy: yes
1
2
chmod 600 /etc/netplan/10-dhcp-all-interfaces.yaml   # 不设 600 netplan 会告警
netplan try                                          # 应用并等待确认，120 秒不确认自动回滚

netplan try 提示 Do you want to keep these settings? 时，另开一个 SSH 窗口验证：

1
2
3
4
ip -br a
ip route | head -3
ping -c2 192.168.5.1
resolvectl status enP1p17s0 | head -10

确认无误回到原窗口按回车。回滚方法：

1
sudo cp /root/netplan.bak /etc/netplan/10-dhcp-all-interfaces.yaml && sudo netplan apply

5.4 验证要点

1
2
default via 192.168.5.1 dev enP1p17s0 proto static     ← 注意 proto static
192.168.5.0/24 dev enP1p17s0 proto kernel scope link src 192.168.5.30

5.5 WiFi 备用管理通道（强烈建议）

R5C 没有显示输出，有线配置一旦写错就彻底失联。给 wlp1s0 配一个静态 IP，并用 metric 200 让有线永远优先。

前置：

1
2
3
apt install -y wpasupplicant rfkill
rfkill unblock all
iw dev            # 确认 wlp1s0 存在

在同一个 netplan 文件末尾追加 wifis 段：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
wifis:
  wlp1s0:
    dhcp4: false
    dhcp6: false
    addresses:
      - 192.168.5.31/24
    routes:
      - to: default
        via: 192.168.5.1
        metric: 200
    nameservers:
      addresses: [192.168.5.1, 223.5.5.5]
    access-points:
      '你的SSID':
        password: '你的密码'
    optional: true

安全的启用流程（防止两端同时失联）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# 1. 确认目标 IP 空闲
ping -c1 -W1 192.168.5.31 && echo "被占用，换一个"

# 2. 先只做语法校验
netplan generate

# 3. 挂 180 秒自动回滚
systemd-run --on-active=180 --unit=netplan-rollback \
  sh -c "cp /root/netplan.bak /etc/netplan/10-dhcp-all-interfaces.yaml && netplan apply"

# 4. 应用并验证
netplan apply && sleep 20
ip -br a show wlp1s0
iw dev wlp1s0 link            # 期望 Connected to ... / SSID / freq
ping -c2 -I 192.168.5.31 192.168.5.1

# 5. 成功则取消回滚
systemctl stop netplan-rollback.timer && systemctl reset-failed netplan-rollback.service

实测结果：

1
2
3
4
5
6
7
8
wlp1s0  UP  192.168.5.31/24
Connected to **:**:**:**:**:**
        SSID: **
        freq: 5200.0
        signal: -30 dBm

default via 192.168.5.1 dev enP1p17s0 proto static                 ← 有线优先
default via 192.168.5.1 dev wlp1s0 proto static metric 200         ← WiFi 备用

验证备用通道确实能独立登录：

1
2
ssh [email protected] 'hostname; iw dev wlp1s0 link | head -3'
curl -s -o /dev/null -w '%{http_code}\n' http://192.168.5.31:8123/

6. 安装 Docker（国内网络版）

6.1 官方脚本会失败

1
2
curl -fsSL https://get.docker.com | sh
# curl: (35) Recv failure: Connection reset by peer   ← download.docker.com 不可达

6.2 改用国内镜像源

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
rm -f /etc/apt/keyrings/docker.asc /etc/apt/sources.list.d/docker.list

apt install -y ca-certificates curl
install -m 0755 -d /etc/apt/keyrings

# 清华源，失败自动退阿里云
curl -fsSL https://mirrors.tuna.tsinghua.edu.cn/docker-ce/linux/debian/gpg \
  -o /etc/apt/keyrings/docker.asc \
|| curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/debian/gpg \
  -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc

echo "deb [arch=arm64 signed-by=/etc/apt/keyrings/docker.asc] https://mirrors.tuna.tsinghua.edu.cn/docker-ce/linux/debian trixie stable" \
  > /etc/apt/sources.list.d/docker.list

apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

若镜像源的 trixie 套件尚未同步（Release 找不到），把 trixie 改成 bookworm 再用，Debian 13 上运行正常。

6.3 完全连不上镜像源时的退路

1
apt install -y docker.io docker-compose

代价：compose 为旧版，命令是 docker-compose 而非 docker compose。

6.4 限制日志大小（保护 eMMC）

1
2
3
4
5
6
7
8
mkdir -p /etc/docker
cat > /etc/docker/daemon.json <<'EOF'
{
  "log-driver": "json-file",
  "log-opts": { "max-size": "10m", "max-file": "3" }
}
EOF
systemctl restart docker

可选：给 Docker Hub 配加速（后面装 Mosquitto / Zigbee2MQTT 时会用到）

1
2
3
4
5
6
7
8
cat > /etc/docker/daemon.json <<'EOF'
{
  "log-driver": "json-file",
  "log-opts": { "max-size": "10m", "max-file": "3" },
  "registry-mirrors": ["https://docker.m.daocloud.io", "https://docker.1ms.run"]
}
EOF
systemctl restart docker

6.5 验证

1
2
3
systemctl enable --now docker
docker version --format 'Docker {{.Server.Version}}'
docker compose version

国内 docker run --rm hello-world 大概率超时（Docker Hub 不可达），这一步失败不代表 Docker 装坏了，直接进第 7 节用镜像站拉 HA。

7. 部署 Home Assistant Container

7.1 目录与 compose 文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
mkdir -p /opt/homeassistant && cd /opt/homeassistant

cat > compose.yaml <<'EOF'
services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:stable
    volumes:
      - ./config:/config
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro
    restart: unless-stopped
    stop_grace_period: 60s
    privileged: true
    cap_add:
      - NET_ADMIN
      - NET_RAW
    network_mode: host
    environment:
      TZ: Asia/Shanghai
EOF

逐项说明：

配置 作用 能否省略
network_mode: host 设备发现（mDNS/SSDP）、HomeKit 必需 ❌ 不能
privileged: true 硬件访问（蓝牙、USB） 建议保留
cap_add: NET_ADMIN/NET_RAW 蓝牙 BLE 扫描必需，实测仅 privileged 不够 ❌ 用蓝牙就必须
/run/dbus 通过 D-Bus 与主机 BlueZ 通信 用蓝牙就必须
/etc/localtime 容器内时区正确 建议
stop_grace_period: 60s 让 HA 干净关闭 sqlite，默认 10s 会写坏库 强烈建议
TZ 时区 建议

7.2 拉取镜像（ghcr.io 不可达时）

1
2
3
4
5
# 南京大学 ghcr 镜像
docker pull ghcr.nju.edu.cn/home-assistant/home-assistant:stable
docker tag ghcr.nju.edu.cn/home-assistant/home-assistant:stable \
           ghcr.io/home-assistant/home-assistant:stable
docker images | grep home-assistant

关键：最后必须 docker tag 成 ghcr.io/...，否则 compose 仍会去连官方源。

备用镜像站（拉完同样要 retag）：

1
2
3
docker pull docker.m.daocloud.io/ghcr.io/home-assistant/home-assistant:stable
docker pull ghcr.dockerproxy.net/home-assistant/home-assistant:stable
docker pull docker.1ms.run/ghcr.io/home-assistant/home-assistant:stable

7.3 启动

1
2
3
4
5
cd /opt/homeassistant
docker compose up -d
sleep 10
docker compose ps
docker compose logs -f --tail=50

首次启动 1~2 分钟（RK3568 上初始化数据库偏慢）。看到以下行即成功：

1
2
Home Assistant initialized in X.XXs
INFO: Starting Home Assistant HTTP server on 0.0.0.0:8123

若日志出现 <jemalloc>: Unsupported system page size（16K/64K 页内核），在 environment 加：

1
DISABLE_JEMALLOC: "true"

8. 验证与初始化

1
2
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8123/    # 期望 302 或 200
docker stats --no-stream homeassistant

⚠️ curl -I（HEAD 请求）会返回 405 Method Not Allowed，这是正常的——HA 只接受 GET，不是故障。

浏览器打开 http://192.168.5.30:8123，初始化建议：

项目 建议值
账号密码 强密码并存入密码管理器（忘记只能删 config/.storage/auth）
位置 真实城市（影响日出日落）
时区 Asia/Shanghai
单位 公制
货币 CNY
设备发现 开启

初始化后在「设置 → 系统 → 关于」确认：安装类型 Home Assistant Container，架构 aarch64。

资源占用基线（RK3568 + 4GB）：

1
2
3
内存 400~760 MB
CPU 空闲 3~8%
SoC 温度 43~46 °C

9. 蓝牙支持

9.1 先装 BlueZ（容器版必须）

容器本身没有蓝牙服务，必须借主机的 BlueZ：

1
2
3
4
5
apt install -y bluez
systemctl enable --now bluetooth

bluetoothctl list        # 期望：Controller **:**:**:**:**:** ha [default]
dmesg | grep -i -E 'btusb|rtl_bt' | tail -10

正常输出示例：

1
2
3
usbcore: registered new interface driver btusb
Bluetooth: hci0: RTL: loading rtl_bt/rtl8822cu_fw.bin
Bluetooth: hci0: RTL: loading rtl_bt/rtl8822cu_config.bin

9.2 权限：privileged 不够，必须显式 cap_add

只设 privileged: true 时 HA 仍会报：

1
2
ERROR (MainThread) [habluetooth.manager] Missing required permissions for Bluetooth management.
PermissionError: Missing NET_ADMIN/NET_RAW capabilities for Bluetooth management

加上：

1
2
3
cap_add:
  - NET_ADMIN
  - NET_RAW

重建并验证：

1
2
3
docker compose up -d
docker exec homeassistant grep CapEff /proc/self/status     # 期望 000001ffffffffff
docker compose logs --tail=60 | grep -i bluetooth            # 期望无输出（无报错）

9.3 验证扫描

主机侧：

1
2
bluetoothctl --timeout 10 scan on
# 期望滚出 [NEW] Device XX:XX:... 以及 RSSI 变化

主机正在扫描时，HA 侧可能暂时拿不到数据（同一适配器只能有一个发现过程），测完记得退出。

9.4 三个常见误解

现象 真相
手机在系统蓝牙里连不上这块板子 正常。板子没暴露 A2DP/HID/PAN 服务，手机配对必然失败。HA 只用 BLE 被动扫描，从不”连接”手机
添加集成时提示”未找到未配置的蓝牙适配器“ 正常。HA 启动时已通过 integration_discovery 自动创建了条目，去「设备与服务」页面找现成的 Bluetooth 卡片即可
日志里 BleakDBusError: No discovery started 无害。容器重启时要停一个本来没在跑的扫描，每台容器版 HA 重启都会出现

9.5 确认条目已存在

1
grep -o '"domain":"[a-z_]*"' /opt/homeassistant/config/.storage/core.config_entries | sort | uniq -c

⚠️ HA 写的是紧凑 JSON（"domain":"bluetooth"，冒号后无空格）。用 grep '"domain": "bluetooth"' 会得到 0，是假阴性。

Python 查看详情：

1
2
3
4
5
6
7
python3 - <<'PY'
import json
d = json.load(open('/opt/homeassistant/config/.storage/core.config_entries'))
for e in d['data']['entries']:
    if e.get('domain') == 'bluetooth':
        print(e['entry_id'], e['source'], e['title'])
PY

实测输出：

1
**************************  integration_discovery  ********  Technology Co.,Ltd None (**:**:**:**:**:**)

title 里的厂商名和 None 来自模块上报信息，不是错误。

9.6 改适配器显示名（可选）

1
2
3
echo 'PRETTY_HOSTNAME=ha' >> /etc/machine-info
systemctl restart bluetooth
bluetoothctl show | head -4

10. 备份策略

10.1 为什么必须停容器

HA 用 SQLite（config/home-assistant_v2.db）。运行中直接 tar 会拷到不一致的数据库文件。正确做法只有两种：

  1. 停容器再打包（本文采用，简单可靠）
  2. sqlite3 ... ".backup" 在线备份（麻烦，一般不必）

10.2 备份脚本

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
cat > /usr/local/sbin/ha-backup.sh <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
DEST=/var/backups/homeassistant
KEEP_DAYS=14
STAMP=$(date +%Y%m%d-%H%M)
cd /opt/homeassistant
mkdir -p "$DEST"

docker compose stop
if ! tar --numeric-owner -czf "$DEST/ha-config-$STAMP.tar.gz" config; then
  docker compose start
  echo "tar failed" >&2
  exit 1
fi
docker compose start

find "$DEST" -name 'ha-config-*.tar.gz' -mtime +"$KEEP_DAYS" -delete
echo "$(date '+%F %T') ok: $DEST/ha-config-$STAMP.tar.gz"
EOF

chmod 755 /usr/local/sbin/ha-backup.sh
/usr/local/sbin/ha-backup.sh
ls -lh /var/backups/homeassistant/

10.3 验证归档完整性

1
2
3
LAST=$(ls -t /var/backups/homeassistant/ha-config-*.tar.gz | head -1)
tar tzf "$LAST" > /tmp/list.txt
grep -E 'config/configuration\.yaml$|config/\.storage/core\.config_entries$|config/home-assistant_v2\.db$' /tmp/list.txt

三个文件都在，才说明备份有效。

小坑：不要用 tar tzf ... | head -5 做检查。set -o pipefail 下 head 提前关闭管道会让 tar 收到 SIGPIPE，脚本会误判失败。

10.4 定时任务

1
2
3
systemctl is-active cron || apt install -y cron
( crontab -l 2>/dev/null; echo '0 4 * * 0 /usr/local/sbin/ha-backup.sh >> /var/log/ha-backup.log 2>&1' ) | crontab -
crontab -l

10.5 必须离机

/var/backups 与系统在同一块 eMMC 上，盘坏了会一起丢。二选一：

  • 有 NAS：把脚本里 DEST 改成挂载点，如 /mnt/nas/ha
  • 没 NAS：电脑上定时 scp 拉走，或用 rclone 推到网盘
1
2
# Windows 端示例（任务计划）
scp -r root@192.168.5.30:/var/backups/homeassistant/*.tar.gz D:\ha-backup\

10.6 恢复流程

1
2
3
4
5
6
7
8
9
10
11
12
cd /opt/homeassistant
docker compose stop

mkdir -p /tmp/restore
tar xzf /var/backups/homeassistant/ha-config-YYYYMMDD-HHMM.tar.gz -C /tmp/restore

# 保留原目录以便回退
mv config config.broken
cp -a /tmp/restore/config config

docker compose start
docker compose logs -f --tail=100

另外在 HA 界面开启内置备份：「设置 → 系统 → 备份 → 自动备份」，保留 3~5 份，与整目录打包互为补充。

11. 锁定内核

滚动版 full-upgrade 可能升级内核/u-boot，导致网卡驱动异常或无法启动；板子没有显示输出，很难现场救。

1
dpkg -l | awk '/^ii/ && $2 ~ /^linux-(image|dtb|u-boot)/ {print $2}'

实测输出：

1
2
3
linux-dtb-current-rockchip64
linux-image-current-rockchip64
linux-u-boot-nanopi-r5c-current
1
2
3
apt-mark hold linux-dtb-current-rockchip64 linux-image-current-rockchip64 linux-u-boot-nanopi-r5c-current
apt-mark showhold
uname -r        # 记录当前版本，例如 6.18.56-current-rockchip64

取舍：kernel 的安全更新也不会自动装。内网 HA 可接受，换来的是不会因内核升级变砖。

需要升级时：

1
2
3
4
5
/usr/local/sbin/ha-backup.sh
apt-mark unhold linux-image-current-rockchip64 linux-dtb-current-rockchip64
apt full-upgrade
reboot
# 确认正常后再 hold 回去

12. HACS

12.1 安装

1
2
3
4
5
6
7
8
9
apt install -y unzip
cd /tmp
curl -fsSL -o hacs.zip https://github.com/hacs/integration/releases/latest/download/hacs.zip

mkdir -p /opt/homeassistant/config/custom_components/hacs
unzip -q -o hacs.zip -d /opt/homeassistant/config/custom_components/hacs

grep -o '"version": *"[^"]*"' /opt/homeassistant/config/custom_components/hacs/manifest.json
cd /opt/homeassistant && docker compose restart

⚠️ 关键坑：官方 zip 没有 hacs/ 这一层目录，文件直接在根。直接 unzip -d custom_components 会把 base.py、config_flow.py 等撒在 custom_components/ 根下，HA 找不到集成。必须先 mkdir .../custom_components/hacs 再解压进去。

12.2 验证

1
docker compose logs --tail=200 | grep -i hacs

看到下面这条是正常的（所有自定义集成都会打）：

1
WARNING (SyncWorker_0) [homeassistant.loader] We found a custom integration hacs which has not been tested by Home Assistant...

12.3 UI 授权

  1. 设置 → 设备与服务 → 添加集成
  2. 搜索 HACS → 勾选 4 项 → 提交
  3. 页面显示 8 位设备码
  4. 打开 https://github.com/login/device 输入授权（手机流量也行）
  5. 左侧边栏出现 HACS

13. 故障排查速查表

现象 原因 处理
curl -I http://ip:8123 返回 405 HA 不接受 HEAD 正常，改用 curl -s -o /dev/null -w '%{http_code}'
容器反复重启，日志 Unsupported system page size 16K/64K 页内核 加 DISABLE_JEMALLOC: "true"
Error binding to 0.0.0.0:8123 [Errno 98] 端口被占 ss -tlnp | grep 8123
容器 Up 但 8123 不通 防火墙拦截 nft list ruleset | head -30
docker pull ghcr.io/... 卡死 ghcr 不可达 用 ghcr.nju.edu.cn 拉 + docker tag 改回官方名
docker run hello-world 超时 Docker Hub 不可达 不影响 HA，忽略或配 registry-mirrors
蓝牙 Missing NET_ADMIN/NET_RAW 缺 capabilities cap_add: [NET_ADMIN, NET_RAW]
添加蓝牙集成提示”未找到未配置的适配器” 已有自动创建的条目 去「设备与服务」找现成卡片
BleakDBusError: No discovery started 重启时的无害报错 忽略
改 netplan 后没生效 新建了同名匹配的第二个文件 只改原文件，别新增
netplan apply 报权限告警 配置文件不是 600 chmod 600 /etc/netplan/*.yaml
备份脚本中途退出、无 cron pipefail + tar | head 触发 SIGPIPE 检查时先写文件再 grep
HACS 装完 HA 里没有 zip 无顶层目录，文件散落 先 mkdir hacs 再解压
docker compose 命令不存在 用的是 Debian 仓库版 用 docker-compose，或换 docker-ce 源

14. 日常维护

升级 HA

1
2
3
4
5
6
7
8
/usr/local/sbin/ha-backup.sh

cd /opt/homeassistant
docker pull ghcr.nju.edu.cn/home-assistant/home-assistant:stable
docker tag ghcr.nju.edu.cn/home-assistant/home-assistant:stable \
           ghcr.io/home-assistant/home-assistant:stable
docker compose up -d
docker compose logs -f --tail=80

常用命令

1
2
3
4
5
6
7
8
9
cd /opt/homeassistant

docker compose ps                      # 状态
docker compose logs -f --tail=100      # 日志
docker compose restart                 # 重启
docker stats --no-stream               # 资源占用
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8123/

docker exec homeassistant ls /config/custom_components/   # 自定义集成

系统健康

1
2
3
uptime; free -h; df -h /
awk '{printf "%.1f C\n", $1/1000}' /sys/class/thermal/thermal_zone0/temp
systemctl --failed

无附加组件商店时的替代方案

附加组件 等价容器
Mosquitto broker eclipse-mosquitto:2
Zigbee2MQTT ghcr.io/koenkk/zigbee2mqtt
Z-Wave JS zwavejs/zwave-js-ui
ESPHome ghcr.io/esphome/esphome
Matter Server ghcr.io/home-assistant-libs/python-matter-server
Node-RED nodered/node-red

把它们追加到同一个 compose.yaml，用 depends_on 串起来即可。代价是要自己维护升级与集成配置。

15. 安全检查清单

  • HA 使用强密码，且已存入密码管理器
  • 8123 端口未映射到公网（外网访问走 HA Cloud / Tailscale / WireGuard）
  • SSH 已改用密钥登录，并考虑 PasswordAuthentication no
  • 备份有一份离开本机（NAS / 电脑 / 网盘）
  • 已 apt-mark hold 内核三件套
  • 记录关键信息：IP、SSH 端口、备份路径、内核版本、WiFi SSID
  • 若临时授权过他人的 SSH 公钥，事后清理：
    sed -i '/<备注>/d' /root/.ssh/authorized_keys

16. 附录：最终配置文件

A. /opt/homeassistant/compose.yaml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:stable
    volumes:
      - ./config:/config
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro
    restart: unless-stopped
    stop_grace_period: 60s
    privileged: true
    cap_add:
      - NET_ADMIN
      - NET_RAW
    network_mode: host
    environment:
      TZ: Asia/Shanghai

B. /etc/netplan/10-dhcp-all-interfaces.yaml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
network:
  version: 2
  renderer: networkd
  ethernets:
    enP1p17s0:
      dhcp4: false
      dhcp6: false
      accept-ra: true
      addresses:
        - 192.168.5.30/24
      routes:
        - to: default
          via: 192.168.5.1
      nameservers:
        addresses: [192.168.5.1, 223.5.5.5]
    enP2p33s0:
      dhcp4: yes
      dhcp6: yes
      ipv6-privacy: yes
    all-lan-interfaces:
      match:
        name: "lan*"
      dhcp4: yes
      dhcp6: yes
      ipv6-privacy: yes
    all-wan-interfaces:
      match:
        name: "wan*"
      dhcp4: yes
      dhcp6: yes
      ipv6-privacy: yes
  wifis:
    wlp1s0:
      dhcp4: false
      dhcp6: false
      addresses:
        - 192.168.5.31/24
      routes:
        - to: default
          via: 192.168.5.1
          metric: 200
      nameservers:
        addresses: [192.168.5.1, 223.5.5.5]
      access-points:
        '你的SSID':
          password: '********'
      optional: true

C. /etc/docker/daemon.json

1
2
3
4
{
  "log-driver": "json-file",
  "log-opts": { "max-size": "10m", "max-file": "3" }
}

D. /usr/local/sbin/ha-backup.sh

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
#!/usr/bin/env bash
set -euo pipefail
DEST=/var/backups/homeassistant
KEEP_DAYS=14
STAMP=$(date +%Y%m%d-%H%M)
cd /opt/homeassistant
mkdir -p "$DEST"

docker compose stop
if ! tar --numeric-owner -czf "$DEST/ha-config-$STAMP.tar.gz" config; then
  docker compose start
  echo "tar failed" >&2
  exit 1
fi
docker compose start

find "$DEST" -name 'ha-config-*.tar.gz' -mtime +"$KEEP_DAYS" -delete
echo "$(date '+%F %T') ok: $DEST/ha-config-$STAMP.tar.gz"

E. crontab

1
0 4 * * 0 /usr/local/sbin/ha-backup.sh >> /var/log/ha-backup.log 2>&1

17. 参考链接

内容 链接
Home Assistant Container 安装文档 https://www.home-assistant.io/installation/linux
废弃 Core / Supervised 的官方公告 https://www.home-assistant.io/blog/2025/05/22/deprecating-core-and-supervised-installation-methods-and-32-bit-systems/
HA Docker 镜像 https://github.com/home-assistant/home-assistant/pkgs/container/home-assistant
蓝牙集成文档 https://www.home-assistant.io/integrations/bluetooth/
HACS 安装文档 https://hacs.xyz/docs/use/download/download/
Docker CE 清华镜像 https://mirrors.tuna.tsinghua.edu.cn/help/docker-ce/
netplan 配置参考 https://netplan.readthedocs.io/en/stable/

变更记录

时间 操作
2026-10-17 22:12 系统更新、时区、主机名
2026-10-17 22:20 netplan 改静态 IP（发现网络由 netplan 管理）
2026-10-17 22:35 Docker 安装（官方源失败，改清华 docker-ce 源）
2026-10-17 22:40 HA 镜像经南大 ghcr 镜像拉取并 retag
2026-10-17 22:45 HA 容器启动，HTTP 302
2026-10-17 22:55 BlueZ 安装、cap_add 修复蓝牙权限
2026-10-17 23:00 蓝牙条目确认为 integration_discovery 自动创建
2026-10-17 23:08 备份脚本 + 每周 cron 上线
2026-10-17 23:10 内核三件套 hold
2026-10-17 23:13 HACS 安装（修正 zip 无顶层目录问题）
2026-10-17 23:18 WiFi 备用通道 192.168.5.31 配置完成

系列文章：NanoPi R5C 安装 Armbian Debian 13 并迁移到 eMMC 全记录（前篇）
记录日期：2026-10-17
设备：NanoPi R5C（RK3568B2 / 4GB / 32GB eMMC）
结果：✅ Home Assistant 2026.10.2 稳定运行，蓝牙可用，每周自动备份已上线