Huginn 2026.10.14 快速入门与 Agent 编排示例

目标：部署完成后快速上手 Huginn，讲清 Agent/Event/Scenario 核心概念，并实测「网页变更监控 → 邮件告警」与「Webhook 接收外部告警」两条编排链路及 Scenario 打包管理。已在 Ubuntu 22.04 实测通过。

按《Huginn 2026.10.14 Ubuntu 22.04 安装指南》或《Huginn 2026.10.14 Docker Compose 部署指南》完成部署后，本文带你从零理解 Huginn 的核心概念，并实测两条完整的自动化链路：网页变更监控 → 条件触发 → 邮件告警与Webhook 接收 → 事件入库。全部操作在 v2026.10.14 实例上执行验证。

一、环境信息

操作系统与架构：沿用前置部署文档的实测环境（Ubuntu 22.04 / x86_64，见《Huginn 2026.10.14 Ubuntu 22.04 安装指南》或《Huginn 2026.10.14 Docker Compose 部署指南》）；
Huginn 版本：v2026.10.14，全部操作在该版本实例上执行验证；
实例入口：http://192.168.1.62:13000/（Web 端口 13000，按实际部署端口为准），管理员账号 admin；
部署形态：复用已部署的 Huginn 实例（源码部署或 Docker Compose 部署均可），本文只做应用层 Agent 编排操作；
邮件链路实测组件：本机 aiosmtpd SMTP 接收器，监听 2525，邮件落盘 .eml；
后台任务：Agent 任务投递到 delayed_jobs 队列，由 Worker 消费。

二、核心概念

2.1 Agent：最小自动化单元

Agent 是 Huginn 的唯一执行单元，每个 Agent 是一种 Ruby 类的实例。常用的开箱类型：

类型	方向	用途
WebsiteAgent	采集	定时抓取网页/RSS/XML，用 CSS/XPath/JSONPath 提取数据
WebhookAgent	接入	开放一个 HTTP 接收端点，等外部系统 POST 数据进来
TriggerAgent	过滤	订阅上游事件，按规则匹配后向下游转发
EmailAgent	动作	把事件渲染成邮件发出
SchedulerAgent	调度	给任意 Agent 附加 cron 表达式
DataOutputAgent	输出	把事件聚合成可订阅的 JSON/XML 接口

2.2 Event 与事件流

Agent 运行后产出的数据叫 Event（JSON 载荷）。Agent 之间通过「接收（Receivers）」连线：A 的输出自动成为 B 的输入。事件流就是若干 Agent 用接收关系串成的流水线。

2.3 Scenario：编排打包

Scenario 是 Agent 的分组与导入导出容器，可整体分享、复制、搬迁实例。

💡 技术拓展：任务调度方式对比。Huginn 里「让 Agent 定期跑」有四种途径：① Agent 自带 schedule（内置每分钟/每小时/每天等固定档位，如 every_1h、midnight，配置简单但档位固定）；② SchedulerAgent（给任意 Agent 挂 cron 表达式，粒度最细，适合复杂节拍）；③ 手动 Run（页面按钮或 API 触发，调试用）；④ 上游事件驱动（下游 Agent 收到事件即执行，WebhookAgent 链路的标准形态）。一个 Agent 只能选一种 schedule，但可以同时被上游事件驱动。

三、首次登录

浏览器访问部署完成的服务（本文实测实例 http://192.168.1.62:13000/，端口按你的部署为准）：

用户名：admin
密码：q1w2e3r4

登录成功进入 Agents 列表页。首次安装完成 db:seed 后自带 7 个示例 Agent（实测清单）：

1  TriggerAgent          Rain Notifier
2  WebsiteAgent          XKCD Source
3  EmailDigestAgent      Afternoon Digest
4  EmailDigestAgent      Morning Digest
5  WeatherAgent          SF Weather Agent
6  WebsiteAgent          FilmJabber Trailer Source
7  EventFormattingAgent  Comic Formatter

这组种子本身就是一个完整示例链：XKCD Source 抓取漫画 → Comic Formatter 格式化 → Rain Notifier 按天气触发 → Morning/Afternoon Digest 定时汇总邮件。拿来当学习样本，比从空白开始更快。

四、实战一：网页变更监控 → 邮件告警

这是官方示例链的原型，本文实测从头走通一遍。

4.1 源 Agent：WebsiteAgent 监控网页

Agents → New Agent，类型选 WebsiteAgent，名称填「Example Domain 监控」，Options 填入（v2026.10.14 实测语法）：

{
  "url": "https://example.com/",
  "mode": "on_change",
  "extract": {
    "title": { "css": "title", "value": "string(.)" },
    "description": { "css": "p", "value": "string(.)" }
  },
  "expected_update_period_in_days": "5"
}

字段含义：

url：抓取目标；
mode: on_change：内容有变化才产出新事件（变化检测模式）；
extract：提取规则，键名（title/description）即事件字段名，css 指定选择器，value 是 XPath 取值表达式；
expected_update_period_in_days：超期告警阈值——若设定天数内没产出过事件，Dashboard 标黄提示。

⚠️ 实测排障：v2026.10.14 对 extract 里的 JSONPath/XPath 校验升级为 RFC 9535 规范（Janeway 引擎）。老教程里 $. 这种「以点结尾」的裸根路径在部分字段会报 error prohibited this Agent from being saved。WebhookAgent 的 payload_path 本版本实测要求字符串（如 "$"），老版的 Hash 映射写法已不通过校验——创建报错时先检查这两点。

Schedule 选 every_1h（每小时检查一次），保持接收者为空，保存。

手动触发验证：进入 Agent 详情页点右上角 Run，随后 Events 标签页出现：

{
  "title": "Example Domain",
  "description": "This domain is for use in illustrative examples in documents..."
}

4.2 触发器：TriggerAgent 条件过滤

新建 TriggerAgent，名称「变更告警判断」，Options（v2026.10.14 实测语法，path 用 RFC 9535 JSONPath）：

{
  "expected_receive_period_in_days": "2",
  "rules": [
    {
      "path": "$.title",
      "type": "regex",
      "value": "Example"
    }
  ],
  "keep_event": "true"
}

rules：匹配条件数组，path 指向事件字段的 JSONPath，type 支持 regex（正则）、field=>value（全等）等比较器，value 是期望值；
keep_event: true：转发时保留原始事件体（下游可引用全部字段）。

（实例种子里的 Rain Notifier 就是这个形态："path": "$.title", "type": "regex", "value": "Example"——可用作对照。）

保存后在 Receivers 里勾选 4.3 的 EmailAgent，让事件自动流向下游。

4.3 动作：EmailAgent 发送告警

新建 EmailAgent，名称「告警邮件」，Options：

{
  "subject": "【Huginn】网页变更告警",
  "body": "网页 {{title}} 发生变更：{{description}}",
  "recipients": "watcher@local.test",
  "expected_receive_period_in_days": "2"
}

recipients 指定收件人（实测种子 Afternoon Digest 即用 "recipients": "watcher@local.test" 形态）；留空时默认发给当前用户注册邮箱。{{title}}、{{description}} 是 Liquid 模板插值，引用事件字段。

4.4 SMTP 配置与实测发送

EmailAgent 依赖实例级 SMTP 配置（源码部署在 .env）：

SMTP_DOMAIN=local.test
SMTP_SERVER=127.0.0.1
SMTP_PORT=2525
SMTP_ENABLE_STARTTLS_AUTO=false
SMTP_AUTHENTICATION=none
EMAIL_FROM_ADDRESS=huginn@local.test

本文实测在本机起了一个本地 SMTP 接收器（aiosmtpd，监听 2525 落盘 .eml）做全链路验证。向 EmailAgent 注入一条事件后的完整实测结果：

事件写入 WebsiteAgent（agent 8）；
TriggerAgent（agent 9）按 title 正则匹配成功并转发；
EmailAgent（agent 10）把事件渲染成任务投递到 delayed_jobs 队列；
Worker 消费任务，SMTP 会话完成，落盘实测邮件（头部解码后）：

From: huginn@local.test
To: watcher@local.test
Subject: Huginn 监控告警：Example 页面更新
Content-Type: multipart/alternative;

Subject 与收件人均来自 Agent Options 的实际配置（agent 10 的 Options："subject":"Huginn 监控告警：Example 页面更新"、"recipients":"watcher@local.test"），正文按 body 模板渲染事件字段——事件字段插值链路验证正确。

⚠️ 实测排障：邮件任务失败会在 Dashboard 顶部出红色提示，典型错误 Connection refused - connect(2) for "127.0.0.1" port 2525——SMTP 地址/端口不可达。改 .env 后需重启 Web 与 Worker 服务生效；堆积的失败任务会在重试队列里继续尝试（FAILED_JOBS_TO_KEEP 只限制数据库里保留多少条失败记录），不必手工清理。

五、实战二：WebhookAgent 接收外部告警

外部系统（Zabbix 脚本、Nginx 日志脚本等）POST 上来的数据走 WebhookAgent 接入。

5.1 创建 WebhookAgent

Agents → New Agent，类型 WebhookAgent，名称「Webhook 接收器」，Options：

{
  "secret": "demo-secret-123",
  "payload_path": "$",
  "no_merge": false
}

secret：URL 里的鉴权段，自定义任意字符串；
payload_path：从请求体提取哪部分作为事件载荷，"$" 表示整个 JSON 体（v2026 要求字符串，见 4.1 排障注）。

Schedule 保持 never（事件由 HTTP 请求驱动，无需定时器）。

5.2 接收端点与实测 POST

端点格式（实测确认）：

POST /users/<用户ID>/web_requests/<AgentID>/<secret>

本实例用户 ID=1、Agent ID=11，实测：

root@huginn-server:~# curl -s -X POST "http://192.168.1.62:13000/users/1/web_requests/11/demo-secret-123" -H "Content-Type: application/json" -d '{"alert":{"level":"warning","title":"磁盘告警","value":"82%"}}' -w "\nhttp:%{http_code}\n"
http:201

返回 201 即事件已入库。Agent 详情页 Events 里确认载荷：

{"alert":{"level":"warning","title":"磁盘告警","value":"82%"}}

下游可以接 TriggerAgent（按 alert.level == "warning" 过滤）→ EmailAgent/SlackAgent 做告警分发。

⚠️ 实测排障：secret 错误或 URL 拼错返回 404；请求体不是合法 JSON 返回 422。另外该端点不带 CSRF 校验（设计为服务器到服务器调用），但生产环境建议：把 secret 当作 API 密钥管理，或前置反代再加一层鉴权。

六、Scenario 编排管理

6.1 创建 Scenario

Scenarios → New Scenario，实测表单字段：

字段	实测值	说明
Name	运维告警演示	显示名
Description	Webhook 接入 → Trigger 过滤 → Email 通知的演示编排	长描述
Icon	fa-bell	Font Awesome 图标类名
Tag 颜色	前景 #ffffff / 背景 #5cb85c	Agent 列表里的彩色小标签

保存后进入 Scenario 详情页，Agents → Add Existing Agents 或在编辑各 Agent 时勾选所属 Scenario，即可把 5.1 的 WebhookAgent、4.2 的 TriggerAgent、4.3 的 EmailAgent 组进同一编排。实测关联后 Scenario 成员数正确累加，列表页出现绿色 运维告警演示 标签。

6.2 Scenario 的导出与复用

详情页右上角 Export 生成一个 JSON（包含全部 Agent 配置与连线，secret 等敏感值可选拼接）；目标实例 Scenarios → Import 即可复刻整套编排。这是把一套「网页监控告警」模板批量铺到多台 Huginn 实例的标准做法。

七、排查与观察

事件没产生：Agent 详情页看 Last checked in 时间与 Logs 标签页；WebsiteAgent 常见原因是目标站反爬（Logs 里 HTTP 状态码一目了然）；
事件没传播：检查上游 Agent 的 Receivers 是否勾选了下游；TriggerAgent 的 expected_receive_period_in_days 只是超期提示，不影响转发；
Worker 假死：Dashboard 顶部出现 The Agent job scheduler is not running 横幅说明后台任务线程停了，源码部署用 systemctl status huginn-worker 检查，Compose 部署看 docker compose logs threaded；
事件堆积：导航栏 Job Management（/jobs 页面）看队列积压与失败重试明细，详见《Huginn 2026.10.14 进阶实战与运维》。

Huginn 2026.10.14 快速入门与 Agent 编排示例

Huginn 2026.10.14 快速入门与 Agent 编排示例

一、环境信息

二、核心概念

2.1 Agent：最小自动化单元

2.2 Event 与事件流

2.3 Scenario：编排打包

三、首次登录

四、实战一：网页变更监控 → 邮件告警

4.1 源 Agent：WebsiteAgent 监控网页

4.2 触发器：TriggerAgent 条件过滤

4.3 动作：EmailAgent 发送告警

4.4 SMTP 配置与实测发送

五、实战二：WebhookAgent 接收外部告警

5.1 创建 WebhookAgent

5.2 接收端点与实测 POST

六、Scenario 编排管理

6.1 创建 Scenario

6.2 Scenario 的导出与复用

七、排查与观察

八、参考链接