Home Assistant 中 AdGuard Home 过滤器刷新动作adguard.refresh完整指南【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io导读adguard.refresh是 Home Assistant 的 AdGuard Home 集成提供的一项动作Action用于让 AdGuard Home 立即重新下载全部过滤器订阅并拉取最新的屏蔽规则。本文以 source/_actions/adguard.refresh.markdown 为骨架结合同域其他过滤器管理动作Add / Remove / Enable / Disable URL与 AdGuard Home 集成文档完整讲解该动作在 UI 与 YAML 中的用法、force参数语义、与增删启用停用动作的配合模式以及可落地的自动化示例。读完本文你将掌握如何让新规则立即生效、如何规避节流、如何编排每日刷新 / 学习时段切换 / 睡前切换等实战场景。一、动作是什么让过滤器订阅立即生效AdGuard Home 是网络级的 DNS 广告与追踪拦截软件Home Assistant 的 AdGuard Home 集成 可以监控并控制它。其中的Refresh动作adguard.refresh会告诉 AdGuard Home重新下载所有过滤器订阅filter subscriptions并拉取最新屏蔽规则从而让阻止列表保持最新并在改动后立刻生效而不是等待 AdGuard Home 自身的定时更新。它天然适合与同域的另外四个过滤器管理动作搭配使用Add URLadguard.add_url订阅一个新的过滤器列表Remove URLadguard.remove_url移除已有订阅Enable URLadguard.enable_url启用此前被关闭的订阅Disable URLadguard.disable_url关闭订阅。按照 Add URL 文档 的说明新添加的订阅会立即启用但 AdGuard Home不会在下载到列表之前按新规则屏蔽。要让规则立刻生效就必须在本动作之后紧跟一次adguard.refresh。同样地Enable URL 文档 也建议在启用后紧跟一次 Refresh。这正是 Refresh 动作在自动化中通常作为收尾动作出现的原因。注意Refresh 动作不支持目标targets。在 UI 中不会提示你选择区域、设备、实体或标签它作用于整个 AdGuard Home 实例的全部过滤器订阅。二、从 UI 使用图形化配置步骤如果你习惯在界面中可视化地构建自动化或脚本可按以下步骤操作对应文档 source/_actions/adguard.refresh.markdown 的 UI 章节进入设置Settings自动化与场景Automations scenes。打开现有的自动化或脚本或选择创建自动化Create automation创建新自动化Create new automation。如果是在新建自动化在当When部分添加触发器。脚本不需要触发器——它们由其他对象调用时运行。在然后执行Then do部分选择添加动作Add action。在搜索框中搜索并选择AdGuard Home: Refresh。可选打开Force强制执行以绕过 AdGuard Home 的更新节流throttling。选择保存Save。UI 中的选项选项说明是否必填Force强制更新绕过 AdGuard Home 的节流。常规刷新时保持关闭。否由于该动作不支持目标选择配置过程非常简单只有一个可选的Force开关。三、YAML 用法在自动化与脚本中调用在 YAML 中该动作的名称为adguard.refresh。文档 source/_actions/adguard.refresh.markdown 给出的基础示例为action: adguard.refresh这会刷新 AdGuard Home 中的所有过滤器订阅。YAML 中的选项字段类型必填默认值说明forceboolean否false强制更新绕过 AdGuard Home 的节流。常规刷新时省略此字段。从源码结构看Home Assistant 的动作Action在 YAML 中统一使用action:字段声明动作名可选的参数放在data:映射中。因此一个带force参数的完整写法是action: adguard.refresh data: force: trueforce: true适用于需要立刻让新规则生效的场景例如刚完成 Add URL / Enable URL 后马上启用严格模式。四、注意事项节流与强制刷新文档 source/_actions/adguard.refresh.markdown 的Good to know章节明确提醒AdGuard Home 通常会对过滤器更新进行节流throttling以降低负载。只有当你需要规则立即更新时才打开Force并且要克制使用。换句话说常规刷新省略force保持false让 AdGuard Home 按自己的节奏更新强制刷新仅在明确需要立即应用新规则时使用force: true且不宜在自动化中高频调用以免给 AdGuard Home 服务器造成额外负载。这与 Add URL 文档中新订阅下载完成后规则才生效的行为相呼应只有 Refresh尤其是强制 Refresh才能真正把已订阅但尚未下载的规则立刻拉下来。五、实战自动化示例5.1 每晚刷新阻止列表文档原例让阻止列表每天在大家睡觉时刷新一次保持最新触发器时间04:00动作AdGuard Home: Refresh文档 source/_actions/adguard.refresh.markdown 给出的完整 YAML 为automation: alias: Refresh AdGuard Home blocklists nightly triggers: - trigger: time at: 04:00:00 actions: - action: adguard.refresh5.2 添加过滤器后立即生效Add URL RefreshAdd URL 文档 强调新添加的订阅立即启用但在下载之前不会按新规则屏蔽。因此标准的上线一个新阻止列表自动化是 Add 后紧跟 Refreshautomation: alias: Add study-time blocklist triggers: - trigger: state entity_id: input_boolean.study_time to: on actions: - action: adguard.add_url data: name: Study-time blocklist url: https://www.example.com/study-blocklist.txt - action: adguard.refresh5.3 启用过滤器后立即生效Enable URL RefreshEnable URL 文档 建议在启用一个此前关闭的订阅后紧跟 Refresh。它给出的睡前切换示例为automation: alias: Enable bedtime blocklist triggers: - trigger: time at: 20:00:00 actions: - action: adguard.enable_url data: url: https://www.example.com/bedtime-blocklist.txt - action: adguard.refresh5.4 上下班自动切换社交屏蔽集成文档原例AdGuard Home 集成文档 中的工作时间屏蔽社交网站示例把 Add URL Refresh 与 Remove URL 配对形成了上班屏蔽、下班解除的闭环automation: - alias: Block social media during work triggers: - trigger: time at: 09:00:00 actions: - action: adguard.add_url data: name: Social media blocklist url: https://raw.githubusercontent.com/example/social-media-blocklist/main/list.txt - action: adguard.refresh - alias: Unblock social media after work triggers: - trigger: time at: 17:00:00 actions: - action: adguard.remove_url data: url: https://raw.githubusercontent.com/example/social-media-blocklist/main/list.txt5.5 完整模式总结将上述示例抽象成模式你可以按需组合场景动作序列订阅新列表并立即应用adguard.add_url→adguard.refresh启用旧列表并立即应用adguard.enable_url→adguard.refresh停用列表adguard.disable_url移除列表adguard.remove_url每日例行更新定时触发adguard.refresh六、与集成的整体配合监控与状态同步Refresh 动作运行在 AdGuard Home 集成 之上。该集成提供了多种实体类型可与 Refresh 动作配合形成完整的网络防护自动化传感器sensorDNS 查询总数、被屏蔽的 DNS 查询数、屏蔽比例、安全浏览拦截数、安全搜索强制执行次数、家长控制拦截数、当前加载的过滤规则数量Rules count、DNS 平均处理速度等开关switchProtection总开关、Filtering、Safe browsing、Parental control、Safe search、Query log更新update检查并安装 AdGuard Home 软件更新。从集成文档的Data updates章节可知该集成每 10 秒轮询一次以提供近乎实时的统计并保持开关状态同步。因此你可以在自动化中通过先 Refresh、再读取 Rules count 传感器的方式确认新规则已经加载到位。集成文档还给出了两个与过滤器动作直接相关的排错要点动作报 Filter URL not found当尝试启用、禁用或移除一个不存在的过滤器 URL 时会出现此错误。请到 AdGuard Home 界面过滤器 DNS 阻止列表核对确切的 URL传感器显示不可用请检查Query log开关是否开启——关闭 Query log 会停止所有传感器更新因为 AdGuard Home 需要查询日志才能产出统计。七、快速测试在界面中验证动作如果你想在不写一行 YAML 的情况下验证adguard.refresh的实际效果可以在设置 工具 动作中搜索该动作填写字段并选择执行动作Perform action对应 try_it.md。你可以在实际实体上立即看到效果——刷新后AdGuard Home 的过滤规则数量应重新加载。结语adguard.refresh虽是一个单参数的轻量动作却是整个 AdGuard Home 过滤器管理链的收尾关键没有它新订阅的列表只是已注册而未生效。通过本文的 UI 步骤、YAML 参数表、force节流语义与 5 个实战示例你可以把它编排进每日定时、学习时段、睡前切换、上下班切换等任何需要立即更新规则的自动化场景让网络防护始终贴合你的家庭策略。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考