forked from longtao.wu/droboticflow
Include the accumulated workflow scheduling, run history, subtree rerun, operator UI, deployment, data asset, object storage, database browser, and documentation changes currently in the worktree.
8.6 KiB
8.6 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
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://wjzh-data-migration/wjzh-0330-Data-migration/__codex_incremental_directory_acceptance__/20260420T0002上完成 5 轮真实验收 - 最终工作流:
workflow-866f6e6fabb343c2fa6fd2171361cf7a - 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




