forked from longtao.wu/droboticflow
333 lines
11 KiB
Markdown
333 lines
11 KiB
Markdown
# 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 项目页
|
||
|
||
项目页用于管理项目、查看项目内工作流,以及复制工作流。
|
||
|
||

|
||
|
||
常见操作:
|
||
|
||
- 新建项目
|
||
- 进入项目详情
|
||
- 在项目内新建工作流
|
||
- 复制已有工作流
|
||
- 删除工作流
|
||
|
||
说明:
|
||
|
||
- 现在“复制工作流”会完整保留工作流顶层参数
|
||
- 包括 `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 路径下的新目录/新文件。
|
||
|
||
```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)
|