Flocks 文档

外观

邮件网关配置 ​

本文介绍如何为 Flocks 配置邮件网关，让 Rex 或指定 Agent 可以通过邮箱接收问题、回复邮件，并把任务中心或 Workflow 的结果发送到指定邮箱。

适用场景 ​

  • 希望让用户直接通过邮件向 Flocks 提问，不依赖 IM 客户端或机器人平台。
  • 希望把定时巡检、告警研判、日报或处置建议发送到值班邮箱、工单邮箱或团队邮件列表。
  • 企业环境已经有可用的 SMTP / IMAP 邮箱服务，且不方便开放公网 Webhook。
  • 需要保留邮件线程，便于在邮件客户端、工单系统或归档系统中追踪上下文。

前置准备 ​

  • 准备一个专用邮箱作为 Flocks 邮件网关账号，不建议使用个人常用邮箱。
  • 确认邮箱已开启 IMAP 收信能力和 SMTP 发信能力。
  • 获取邮箱账号、应用专用密码或授权码。启用双因素认证的邮箱通常不能直接使用登录密码。
  • 确认 Flocks 所在服务器可以访问邮箱服务商的 IMAP / SMTP 主机和端口。
  • 生产环境建议提前整理允许发信人名单，避免任何知道邮箱地址的人都能触发 Agent。

常见端口如下，具体以邮箱服务商文档或企业邮件管理员提供的信息为准：

协议常见端口加密方式用途
IMAP993SSL / TLS接收新邮件
SMTP587STARTTLS发送回复邮件
SMTP465SSL / TLS部分邮箱服务商使用的 SMTPS 发信端口

操作步骤 ​

1. 准备专用邮箱 ​

建议使用一个职责清晰的邮箱，例如：

text
flocks-assistant@example.com
soc-rex@example.com

专用邮箱的好处是：

  • 邮箱内只保存与 Flocks 交互相关的邮件，便于审计和排障。
  • 可以单独设置应用专用密码、转发规则、保留周期和访问权限。
  • 账号泄露或需要轮换时，不会影响个人邮箱或其他业务邮箱。

2. 开启 IMAP / SMTP 并生成应用密码 ​

不同邮箱服务商的入口不同，常见做法如下：

  • Gmail：开启两步验证后，在 Google Account 的 App Passwords 中生成应用密码；同时确认 Gmail 设置中已启用 IMAP。
  • Outlook / Microsoft 365：确认组织允许 IMAP / SMTP AUTH；启用多因素认证后使用应用密码，或按企业策略申请 SMTP AUTH。
  • 企业邮箱：联系邮件管理员确认 IMAP 主机、SMTP 主机、端口、加密方式和是否需要授权码。

不要把个人登录密码直接填入 Flocks。优先使用应用专用密码、授权码或企业分配的最小权限凭据。

3. 在 Flocks 中填写邮件网关配置 ​

进入 Flocks WebUI 的「通道配置 → 邮件网关」或「Email」页面，填写基础连接信息。

配置项说明
邮箱地址Flocks 用于收发邮件的完整邮箱地址，例如 flocks-assistant@example.com。
邮箱密码 / 授权码邮箱服务商生成的应用专用密码或授权码。
IMAP 主机收信服务器地址，例如 imap.gmail.com、outlook.office365.com 或企业邮箱 IMAP 地址。
IMAP 端口通常为 993。
IMAP 加密方式通常选择 SSL / TLS。
SMTP 主机发信服务器地址，例如 smtp.gmail.com、smtp.office365.com 或企业邮箱 SMTP 地址。
SMTP 端口通常为 587，部分服务商使用 465。
SMTP 加密方式587 常用 STARTTLS，465 常用 SSL / TLS。
默认 Agent新邮件默认交给哪个 Agent 处理。
轮询间隔Flocks 检查新邮件的间隔。默认可保持 15 秒左右；企业邮箱限流严格时可适当调大。
允许的发件人只处理名单内发件人的邮件。生产环境建议必填。
默认收件人任务中心或 Workflow 未明确指定目标时，默认发送到哪个邮箱或邮件组。

保存配置前，建议先使用邮件客户端或 openssl s_client / telnet 等方式确认服务器网络可达，避免把账号问题和网络问题混在一起排查。

4. 启用并验证通道 ​

  1. 点击 启用，然后点击 保存。
  2. 等待邮件网关状态变为运行中。
  3. 使用允许名单内的邮箱给 Flocks 专用邮箱发送一封测试邮件。
  4. 邮件主题可写成 测试 Flocks 邮件网关，正文写入一个简单问题，例如：
text
请回复当前邮件网关是否已连通。

如果 Flocks 能在同一邮件线程中回复，说明 IMAP 收信、Agent 处理和 SMTP 发信链路都已打通。

收信与回复机制 ​

邮件网关通常按轮询方式读取收件箱中的新邮件，不需要公网回调地址。处理流程如下：

  1. Flocks 定期连接 IMAP 收件箱，查找未读或未处理的新邮件。
  2. 对命中允许名单的邮件，提取发件人、主题、正文和必要上下文。
  3. Rex 或配置的默认 Agent 处理邮件正文。
  4. Flocks 通过 SMTP 回复原发件人，并尽量保持原邮件线程。

邮件主题会作为上下文参与处理。回复邮件会保留 Re: 主题和邮件线程头，方便用户在邮箱客户端中连续追踪同一问题。

附件处理 ​

如果邮件网关支持附件处理，建议按下面策略使用：

  • 图片、PDF、压缩包、日志等附件会下载到 Flocks 工作区或通道缓存目录，供 Agent 读取或分析。
  • 对不可信来源，应关闭附件处理，或只允许白名单发件人的附件进入 Flocks。
  • 不要让邮件网关自动处理可执行文件、宏文档或未知格式附件。
  • 大附件可能触发邮箱服务商大小限制，也会增加 Agent 处理成本，建议通过 Workspace 或对象存储传递大型文件。

生产环境如需完全忽略入站附件，可在邮件网关高级设置中关闭附件处理；具体字段以当前版本 WebUI 为准。

访问控制与安全建议 ​

邮件地址天然容易被转发或猜测，因此邮件网关必须做访问控制。

  • 生产环境务必配置 允许的发件人，只允许可信邮箱、邮箱组或工单系统地址触发 Flocks。
  • 尽量使用专用邮箱和应用专用密码，不要使用个人邮箱或主登录密码。
  • 定期轮换邮箱应用密码，离职、项目结束或怀疑泄露时立即吊销旧密码。
  • 对邮件网关账号启用登录保护、异常登录提醒和最小权限策略。
  • 不要把邮箱密码、授权码或 .env / 配置导出文件提交到 Git。
  • 如果 Flocks 具备命令执行、设备操作或工单变更能力，邮件触发入口应结合 Agent 工具白名单和权限审批使用。

如果确实需要允许所有发件人访问，建议只绑定只读分析类 Agent，并关闭高风险工具。

结果推送与 session ID ​

如需在 Flocks 页面、任务中心或 Workflow 中主动向邮箱发送结果，可以使用邮件地址或先建立邮件会话绑定。

常见写法：

text
把本次巡检摘要发送到 soc@example.com。

如果当前版本支持邮件会话绑定，也可以在目标邮件线程中询问 Rex：

text
你的 sessionid 是什么？

拿到 session ID 后，可以在任务描述或 Workflow 中固定投递目标：

text
给 sessionid：<sessionID>，发送：今日巡检完成，发现 2 条高危告警。

邮件线程发生变化、用户重新发起新主题或会话被重置后，建议重新确认目标 session ID。

常见问题 ​

IMAP 连接失败 ​

优先检查：

  • IMAP 主机和端口是否正确。
  • 邮箱账号是否开启 IMAP。
  • Flocks 服务器是否可以访问 IMAP 主机。
  • 企业邮箱是否限制来源 IP 或要求 VPN / 内网访问。
  • 加密方式是否与端口匹配，例如 993 通常使用 SSL / TLS。

SMTP 发信失败 ​

优先检查：

  • SMTP 主机、端口和加密方式是否正确。
  • 是否使用了应用专用密码或授权码，而不是普通登录密码。
  • 邮箱服务商是否限制 SMTP AUTH、发信频率或来源 IP。
  • 发件人地址是否必须与登录账号一致。

收不到邮件或没有回复 ​

优先检查：

  • 发件人是否在允许名单中。
  • 测试邮件是否进入垃圾邮件、隔离区或其他文件夹。
  • 邮件网关是否只处理收件箱中的新邮件。
  • 是否有多个 Flocks 实例同时连接同一个邮箱，导致邮件被其中一个实例提前标记为已处理。

邮件回复没有串在同一线程 ​

不同邮箱客户端对线程展示规则不完全一致。优先确认原邮件的 Message-ID、In-Reply-To、References 等线程头没有被中间系统删除；同时避免在自动回复中反复改写主题。

响应速度较慢 ​

邮件网关通常通过轮询收件箱工作。可以适当缩短轮询间隔，但过低的间隔会增加 IMAP 连接频率，可能触发企业邮箱限流。生产环境建议在响应速度和邮箱服务商限制之间取平衡。

相关：通道配置总览 · 钉钉通道配置 · 飞书通道配置 · 企业微信通道配置 · Slack 通道配置 · Telegram 通道配置 · 微信通道配置 · WhatsApp 通道配置

基于 VitePress 构建

Copyright © Flocks