droboticflow/docs/platform-usage-manual.zh-CN.md
2026-08-28 18:50:56 +08:00

11 KiB
Raw Permalink Blame History

Drobodata 平台使用手册

本文档面向平台使用者,覆盖项目、工作流、模板、运行、数据管理、对象存储和常见排障。文中截图来自当前线上环境,流程说明基于当前代码与真实运行行为。

1. 平台结构总览

平台里最核心的 6 个对象是:

  • 项目:一组相关工作流的容器
  • 工作流:由多个算子节点组成的 DAG
  • 模板:可复用的工作流蓝本
  • 运行:某次工作流执行实例
  • Artifact:算子之间传递的数据产物
  • 数据源:BOS、目录、JSON、CSV、Mongo 等外部输入

典型处理链路如下:

flowchart LR
  A["项目"] --> B["工作流"]
  B --> C["运行"]
  C --> D["节点执行"]
  D --> E["Artifacts / Stage Manifest"]
  E --> F["上传结果 / 数据管理 / 成品包"]

2. 主要页面

2.1 项目页

项目页用于管理项目、查看项目内工作流,以及复制工作流。

项目列表

常见操作:

  • 新建项目
  • 进入项目详情
  • 在项目内新建工作流
  • 复制已有工作流
  • 删除工作流

说明:

  • 现在“复制工作流”会完整保留工作流顶层参数
  • 包括 kind、scanConfig、并发、超时、重试等
  • 对扫描型工作流,数据源、bucket/prefix、accessKeyId/secretAccessKey 也会一并复制

2.2 模板页

模板页用于沉淀标准流程、复制模板,以及从模板创建工作流。

模板页

常见操作:

  • 创建空模板
  • 将已有工作流保存为模板
  • 复制模板
  • 从模板创建新工作流

说明:

  • 现在“保存为模板”和“从模板创建工作流”都保留完整参数
  • 包括 scanConfig、执行参数、节点、边、调度配置

2.3 工作流编辑器

工作流编辑器用于配置节点、连接节点、保存和运行工作流。

工作流编辑器

编辑器里的关键概念:

  • 左侧:算子面板
  • 中间:画布
  • 右侧或弹层:节点参数配置
  • 顶部:保存、运行、导出模板等动作

当前约束:

  • 同一个输入端口只允许一条入边
  • 如果需要上传多个不同结果,必须为每个结果添加独立的“结果上传”算子

2.4 数据管理页

数据管理页用于查看扫描导入的数据、目录索引、成品包等。

数据管理

适合查看:

  • 采集目录
  • 视频、JSON、配置文件
  • 成品包
  • 运行产出 manifest
  • 上传后的 BOS 路径

2.5 算子列表页

算子列表页用于查看当前内置算子、分类、描述和输入输出能力。

算子列表

3. 典型使用流程

3.1 创建项目和工作流

  1. 在项目页点击“新建项目”
  2. 进入项目详情页
  3. 点击“新建工作流”
  4. 打开工作流编辑器
  5. 拖入需要的算子并配置参数
  6. 保存工作流

3.2 保存为模板并复用

  1. 在项目详情页选择现有工作流
  2. 点击“保存为模板”
  3. 在模板页选择该模板
  4. 点击“使用模板”
  5. 选择目标项目
  6. 系统会创建一条新的工作流实例

当前行为:

  • 工作流复制
  • 模板导出
  • 模板实例化

以上三条链路都完整保留:

  • kind
  • scanConfig
  • bucket/prefix/endpoint
  • accessKeyId/secretAccessKey
  • maxConcurrentRuns
  • nodeTimeoutSeconds
  • runTimeoutSeconds
  • maxRetryAttempts
  • retryBackoffSeconds
  • schedule
  • nodes
  • edges

3.3 执行工作流

  1. 打开工作流
  2. 点击“运行”
  3. 查看执行状态
  4. 进入运行详情页查看节点状态、日志和产物

运行状态通常有:

  • pending
  • running
  • completed
  • failed

3.4 持续处理完整目录

已发布工作流可以绑定一个持续增长的 BOS 目录。系统把监听目录下的每个一级子目录都视为候选记录,不要求目录名符合固定前缀或正则表达式;是否启动只由该目录内的必需文件是否齐全决定。

以 Orbbec Ego 双目记录为例,默认要求:

  • 左相机视频、右相机视频
  • 左相机 PTS、右相机 PTS
  • IMU CSV
  • 相机 Calibration、IMU Calibration

文件未齐时记录保持“等待文件齐全”,不会创建 Run。文件齐全后,每个一级目录独立创建一次正式 Run。系统使用 workflowId + 一级目录路径 保存 Capture 身份,并以文件 key + ETag + size 的 SHA256 作为内容指纹;重复扫描和 Worker 重启不会重复创建 Run。

持续处理页面还可以配置:

  • maxRetryAttempts:失败后最多自动重试多少次,0 表示不自动重试。
  • retryBackoffSeconds:每次重试前等待的秒数。

每次重试都会创建有父子关系的新 Run,保留原失败记录;Capture 的当前 Run 会跟随最新重试,并同步显示最终状态。failed 与用户主动停止产生的 cancelled 分开统计。

用户主动取消后不会触发自动重试。管理员可以在持续处理页面执行:

  • 重新处理:仅针对失败或已取消记录;填写原因后创建新的 retry Run,原 Run 保留。
  • 永久放弃:停止监听器继续处理该一级目录,不删除源文件。
  • 恢复:把已放弃记录恢复到放弃前状态,重新参加完整性检查。

三个操作都必须填写原因,并保留操作者、时间、状态变化和关联 Run 的审计历史。相同操作采用原子状态转换,重复点击不会创建多个 Run。

从某个工作流 Run 进入标注中心时,切分与语义标注、审核、最终验收三个二级页面会持续保留 workflowId + runId 作用域。当前 Run 尚未到人工节点时页面显示明确空态,不会混入旧版本或历史 Run 的已通过任务。管理员默认查看“可领取”任务;只有主动切换“全部任务”时才显示历史记录。

4. 扫描型工作流

扫描型工作流用于轮询或增量嗅探 BOS 路径下的新目录/新文件。

flowchart LR
  A["BOS 增量扫描"] --> B["数据集索引"]
  B --> C["目录校验"]
  C --> D["后续处理工作流"]

建议配置项:

  • dataSource=BOS
  • bucket
  • prefix
  • endpoint
  • accessKeyId
  • secretAccessKey
  • scanMode=INCREMENTAL

当前平台能力:

  • 支持增量 source state
  • 支持发现新目录后触发后续处理
  • 支持在共享 PVC 上保存阶段 manifest 和中间态

目录级循环增量工作流推荐配置:

  • type=streaming
  • kind=scan
  • schedule.interval=20 或更长
  • maxConcurrentRuns=1
  • scanMode=INCREMENTAL
  • incrementalUnit=DIRECTORY
  • directoryDepth=1

目录级模式语义:

  • OBJECT:按文件对象判增量,新增文件或覆盖更新文件都会触发
  • DIRECTORY:按目录判增量,只有新目录首次出现时才触发,并把该目录下全部内容推给后续节点
  • DIRECTORY 模式下,如果老目录里只新增了一个文件,不会重新把这个目录当成新目录触发

一个稳定的目录级循环链路通常是:

flowchart LR
  A["BOS 增量扫描 (DIRECTORY)"] --> B["X 平台数据集索引"]
  B --> C["采集目录校验"]

真实验收结论:

  • 已在目标 BOS 数据路径的独立增量验收前缀上完成 5 轮真实验收
  • 最终工作流:已记录在对应环境的运行日志中
  • 5 轮结果如下:
    • 第 1 轮:新增 2 个新目录,newCount=8,listedCount=8
    • 第 2 轮:无新增,newCount=0,listedCount=8
    • 第 3 轮:老目录新增 notes.txt,仍然 newCount=0,listedCount=9
    • 第 4 轮:新增 2 个新目录,newCount=8,listedCount=17
    • 第 5 轮:无新增,newCount=0,listedCount=17

这说明目录级模式已经满足“新增目录即触发整目录内容进入后续流程;老目录新增单文件不触发整目录重跑”的要求。

注意:

  • 增量扫描依赖 source state
  • 如果你重置 source state,下一次会重新把已有对象视为新对象
  • 线上要确保 droboticflow-worker 的 OPERATOR_RUNNER_IMAGE 已切到支持目录级增量的 runner;否则节点里即使写了 INCREMENTAL_UNIT=DIRECTORY,实际运行也可能仍落到旧镜像

5. 运行和结果怎么看

每次运行至少有三层信息:

  1. 工作流级状态
  2. 节点级状态
  3. artifact / manifest / 日志

建议排查顺序:

  1. 先看工作流是否 failed
  2. 再看失败节点
  3. 再看该节点日志
  4. 再看该节点输出的 stage-manifest
  5. 最后回溯上游 artifact

6. 数据传输与上传原则

平台当前是 Kubernetes Job + 共享 PVC + BOS 的混合数据面:

  • 小型结构化数据:通过 JSON artifact 传递
  • 大文件和中间态:通过共享 PVC 上的 manifest / payloadPath 传递
  • 长期持久化结果:通过 BOS 上传保存

使用建议:

  • 不要让多个上游结果并到同一个输入端口
  • 需要多个上传结果时,拆成多个“结果上传”节点
  • 大视频/大 JSON 不要依赖浏览器直接预览全部内容

7. 常见问题

7.1 为什么复制工作流后参数丢了?

旧版本前端只复制了基础字段,后端又把 scanConfig 里的密钥清空了。当前版本已经修复,复制/模板链路会完整保留参数。

7.2 为什么一个上传节点不能接多个上游结果?

当前平台规定:一个输入端口只能有一条入边。多个结果请拆成多个上传节点,否则语义不清晰,也会被前后端拒绝保存/运行。

7.3 为什么大视频处理慢?

大文件工作流主要受以下因素影响:

  • BOS 拉取速度
  • ffmpeg 切片模式
  • PVC 吞吐
  • 多节点并发

当前平台已经优先对切片走 stream copy,失败时再回退重编码。

7.4 为什么删除目录时会报 NoSuchKey?

旧版本把 BOS 的目录占位 key 错误裁掉了末尾 /。当前版本已修复,递归删目录会按真实 key 删除。

8. 推荐实践

  • 标准流程优先沉淀为模板
  • 需要复用数据源时,用扫描型工作流保存 scanConfig
  • 对大文件结果,尽量上传到 BOS,再让下游消费远程 artifact
  • 对多分支输出,给每个最终产物单独配上传节点
  • 对增量目录处理,优先使用 BOS 增量扫描 + source state

9. 相关文档