Hatchet CLI 开发模式启动 Worker 完整指南hatchet worker dev与hatchet.yaml实战解析【免费下载链接】hatchet An orchestration engine for background tasks, AI agents, and durable workflows项目地址: https://gitcode.com/GitHub_Trending/ha/hatchet本文基于仓库中的官方 Agent 技能文档 start-worker.md 展开并结合 Hatchet CLI 的实际源码实现worker.go、pm.go、filewatcher.go 等进行深度补充。你将掌握如何通过hatchet.yaml声明式配置 Worker 的开发运行方式如何用hatchet worker dev启动一个带热重载能力的 Worker以及这套机制在底层是如何用进程管理 文件监听实现的。导读在 Hatchet 中Worker 是真正执行任务Task的进程。日常开发调试时最关心的问题是如何快速把本地代码跑成一个可被调度器调度的 Worker并在改代码后免去手动重启。本文讲解的hatchet worker dev开发模式正是为此设计它通过项目根目录下的hatchet.yaml声明 Worker 的启动命令、监听文件与热重载行为让改代码 → 自动重启 → 立刻验证成为一条顺畅的开发流水线。读完本文你将能够独立完成 Worker 开发环境的搭建、配置与故障排查并理解命令背后进程管理器与文件监听器的完整实现链路。前提条件Profile 或嵌入式模式文档明确假设你已有一个指向 Hatchet 部署的 Profile。Profile 是 CLI 连接 Hatchet 实例Hatchet Cloud 或自托管的凭证载体一个 Profile 对应一个 API Token。相关的安装与配置流程见 setup-cli.md# 检查是否已安装 hatchet --version # 创建 ProfileHATCHET_PROFILE 为自定义名称如 local/staging/production hatchet profile add --name HATCHET_PROFILE --token API_TOKEN # 可选设为默认 Profile后续命令可省略 -p hatchet profile set-default --name HATCHET_PROFILE关键决策点在于连接模式本地开发默认推荐使用嵌入式模式embedded mode。它直接在 Worker 进程内启动一个完整的 Hatchet 引擎并内置 Postgres不需要 API Token、账号、Docker 或独立服务器。具体见 local-dev-embedded.md。连接 Hatchet Cloud 或自托管实例必须使用上述基于 API Token 的 Profile。这也解释了为什么hatchet worker dev默认会要求指定 Profile——它面向的是连接已有部署的场景纯本地零依赖开发则走嵌入式模式。创建hatchet.yamldev 配置详解启动开发模式 Worker 前项目根目录必须存在hatchet.yaml。如果不存在按以下结构创建dev: runCmd: python src/worker.py files: - **/*.py reload: truedev区块由四个配置项组成它们与源码中的结构体一一对应见 config.go配置项类型说明源码字段runCmdstring启动 Worker 子进程的完整命令WorkerDevConfig.RunCmdfiles[]string用于文件监听与热重载的 glob 模式列表WorkerDevConfig.Filesreloadbool是否在监听文件变化时自动重启 WorkerWorkerDevConfig.ReloadpreCmds[]string在 Worker 启动前执行的准备命令WorkerDevConfig.PreCmdsrunCmd需要按项目语言与入口调整Pythonpoetry run python src/worker.py或python src/worker.pyTypeScript/Nodenpx ts-node src/worker.ts或npm run devGogo run ./cmd/workerfiles中的 glob 模式决定了哪些文件被纳入监听范围reload: true则开启监听文件变化 → 自动重启 Worker的能力。可选preCmds 前置命令如果 Worker 启动前需要安装依赖或执行其他准备动作可以添加preCmdsdev: preCmds: - poetry install - npm install runCmd: poetry run python src/worker.py files: - **/*.py reload: true按文档描述这些命令会在每次 Worker 启动时包括热重载执行。从源码实现看详见下文热重载机制深入一节preCmds在RunWorkerDev启动阶段被逐一执行而热重载路径只重启runCmd子进程——因此实际行为以首次启动时执行一次、重载时是否重复执行取决于版本实现为准建议将幂等的安装类命令放入其中。补充triggers顶层配置除了dev区块hatchet.yaml的顶层还支持triggers配置源码中对应WorkerConfig.Triggers用于声明可触发的命令每个触发器包含command、可选name与description。日常开发调试通常只需关注dev区块。配置加载机制从 YAML 到结构体配置的解析位于 config.go 的LoadWorkerConfigCLI 以当前工作目录下的hatchet.yaml为唯一配置源用 Viper 读取并反序列化到WorkerConfig。也就是说必须在项目根目录即hatchet.yaml所在目录执行hatchet worker dev否则命令会因找不到配置而直接退出。若文件不存在LoadWorkerConfig返回 nilCLI 会渲染workerConfigMissingView提示信息引导用户用hatchet quickstart生成项目或手工创建配置文件。启动开发模式 Workerhatchet worker dev在后台终端Worker 是必须持续存活的长驻进程中执行hatchet worker dev -p HATCHET_PROFILE命令会用指定 Profile 连接 Hatchet然后按hatchet.yaml的dev配置启动 Worker 并开始监听任务。完整命令与 Flagsdev子命令挂在worker命令族下hatchet worker dev相关 Flags 定义于 worker.goFlag简写默认值说明--profile-p默认/唯一 Profile否则交互式选择指定连接 Hatchet 用的 Profile--no-reload-false关闭文件变化自动重启--run-cmd-r取自hatchet.yaml覆盖runCmd无需改配置文件典型用法# 使用默认或唯一 Profile 启动 hatchet worker dev # 指定 Profile hatchet worker dev --profile local # 指定 Profile 并关闭自动重载 hatchet worker dev --profile production --no-reload # 用命令行参数覆盖运行命令 hatchet worker dev --run-cmd npm run dev注意 Flags 的优先级--no-reload与--run-cmd会在加载配置后覆盖hatchet.yaml中的对应值方便临时调整而无需编辑文件。无 Profile 时的交互式引导如果既没传-p也没有可用的默认 ProfileCLI 会弹出交互式表单handleNoProfiles见 worker.go提供三个选项Start a local Hatchet server (requires Docker)启动本地服务器并自动创建 ProfileConnect to an existing Hatchet instance with an API token输入 Token 创建远程 ProfileCancel取消。选定后 Worker 会立即以该 Profile 启动。整个worker命令族还包含hatchet worker list与hatchet worker get worker-id分别以 TUI 或-o json形式查看 Worker 列表与详情便于开发时确认 Worker 是否已注册。源码级原理从命令到子进程hatchet worker dev的执行链路由三条关键路径构成理解它们能帮你更好地使用这个命令。第一步startWorker解析 ProfilestartWorkerworker.go负责优先使用-p指定的 Profile → 否则进入 Profile 选择/创建流程 → 从cli.Profiles.GetProfile取出 Profile 对象 → 创建可被 CtrlC 中断的 Context → 打印启动信息workerStartingView会展示所用 Profile 与 Auto-reload 状态→ 调用RunWorkerDev。第二步RunWorkerDev编排 preCmds 与进程RunWorkerDevworker.go按顺序执行依次执行devConfig.PreCmds每条命令打印 Running pre-command: ... 后通过pm.Exec同步执行失败即中止用pm.NewProcessManager(devConfig.RunCmd, profile)创建进程管理器若reload: true调用pm.WatchFiles(ctx, devConfig.Files, proc)进入监听 重启循环否则直接proc.StartProcess(ctx)常驻运行等待ctx.Done()后proc.KillProcess()收尾。第三步ProcessManager管理子进程生命周期ProcessManagerpm.go是核心的进程抽象负责启动、停止与重启子进程命令解析StartProcess用shellquote.Split把runCmd拆成 argv避免引号与空格带来的解析问题再通过exec.Command启动环境注入prepareEnviron会把 Profile 的 Token 以HATCHET_CLIENT_TOKENtoken注入子进程环境当 Profile 的TLSStrategy不是默认的tls时还会追加HATCHET_CLIENT_TLS_STRATEGYstrategy。这正是Worker 用 Profile 连接 Hatchet的机制核心——凭证通过环境变量透传给你的 Worker 代码输出透传子进程的 stdout/stderr 直接连接到 CLI 终端因此 Worker 的日志会原样显示非阻塞等待启动后不阻塞由独立 goroutine 等待退出并汇报错误。热重载机制深入reload: true的热重载不是简单的轮询文件修改时间而是一套完整的文件监听实现位于 filewatcher.go构建监听器使用fsnotify创建底层文件系统事件监听编译 glob 模式把files中的模式交给patternmatcher编译该实现源自 moby 的 patternmatcher见 patternmatcher.go。它支持标准的文件通配语法并额外支持以!开头的排除模式例如files: [**/*.go, !**/vendor/**]为精细控制监听范围留出空间递归注册监听从当前工作目录递归遍历整棵目录树凡是命中模式或父目录命中的目录与文件都被加入 watcher因此新建文件/目录也能被感知无需重启事件驱动重载收到Write事件且文件匹配模式 → 触发重载收到Create事件 → 新文件/新目录匹配时注册监听文件则同时触发重载。重载信号通过容量为 1 的缓冲 channel 传递非阻塞写入天然去抖收到信号后打印 Reloading worker... 并调用pm.StartProcess重启runCmd子进程启动即重载循环WatchFiles会先执行一次StartProcess启动 Worker随后持续监听直到 Context 取消。启动时会打印Watching pattern: ...、Watching file: ...与Watching N file(s) and directories等日志方便你确认监听范围是否符合预期。进程的优雅停止重启或退出时的进程清理由 process_unix.go 完成子进程以独立进程组启动Setpgid: true停止时先对整个进程组发送SIGTERM优雅退出等待 3 秒仍无响应则升级为SIGKILL强制终止确保 Worker 及其所有子进程比如 Python 的解释器及其派生的协程进程都被干净回收不会留下僵尸进程占用端口或任务槽位。注意事项与最佳实践Worker 必须先于任务触发运行Worker 必须在触发工作流之前处于运行状态。如果工作流被触发时没有任何 Worker 在跑任务会无限期停留在QUEUED状态。开发时若发现任务迟迟不执行第一反应应是检查后台终端里的 Worker 是否还活着。热重载的正确打开方式开启reload: true后编辑任何被监听的文件例如一个 Task 函数都会触发 Worker 自动重启改完代码立刻生效无需手动重启需要临时关闭自动重载加--no-reload需要临时换启动命令用--run-cmd your command here覆盖两个 Flag 都不会改动hatchet.yaml文件本身。排错清单Worker 启动失败时按以下顺序排查Profile 是否存在且指向正确hatchet profile list查看缺失时参考 setup-cli.md 用hatchet profile add创建Hatchet 服务器是否可达可用hatchet runs list -o json -p HATCHET_PROFILE --since 1h --limit 1验证连通性返回 JSON 即连接正常空 rows 也 OK是否在正确的目录执行hatchet.yaml必须位于当前工作目录runCmd是否正确命令解析失败、可执行文件不存在都会在启动阶段报错可用--run-cmd快速试错。快速生成项目骨架如果连hatchet.yaml都不想手写hatchet quickstartquickstart.go可以根据语言python/typescript/go、包管理器Python 的 poetry/uv/pipTypeScript 的 npm/pnpm/yarn/bun与用例模板如scheduled直接生成一个带完整hatchet.yaml与示例 Worker 代码的工程是上手开发模式最快捷的路径。本地开发的替代方案嵌入式模式最后要再次强调hatchet worker dev -p profile面向连接已有部署的场景。如果你只是在本机做纯开发local-dev-embedded.md 推荐的嵌入式模式通常体验更佳——它不需要 Token、Profile 或独立服务器直接在进程内启动完整引擎Pythonhatchet Hatchet.from_embedded()TypeScriptHatchetEmbeddedClient.init()Gohatchet.NewClient(hatchet.WithEmbedded())需 blank importhatchet-embedded模块嵌入式模式首次运行会下载引擎与内置 Postgres数十 MB可能耗时数分钟之后的运行从缓存秒级启动。两种模式配合使用可以覆盖从零依赖本地联调到连真实环境的全部开发场景而hatchet.yamlhatchet worker dev的这套配置与进程管理能力则是你在这两种模式下都绕不开的坚实基础。【免费下载链接】hatchet An orchestration engine for background tasks, AI agents, and durable workflows项目地址: https://gitcode.com/GitHub_Trending/ha/hatchet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考