ha-addon

Home Assistant 插件开发

为使用 Docker、Supervisor 集成和多架构支持构建、配置和发布 Home Assistant 插件提供专业指导。

开始之前

此技能可帮助避免常见的 Home Assistant 插件开发错误：

问题	症状	解决方案
权限错误	调用 Supervisor API 时出现 Permission denied	使用正确的 SUPERVISOR_TOKEN 和 API 端点
配置验证	插件无法加载	发布前验证 config.yaml 架构
Docker 基础镜像错误	运行时缺少依赖项	使用 Home Assistant 官方基础镜像（ghcr.io/home-assistant）
Ingress 配置错误	无法通过 HA 访问 Web UI	正确配置 nginx 反向代理
多架构构建失败	插件只能在一种架构上运行	使用架构矩阵设置 build.yaml

快速入门：从头创建插件

步骤 1：创建插件目录结构

mkdir -p my-addon/{rootfs,rootfs/etc/s6-overlay/s6-rc.d/service-name}
cd my-addon

重要原因： Home Assistant 要求使用特定的目录布局。rootfs/ 包含实际的应用文件，这些文件会被打包到 Docker 镜像中。

步骤 2：创建 config.yaml

---
name: My Custom Add-On
description: My awesome Home Assistant add-on
version: 1.0.0
slug: my-addon
image: ghcr.io/home-assistant/{arch}-addon-my-addon
arch:
  - amd64
  - armv7
  - aarch64
ports:
  8080/tcp: null
options:
  debug: false
schema:
  debug: bool
permissions:
  - homeassistant  # Read/write Home Assistant core data

重要原因： 这是插件的清单文件。slug 会成为内部标识符，并决定配置的存储位置。

步骤 3：创建 Dockerfile

FROM ghcr.io/home-assistant/amd64-base:latest

# Install dependencies
RUN apk add --no-cache python3 py3-pip

# Copy application
COPY rootfs /

# Set working directory
WORKDIR /app

# Install Python packages if needed
RUN if [ -f requirements.txt ]; then pip install -r requirements.txt; fi

# Run using S6 overlay
CMD ["/init"]

重要原因： 使用 Home Assistant 基础镜像可包含关键的运行时组件（S6 overlay、bashio 助手程序、Supervisor 集成）。

步骤 4：创建 S6 服务脚本

创建 rootfs/etc/s6-overlay/s6-rc.d/service-name/run：

#!/command/execlineb -P
foreground { echo "Starting my add-on..." }
/app/my-service

使其可执行：

chmod +x rootfs/etc/s6-overlay/s6-rc.d/service-name/run

重要原因： S6 overlay 是 Home Assistant 的初始化系统。它负责管理服务启动、日志记录和正常关闭。

关键规则

✅ 务必做到

• ✅ 使用 Home Assistant 官方基础镜像（ghcr.io/home-assistant/{arch}-base）
• ✅ 在 config.yaml 中包含所有受支持的架构（amd64、armv7、aarch64）
• ✅ 使用 bashio 助手函数执行常见操作（bashio::log::info、bashio::addon::option）
• ✅ 发布前验证 config.yaml 架构
• ✅ 在 schema 部分记录配置选项
• ✅ 在日志中包含 addon_uuid，便于调试

❌ 切勿这样做

• ❌ 不要硬编码路径——使用 bashio 获取配置目录（/data/）
• ❌ 除非绝对必要，否则不要以 root 身份运行服务（在 Dockerfile 中设置 USER）
• ❌ 未设置 SUPERVISOR_TOKEN 时，不要调用 Supervisor API
• ❌ 不要忽略 SIGTERM 信号——实现正常关闭
• ❌ 不要假定只有一种架构——在镜像名称中使用 {arch} 占位符
• ❌ 不要在 /data/ 之外存储数据——Home Assistant 不会保留这些数据

常见错误

❌ 错误：硬编码路径

#!/bin/bash
CONFIG_PATH="/config/my-addon"

✅ 正确：使用 bashio 进行配置

#!/command/execlineb -P
CONFIG_PATH=${"$(bashio::addon::config_path)"}

原因： bashio 会处理路径解析，并确保插件在任何 Home Assistant 安装中都能正常工作。

配置参考

config.yaml 结构

---
name: String                          # Display name
description: String                   # Short description
version: String                       # Semantic version (1.0.0)
slug: String                          # URL-safe identifier
image: String                         # Docker image URL with {arch} placeholder
arch:
  - amd64|armv7|aarch64|armhf|i386    # Supported architectures
ports:
  8080/tcp: null                      # TCP port (null=internal only, number=external)
  53/udp: 53                          # UDP with external port mapping
devices:
  - /dev/ttyACM0                      # Device access
services:
  - mysql                             # Depends on other service
options:
  debug: false                        # User configuration options
  log_level: info
schema:
  debug: bool                         # Configuration validation schema
  log_level:
    - debug
    - info
    - warning
    - error
permissions:
  - homeassistant                     # Read/write HA config
  - hassio                            # Full supervisor API access
  - admin                             # Broad system access
  - backup                            # Backup/restore operations
environment:
  NODE_ENV: production
webui: http://[HOST]:[PORT:8080]     # Web UI URL pattern
ingress: true                         # Enable ingress proxy
ingress_port: 8080                    # Internal port for ingress
ingress_entry: /                      # URL path for ingress entry

关键设置：

• slug：供内部和 Supervisor API 调用使用
• arch：列出所有受支持的架构，否则构建会失败
• image：必须使用 {arch} 占位符进行动态构建
• options：用户可配置的设置
• permissions：控制 Supervisor API 访问级别
• ingress：为 Web UI 启用反向代理

常见模式

使用 bashio 记录日志

#!/command/execlineb -P
foreground { bashio::log::info "Add-on started" }
foreground { bashio::log::warning "Low disk space" }
foreground { bashio::log::error "Failed to connect" }

访问配置选项

#!/command/execlineb -P
define DEBUG "$(bashio::addon::option 'debug')"
define LOG_LEVEL "$(bashio::addon::option 'log_level')"
if { test "${DEBUG}" = "true" }
  bashio::log::debug "Debug mode enabled"

Supervisor API 通信

#!/bin/bash
# Get addon info
curl -X GET \
  -H "Authorization: Bearer $SUPERVISOR_TOKEN" \
  http://supervisor/addons/self/info | jq .

# Send notification
curl -X POST \
  -H "Authorization: Bearer $SUPERVISOR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"Warning message"}' \
  http://supervisor/notifications/create

多架构 Docker 构建

创建 build.yaml：

build_from:
  amd64: ghcr.io/home-assistant/amd64-base:latest
  armv7: ghcr.io/home-assistant/armv7-base:latest
  aarch64: ghcr.io/home-assistant/aarch64-base:latest
  armhf: ghcr.io/home-assistant/armhf-base:latest
codenotary: your-notary-id  # Optional code signing

为 Web UI 配置 Ingress

ingress: true
ingress_port: 8080
ingress_entry: /
# Optional ingress_stream for streaming endpoints

在应用中使用正确的反向代理标头：

# nginx configuration in your app
location / {
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Forwarded-Proto $scheme;
  proxy_set_header Host $host;
  proxy_pass http://localhost:8080;
}

已知问题预防

问题	根本原因	解决方案
插件无法启动	缺少 S6 服务文件	创建 /etc/s6-overlay/s6-rc.d/service-name/，并添加可执行的 run 文件
Supervisor API 返回 401	SUPERVISOR_TOKEN 无效	确认 Home Assistant 已设置此令牌（使用 addon_uuid 检查日志）
配置未持久化	保存位置不在 /data/ 下	始终使用 bashio::addon::config_path 或 /data/ 进行持久化
端口已被占用	多个服务使用同一端口	检查配置：每个服务都需要唯一端口
架构不匹配	未使用 {arch} 占位符	在镜像字段中使用准确的占位符：ghcr.io/home-assistant/{arch}-base
构建失败并提示“未知架构”	config.yaml 列出了不受支持的架构	仅使用：amd64、armv7、aarch64、armhf、i386

Supervisor API 端点

# Authentication: Pass SUPERVISOR_TOKEN header
# Base URL: http://supervisor

GET /addons/self/info            # Get current add-on details
POST /addons/self/restart        # Restart this add-on
GET /addons/installed            # List installed add-ons
GET /info                        # System information
POST /notifications/create       # Send notification to user
GET /config/homeassistant        # Read Home Assistant config

# Example with bashio
bashio::addon::self_info         # Helper function for self info

依赖项

必需

软件包	版本	用途
Home Assistant	2024.1+	插件平台和 Supervisor
Docker	Latest	容器运行时
S6 Overlay	3.x	初始化系统（包含在基础镜像中）

可选

软件包	版本	用途
bashio	Latest	辅助函数（包含在基础镜像中）
python3	3.9+	基于 Python 的插件
nodejs	18+	基于 Node.js 的插件

官方文档

• Home Assistant 插件开发
• 插件配置参考
• Supervisor 开发
• bashio 辅助函数
• S6 Overlay 文档

故障排查

插件无法启动

症状： 插件显示为“未运行”或“未知”

解决方案：

# Check logs
docker logs addon_name_latest  # Or use HA UI: Settings > System > Logs

# Common causes:
# 1. Invalid config.yaml syntax
# 2. Missing S6 service files
# 3. Dockerfile can't find base image
# 4. Permission denied on rootfs files

Supervisor API 返回 401

症状： API 调用失败并提示“未授权”

解决方案：

# Verify SUPERVISOR_TOKEN is set
echo $SUPERVISOR_TOKEN

# Check add-on logs for token errors
# Token is automatically injected by Home Assistant

# Verify permissions in config.yaml
# If calling hassio endpoints, add: permissions: [hassio]

配置未保存

症状： 重启后选项丢失

解决方案：

# Always save to /data/ or use bashio
CONFIG_PATH="$(bashio::addon::config_path)"  # Returns /data/
echo "my_value=123" > "${CONFIG_PATH}/settings.json"

# Verify /data/ exists and is writable
ls -la /data/

Ingress Web UI 无法访问

症状： Ingress URL 返回 502 或空白页面

解决方案：

# 1. Verify service is listening on correct port
netstat -tlnp | grep 8080

# 2. Check reverse proxy headers in app config
# X-Forwarded-For, X-Forwarded-Proto must be set

# 3. Verify ingress settings in config.yaml
ingress: true
ingress_port: 8080
ingress_entry: /

构建失败并提示架构错误

症状：“未知架构”或“找不到镜像”

解决方案：

# Check config.yaml has valid arch values
arch:
  - amd64      # x86 64-bit
  - armv7      # 32-bit ARM (Pi 2/3)
  - aarch64    # 64-bit ARM (Pi 4+)
  - armhf      # 32-bit ARM (older devices)
  - i386       # 32-bit x86 (rare)

# Dockerfile must use {arch} placeholder
FROM ghcr.io/home-assistant/{arch}-base:latest

设置检查清单

发布插件前，请确认：

• config.yaml 的 YAML 语法有效（使用在线 YAML 验证器）
• 列出的所有架构均受支持（amd64、armv7、aarch64、armhf、i386）
• Dockerfile 使用官方 Home Assistant 基础镜像
• S6 服务文件存在且可执行（chmod +x）
• 所有配置选项均已在 schema 中记录
• 没有硬编码路径（使用 bashio 辅助函数）
• permissions 字段列出了所需的 Supervisor API 访问权限
• 已在至少 amd64 和 ARM 架构上测试
• 日志使用 bashio::log 函数
• 已实现对 SIGTERM 的平稳关闭
• 所有持久化数据均使用 /data/
• 如果提供 Web UI，Ingress 可正常工作
• README 包含安装和使用说明

创建仓库

如需发布多个插件：

1. 创建仓库结构

mkdir my-addon-repo
cd my-addon-repo

2. 创建 repository.yaml

---
name: My Add-On Repository
url: https://github.com/username/my-addon-repo
maintainer: Your Name <[email protected]>

3. 添加插件

my-addon-repo/
├── repository.yaml
├── my-addon-1/
│   ├── config.yaml
│   ├── Dockerfile
│   └── rootfs/
└── my-addon-2/
    ├── config.yaml
    ├── Dockerfile
    └── rootfs/

4. 推送到 GitHub

将仓库 URL 添加到 Home Assistant，使插件可供发现。

进阶：发布到 GitHub Container Registry

适用于私有仓库或多架构构建：

# Build and push for all architectures
docker buildx build \
  --platform linux/amd64,linux/arm/v7,linux/arm64/v8 \
  -t ghcr.io/username/my-addon:1.0.0 \
  --push .

相关技能

• docker-configs - Docker 基础知识和最佳实践
• esphome-config-helper - 相关的 IoT 设备集成模式
• home-assistant-automation - Home Assistant 自动化和脚本编写