智能家居物联网【免费下载链接】addons:heavy_plus_sign: Docker add-ons for Home Assistant项目地址https://gitcode.com/GitHub_Trending/add/addons点击查看免费下载导读本文以 addons 仓库中 Terminal SSHslug: ssh 附加组件的版本变更记录CHANGELOG为主线结合该组件的配置清单、Dockerfile、启动脚本与 SSH 配置模板系统梳理其两大核心能力——基于 Ingress 的浏览器 Web 终端与远程 SSH 服务器——的实现原理、配置方法、安全注意点及十余个版本的演进脉络。读完本文你将掌握该组件每个配置项的实际效果、登录认证机制的源码级细节以及从 8.0.0 到 10.4.0 的完整功能演进史可直接用于自己的 Home Assistant 环境的部署排障与安全加固。一、组件定位一个容器内的远程运维入口Terminal SSH 附加组件的官方描述是Allow logging in remotely to Home Assistant using SSH即允许你通过任意 SSH 客户端远程登录 Home Assistant 的文件系统并附带一个用于调用 Home Assistant API 的命令行工具。从 config.yaml 可以看到它的运行形态架构支持仅aarch64与amd649.21.0 起移除了 armhf、armv7、i386启动时机startup: services随系统服务阶段启动宿主能力挂载audio、uart、host_dbus全部启用并声明hassio_api与hassio_role: manager拥有通过 Supervisor API 管理 Home Assistant 的权限目录映射addons、all_addon_configs、backup、homeassistant_config、media、share、ssl全部以读写方式:rw映射进容器网络暴露22/tcp端口默认值为null即默认关闭远程 SSH入口启用ingress面板图标为mdi:console面板标题为Terminal。无论你通过浏览器 Web 终端Ingress还是 SSH 客户端接入最终都落在该组件自己的容器内Home Assistant 配置目录挂载在/config实际指向/homeassistant因此该组件本质上是 Home Assistant 超级用户最常用的后门型运维终端。二、两种接入方式与使用实操官方文档 明确指出该组件提供两个核心功能浏览器内的 Web 终端通过 SSH 客户端远程连接系统。2.1 Web 终端Ingress安装在 Home Assistant 中进入设置 应用 安装应用选择Terminal SSH安装使用在组件 Info 页点击Open Web UI即可打开若在 Info 页开启Show in sidebar侧边栏会添加快捷入口复制文本按住SHIFT用鼠标选中文本松开左键即复制到系统剪贴板此交互能力源自 9.16.0 升级 ttyd 1.7.7 修复的 shiftdrag 复制问题粘贴文本按SHIFT INSERT。从源码看Web 终端由 ttyd 承载。ttyd 启动脚本 中执行的是exec ttyd --writable -p 8099 tmux -u new -A -s homeassistant bash -l即 ttyd 监听 8099 端口拉起一个命名会话为homeassistant的 tmux-A表示若会话已存在则附加到它-u为 UTF-8 模式在其中运行bash -l登录 shell。这意味着在 Web 终端中即使连接断开tmux 会话也会在容器内持续存活重连后现场仍在——这正是 8.2.0 版本修复创建新 tmux 终端窗口演进点的最终形态。2.2 SSH 服务器连接远程 SSH 默认是关闭的端口映射值为null见 config.yaml。要启用需要两步在组件配置中提供认证凭据——密码或 SSH 公钥在网络Network配置中指定宿主机上绑定的 TCP 端口标准 SSH 端口为 22该端口会被映射进组件容器。之后使用用户名root连接该端口即可。官方文档明确警告启用 SSH 服务器可能降低系统安全性因为它可能让互联网上的任何人尝试登录你的系统同时强烈建议使用公私钥而非密码登录因为只要私钥保管得当破解难度会远高于密码。文档还特别提示生成密钥时应选择ECDSA而非 RSARSA 已不再受支持详见下文 9.6.0 的破坏性变更。需要特别注意的是启用密码登录会禁用密钥登录两者不能同时启用这一点与源码中 sshd_config 模板的分支逻辑完全一致见 4.2 节。三、配置项全解组件配置清单 中定义了四个顶层配置项官方文档给出了完整示例authorized_keys: - ssh-rsa AKDJD3839... my-key password: apks: [] server: tcp_forwarding: false3.1authorized_keys你的公钥列表可添加多个公钥以授权多把密钥登录。官方文档提示若添加密钥时报错很可能是公钥内容与 YAML 语法冲突用双引号包裹密钥即可规避。3.2password设置登录密码。官方明确标注不推荐此方式We do NOT recommend this variant因为密码登录的安全性远低于密钥登录。3.3apks容器启动时要额外安装的 Alpine 软件包列表。该功能的实现位于 apks.sh若配置了apks先apk update更新索引再逐个apk add任何一步失败都会通过bashio::exit.nok中止启动。该能力自 9.1.0 版本引入配合 Dockerfile 中预装的基础工具git、nano、vim、tmux、mosquitto-clients、bash-completion、bluez、pulseaudio-utils 等可以按需扩展容器工具链。3.4server.tcp_forwarding是否允许 SSH TCP 端口转发-L、-R等。该值由 sshd_config 模板 渲染进AllowTcpForwarding指令。官方文档注明启用会降低 SSH 服务器安全性同时附言这一警告本身存在争议。此功能源自 8.6.0 版本加入的本地 TCP 转发支持。3.5 网络端口Network官方文档单独强调只有在想用 SSH 客户端接入时才需要配置网络。在 Network 输入框中填入希望映射的宿主机 TCP 端口标准为 22保存并重启组件后生效清空输入框并重启即可再次禁用远程 SSH。9.5.1应为 8.5.1版本起若 SSH 端口被禁用启动时会显示警告对应 sshd 服务脚本 中的bashio::log.warning SSH port is disabled. Prevent start of SSH server.此时用sleep infinity替代 sshd 进程。四、源码级实现剖析4.1 启动初始化链路cont-init.d组件启动时依次执行四个初始化脚本共同构成完整的认证与环境装配流程keygen.sh——主机密钥的持久化SSH 主机密钥保存在/data/host_keys。首次启动执行ssh-keygen -A生成全套主机密钥并拷贝到持久目录之后每次启动从持久目录恢复。这保证了容器重建或重启后客户端不会因主机密钥变化而触发 known_hosts 冲突告警。profile.sh——用户环境的持久化将.bash_history与.bash_profile重定向到/data持久化确保重启后命令历史与自定义 profile 不丢失对应 8.1.0 修复.bash_profile 不存在导致启动错误、9.2.2 修复bash 彩色提示符转义码、9.12.0 修复bash_history 文件检查等历史问题用 tempio 把SUPERVISOR_TOKEN渲染进/etc/profile.d/homeassistant.sh模板见 homeassistant.profile使登录 shell 内可直接使用该令牌调用 Home Assistant CLI在用户 home 目录下为addon_configs、addons、backup、homeassistant、media、share、ssl创建符号链接并把/homeassistant链接为/config兼顾文档表述9.8.0 起/config更名为/homeassistant9.8.1 添加/config符号链接做向后兼容与用户肌肉记忆。ssh.sh——认证装配这是整个组件的核心逻辑持久化/data/.ssh目录chmod 700保证.ssh跨重启不丢8.0.0 引入通过 tempio 把SUPERVISOR_TOKEN写入/data/.ssh/environment模板见 ssh.environment配合 sshd_config 中的PermitUserEnvironment SUPERVISOR_TOKEN使得非交互式 SSH 命令如ssh roothost ha info也能直接使用该环境变量——这正是 9.6.2 版本将 SUPERVISOR_TOKEN 作为 SSH 环境变量、无需交互 bash 会话即可调用 HA CLI的实现认证分支配置了authorized_keys则写入/data/.ssh/authorized_keyschmod 600并用pwgen生成随机 64 位密码chpasswd锁定/解锁账户配置了password则直接写入该密码若两者都没有但配置了 22 端口映射则报错退出 You need to setup a login!最后用 tempio 渲染/etc/ssh/sshd_config。apks.sh按 3.3 节逻辑安装额外软件包。4.2 sshd_config 模板与认证互斥sshd_config 模板 揭示了几个关键实现事实PermitRootLogin yes允许 root 直接登录连接用户名为rootAllowTcpForwarding由server.tcp_forwarding决定GatewayPorts no、X11Forwarding no认证互斥逻辑authorized_keys存在时设置PasswordAuthentication no与KbdInteractiveAuthentication no否则若设置了password则PasswordAuthentication yes、PermitEmptyPasswords no。这就是密码与密钥不能共存的源码根源对应 9.19.0 的使用密钥时禁用键盘交互认证演进PermitUserEnvironment SUPERVISOR_TOKEN仅允许该环境变量从用户环境文件注入避免任意环境变量注入扩大攻击面。4.3 镜像装配DockerfileDockerfile 展示了镜像的完整装配过程基础软件bash-completion、pulseaudio-utils、alsa-plugins-pulse、bluez、git、libuv、mosquitto-clients、nano、openssh、pwgen、tmux、ttyd、vim为 nano 添加 YAML 语法高亮下载 yaml.nanorc 并启用/usr/share/nano/*.nanorc的 include通过sed将/etc/passwd的默认 shell 从/bin/sh改为/bin/bash对应 10.0.1、9.20.1 两次修复默认 shell从 Home Assistant CLI 发布页下载对应架构的ha二进制到/usr/bin/ha并执行ha completion生成 bash 补全文件对应 9.12.0 的补全安装、9.13.0 为非登录 shell 启用补全10.0.0 起 ttyd 直接从 Alpine 软件仓库安装不再自行编译。五、版本演进全览8.0.0 – 10.4.0CHANGELOG.md 完整记录了从 8.0.0 到当前 10.4.0 的 40 余个版本。按主题归类如下5.1 基础底座与依赖升级主题关键版本Alpine 版本升级3.118.0.0→ 3.128.7.0→ 3.139.0.0→ 3.149.2.0→ 3.169.6.0→ 3.179.7.0→ 3.189.8.0→ 3.199.9.0→ 3.229.20.0→ 3.2310.0.0→ 3.2410.4.0Home Assistant CLI4.0.18.3.0起几乎逐版跟进至 5.3.110.4.0ttyd / libwebsocketsttyd 1.6.0 lws 3.2.28.3.0→ 1.7.79.16.0→ 10.0.0 起使用 Alpine 仓库版本基础镜像迁移至 GitHub Container Registry9.1.1后续更新至 3.23-2026.03.1 / 3.23-2026.04.010.1.0 / 10.2.05.2 重大功能里程碑8.0.0新增 Ingress Web 终端、改进 API token 处理、.ssh文件夹跨重启持久化、home 目录辅助符号链接8.4.0支持仅使用 Web 终端而不启用 SSH 服务器注意如需 SSH 需把 Port 配置加回来8.5.0迁移到 s6-overlay支持 PulseAudio新音频后端8.6.0本地 TCP 转发支持即tcp_forwarding配置项8.8.0系统关机/重启操作包装为调用 Supervisor 执行8.9.0新增蓝牙支持bluez9.1.0支持启动时安装 APK即apks配置项9.6.2SUPERVISOR_TOKEN 作为 SSH 环境变量非交互命令可直接调用 HA CLI9.8.0/config更名/homeassistant支持访问公共附加组件配置对应 config.yaml 中的all_addon_configs映射10.0.0升级 Alpine 3.23、ttyd 改用 Alpine 仓库包。5.3 安全与兼容性要点9.6.0 破坏性变更OpenSSH 因安全漏洞禁用了基于 SHA-1 算法生成的 RSA 密钥。升级后若 RSA 密钥失效需用更强算法重新生成密钥或改用 ECDSA / Ed25519 类型密钥这也是官方文档建议生成 ECDSA 密钥的原因9.19.0使用密钥时禁用键盘交互认证KbdInteractiveAuthentication9.4.0启用镜像签名9.21.0移除 armhf、armv7、i386 架构支持10.0.2移除配置中的 advanced 标记。5.4 体验细节修复8.1.0 修复.bash_profile启动错误、提示符显示当前短路径8.2.0 修复 tmux 新窗口创建与 authorized_keys 目录问题9.2.0 提示符更鲜艳、9.2.2 修复彩色提示符转义码9.13.0 为非登录 shell如 Web 终端启用ha命令补全9.16.0 修复 Web UI 中 shift 键拖拽复制文本。六、安全使用建议与已知限制综合官方文档与源码给出以下实践建议默认保持远程 SSH 关闭仅通过 Ingress Web 终端使用是风险最低的用法确需远程 SSH 时使用 ECDSA 或 Ed25519 公钥认证勿用密码密钥与密码不可同时启用是设计约束而非缺陷除非确有内网穿透、端口转发等需求否则保持server.tcp_forwarding: false利用apks按需扩展工具避免镜像体积膨胀。已知限制官方明确声明该组件不会让你以 root 身份安装系统级软件包或执行任何超出容器边界的操作——这与 Home Assistant 的权限模型相关容器内能做的仅限于已挂载目录/config、/share、/media、/backup、/ssl、/addons等内的读写与 Supervisor API 调用。七、结语Terminal SSH 是 Home Assistant 官方附加组件中结构紧凑但演进极其活跃的一个十余年从 8.0.0 到 10.4.0的版本记录清晰呈现了 Alpine 底座升级、CLI 工具逐版跟进、Web 终端体验打磨、安全加固与架构裁剪的完整轨迹。配合 config.yaml 与 cont-init.d 下的初始化脚本你可以精确理解每个配置项背后由谁渲染、由谁执行进而在自己的部署中做出安全且高效的配置决策。赞分享智能家居物联网【免费下载链接】addons:heavy_plus_sign: Docker add-ons for Home Assistant项目地址https://gitcode.com/GitHub_Trending/add/addons点击查看免费下载相关推荐Home Assistant Mosquitto broker 插件版本演进、认证架构与核心配置深度解析Home Assistant Mosquitto broker 插件版本演进、认证架构与核心配置深度解析 本文以 mosquitto/CHANGELOG.md智能家居物联网Midway RabbitMQ 组件深度解析从版本演进到源码级消息订阅实践Midway RabbitMQ 组件深度解析从版本演进到源码级消息订阅实践 导读 midwayjs/rabbitmq 是 Midway 框架内置的 Rabb后端微服务云原生WeChatMsg颠覆性微信聊天记录智能备份与深度分析解决方案WeChatMsg颠覆性微信聊天记录智能备份与深度分析解决方案 在数字时代微信聊天记录承载着我们的珍贵记忆、重要工作信息和情感历程然而官方工具的局限性让这数据可视化UI组件上一篇FastAPI-Users项目实战如何获取当前用户信息下一篇如何创建自定义翻译器将ChatGPT等AI服务集成到Linguist中创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考