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

apify-debug-bundle

部署与运维

查看项目

更新于 10-16 09:08

技能介绍

用途

Apify Debug Bundle 用于收集排查失败的 Actor 运行和准备 Apify 支持工单所需的全部诊断信息。它将运行元数据、日志、数据集样本和环境信息拉取到一个单一打包文件中，使支持工程师（或你自己）无需实时访问你的账户即可诊断故障。

适用于 Actor 运行已失败、卡住，或产生了空输出，且你需要诊断原因的场合。

主要能力

该工作流包含四个步骤：

  1. 调查失败的运行 —— 通过 SDK 拉取运行摘要、数据集统计和日志尾部。核心调用：
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.run(runId).get();
const log = await client.run(runId).log().get();

  1. 创建调试包 —— 运行 apify-debug-bundle.sh <RUN_ID>。它收集环境信息、运行详情、日志、5 条数据集样本、键值存储键列表、脱敏后的 .env 和平台健康状态，然后将所有内容打包成一个带时间戳的 .tar.gz 文件。

  2. 与良好运行对比（可选） —— 逐字段 diff 一次成功运行和一次失败运行，以发现差异（compareRuns(successId, failId)）。

  3. 实时跟踪正在运行的 Actor（可选） —— 当最终日志尚不可用时流式输出日志。

每个步骤的可复制代码见 implementation.md。

输出

一个带时间戳的 tarball：apify-debug-YYYYMMDD-HHMMSS.tar.gz，包含：

文件 内容
environment.txt Node/npm 版本、已安装的 Apify 包、CLI 版本
run-details.json 运行状态、选项、统计、用量、成本
run-log.txt 完整运行日志（平台自动脱敏机密信息）
dataset-sample.json 前 5 条数据集条目
kv-store-keys.json 键值存储键列表
env-redacted.txt 本地 .env，所有值已脱敏
platform-health.json Apify 平台健康快照

该 tarball 可直接附加到 Apify 支持工单。

使用方式

前置条件：

  • 已安装 apify-client
  • 已配置 APIFY_TOKEN
  • 有一个要调查的失败或有问题的运行 ID

认证：

所有 API 调用使用 APIFY_TOKEN 作为 Bearer 头认证（Authorization: Bearer $APIFY_TOKEN），SDK 从 process.env.APIFY_TOKEN 读取同一令牌。令牌可从 Apify Console 的 Settings → Integrations → Personal API tokens 获取。切勿提交该令牌——打包脚本在打包前会脱敏本地 .env，平台也会自动脱敏运行日志中的机密信息。

快速上手：

export APIFY_TOKEN="apify_api_..."
./apify-debug-bundle.sh abc123DEF          # → apify-debug-20260717-142530.tar.gz
tar -xzf apify-debug-*.tar.gz && tail -40 apify-debug-*/run-log.txt

适用场景

  • 普通 FAILED 运行排查
  • "昨天还好好的" 回归对比（比较成功与失败运行）
  • 空数据集调查
  • 实时跟踪卡住的运行

以上四类场景的完整演练（包括阅读对比输出和理解实时跟踪）见 examples.md。

敏感数据处理

分享前始终脱敏：

  • API 令牌（apify_api_*）
  • 代理密码
  • PII（邮箱、姓名、IP）
  • 自定义环境变量

可安全包含：

  • 运行 ID、Actor ID、数据集 ID
  • 错误消息和堆栈跟踪
  • 运行配置（内存、超时）
  • 平台健康状态

升级路径

  1. 检查运行日志中的堆栈跟踪
  2. 与成功运行对比
  3. 检查 Apify Status 是否宕机
  4. 创建调试包
  5. 将调试包作为附件提交给 Apify Support

错误处理

问题 原因 解决方案
运行未找到 运行 ID 无效或已过期 未命名运行 7 天后过期
日志不可用 运行仍在进行中 等待完成或实时流式输出
空数据集 Actor 未产生输出 检查代码中的 failedRequestHandler
高 CU 用量 内存过高或执行缓慢 降低内存、优化代码

限制

关于速率限制问题，参见 apify-rate-limits 技能。

资源

  • 完整实现演练
  • 已完成的示例
  • Actor Run API
  • Run Log API
  • Apify Support Portal