企业官网建设流程全解析

• 智能家居
• 物联网

导读

本文以 addons 仓库中 Terminal & SSH（slug: 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与amd64（9.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 超级用户最常用的"后门"型运维终端。

二、两种接入方式与使用实操

官方文档 明确指出该组件提供两个核心功能：

1. 浏览器内的 Web 终端；
2. 通过 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 修复的 shift+drag 复制问题）；
• 粘贴文本：按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）。要启用，需要两步：

1. 在组件配置中提供认证凭据——密码或 SSH 公钥；
2. 在网络（Network）配置中指定宿主机上绑定的 TCP 端口（标准 SSH 端口为 22），该端口会被映射进组件容器。

之后使用用户名root连接该端口即可。官方文档明确警告：启用 SSH 服务器可能降低系统安全性，因为它可能让互联网上的任何人尝试登录你的系统；同时强烈建议使用公私钥而非密码登录，因为只要私钥保管得当，破解难度会远高于密码。文档还特别提示：生成密钥时应选择ECDSA而非 RSA（RSA 已不再受支持，详见下文 9.6.0 的破坏性变更）。

需要特别注意的是：启用密码登录会禁用密钥登录，两者不能同时启用，这一点与源码中 sshd_config 模板的分支逻辑完全一致（见 4.2 节）。

三、配置项全解

组件配置清单 中定义了四个顶层配置项，官方文档给出了完整示例：

authorized_keys: - "ssh-rsa AKDJD3839...== my-key" password: '' apks: [] server: tcp_forwarding: false

3.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更名为/homeassistant，9.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 root@host "ha info"）也能直接使用该环境变量——这正是 9.6.2 版本"将 SUPERVISOR_TOKEN 作为 SSH 环境变量、无需交互 bash 会话即可调用 HA CLI"的实现；
• 认证分支：配置了authorized_keys则写入/data/.ssh/authorized_keys（chmod 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 直接登录（连接用户名为root）；
• AllowTcpForwarding由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 镜像装配（Dockerfile）

Dockerfile 展示了镜像的完整装配过程：

• 基础软件：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.0）

CHANGELOG.md 完整记录了从 8.0.0 到当前 10.4.0 的 40 余个版本。按主题归类如下：

5.1 基础底座与依赖升级

5.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：新增蓝牙支持（bluez）；
• 9.1.0：支持启动时安装 APK（即apks配置项）；
• 9.6.2：SUPERVISOR_TOKEN 作为 SSH 环境变量，非交互命令可直接调用 HA CLI；
• 9.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：使用密钥时禁用键盘交互认证（KbdInteractiveAuthentication）；
• 9.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 键拖拽复制文本。

六、安全使用建议与已知限制

综合官方文档与源码，给出以下实践建议：

1. 默认保持远程 SSH 关闭，仅通过 Ingress Web 终端使用，是风险最低的用法；
2. 确需远程 SSH 时，使用 ECDSA 或 Ed25519 公钥认证，勿用密码；密钥与密码不可同时启用是设计约束而非缺陷；
3. 除非确有内网穿透、端口转发等需求，否则保持server.tcp_forwarding: false；
4. 利用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 下的初始化脚本，你可以精确理解每个配置项背后由谁渲染、由谁执行，进而在自己的部署中做出安全且高效的配置决策。

• 智能家居
• 物联网