# Drobodata 平台使用手册 本文档面向平台使用者,覆盖项目、工作流、模板、运行、数据管理、对象存储和常见排障。文中截图来自当前线上环境,流程说明基于当前代码与真实运行行为。 ## 1. 平台结构总览 平台里最核心的 6 个对象是: - `项目`:一组相关工作流的容器 - `工作流`:由多个算子节点组成的 DAG - `模板`:可复用的工作流蓝本 - `运行`:某次工作流执行实例 - `Artifact`:算子之间传递的数据产物 - `数据源`:BOS、目录、JSON、CSV、Mongo 等外部输入 典型处理链路如下: ```mermaid flowchart LR A["项目"] --> B["工作流"] B --> C["运行"] C --> D["节点执行"] D --> E["Artifacts / Stage Manifest"] E --> F["上传结果 / 数据管理 / 成品包"] ``` ## 2. 主要页面 ### 2.1 项目页 项目页用于管理项目、查看项目内工作流,以及复制工作流。 ![项目列表](./assets/manuals/platform-projects.png) 常见操作: - 新建项目 - 进入项目详情 - 在项目内新建工作流 - 复制已有工作流 - 删除工作流 说明: - 现在“复制工作流”会完整保留工作流顶层参数 - 包括 `kind`、`scanConfig`、并发、超时、重试等 - 对扫描型工作流,数据源、`bucket/prefix`、`accessKeyId/secretAccessKey` 也会一并复制 ### 2.2 模板页 模板页用于沉淀标准流程、复制模板,以及从模板创建工作流。 ![模板页](./assets/manuals/platform-templates.png) 常见操作: - 创建空模板 - 将已有工作流保存为模板 - 复制模板 - 从模板创建新工作流 说明: - 现在“保存为模板”和“从模板创建工作流”都保留完整参数 - 包括 `scanConfig`、执行参数、节点、边、调度配置 ### 2.3 工作流编辑器 工作流编辑器用于配置节点、连接节点、保存和运行工作流。 ![工作流编辑器](./assets/manuals/platform-workflow-editor.png) 编辑器里的关键概念: - 左侧:算子面板 - 中间:画布 - 右侧或弹层:节点参数配置 - 顶部:保存、运行、导出模板等动作 当前约束: - 同一个输入端口只允许一条入边 - 如果需要上传多个不同结果,必须为每个结果添加独立的“结果上传”算子 ### 2.4 数据管理页 数据管理页用于查看扫描导入的数据、目录索引、成品包等。 ![数据管理](./assets/manuals/platform-data-assets.png) 适合查看: - 采集目录 - 视频、JSON、配置文件 - 成品包 - 运行产出 manifest - 上传后的 BOS 路径 ### 2.5 算子列表页 算子列表页用于查看当前内置算子、分类、描述和输入输出能力。 ![算子列表](./assets/manuals/platform-operators.png) ## 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 路径下的新目录/新文件。 ```mermaid 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` 模式下,如果老目录里只新增了一个文件,不会重新把这个目录当成新目录触发 一个稳定的目录级循环链路通常是: ```mermaid 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. 相关文档 - [API 文档](./api.md) - [运维文档](./operations.md) - [自定义算子手册](./custom-operator-manual.zh-CN.md) - [自定义算子 Markdown 体系](./custom-operators/README.md) - [内置算子手册](./builtin-operators-manual.zh-CN.md) - [内置算子分册索引](./operators/README.md) - [目录级循环增量工作流验收记录](./plans/2026-04-20-directory-incremental-loop-acceptance.md) - [算子开发文档](./operator-authoring.md)