11 KiB
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 创建项目和工作流
- 在项目页点击“新建项目”
- 进入项目详情页
- 点击“新建工作流”
- 打开工作流编辑器
- 拖入需要的算子并配置参数
- 保存工作流
3.2 保存为模板并复用
- 在项目详情页选择现有工作流
- 点击“保存为模板”
- 在模板页选择该模板
- 点击“使用模板”
- 选择目标项目
- 系统会创建一条新的工作流实例
当前行为:
- 工作流复制
- 模板导出
- 模板实例化
以上三条链路都完整保留:
kindscanConfigbucket/prefix/endpointaccessKeyId/secretAccessKeymaxConcurrentRunsnodeTimeoutSecondsrunTimeoutSecondsmaxRetryAttemptsretryBackoffSecondsschedulenodesedges
3.3 执行工作流
- 打开工作流
- 点击“运行”
- 查看执行状态
- 进入运行详情页查看节点状态、日志和产物
运行状态通常有:
pendingrunningcompletedfailed
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=BOSbucketprefixendpointaccessKeyIdsecretAccessKeyscanMode=INCREMENTAL
当前平台能力:
- 支持增量 source state
- 支持发现新目录后触发后续处理
- 支持在共享 PVC 上保存阶段 manifest 和中间态
目录级循环增量工作流推荐配置:
type=streamingkind=scanschedule.interval=20或更长maxConcurrentRuns=1scanMode=INCREMENTALincrementalUnit=DIRECTORYdirectoryDepth=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
- 第 1 轮:新增 2 个新目录,
这说明目录级模式已经满足“新增目录即触发整目录内容进入后续流程;老目录新增单文件不触发整目录重跑”的要求。
注意:
- 增量扫描依赖 source state
- 如果你重置 source state,下一次会重新把已有对象视为新对象
- 线上要确保
droboticflow-worker的OPERATOR_RUNNER_IMAGE已切到支持目录级增量的 runner;否则节点里即使写了INCREMENTAL_UNIT=DIRECTORY,实际运行也可能仍落到旧镜像
5. 运行和结果怎么看
每次运行至少有三层信息:
工作流级状态节点级状态artifact / manifest / 日志
建议排查顺序:
- 先看工作流是否
failed - 再看失败节点
- 再看该节点日志
- 再看该节点输出的
stage-manifest - 最后回溯上游 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




