尧图网站建设 
Windmill Agent Worker 本地端到端调试指南从 Feature 编译到 dbt 任务验证【免费下载链接】windmillOpen-source developer platform to power your entire infra and turn scripts into webhooks, workflows and UIs. Fastest workflow engine (13x vs Airflow). Open-source alternative to Retool and Temporal.项目地址: https://gitcode.com/GitHub_Trending/wi/windmillAgent Worker 是 Windmill 中一类特殊的工作进程它不直接连接数据库而是仅通过 HTTP API 与服务器通信因此其整条代码路径Connection::Http不会在常规的cargo run中被触发必须用真实环境才能完整演练。本文基于 docs/agent-worker-e2e.md 整理出一套可复现的本地端到端e2e调试流程从正确的 feature 组合编译二进制到启动无本地 worker 的服务器、铸造 agent token、拉起 agent再到验证任务确由 agent 执行、以及 dbt 任务在 agent 上的运行行为。每个步骤都伴随典型的看起来像别的问题的失败模式与对应报错帮助读者在本地一次性打通 agent worker 全链路。1. 用正确的 Feature 组合编译Agent Worker 链路涉及四个 feature其中最容易被遗漏的是 agent 自身的模式门控mode gatecd backend cargo build --features quickjs,private,enterprise,license,agent_worker_server各 feature 的作用如下agent_worker_server在服务器侧挂载/api/agent_workers/*路由。缺少它时create_agent_token会返回404且响应体为空。在 backend/Cargo.toml 中可以看到该 feature 的传递关系agent_worker_server [windmill-api/agent_worker_server, dep:windmill-api-agent-workers, windmill-test-utils/agent_worker_server]而 backend/windmill-api/src/lib.rs 中对应路由均以#[cfg(feature agent_worker_server)]条件编译。enterpriselicense把 agent 模式MODEagent编译进二进制。缺少时 worker 会立即退出并打印Agent mode is only available in the EE——即使服务器侧工作正常、token 也铸造成功。该 panic 位于 backend/windmill-common/src/utils.rs其中#[cfg(not(feature enterprise))]分支直接panic!(Agent mode is only available in the EE, ignoring...)同时注意 agent 模式下BASE_INTERNAL_URL是必填的缺失同样会 panic同文件 L124-L126。quickjs、private前者提供脚本运行时后者启用windmill-api-agent-workers中的 EE 实现mod ee由#[cfg(feature private)]引入见 backend/windmill-api-agent-workers/src/lib.rs。在投入握手调试之前先验证二进制确实带上了 agent 模式——panic 字符串必须不存在strings target/debug/windmill | grep -c Agent mode is only available in the EE # want 0整个调试会话务必固定这一 feature 组合。target/debug/windmill是所有 feature 组合共享的同一路径cargo 会随组合变化在缓存中交换产物如果在另一个终端执行cargo build --features quickjs或其他不同组合的构建会在不到一秒内悄悄替换掉服务器和 agent 即将运行的二进制且换回过程同样极快看起来完全不像是发生过重新构建。典型症状是agent 原本工作正常却突然开始 401或 EE panic 再次出现。每当出现意外回退时重新执行上面的strings检查并确保服务器与 agent从同一次构建产物启动。2. 运行服务器不启动本地 worker以MODEserver启动确保没有其他进程会排空队列从而证明任务确实是 agent 执行的DATABASE_URLthis worktrees db PORT8420 MODEserver ./target/debug/windmillMODE的取值在 backend/windmill-common/src/utils.rs 中解析server、worker、agent、indexer、standalone、mcp等未识别值会打印告警并默认回退到standalone。这里显式用MODEserver可避免本机 worker 抢占队列。3. 铸造 Token——带过期时间且不加引号TOK$(curl -s -X POST localhost:8420/api/auth/login -H Content-Type: application/json \ -d {email:adminwindmill.dev,password:changeme}) AT$(curl -s -X POST localhost:8420/api/agent_workers/create_agent_token \ -H Authorization: Bearer $TOK -H Content-Type: application/json \ -d {worker_group:agentgrp,tags:[dbt],exp:1900000000} | tr -d )/api/agent_workers/create_agent_token在 backend/windmill-api/openapi.yaml 中有完整定义同路径下还有blacklist_token、list_blacklisted_tokens、get_min_version等管理端点。此处有两个陷阱二者都会在 agent 侧表现为裸401而解码后的真实原因只出现在服务器日志中exp必须是真实时间戳。传exp: null铸造出的 token 会被校验器以Missing required claim: exp拒绝。响应是 JSON所以 token 是带引号返回的。保留会得到Base64 error: Invalid byte 34, offset 0——因此需要tr -d 去掉引号。传给 agent 的 token 必须原样使用。它形如jwt_agent_jwt客户端会自行追加由主机名派生的后缀组成jwt_agent_suffix_jwt服务器正是按此格式切分的。若你自己额外添加后缀会得到Base64 error: Encoded text cannot have a 6-bit remainder。4. 启动 AgentWORKER_TAGS必须包含任务实际携带的 tag而不是你随意发明的 tag——没有 worker 服务的 tag 任务会永远留在v2_job_queue中看起来像卡死。dbt 脚本默认使用dbttag。AGENT_TOKEN$AT BASE_INTERNAL_URLhttp://localhost:8420 MODEagent \ WINDMILL_DIR/home/$USER/wmagent \ WORKER_GROUPagentgrp WORKER_TAGSdbt PORT8499 ./target/debug/windmillWINDMILL_DIR放在/tmp之外在开发机上很重要。放在/tmp时任务会在写入项目文件阶段报IoErr: Disk quota exceeded (os error 122)而df看起来一切正常——空闲空间和空闲 inode 都没问题。原因是/tmp是 tmpfsLinux 支持对其做按用户的配额限制所以超限的是用户配额而非文件系统容量多个 agent 会话的缓存积累在/tmp下就足以撞上该配额。正确做法是把 worker 指向真实磁盘而不是试图在配额内清理。确认 agent 已注册而不是轻信安静的日志SELECT worker FROM worker_ping WHERE worker_group agentgrp AND ping_at now() - interval 2 min; -- ag-agentgrp-host-rand读取失败信息Agent 侧永远只打印一句Agent worker cannot connect to server. Please check AGENT_TOKEN and BASE_INTERNAL_URL。真实原因在服务器日志中来自windmill-api-agent-workers的 EE 模块——grep 关键字JWT_AGENT auth error即可定位。注意该模块的 EE 实现文件由privatefeature 门控mod ee这也解释了为什么本地 e2e 必须在构建时带上private。确认任务确由 Agent 执行已完成任务的worker字段以ag-开头curl -s -H Authorization: Bearer $TOK \ localhost:8420/api/w/ws/jobs_u/completed/get/job | jq -r .worker服务器侧对 agent worker 的识别在数据库健康检查中也有体现backend/windmill-api/src/db_health.rs 注明live_agent_workers仅作上下文参考——agent worker 走 HTTP 而非 postgres 连接因此在统计活跃连接数时被排除。这也是理解 agent worker 架构差异的关键点它连 token 的 worker 名都是从 API 侧解析的非private编译时extract_worker_name返回None见 backend/windmill-api-agent-workers/src/lib.rs。完整的端到端测试还可以参考 backend/tests/agent_workers.rs该测试文件以#![cfg(all(feature private, feature agent_worker_server))]为前置条件覆盖了create_agent_token、build_agent_http_client与update_ping的完整握手流程是本文手动步骤的自动化版本。dbt 在 Agent Worker 上的行为dbt 任务在 agent worker 上会运行、重试并发布其 graph——包括为动态描述符生成的一次性快照per-run snapshot该快照通过 POST 到/api/agent_workers/dbt_graph/{workspace}发布而不是自己写库。它不会得到的是实时进度LIVE progressreporter 需要 tail JSON 事件日志并依赖 SQL 连接因此每个 model 的状态是在运行结束时从run_results.json落定的。重试状态只存在于 worker 本地的 generation 中——因为数据库里没有对应行可供仲裁——这正是state_dir要按 principal执行主体分键的原因。快照落库的持久化结构可以在迁移 backend/migrations/20260725084314_dbt_runtime.up.sql 中看到dbt_graph_snapshot表通过(workspace_id, script_hash)外键关联脚本并为(workspace_id, job_id)、(ingested_at)建立索引随后的迁移 backend/migrations/20260801121717_dbt_editor_preview_graph.down.sql 进一步补充了编辑器预览所需的permissioned_as等列。确认一次运行确实走过该发布路径SELECT job_id, count(*) FROM dbt_node WHERE script_path path GROUP BY job_id; -- 存在以 JOB id而非零 UUID为键的行说明 agent 发布了快照排错速查表症状报错/现象根因处理create_agent_token返回 404 空响应HTTP 404缺agent_worker_serverfeature重编译并固定 feature 组合worker 立即退出Agent mode is only available in the EE缺enterpriselicensefeature加上后重编译用strings验证 panic 字符串消失agent 401Missing required claim: exptoken 的exp为 null传真实时间戳agent 401Base64 error: Invalid byte 34, offset 0token 带引号tr -d 去掉引号agent 401Base64 error: Encoded text cannot have a 6-bit remainder手动给 token 追加后缀原样传递铸造出的 token任务看起来卡死永远留在v2_job_queueWORKER_TAGS与任务 tag 不匹配使用任务实际携带的 tagdbt 默认dbt任务写文件失败IoErr: Disk quota exceeded (os error 122)/tmptmpfs 的用户配额WINDMILL_DIR指向真实磁盘agent 无法连接仅显示Agent worker cannot connect to server...真实原因在服务器侧在服务器日志 grepJWT_AGENT auth error整套流程的要点可归纳为三条固定四 feature 编译组合并用strings验证、token 原样传递真实exp 去引号、以及任何异常先从服务器日志找根因。按照上述步骤操作即可在本地完整验证Connection::Http这条只在 agent worker 上才会触发的代码路径。【免费下载链接】windmillOpen-source developer platform to power your entire infra and turn scripts into webhooks, workflows and UIs. Fastest workflow engine (13x vs Airflow). Open-source alternative to Retool and Temporal.项目地址: https://gitcode.com/GitHub_Trending/wi/windmill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Windmill Agent Worker 本地端到端调试指南：从 Feature 编译到 dbt 任务验证
Windmill Agent Worker 本地端到端调试指南从 Feature 编译到 dbt 任务验证【免费下载链接】windmillOpen-source developer platform to power your entire infra and turn scripts into webhooks, workflows and UIs. Fastest workflow engine (13x vs Airflow). Open-source alternative to Retool and Temporal.项目地址: https://gitcode.com/GitHub_Trending/wi/windmillAgent Worker 是 Windmill 中一类特殊的工作进程它不直接连接数据库而是仅通过 HTTP API 与服务器通信因此其整条代码路径Connection::Http不会在常规的cargo run中被触发必须用真实环境才能完整演练。本文基于 docs/agent-worker-e2e.md 整理出一套可复现的本地端到端e2e调试流程从正确的 feature 组合编译二进制到启动无本地 worker 的服务器、铸造 agent token、拉起 agent再到验证任务确由 agent 执行、以及 dbt 任务在 agent 上的运行行为。每个步骤都伴随典型的看起来像别的问题的失败模式与对应报错帮助读者在本地一次性打通 agent worker 全链路。1. 用正确的 Feature 组合编译Agent Worker 链路涉及四个 feature其中最容易被遗漏的是 agent 自身的模式门控mode gatecd backend cargo build --features quickjs,private,enterprise,license,agent_worker_server各 feature 的作用如下agent_worker_server在服务器侧挂载/api/agent_workers/*路由。缺少它时create_agent_token会返回404且响应体为空。在 backend/Cargo.toml 中可以看到该 feature 的传递关系agent_worker_server [windmill-api/agent_worker_server, dep:windmill-api-agent-workers, windmill-test-utils/agent_worker_server]而 backend/windmill-api/src/lib.rs 中对应路由均以#[cfg(feature agent_worker_server)]条件编译。enterpriselicense把 agent 模式MODEagent编译进二进制。缺少时 worker 会立即退出并打印Agent mode is only available in the EE——即使服务器侧工作正常、token 也铸造成功。该 panic 位于 backend/windmill-common/src/utils.rs其中#[cfg(not(feature enterprise))]分支直接panic!(Agent mode is only available in the EE, ignoring...)同时注意 agent 模式下BASE_INTERNAL_URL是必填的缺失同样会 panic同文件 L124-L126。quickjs、private前者提供脚本运行时后者启用windmill-api-agent-workers中的 EE 实现mod ee由#[cfg(feature private)]引入见 backend/windmill-api-agent-workers/src/lib.rs。在投入握手调试之前先验证二进制确实带上了 agent 模式——panic 字符串必须不存在strings target/debug/windmill | grep -c Agent mode is only available in the EE # want 0整个调试会话务必固定这一 feature 组合。target/debug/windmill是所有 feature 组合共享的同一路径cargo 会随组合变化在缓存中交换产物如果在另一个终端执行cargo build --features quickjs或其他不同组合的构建会在不到一秒内悄悄替换掉服务器和 agent 即将运行的二进制且换回过程同样极快看起来完全不像是发生过重新构建。典型症状是agent 原本工作正常却突然开始 401或 EE panic 再次出现。每当出现意外回退时重新执行上面的strings检查并确保服务器与 agent从同一次构建产物启动。2. 运行服务器不启动本地 worker以MODEserver启动确保没有其他进程会排空队列从而证明任务确实是 agent 执行的DATABASE_URLthis worktrees db PORT8420 MODEserver ./target/debug/windmillMODE的取值在 backend/windmill-common/src/utils.rs 中解析server、worker、agent、indexer、standalone、mcp等未识别值会打印告警并默认回退到standalone。这里显式用MODEserver可避免本机 worker 抢占队列。3. 铸造 Token——带过期时间且不加引号TOK$(curl -s -X POST localhost:8420/api/auth/login -H Content-Type: application/json \ -d {email:adminwindmill.dev,password:changeme}) AT$(curl -s -X POST localhost:8420/api/agent_workers/create_agent_token \ -H Authorization: Bearer $TOK -H Content-Type: application/json \ -d {worker_group:agentgrp,tags:[dbt],exp:1900000000} | tr -d )/api/agent_workers/create_agent_token在 backend/windmill-api/openapi.yaml 中有完整定义同路径下还有blacklist_token、list_blacklisted_tokens、get_min_version等管理端点。此处有两个陷阱二者都会在 agent 侧表现为裸401而解码后的真实原因只出现在服务器日志中exp必须是真实时间戳。传exp: null铸造出的 token 会被校验器以Missing required claim: exp拒绝。响应是 JSON所以 token 是带引号返回的。保留会得到Base64 error: Invalid byte 34, offset 0——因此需要tr -d 去掉引号。传给 agent 的 token 必须原样使用。它形如jwt_agent_jwt客户端会自行追加由主机名派生的后缀组成jwt_agent_suffix_jwt服务器正是按此格式切分的。若你自己额外添加后缀会得到Base64 error: Encoded text cannot have a 6-bit remainder。4. 启动 AgentWORKER_TAGS必须包含任务实际携带的 tag而不是你随意发明的 tag——没有 worker 服务的 tag 任务会永远留在v2_job_queue中看起来像卡死。dbt 脚本默认使用dbttag。AGENT_TOKEN$AT BASE_INTERNAL_URLhttp://localhost:8420 MODEagent \ WINDMILL_DIR/home/$USER/wmagent \ WORKER_GROUPagentgrp WORKER_TAGSdbt PORT8499 ./target/debug/windmillWINDMILL_DIR放在/tmp之外在开发机上很重要。放在/tmp时任务会在写入项目文件阶段报IoErr: Disk quota exceeded (os error 122)而df看起来一切正常——空闲空间和空闲 inode 都没问题。原因是/tmp是 tmpfsLinux 支持对其做按用户的配额限制所以超限的是用户配额而非文件系统容量多个 agent 会话的缓存积累在/tmp下就足以撞上该配额。正确做法是把 worker 指向真实磁盘而不是试图在配额内清理。确认 agent 已注册而不是轻信安静的日志SELECT worker FROM worker_ping WHERE worker_group agentgrp AND ping_at now() - interval 2 min; -- ag-agentgrp-host-rand读取失败信息Agent 侧永远只打印一句Agent worker cannot connect to server. Please check AGENT_TOKEN and BASE_INTERNAL_URL。真实原因在服务器日志中来自windmill-api-agent-workers的 EE 模块——grep 关键字JWT_AGENT auth error即可定位。注意该模块的 EE 实现文件由privatefeature 门控mod ee这也解释了为什么本地 e2e 必须在构建时带上private。确认任务确由 Agent 执行已完成任务的worker字段以ag-开头curl -s -H Authorization: Bearer $TOK \ localhost:8420/api/w/ws/jobs_u/completed/get/job | jq -r .worker服务器侧对 agent worker 的识别在数据库健康检查中也有体现backend/windmill-api/src/db_health.rs 注明live_agent_workers仅作上下文参考——agent worker 走 HTTP 而非 postgres 连接因此在统计活跃连接数时被排除。这也是理解 agent worker 架构差异的关键点它连 token 的 worker 名都是从 API 侧解析的非private编译时extract_worker_name返回None见 backend/windmill-api-agent-workers/src/lib.rs。完整的端到端测试还可以参考 backend/tests/agent_workers.rs该测试文件以#![cfg(all(feature private, feature agent_worker_server))]为前置条件覆盖了create_agent_token、build_agent_http_client与update_ping的完整握手流程是本文手动步骤的自动化版本。dbt 在 Agent Worker 上的行为dbt 任务在 agent worker 上会运行、重试并发布其 graph——包括为动态描述符生成的一次性快照per-run snapshot该快照通过 POST 到/api/agent_workers/dbt_graph/{workspace}发布而不是自己写库。它不会得到的是实时进度LIVE progressreporter 需要 tail JSON 事件日志并依赖 SQL 连接因此每个 model 的状态是在运行结束时从run_results.json落定的。重试状态只存在于 worker 本地的 generation 中——因为数据库里没有对应行可供仲裁——这正是state_dir要按 principal执行主体分键的原因。快照落库的持久化结构可以在迁移 backend/migrations/20260725084314_dbt_runtime.up.sql 中看到dbt_graph_snapshot表通过(workspace_id, script_hash)外键关联脚本并为(workspace_id, job_id)、(ingested_at)建立索引随后的迁移 backend/migrations/20260801121717_dbt_editor_preview_graph.down.sql 进一步补充了编辑器预览所需的permissioned_as等列。确认一次运行确实走过该发布路径SELECT job_id, count(*) FROM dbt_node WHERE script_path path GROUP BY job_id; -- 存在以 JOB id而非零 UUID为键的行说明 agent 发布了快照排错速查表症状报错/现象根因处理create_agent_token返回 404 空响应HTTP 404缺agent_worker_serverfeature重编译并固定 feature 组合worker 立即退出Agent mode is only available in the EE缺enterpriselicensefeature加上后重编译用strings验证 panic 字符串消失agent 401Missing required claim: exptoken 的exp为 null传真实时间戳agent 401Base64 error: Invalid byte 34, offset 0token 带引号tr -d 去掉引号agent 401Base64 error: Encoded text cannot have a 6-bit remainder手动给 token 追加后缀原样传递铸造出的 token任务看起来卡死永远留在v2_job_queueWORKER_TAGS与任务 tag 不匹配使用任务实际携带的 tagdbt 默认dbt任务写文件失败IoErr: Disk quota exceeded (os error 122)/tmptmpfs 的用户配额WINDMILL_DIR指向真实磁盘agent 无法连接仅显示Agent worker cannot connect to server...真实原因在服务器侧在服务器日志 grepJWT_AGENT auth error整套流程的要点可归纳为三条固定四 feature 编译组合并用strings验证、token 原样传递真实exp 去引号、以及任何异常先从服务器日志找根因。按照上述步骤操作即可在本地完整验证Connection::Http这条只在 agent worker 上才会触发的代码路径。【免费下载链接】windmillOpen-source developer platform to power your entire infra and turn scripts into webhooks, workflows and UIs. Fastest workflow engine (13x vs Airflow). Open-source alternative to Retool and Temporal.项目地址: https://gitcode.com/GitHub_Trending/wi/windmill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考