SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场debug-failed-run

debug-failed-run

部署与运维

查看项目

更新于 10-15 11:46

技能介绍

用途

本技能用于调查 Activepieces 流程运行失败的原因。它把两个「事实来源」结合起来：DevOps 调试脚本（实时 BullMQ 作业 + Postgres 的 flow_run、flow_version、flow 表 + 运行日志文件，合并成一份 JSON 报告，需通过 SSH 运行）和 ClickHouse 日志（集中式的服务端/worker 日志，通过 ClickStack MCP 查询）。ClickHouse 用于补充脚本无法覆盖的内容：上下文日志行、基础设施错误，以及当脚本所在主机无法解压时提供解压后的运行 body。该技能存在于仓库中，而非 DevOps 主机上，它通过 SSH 驱动远程脚本。

主要能力

  • 拉取作业/运行报告（SSH）：脚本位于 DevOps 主机的 /root/queue，通过 .env 读取服务器使用的同一套 AP_* 环境变量（Redis、Postgres、S3），以普通 node 运行。stdout 为单行 JSON 报告（便于管道处理），进度信息输出到 stderr。优先查看的字段包括：summary / diagnostics（可读的结论与注意事项）、job.failedReason + job.stacktrace（BullMQ 失败；"Internal error" 为通用包装，真实原因在 stacktrace 中）、flowRun.status 及失败步骤（steps[].isFailedStep、runLogs.steps[].errorMessage）、flow / flowVersion（含 flowVersion.connectionIds 用于连接问题）、triggerPayload（触发运行的内容）。
  • 与 ClickHouse 日志关联（ClickStack MCP）：使用 Logs 数据源（id: 6a2a91b1d37162f45ad78233；关键列 Body、ServiceName、SeverityText、TraceId，attrs 在 LogAttributes 中）。围绕运行的失败时间，用运行 id、flow id、project id 或 platform id 检索。可使用 clickstack_search（对 Body + 属性做关键词/Lucene 风格检索）或 clickstack_sql（在需要精确过滤 LogAttributes 或聚合时使用，需先从 clickstack_list_sources 获取连接 id）。将时间窗口限定在报告中的 processedAt/finishedAt 前后几分钟，以降低查询成本，寻找包围失败点的 engine/worker 日志行，如 sandbox 崩溃、OOM、RPC 超时、连接刷新失败。
  • 将失败追踪到本仓库源码：取 stacktrace / failedReason / 日志 Body 中最具辨识度的部分（抛出的确切消息、ActivepiecesError 代码如 ENTITY_NOT_FOUND、PIECE_NOT_FOUND，或函数名），在 packages/ 下 Grep。对 piece 失败，用失败步骤的 settings.pieceName/pieceVersion 指向 packages/pieces/**/<piece>。对 engine/worker 失败，查看 packages/server/{api,worker} 与 packages/engine。
  • 聚合失败积压（仅在要求时）：扫描 workerJobs 中所有失败作业并分类（ConnectionNotFound、StorageError、evalInScope 错误、stalled、RPC 超时、SANDBOX_INTERNAL_ERROR 等），打印每类的计数与样本 job id。

使用方式

输入：id（必填）为流程运行 id；对于流程执行，BullMQ 的 jobId === flowRun.id，因此 --run 与 --job 均适用。host（必填）为 DevOps 机器的 SSH 目标，例如 user@host；必须向用户索取或从其本地 SSH 配置 / ~/.ssh/config 别名读取，不得假定。--queue（可选）为 BullMQ 队列名，默认 workerJobs；专用 worker 组的作业可能位于 platform-<workerGroupId>-jobs。

步骤一（SSH 拉取报告）的命令：

ssh -o BatchMode=yes -o ConnectTimeout=10 <host> \
  'cd /root/queue && node ./debug-failed-job.js --run <id>'

Node 注意事项：该主机运行 Node v20，但运行日志 body 为 ZSTD 压缩，需要 Node ≥ 22.15 才能解压。当 runLogs 返回 "lacks node:zlib zstd support" 提示时，job/run/DB 数据仍然完整，此时应在步骤二从 ClickHouse 获取实际日志行。

步骤二：使用 Logs 数据源（id: 6a2a91b1d37162f45ad78233），在失败时间附近检索 run id、flow id、project id 或 platform id。先用 clickstack_search 从流程运行 id 开始，再扩展到 projectId / platformId / piece 名称，可过滤 SeverityText 为 error/warn 以减少噪声；需要精确过滤或聚合时用 clickstack_sql。

步骤三：把 stacktrace / failedReason / 日志 Body 中的特征字符串或 ActivepiecesError 代码在本仓库 packages/ 下 Grep，定位抛出的代码路径及其错误处理，判断触发它的输入（triggerPayload / 步骤 input）是否被错误处理。

步骤四（仅在被要求时）聚合失败积压的命令：

ssh -o BatchMode=yes -o ConnectTimeout=10 <host> \
  'cd /root/queue && node ./aggregate-internal-errors.js'

用其样本 job id 再回到步骤一深入具体运行。

适用场景

  • 收到一个失败的流程运行 id，需要定位失败原因。
  • 需要将运行时数据（BullMQ、Postgres、运行日志）与集中式 ClickHouse 日志相互印证。
  • 需要判断失败是产品缺陷、用户配置问题还是基础设施问题，并给出文件:行号和修复方向。
  • 需要了解当前失败积压的整体分布（如「哪些在失败」「对内部错误分类」「最常见的失败原因」）。

限制与说明

  • host 为必填且不得假定，必须向用户索取或从其本地 SSH 配置读取；示例中的 <host> 为占位符，运行时需替换为真实目标。
  • 仅在用户要求时才编辑代码；对于产品缺陷，应指出文件:行号、解释到达该路径的方式并提出修复，是否改代码取决于用户。
  • Node 版本限制可能导致运行日志 body 无法解压，此时需改用 ClickHouse 日志补齐。
  • 输出应先给出一行根因及其分类（产品缺陷 / 用户配置 / 基础设施），随后给出失败步骤 + 错误、佐证的 ClickHouse 日志行，若为产品缺陷则给出本仓库中的文件:行号与修复建议，否则给出需更改的配置或需上报的运维信号；应引用实际的 failedReason / stacktrace 与日志 Body，不得转述走样。