跳转至

管理员指南

这篇给负责交付、升级、验收和现场支持的人。它回答的不是“模块怎么开发”，而是下面这些问题：

  • 交付当天最少要确认什么
  • 现场升级前要看什么
  • 验收证据怎么留
  • 遇到故障怎么快速分诊
  • 什么情况该继续处理，什么情况必须升级给研发

1. 先分清你的职责边界

管理员或实施同学通常负责：

  1. 安装并启动客户端
  2. 完成首次全局设置
  3. 安装或升级正式模块
  4. 协助业务同学完成第一条作业
  5. 留存验收证据
  6. 发生故障时做第一轮分诊

不属于这篇手册的内容：

  • 源码运行
  • SDK CLI 使用
  • 模块开发
  • DevLink 联调细节

这些属于开发者路径，不应该塞回普通用户手册。

2. 交付前最小准备清单

到现场前，最好确认你已经拿到：

  1. 客户端本体
  2. 模块正式安装源：本地 ZIP 或 GitHub 仓库地址
  3. 外部浏览器类型、程序位置和 API 端口
  4. 测试账号或最小可验证目标
  5. 现场网络策略：是否需要代理、是否需要 IP 池

3. 现场最小开局顺序

交付当天建议固定按下面顺序推进：

  1. 按 安装与第一次打开 确认客户端能稳定启动
  2. 按 首次设置 核对全局设置
  3. 按 开始使用 跑通第一次闭环
  4. 再进入 日常使用 做日常化配置或优化

不要跳步。很多所谓“产品有问题”，最后都是因为第一步没把设置和模块状态看清。

4. 现场最小验收标准

一套交付至少要满足下面几条：

  • 客户端能正常打开
  • 左侧 6 个主导航入口可用
  • 系统设置能保存
  • 目标模块能安装并显示 已启用
  • 能创建一条作业
  • 能手动 执行一次
  • 作业详情里能看到任务实例和日志
  • 你能从 结果/错误 或日志判断这次执行结果

如果连这些最小条件都不满足，不建议宣布“已经交付完成”。

5. 模块升级怎么做

正式升级优先走 模块管理 页面：

  1. 打开 模块管理
  2. 先点击 检查更新
  3. 只对需要升级的模块继续处理
  4. 如果当前还有运行中的任务，先停任务，再升级
  5. 升级后重新确认模块版本、状态和关键流程

升级前必须确认的事

  • 当前没有关键运行中的作业
  • 业务方知道即将升级
  • 你保留了升级前的版本信息和现场截图
  • 升级后会重新验证第一条任务

什么时候不要升级

  • 当前任务还在跑
  • 现场问题尚未定位，贸然升级只会放大变量
  • 你拿到的升级包来源不明确

6. 现场最小证据包

交付完成或现场报障时，建议最少留下面这些证据：

  1. 主界面截图，能看见版本号
  2. 模块列表截图，能看见模块名、版本和状态
  3. 新建作业或任务监控截图
  4. 一次真实执行后的状态截图
  5. 作业详情截图，能看见任务实例和日志
  6. 关于 页面截图
  7. 日志路径或日志文件打包

日志默认在：

  • 应用数据目录/logs/crawler4j.log

7. 报障时最小信息包

发给研发或上游支持时，至少带上这些：

  • 客户端版本号
  • 模块名和模块版本
  • 作业名
  • 触发时间
  • 错误弹窗原文
  • 作业详情中的 结果/错误
  • 主日志文件或关键日志片段

没有这些信息，现场常常会陷入“只能口头描述，大量来回猜测”。

可以直接复制的报障模板

问题时间：
客户现场：
客户端版本：
模块名 / 模块版本：
作业名：
触发方式：
现象描述：
错误弹窗原文：
作业详情中的结果/错误：
是否有任务实例：
环境状态：
是否使用代理 / IP 池：
已附截图：
已附日志：

8. 现场一页分诊

现象 先看哪里 先判断成什么问题 什么时候升级给研发
应用打不开 程序本体、系统权限、应用数据目录、主日志 安装或系统策略问题 这些都确认正常后仍无法启动
页面空白或某页打不开 页面截图、版本号、主日志 客户端页面或资源加载问题 重启后仍稳定复现
模块不是 已启用 模块列表、安装源、模块详情 模块安装或兼容性问题 正确安装后仍异常
登录或权限异常 作业详情、任务日志、模块配置 账号、流程参数或站点权限问题 配置确认无误仍持续失败
点击 执行一次 没变化 系统设置、运行模板、作业状态 设置或模板问题 这些都确认无误仍无反应
任务实例生成了但全失败 作业详情、任务日志、模块配置 已进入执行链，先看业务或环境问题 日志指向代码或模块契约问题
环境一直不可用 环境管理、外部浏览器、IP 池 环境或浏览器连接问题 现场浏览器链路确认正常后仍失败
升级失败 模块来源、当前运行任务、主日志 升级窗口期或安装源问题 停任务后仍无法升级
升级后行为和升级前明显不一致 版本信息、模块配置、任务日志 版本变更影响 需要改代码或回滚时

9. 什么时候必须停手升级

出现下面任意一种情况，不要继续靠“多点几次”“重装一下”硬试：

  1. 应用根本无法启动
  2. 按正式流程安装后，模块仍然无法启用
  3. 设置、模块、运行模板都确认正确，但任务完全不进入执行链
  4. 日志已经明确指向模块代码、契约或宿主缺陷
  5. 需要临时改源码、改模块包或改正式契约才能继续

这时应该收集证据并升级给研发，而不是在现场继续制造新变量。

一旦决定升级给研发，先立刻收这 5 样

  1. 关于 页面版本截图
  2. 模块列表截图
  3. 作业详情截图
  4. 错误弹窗原文
  5. crawler4j.log

10. 管理员最容易犯的 5 个错

  1. 没先停运行中的任务就直接升级
  2. 没留版本信息和截图就开始操作
  3. 把 DevLink 联调路径当成正式交付路径
  4. 没进作业详情，只在列表页判断“有没有结果”
  5. 问题还没分清是设置、环境还是模块，就急着归因给产品本身

11. 交付收口时再确认一次

离场前，至少再核对一遍：

  • 当前版本号
  • 当前模块版本
  • 第一条验证作业的执行结果
  • 日志路径
  • 后续现场联系人知道看哪几篇文档

普通使用者通常只需要：

管理员则应额外保留这篇 管理员指南。