basnijholt/home-assistant-streamdeck-yaml Docker 镜像 - 轩辕镜像 | Docker 镜像高效稳定拉取服务

Home Assistant on Stream Deck Docker镜像文档

镜像概述

本Docker镜像用于在Stream Deck设备上运行Home Assistant控制界面，通过YAML配置文件（支持模板功能）自定义设备行为，实现跨平台运行（兼容所有操作系统），为智能家居控制提供便捷的物理按键交互方式。

核心功能与特性

• YAML配置系统：通过YAML文件定义Stream Deck按钮行为，支持Jinja2模板语法动态生成内容
• 跨平台兼容：可在Windows、macOS、Linux等所有主流操作系统上运行
• Home Assistant深度集成：直接对接Home Assistant API，支持设备控制、状态显示、事件响应
• 模板支持：允许通过模板动态调整按钮图标、标签和状态，适配设备实时状态变化
• 轻量级部署：基于Docker容器化设计，简化依赖管理和环境配置

使用场景与适用范围

• 智能家居用户：通过Stream Deck物理按键快速控制灯光、温控、窗帘等Home Assistant管理的智能设备
• 家庭自动化爱好者：自定义复杂控制逻辑，实现一键执行场景模式（如"回家模式"、"影院模式"）
• 跨平台需求用户：在不同操作系统环境下保持一致的Stream Deck与Home Assistant集成体验
• 开发测试环境：快速部署独立的Stream Deck控制实例，避免影响本地系统配置

使用方法与配置说明

前提条件

• 已安装Docker Engine（20.10+）及Docker Compose（可选）
• Stream Deck设备已通过USB连接至主机，并确保系统能识别（可通过lsusb或设备管理器确认）
• 运行中的Home Assistant实例（本地或远程），并已获取长期访问令牌（Long-Lived Access Token）

基础使用方法

Docker Run命令

bash
docker run -d \
  --name=ha-streamdeck \
  --restart=unless-stopped \
  --device=/dev/bus/usb/001/003 \  # 根据实际Stream Deck USB路径调整（通过lsusb查看）
  -v /path/to/local/config:/app/config \  # 挂载本地配置目录
  -e HA_BASE_URL="[***]" \  # Home Assistant访问地址
  -e HA_ACCESS_TOKEN="your_long_lived_token" \  # Home Assistant长期访问令牌
  homeassistant-streamdeck:latest

Docker Compose配置示例

yaml
version: '3.8'
services:
  ha-streamdeck:
    image: homeassistant-streamdeck:latest
    container_name: ha-streamdeck
    restart: unless-stopped
    devices:
      - /dev/bus/usb/001/003:/dev/bus/usb/001/003  # 映射Stream Deck USB设备
    volumes:
      - ./config:/app/config  # 本地配置目录映射
    environment:
      - HA_BASE_URL="[***]"  # Home Assistant IP:端口
      - HA_ACCESS_TOKEN="eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."  # 替换为实际令牌
      - LOG_LEVEL=info  # 日志级别：debug/info/warn/error

配置文件说明

配置目录（/path/to/local/config）需包含config.yaml主配置文件，示例结构如下：

yaml
# config.yaml示例
buttons:
  - position: (0, 0)  # 按钮坐标（行, 列），从左上角(0,0)开始
    type: entity  # 按钮类型：entity/script/scene
    entity_id: light.living_room  # Home Assistant实体ID
    name: "客厅主灯"  # 按钮标签
    icon: /app/config/icons/light.svg  # 图标路径（支持本地文件或URL）
    template: |  # 模板示例：根据设备状态显示不同文本
      {% if is_state(entity_id, 'on') %}
        开启中
      {% else %}
        已关闭
      {% endif %}
    press_action:  # 按下按钮动作
      service: homeassistant.toggle
      target:
        entity_id: "{{ entity_id }}"
  # 可添加更多按钮配置...

环境变量参数

注意事项

• USB设备映射：需根据主机实际USB总线路径调整--device参数（可通过lsusb命令查询Stream Deck设备路径）
• 权限配置：确保Docker用户对USB设备有读写权限，Linux系统可能需要添加udev规则
• 配置验证：启动前建议通过YAML验证工具检查config.yaml语法正确性
• Home Assistant版本：推荐使用2021.12.0及以上版本以确保API兼容性
• 备份策略：定期备份配置目录，避免更新镜像时丢失自定义配置