企业官网建设流程全解析

在 Home Assistant 中安装 Tandoor Recipes：社区 Add-on 部署指南

【免费下载链接】recipesApplication for managing recipes, planning meals, building shopping lists and much much more!项目地址: https://gitcode.com/GitHub_Trending/re/recipes

本指南面向希望把 Tandoor Recipes（TandoorRecipes，食谱管理与烹饪规划应用）直接部署在 Home Assistant 设备上的用户，完整介绍基于 alexbelgium 社区维护的 hassio-addons 仓库的 Add-on 安装、配置、更新与备份流程。读完本文，你将能够把 Tandoor 以本地 Add-on 形式运行在 Home Assistant 上，并理解其与 HA 之间双向联动的底层实现（购物清单与 HA Todo 列表的同步连接器）。

背景：为什么在 Home Assistant 上运行 Tandoor

Home Assistant 是一款免费开源的智能家居自动化软件，定位为智能家居设备的集中控制中枢，重点关注本地控制与隐私。它可以通过 Web 界面访问，也支持 Android / iOS 配套 App，或通过 Google Assistant、Amazon Alexa 等虚拟助手进行语音控制。

Home Assistant 有两种主流部署形态：

• 独立操作系统（HA OS）：部署在专用设备上，通过 Over The Air（OTA）方式即可完成系统更新，安装与维护都极其简单；
• Docker 容器：运行在已有 Docker 环境中的容器形态。

除了丰富的原生功能外，HA 通过**模块化 Add-on（附加组件）**体系可以不断扩展能力。社区为 Tandoor Recipes 专门编写了 Add-on，让你可以直接把 Tandoor 的服务端托管在运行 Home Assistant 的设备上，并通过两种方式访问界面：

• Ingress：直接在 Home Assistant 的 Web 界面内嵌访问（更安全，免端口暴露）；
• 直连 Web UI：通过http://homeassistant.local:9928访问。

说明：本文档属于社区贡献内容，并非官方维护、也未经官方持续更新和测试。特别感谢 alexbelgium 实现并维护了让 Tandoor 在 HA 中运行所需的一切。

兼容性提示：Tandoor 2 与端口变化

!!! danger "Tandoor 2 兼容性" 本指南尚未针对Tandoor 2进行验证/测试。Tandoor 2 在默认 Docker 容器内集成了 nginx 服务，并将服务端口从8080改为80暴露。

在跟随本指南配置前，请确认你将要运行的 Tandoor 版本。Add-on 支持的硬件架构包括aarch64、amd64、armv7（对应的 HA 设备如树莓派 4 / 5、x86 主机等均可覆盖）。

安装步骤

在开始之前，请确保你已有一个正常运行的 Home Assistant 系统（HA OS 或 Docker 形态均可，前提是具备 Supervisor / Add-on 能力）。然后按以下步骤操作：

1. 添加自定义仓库：将 alexbelgium 的自定义 Add-on 仓库添加到你的 HA 系统。HA 官方提供了"带预填仓库 URL 的添加仓库对话框"跳转按钮，点击后只需填入你的 HA 地址即可完成添加；也可以直接在 HA 的 Supervisor 界面中手动添加仓库地址。
2. 安装 Add-on：在商店中找到该 Add-on 并点击安装。
3. 按需配置选项：根据你的使用场景设置 Add-on 选项（配置项含义见下文「配置详解」章节）。
4. 启动 Add-on。
5. 检查日志：打开 Add-on 的日志页面，确认启动过程一切正常、没有报错。
6. 打开 WebUI：通过 Ingress（内嵌于 HA 界面）或直连http://homeassistant.local:9928访问 Tandoor 界面，并在应用内完成语言、账号等初始设置。

网络访问前提

由于 Tandoor 运行在 HA 设备本地，WebUI 直连地址使用 HA 设备在局域网内的主机名homeassistant.local。如果你的 HA 设备主机名不同，请以实际主机名为准。若要通过 HA 的 Ingress 机制访问，需要在配置中把 Home Assistant 的访问 URL（含端口）填入ALLOWED_HOSTS（见下节），否则 Ingress 请求会被 Tandoor 拒绝。

配置详解

Add-on 的配置通过环境变量暴露，可在 Add-on 的「Configuration」选项卡中填写。下表列出了全部可配置项，其中带#注释的行为 JSON 配置键及填写说明：

Required : "ALLOWED_HOSTS": "your system url", # 必填。填入你的 homeassistant urls（逗号分隔、不要有空格），Ingress 才能正常工作 "DB_TYPE": "list(sqlite|postgresql_external|mariadb_addon)" # 数据库类型。mariadb_addon 会在已安装 maria_db addon 时自动配置；sqlite 为内置数据库；postgresql_external 需填写下方设置 "SECRET_KEY": "str", # 你的加密密钥，务必设置为随机长字符串 "PORT": 9928 # 默认 WebUI 端口 http://homeassistant.local:9928。如需改端口，绝不能改应用内部，只能通过此选项修改 Optional : "POSTGRES_HOST": "str?", # 使用 postgresql_external 时必需 "POSTGRES_PORT": "str?", # 使用 postgresql_external 时必需 "POSTGRES_USER": "str?", # 使用 postgresql_external 时必需 "POSTGRES_PASSWORD": "str?", # 使用 postgresql_external 时必需 "POSTGRES_DB": "str?" # 使用 postgresql_external 时必需

关键配置项说明

关于环境变量的底层作用机制，可参考官方 Docker 安装文档（Add-on 本质上是把同一套 Tandoor 镜像以受限容器方式跑在 HA 中，因此环境变量体系与 Docker 部署一致）以及 配置文档。

更新与备份

自动更新

alexbelgium 的仓库内置了一个脚本，每 3 天将 Add-on 与官方发布的容器镜像对齐同步。这意味着你无需手动跟踪版本，只要等待几个小时后，HA 刷新仓库列表，更新就会自动出现在你的 HA 系统中，届时在 Add-on 页面点击更新即可。

备份策略

官方强烈建议频繁备份。Tandoor 的所有数据都存放在 Add-on 之外的主目录/config/addons_config/tandoor_recipes下，因此：

1. 更新前必须备份该目录，而不仅仅是备份 Add-on 本身；
2. 如果你选择了mariadb数据库选项，不要忘记同时备份数据库（数据文件在 maria_db Add-on 的存储目录中）；
3. 使用 HA 官方「备份」功能时，请确认上述外部目录与数据库都被纳入备份范围。

支持渠道

遇到问题时的反馈路径如下（按问题归属分流）：

• Add-on 本身的问题：报告到维护者仓库（alexbelgium/hassio-addons）；
• Home Assistant 的问题：报告到 HA 官方社区论坛；
• Tandoor Recipes 本身的问题：报告到本仓库（TandoorRecipes/recipes）。

纵深：Tandoor 与 Home Assistant 的双向联动（Connectors）

安装好 Add-on 之后，Tandoor 与 Home Assistant 之间还有一层值得了解的深度集成：Connectors（连接器）。它把 Tandoor 的购物清单操作转换为对 HA 外部服务的 API 调用，实现「Tandoor 操作 → HA Todo 列表」的自动同步。该功能目前处于beta 阶段（详见 Connectors 特性文档）。

连接器支持的能力

当前 HomeAssistant 连接器（源码见 cookbook/connectors/homeassistant.py）支持以下三种动作：

1. 新建购物清单条目时：把新条目推送到 HA 的 Todo 列表；
2. 把食谱加入购物清单时：将该食谱的所有食材条目一并推送；
3. 删除 Todo 项时：仅当该项自 Tandoor 侧移除、且内容未被外部修改时，才从 HA Todo 中删除。

安全警告：连接器需要存储认证信息才能向外部服务推送数据，请在可行时尽量使用只读/独立账号或应用专用密码，避免泄漏主账号凭证。

配置一个 HomeAssistant 连接器

在 Tandoor 界面中进入 Connectors 管理页，新建 HomeAssistant 类型连接器，按三步完成：

第 1 步：生成 HA 长生命周期访问令牌（Long-Lived Access Token）在 HA 用户资料页 → 安全（Security）→ 长期访问令牌（Long-Lived Access Tokens）处创建，并复制保存（只显示一次）。

第 2 步：准备目标 Todo 列表在 HA 中创建/获取一个需要同步的 Todo 列表条目，记住它的完整实体 ID（Entity ID）。

第 3 步：填写连接器字段

• URL：你的 Home Assistant 地址，必须包含/api后缀。例如：

  http://homeassistant.local:8123/api

  或

  https://homeassistant.example.com/api

  注意：较新版本的连接器界面不再明确提示要加/api，但 URL 中缺少/api会导致连接器无法工作。

• Access Token：粘贴第 1 步生成的 Long-Lived Access Token。

• Name of Todo List：填写 HA Todo 的完整实体 ID（如todo.shopping），而不是显示名称（shopping）。填错将导致找不到目标列表。

源码层面的实现细节

从源码结构看（cookbook/models.py），ConnectorConfig模型记录了连接器的全部配置字段：

• url：HA 地址（模型字段为URLField）；
• token：长生命周期访问令牌（CharField(max_length=512)，在序列化器中标记为write_only，即 API 返回时永不回显，见 cookbook/serializer.py）；
• todo_entity：Todo 实体 ID（CharField(max_length=128)）；
• 三个布尔开关：on_shopping_list_entry_created_enabled/on_shopping_list_entry_updated_enabled/on_shopping_list_entry_deleted_enabled，分别控制三种动作是否启用；
• supports_description_field：目标 Todo 实体是否支持 description 字段（默认True）。

在运行层，cookbook/connectors/homeassistant.py 中HomeAssistant类的 API 调用逻辑为：

• 通过urljoin拼接请求路径，请求头携带Authorization: Bearer <token>；
• 新增条目时调用POST services/todo/add_item，数据体包含entity_id与item；若目标支持 description 字段，则附带形如From TandoorRecipes, by <用户>的描述；
• 删除条目时调用POST services/todo/remove_item（若 HA 中不存在该条目，ClientResponseError一定会被抛出，此时按debug级别记录，属于预期行为）；
• 条目文本会带上数量与单位，例如牛奶 (1.50 l)，数量小数末尾的 0 会被自动去除（见 homeassistant.py）。

连接器的调度架构

连接器的触发与调度由 cookbook/connectors/connector_manager.py 中的ConnectorManager完成，其工作方式（源码注释中亦有说明）为：

1. 应用启动时（见 cookbook/apps.py），通过 Django 的post_save/post_delete信号把ConnectorManager挂接为处理器；
2. 任何ShoppingListEntry或ConnectorConfig的增删改都会把Work(actionType, instance)非阻塞地推入一个queue.Queue（队列上限由EXTERNAL_CONNECTORS_QUEUE_SIZE控制，默认 100，见 recipes/settings.py）；
3. 后台线程中的 worker 逐个消费队列：如果是ConnectorConfig变化，则清空并按 space 维度重建该空间的连接器缓存；如果是购物清单条目变化，则异步并发地触发该空间所有已启用连接器的对应回调，总耗时取决于最慢的那个连接器；
4. 可通过DISABLE_EXTERNAL_CONNECTORS环境变量（默认False）整体关闭连接器功能。

对应的调度正确性由测试覆盖（见 cookbook/tests/other/test_connector_manager.py）：例如test_run_connectors验证了对一个ShoppingListEntry执行DELETED动作时，只会调用连接器的on_shopping_list_entry_deleted，而不会误触created/updated回调。

总结

在 Home Assistant 上部署 Tandoor Recipes 的完整路径是：添加 alexbelgium 社区仓库 → 安装 Add-on → 配置ALLOWED_HOSTS/DB_TYPE/SECRET_KEY/PORT（及可选的 PostgreSQL 参数）→ 启动并检查日志 → 通过 Ingress 或http://homeassistant.local:9928使用。日常维护只需记住两件事：更新由每 3 天一次的镜像对齐自动推送，以及务必备份/config/addons_config/tandoor_recipes目录（以及 mariadb 数据库）。如果需要让购物清单在 Tandoor 与 HA Todo 列表之间自动同步，再在应用内配置 HomeAssistant 连接器即可。安装部署细节可进一步参考 Docker 安装文档 与 配置文档。

【免费下载链接】recipesApplication for managing recipes, planning meals, building shopping lists and much much more!项目地址: https://gitcode.com/GitHub_Trending/re/recipes