跳转至

异常案例

这页给两类人看：

  • 普通用户：遇到问题时先知道该点哪里，不要乱点。
  • 现场支持：先做第一轮分诊，再判断是继续处理，还是升级给管理员或研发。

这页只按你看到的症状组织，不按内部技术模块组织。

遇到问题时，先尽量留 4 样：

  1. 关于 页面版本截图。
  2. 模块列表或作业详情截图。
  3. 错误弹窗原文。
  4. 应用数据目录/logs/crawler4j.log。

1. 应用打不开

现象

  • 双击客户端后完全没主窗口。
  • 主窗口一闪而退。
  • 系统直接提示“已阻止打开”“无法验证开发者”或类似拦截信息。

先看哪里

  • 安装与第一次打开
  • 当前系统的安全拦截提示
  • 应用数据目录是否已经创建
  • 应用数据目录/logs/crawler4j.log

先做什么

  1. 先确认你打开的是客户端本体，不是模块 ZIP，也不是源码目录。
  2. 确认程序已经完整安装或解压，不是在压缩包预览或 .dmg 挂载状态里直接运行。
  3. macOS 先看系统安全策略是否拦截；Windows 先看 SmartScreen 或杀毒软件是否拦截。
  4. 再次打开一次，并记住具体时间，方便后面核对日志。

什么情况升级给管理员或研发

  • 应用数据目录和主日志都完全没有生成，先升级给管理员排查机器权限、安装路径或系统策略。
  • 安装源、系统拦截、程序位置都确认无误后，客户端仍稳定打不开，再把系统提示和主日志升级给研发。

2. 页面空白

现象

  • 左侧导航还在，但右侧内容区一片空白。
  • 进入某个页面后，只剩白屏或大面积空白区域。
  • 某一页每次进入都空白，但其他页面还能打开。

先看哪里

  • 当前到底是哪个页面空白
  • 关于 页面版本信息
  • 应用数据目录/logs/crawler4j.log
  • 安装与第一次打开

先做什么

  1. 先分清“空列表”和“空白页”不是一回事。第一次启动时，任务监控、环境管理、模块管理 为空列表可以是正常现象。
  2. 先切到别的页面，再回到这个页面重开一次。
  3. 关闭客户端后重新打开，再看是否还能稳定复现。
  4. 记录是“只有某一页空白”，还是“多个页面都空白”。

什么情况升级给管理员或研发

  • 重启后仍稳定复现同一个空白页，先升级给管理员留证据和版本信息。
  • 模块管理、系统设置 这类基础页面也稳定空白，或主日志里已经出现明显报错，再升级给研发。

3. 模块未启用

现象

  • 模块管理 里看不到目标模块。
  • 看得到模块，但状态不是 已启用。
  • 新建作业时选不到目标模块或流程。

先看哪里

  • 模块管理 列表页
  • 模块详情里的基本信息和 任务链
  • 模块安装来源：本地 ZIP 还是 GitHub 源
  • 日常使用

先做什么

  1. 先确认模块是否真的已经安装进客户端，而不是只拿到了模块包。
  2. 如果模块在列表里但状态是 已禁用，先执行 启用，不要直接继续建作业。
  3. 打开模块详情，确认版本、状态和 任务链 里的流程都正常可见。
  4. 如果列表里根本没有模块，回到 模块管理 重新走正式安装入口。

什么情况升级给管理员或研发

  • 按正式安装路径安装后，模块仍无法显示或无法启用，先升级给管理员核对交付包和版本。
  • 模块能看到但启用失败、状态反复回退，或 任务链 缺失关键流程，再升级给研发。

4. 执行一次没反应

现象

  • 点击 ▶ 执行一次 后，列表状态完全不变。
  • 没看到 执行中、运行中、已完成 或 异常。
  • 作业详情里也没有新增任务实例。
  • 或者列表先进入 环境启动中，但长时间没有切到 执行中，随后顶部又弹出外部浏览器启动失败提示。

先看哪里

  • 任务监控 里的作业状态
  • 当前作业使用的运行模板
  • 模块是否已经 已启用
  • 系统设置 中的浏览器、代理和日志配置
  • 日常使用

先做什么

  1. 先不要连续狂点，确认当前作业不是已经处于 执行中。
  2. 确认这条作业真的是你要手动触发的那条作业，并且运行模板已经选好模块、流程和环境策略。
  3. 回到 模块管理，确认目标模块状态仍是 已启用。
  4. 如果任务已经进了 执行中 但明显卡住，可以先点 ⏹ 中止；按现场需要选择 保留环境中止 或 删除环境中止。如果当前是复用环境模式，只会提供关闭不删。
  5. 如果顶部错误提示里已经出现 VirtualBrowser launchBrowser 失败、DevTools port 或类似字样，优先按这个错误检查外部浏览器本体是否真的能打开、调试端口是否可用。
  6. 回到 系统设置，确认外部浏览器端口、程序位置和代理配置已经保存正确。

什么情况升级给管理员或研发

  • 设置、模块状态、运行模板都确认正确后，多次点击仍完全没有状态变化，先升级给管理员做首轮分诊。
  • 主日志已经能看出任务没有进入执行链，或者弹窗和日志明确指向宿主/模块缺陷，再升级给研发。

5. 任务实例全失败

现象

  • 作业详情里已经有任务实例，但状态几乎全是 failed。
  • 列表页显示 异常，每次进去都看到失败实例。
  • 任务确实启动了，但业务结果一直失败。

先看哪里

  • 作业详情里的 结果/错误
  • 作业详情底部的 任务日志
  • 模块详情里的 模块配置 和 Workflow 配置
  • 当前任务实例对应的环境信息

先做什么

  1. 先确认这不是“没执行”，而是“已经进入执行链但执行失败”。
  2. 打开作业详情，先看 结果/错误，再看 任务日志，不要只停留在列表页。
  3. 看多个失败实例是不是同一种错误，还是每次都不一样。
  4. 再回到模块配置和运行模板，确认账号、流程参数、环境选择和 IP 策略没有填错。

什么情况升级给管理员或研发

  • 现场参数、环境和账号都确认无误后，任务实例仍稳定全失败，先升级给管理员整理证据。
  • 日志已经明确指向模块代码、宿主契约或正式包缺陷，或者必须改代码/改模块包才能继续时，再升级给研发。

6. 环境不可用

现象

  • 没有可用的 就绪 环境。
  • 环境一直卡在 运行中、暂停 或异常状态。
  • 手动创建环境失败，或环境建出来也无法被任务接管。

先看哪里

  • 环境管理
  • 系统设置 -> 网络
  • 如果用了代理，再看 环境管理 -> IP 池管理
  • 首次设置
  • 日常使用

先做什么

  1. 先确认当前项目到底应该“复用已有环境”还是“创建新环境”，不要把运行模板配反。
  2. 去 环境管理 看是否真的存在可用的 就绪 环境。
  3. 回到 系统设置 -> 网络，确认外部浏览器类型、API 端口 和 程序位置 与现场机器一致。
  4. 如果任务依赖代理或 IP 池，再确认池存在、池里有可用 IP，且模板真的绑定到了这个池。

什么情况升级给管理员或研发

  • 浏览器类型、端口、路径和 IP 池都核对正确后，环境仍长期不可用，先升级给管理员。
  • 所有环境都无法恢复、无法回收，或主日志已经明确指向外部浏览器连接/运行时故障，再升级给研发。

7. 升级失败

现象

  • 检查更新 或 升级 时报错。
  • 升级过程中中断，模块版本没有更新成功。
  • 升级后模块消失、被禁用，或关键流程不见了。

先看哪里

  • 模块管理 列表页里的版本和状态
  • 当前模块的升级来源：本地 ZIP 还是 GitHub 源
  • 当前是否还有运行中的任务
  • 应用数据目录/logs/crawler4j.log
  • 管理员指南

先做什么

  1. 先停掉当前仍在运行的任务，不要边跑任务边升级。
  2. 记录升级前的模块版本、状态和截图。
  3. 确认你拿到的是正确升级源，而且现场网络条件允许当前升级方式继续执行。
  4. 升级后先重新确认模块版本、状态和 任务链，再跑第一条验证作业。

什么情况升级给管理员或研发

  • 没有运行中的任务、升级源也确认正确后，仍无法完成升级，先升级给管理员。
  • 升级完成后模块状态异常、流程缺失，或行为和升级前明显不一致，需要回滚、补包或改代码时，再升级给研发。

8. 结果找不到

现象

  • 作业已经跑过，但你不知道结果应该去哪里看。
  • 列表页状态变了，却看不到明确结果。
  • 你怀疑“已经跑完了”，但找不到成功或失败依据。

先看哪里

  • 任务监控 -> 点击作业行 -> 作业详情
  • 作业详情里的 任务实例 (Tasks)
  • 作业详情里的 结果/错误
  • 作业详情底部的 任务日志
  • 日常使用

先做什么

  1. 先记住标准通用结果入口不在列表页，而在作业详情里。
  2. 进入作业详情后，先看 结果/错误，再看 任务日志。
  3. 如果连任务实例都没有，先回到“执行一次没反应”排查。
  4. 只有模块负责人明确说“结果在模块自定义页或数据页”时，你才需要继续去找模块扩展页。

什么情况升级给管理员或研发

  • 作业已经显示 已完成 或 异常，但作业详情既没有清晰结果，也没有可用日志，先升级给管理员。
  • 多条作业都稳定出现“执行了但结果入口没有内容”，或者模块声称有结果页但正式包里根本不存在，再升级给研发。