1. 从脚本烟囱到统一代理hermes-agent解决的真实痛点先说个场景做运维和后台开发的朋友应该都懂。我手头曾经管着七八个业务系统的自动化任务每个系统都有一套自己的脚本数据库备份用Shell写报表生成用Python写接口健康检查用Go写了个小工具还有一堆散落在各台机器上的crontab。这套东西在业务量小的时候勉强能转但真正压垮人的不是任务多而是任务之间的协作和失败兜底。有一次凌晨两点短信平台一条告警都没发我差点以为是业务挂了最后排查发现是生成告警数据的脚本在跑批时被一个上游接口超时卡住了后续依赖它的十几个下游任务全部排队等死没有重试机制也没有超时熔断所有失败全靠第二天早上人工发现。从那之后我下了决心把乱七八糟的脚本收口到一个统一的代理系统里这就是hermes-agent最初的雏形。1.1 我当时的混乱现场先还原一下典型的脚本烟囱长什么样同一个数据源被三个脚本各自采集了一遍全量扫描了一天数据库承压严重任务A给任务B产生的数据文件靠文件名加时间戳约定经常出现B跑的时候A还没写完一查全是空数据定时任务的时间全部写死在crontab里改一个任务的上游依赖要通知所有相关人改自己机器上的配置没有统一的日志中心脚本的print输出散落在各种nohup文件里排查问题靠 grep 加运气每次版本发布之后手工跑数据校验的要单独找人盯着这些问题的本质不是某一个脚本写得不好而是没有一个统一的任务编排和调度中枢导致任务之间只能用约定而不是规则来协作。跟几个朋友聊下来发现这不是我一个人的问题中小团队到了一定规模几乎都会撞上这堵墙。大厂的调度系统倒是很强但对我们这种几个人的小组来说太重了光部署和定制就得花掉两周。hermes-agent的想法就是做一套轻量的、能跑在少量服务器上的代理调度框架把脚本收口、任务编排、失败重试、告警通知这几件事一次性解决。1.2 hermes-agent给自己的定位在设计hermes-agent时我给自己定了几条规矩这也是它和其他调度平台最大的区别第一它不是一个大数据调度平台不追求可视化编排的炫酷界面所有编排通过YAML配置和少量Python代码描述配置即代码能进Git做版本管理。第二它不是一个低代码平台没有复杂的web界面拖拽目标是让懂代码的人用最少的门槛把事情做漂亮而不是让不懂代码的人点鼠标。第三它是一个代理层位于任务实际执行者的上游。插件负责干活agent负责调度、路由、重试、通知职责分离得非常清楚。运行一段时间后我有个直观感受这个架构最大的价值不在于自动化本身而在于把所有的执行过程都变成了可观测、可回放、可恢复的事件流。以前脚本挂了只能看日志猜现在每一次任务执行的状态、输出、耗时、重试记录全部落表出问题先看任务表就能定位到一半。1.3 哪些人适合用哪些人不适合用下来我觉得几类人比较适合直接上手hermes-agent后端开发兼运维的小团队任务数量在几十到几百这个量级需要统一调度但不想上重平台数据分析团队有大量的SQL跑批、报表生成、数据校验类任务需要上下游依赖和失败通知自动化测试团队想把接口测试、回归测试、环境健康检查做成定时流水线不太适合的场景我也要说清楚如果你的任务量级到了几千上万个需要细粒度权限管控、跨机房容灾、租户隔离那就别硬用hermes-agent去考虑成熟的商业调度系统或者自研分布式调度会更合适。任何工具都有边界知道边界在哪才能把它用好。2. 任务、插件、调度三层拆解理解agent的消息循环hermes-agent最核心的设计是三层模型任务Mission、插件Plugin、调度Scheduler。很多agent框架喜欢把智能放在一个统一的执行器里让一个Agent什么都能干但在我看来这个思路在小规模自动化场景下是反面模式因为什么都写在同一个执行器里责任边界就会模糊出了问题改一个功能影响的是一大片。我采用的方案是让hermes-agent做三层分工调度层负责什么时候该做什么任务层负责这件事要传什么参数、依赖什么前置条件插件层负责具体怎么落地执行这样分工之后开发一个新任务通常只需要写一个新插件配置一下YAML不需要去动agent框架本身。2.1 核心抽象任务体与状态流转整个agent的运转可以抽象成一个消息循环调度器触发一个任务生成一个任务体投递到dispatcherdispatcher根据路由规则找到对应的插件插件执行完成后把结果回传调度器根据结果决定是标记成功、触发重试还是走告警。任务体的数据结构大概是这样的dataclass class TaskInstance: task_id: str mission_id: str # 归属的mission plugin_type: str # 目标插件类型 priority: int # 优先级0-100数值越大越优先 payload: dict # 任务参数由YAML配置传入 max_retries: int 3 timeout: float 600 # 单次执行超时单位秒 created_at: float 0.0 state: TaskState TaskState.PENDING状态流转是agent的核心逻辑我设计了这样一条链路PENDING排队→ RUNNING执行中→ SUCCESS成功/ FAILED失败→ 失败时RETRYING重试中→ SUCCESS 或 DEAD_LETTER进入死信队列这套状态机的收益在排障时体现得很明显。以前脚本挂了只能凭印象判断跑到哪一步现在任何一个任务实例打开状态表当前卡在哪个环节、重试了几次、耗时多久一目了然。2.2 dispatcher的匹配逻辑路由表不是死规则dispatcher的作用是根据任务体里的plugin_type字段找到对应的插件实例。一开始我图省事直接用字典映射{shell: ShellPlugin, http: HttpPlugin, sql: SQLPlugin}。用了一段时间发现不够用因为同一个插件类型在不同业务场景下的行为差异很大比如「SQL查询」插件在报表任务里要带读超时在数据订正任务里要带写权限检查仅靠plugin_type区分不了。最后我加了一层路由规则链支持按mission_id、payload里的业务字段做二次匹配配置在插件路由表里plugin_routing: - match: plugin_type: sql payload.operation: report executor: SQLReportExecutor options: read_only: true query_timeout: 60 - match: plugin_type: sql payload.operation: fix executor: SQLFixExecutor options: allow_write: true audit_log: true这个改动让dispatcher从死字典变成了可配置路由表业务扩展时不需要改agent框架代码只需要在配置里加一条路由规则。实际用下来这个设计是hermes-agent里最省心的一个点因为新接入一个业务方的时候不会动到核心链路。2.3 executor插件协议一个插件最小实现插件协议是整个框架里我要重点强调的。很多框架设计插件时容易把接口定义得特别复杂回调方法十几个写一个插件恨不得要看半小时文档。hermes-agent的插件接口我刻意做得很小核心就两个方法class BasePlugin: def validate(self, payload: dict) - None: 执行前校验参数不需要时直接pass raise NotImplementedError def execute(self, payload: dict) - PluginResult: 执行任务返回结果抛异常会被调度层捕获并按策略处理 raise NotImplementedError一个最小可用的Shell执行插件代码不到30行class ShellPlugin(BasePlugin): def __init__(self, workdir/tmp, default_shell/bin/bash): self.workdir workdir self.default_shell default_shell def validate(self, payload): if cmd not in payload: raise ValueError(payload缺少cmd字段) def execute(self, payload): import subprocess cmd payload[cmd] timeout payload.get(timeout, 300) proc subprocess.run( cmd, shellTrue, cwdself.workdir, executableself.default_shell, capture_outputTrue, textTrue, timeouttimeout ) if proc.returncode ! 0: raise ExecutionError(f命令执行失败: {proc.stderr[-500:]}) return PluginResult(successTrue, outputproc.stdout[-2000:])插件协议设计得小带来的直接好处是团队里新人上手成本极低。我统计过团队里一个之前完全没用过hermes-agent的同事从看文档到写出来第一个自定义插件大约只用了四十分钟这里面大部分时间还是花在理解他的业务逻辑上。3. 部署与初始化五个我必须写进文档的坑hermes-agent的部署本身不复杂核心服务只有一个Python进程装好依赖、配好YAML、启动即可。但在我自己部署和使用过程中确实踩过一些坑这些坑不看文档是真的会耗掉半天时间所以后来我全部写进了项目里的DEPLOY.md。3.1 依赖安装顺序从源码装还是用发行版包hermes-agent依赖几个基础库包括PyYAML、APScheduler、requests、pydantic。PyYAML建议用pip直接装但如果你用的是CentOS这类老系统系统自带的python3是3.6PyYAML最新版可能不支持需要先升级Python版本。我推荐用pyenv管理Python版本装到3.10然后用虚拟环境安装依赖。一条命令python3.10 -m venv .venv source .venv/bin/activate pip install -r requirements.txt这里有个细节requirements.txt里我建议把pydantic的版本固定下来因为pydantic v1和v2的API差异比较大如果不锁版本过半年一升级可能跑不起来。3.2 YAML配置的陷阱一个缩进引发的血案YAML配置里最容易出问题的不是缩进而是同一份配置里混合使用tab和空格、key有中文、特殊字符没有加引号。我遇到过最诡异的一件事任务配置里的某个通知地址含有一个字符没有加引号结果YAML解析时被解析成了锚点语法agent启动后这条通知规则完全没生效而启动日志里没有报错。排查了两个小时才定位到之后我给自己定了个规矩所有URL类的value一律手工加引号。# 错误的写法如果url里有符号可能导致解析异常 notify_url: https://example.com/webhook?a1b2 # 正确的写法 notify_url: https://example.com/webhook?a1b2另外强烈建议在CI里加一步YAML配置的schema校验hermes-agent支持通过--validate参数启动前检查配置这能挡掉一大半的低级错误。3.3 插件的权限隔离agent越权是最大的安全风险agent进程需要执行shell命令、访问数据库、调用外部API如果权限控制不好一旦agent被入侵等于拿到了服务器的执行权限。我的建议是生产环境一定不要用root跑agent单独建一个agent系统用户数据库连接账号按最小权限原则创建只授权任务实际需要的库和操作shell类的插件默认禁止执行rm -rf、mkfs等危险命令可以在plugin_security.yaml里配置命令黑名单。这个防线上确实费了些功夫但值得。之前我把一个测试环境的agent跑在root下某次插件写得有问题一条命令差点把系统文件删了从那以后所有环境的agent都强制跑了普通用户。3.4 时区与时间精度另一个容易被忽视的是时区配置。agent的调度基于cron表达式如果agent机器的时区是UTC而业务方默认用北京时间定时任务就会全部偏移8个小时。我在配置里加了timezone: Asia/Shanghai同时要求所有任务的时间字段统一使用ISO8601格式带时区偏移。这样无论调度器跑在哪台机器都能保证触发时间一致。3.5 系统资源限制agent同时跑的任务数量受两个因素限制一是CPU/内存二是系统的进程/文件描述符上限。尤其是用Shell插件跑并发任务时系统默认的ulimit -n 1024很容易不够用导致任务莫名失败日志里报的却是Too many open files这种让人摸不着头脑的错误。我在系统的systemd单元文件里加了[Service] LimitNOFILE65535 LimitNPROC10240这个限制调大之后并发执行任务时的稳定性明显提升。4. workflow编排实战串并行、重试与告警升级一个agent如果只会跑单个任务价值有限真正的价值在于把多个任务编排成一个工作流。hermes-agent的mission配置中可以用steps字段定义工作流支持串行、并行依赖和条件分支。4.1 一个真实的发布任务示例拿我最常用的数据报表发布流程举例它包含四个步骤从业务库抽取数据到数据仓库对抽取的数据做质量校验比如行数波动、空值率生成日报表并推送PDF到内部文档系统发送通知给业务群这个mission的配置长这样missions: - mission_id: daily_report name: 每日报表发布 schedule: 0 2 * * * steps: - id: extract plugin: sql params: operation: extract source: business_db target: dw_db on_failure: retry retries: 2 - id: validate plugin: data_quality params: ref_table: dw_db.report_base min_rows: 1000 max_rows_drop_rate: 0.3 depends_on: [extract] on_failure: stop - id: generate_pdf plugin: report params: template_id: daily_report_v3 output_path: /data/reports/daily depends_on: [validate] on_failure: stop - id: notify plugin: notify params: channel: wecom_group template: report_notify depends_on: [generate_pdf] on_failure: warn_only从配置里能看出来depends_on决定任务的依赖关系没有depends_on的步骤默认与前置步骤并行。比如你把extract替换成两个互不依赖的数据抽取它们就会并行跑。4.2 失败重试与退避策略别让重试变成二次事故重试机制是agent里面最容易写错的一部分。很多人图省事失败就立即重试结果在下游接口还没恢复的时候反复打同一个接口把故障扩大成一个雪崩。hermes-agent的重试策略支持指数退避加抖动配置是这样的retry_policy: max_retries: 3 base_delay: 5 # 首次重试前等待5秒 multiplier: 2 # 每次翻倍 max_delay: 60 # 上限60秒 jitter: 0.2 # 20%的随机抖动防止多个任务同时重试造成流量峰值这里的关键是jitter。如果没有抖动几十个失败任务同时进入重试退避时间相同恢复后请求会精确地同时打到服务上又是一次峰谷震荡。加了随机抖动虽然每个任务的重试时间看起来不那么整齐但对于保护下游系统来说非常重要。4.3 告警升级链路从群消息到电话任务失败如果不通知那自动化就没有意义。但是如果每次失败都轰炸所有人几天后大家就对告警脱敏了。我采用的是一条三级升级链路第一级任务第一次失败重试中往专门的运维群里发一条消息不任何人这类信息是给值班同事瞟一眼用的。第二级所有重试都失败任务进入DEAD_LETTER状态这时候会在群里当天的值班负责人并发送一条邮件到团队的当周oncall邮箱。第三级如果进入死信队列的任务优先级很高或者连续三个高优任务同时失败说明可能有系统性故障agent会直接拨打值班负责人的电话通过语音通知API。这套升级链路在实际值班中帮我们省了很多精力。低等级的任务失败后台悄悄重试不影响人真出大事了值班手机响起来第一时间就有人进场处理。告警的最终目的不是通知而是让人在正确的时间介入。5. 无人值守的底气可靠性设计里的细节用agent跑任务最怕的就是看起来全绿实际上静默失败。自动化系统一旦没有人类天天盯着就必须把可靠性设计摆在第一位。这一章聊聊我在hermes-agent里做的几个可靠性设计。5.1 任务表与幂等恢复调度器把任务分发出去之后如果agent进程崩了重启那些执行中的任务该怎么办如果直接重新执行可能产生重复数据如果不执行可能漏跑关键任务。我的解决方案是给所有任务实例落一张任务表状态按前面说的状态机流转。agent启动时扫描状态表中所有为RUNNING或PENDING的任务然后做一次恢复决策RUNNING状态且没有收到执行结果判断为执行状态丢失进入幂等检查逻辑PENDING状态重新投递到调度队列幂等检查是这里的核心。每个任务定义时要声明idempotent: true/false。幂等任务直接重新执行非幂等任务进入人工确认队列由值班负责人决定是跳过还是手工补齐。这个设计我在好几次宕机恢复中验证过确实能避免重复扣款或者重复发送这类严重事故。5.2 看门狗与自愈agent自己也是会挂的。如果agent挂了谁来调度任务我给hermes-agent加了一个独立的看门狗进程它与主进程不在同一个物理机上通过心跳接口监控主进程状态。如果连续两次心跳超时看门狗会尝试拉起主服务并切换备节点。备节点在部署时通过--standby参数启动会持续从任务表同步状态。这里有个注意点看门狗不能太勤快。如果只是网络抖动导致一次心跳丢失就立刻切换反而会在主备之间造成脑裂。我的策略是连续3次超过5秒心跳超时才触发切换并且切换前先尝试一次优雅stop给它10秒清理资源的机会。5.3 埋点与监控指标没有数据的调度系统是盲的可靠性不是靠感觉需要用数据说话。hermes-agent内置了一个metrics模块每个任务实例都会记录以下指标执行耗时分位数成功/失败/重试次数队列积压量调度延迟任务触发时间和实际执行时间之差各插件失败率这些指标通过Prometheus的格式暴露出来接入Grafana之后我能直接在仪表盘上看整个系统的健康状况。有段时间报表任务经常在凌晨3点到5点变慢但单独看每次执行都在超时阈值以内很难定位。后来看了执行耗时的P99曲线才发现原来这几个小时任务并发量最大锁表竞争严重。顺着这条线索优化了数据库索引P99从11秒降到了2.3秒。这种优化如果没有埋点数据支撑靠猜是根本猜不出来的。所以我真心建议任何agent框架的第一版就要把metrics做进去哪怕只是最基础的几个数字。6. 关于agent设计与落地几个我吃过亏之后才想明白的事写hermes-agent这几年我发现技术本身反而是最简单的事难的是想清楚边界、稳定性、演进节奏。这章算是我个人总结的几个吃亏之后才懂的点也许能帮后来者少走弯路。6.1 agent与脚本的边界不是所有任务都值得交给agent有段时间我陷入了万物皆agent的倾向连单机上的一个临时数据分析脚本都想塞进hermes-agent里任务表里躺了一堆只执行过一两次的僵尸任务每天还要花时间检查它们的失败重试。后来我把agent的适用场景收敛为三个条件至少满足两个才会接入任务需要被定时触发且依赖时间窗口任务需要和其他任务协作存在上下游关系任务失败需要通知人不能静默失败单次执行的、没人关心的、没有依赖关系的脚本老老实实留在一个目录里手动跑就行。把agent当成一种有边界的基础设施而不是万能收纳盒。6.2 插件接口稳定压倒一切插件协议一旦发布出去尽量不要做破坏性变更。我在0.3版本时为了优化,把execute方法的返回值从ProtocolBuffer对象换成了pydantic model结果二十多个存量插件全部要改。虽然版本升级脚本写了但测试回归花了两天半。后来我学乖了插件协议采用只增不改原则新功能通过新增可选参数或者新增接口实现老接口保持兼容哪怕内部实现已经重写了。6.3 给新人的落地建议如果你想在自己的团队里引入hermes-agent我建议按这个节奏推进第一周部署核心服务先把两个高频的定时任务接进来比如日志清理、健康检查跑通Agent的基础链路。第二周梳理现有脚本选出三个有依赖关系的任务改造成mission工作流。这一步的目的是验证编排能力而不是迁移所有任务。第三周把失败告警和值班通知接上让agent在没人盯的情况下也能被信任。一个月后评估效果如果稳定再逐步扩大任务范围。千万不要一开始就想做成一个大平台把几十个任务全部迁移过来再上线。分批迁移的好处是每批上线都能提前发现配置、权限、依赖上的问题。最后再分享一个我自己的体会工具永远是为了解决具体问题而存在的如果某天你发现hermes-agent在某个场景下很难用大概率不是工具的问题而是这个场景本来就不该由它来处理。想清楚这个问题比学会任何配置项都重要。