Dataflow

1. 概述

Dataflow 是 CSGHub 平台中的数据流管理与标注子系统，用于处理模型训练数据、标注任务、数据预处理与分发等流程。

通过 Helm Chart 部署，可以快速在 Kubernetes 环境中运行 Dataflow 及其依赖的 Label Studio 和 PostgreSQL 等组件。Dataflow 服务已不再需要 Redis 和 MongoDB（自 chart v2.2.0 移除）。本 Chart 既支持 一键安装全部依赖（内置模式），也支持 连接外部托管资源。

2. 环境要求

项目	说明
Kubernetes 版本	v1.33+
Helm 版本	v3.12+
网络要求	集群节点需能访问 CSGHub 主服务（externalUrl）
权限要求	具备创建命名空间、Service、PVC、Gateway 等资源的权限
集群要求	需要支持 ReadWriteOnce 的存储卷（v2.2.0 从 RWX 改为 RWO）

3. 开始部署

1. 添加 Helm 仓库

   helm repo add csghub https://charts.opencsg.com/csghub
   helm repo update

2. 创建命名空间（可选）

   kubectl create namespace csghub

3. 部署 Dataflow

   ⚠️ standalone 模式下 externalUrl 必填，且需保证从 Dataflow 所在集群可正常访问该 URL。

   helm get notes csghub -n csghub | grep -A 6 'Access your CSGHub'

   通过以上命令获取 CSGHub 访问地址。

• 执行部署操作

  💡 提示：建议将自定义配置写入 custom-values.yaml，方便后续升级与版本管理。

  helm install dataflow csghub/dataflow \
    --namespace csghub \
    --create-namespace \
    --set global.gateway.external.domain="example.com" \
    --set externalUrl="<csghub externalUrl>" \
    --set dataflow.postgresql.database="csghub_dataflow" \
    --set labelStudio.postgresql.database="csghub_label_studio"

  国内部署（使用国内镜像仓库加速拉取镜像）：

  helm install dataflow csghub/dataflow \
    --namespace csghub \
    --create-namespace \
    --set global.gateway.external.domain="example.com" \
    --set externalUrl="<csghub externalUrl>" \
    --set dataflow.postgresql.database="csghub_dataflow" \
    --set labelStudio.postgresql.database="csghub_label_studio" \
    --set global.image.registry="registry.opencsg.com" \
    --set global.imageRegistry="registry.opencsg.com/opencsghq"

  此方式会自动启动：

  • Dataflow 主服务

  • Label Studio 标注服务

  • 内置 PostgreSQL

  • 内置 Gateway API Controller 控制器

  ℹ️ v2.2.0 起 Dataflow 不再需要 Redis 和 MongoDB 依赖。 仅需 PostgreSQL。

4. 使用外部资源

建议在生产环境中使用外部托管数据库与缓存服务：

helm upgrade --install dataflow csghub/dataflow \
  --namespace csghub \
  --create-namespace \
  --set dataflow.postgresql.database="csghub_dataflow" \
  --set labelStudio.postgresql.database="csghub_label_studio" \
  -f custom-values.yaml

示例 custom-values.yaml：

global:
  gateway:
    external:
      domain: "company.com"
    tls:
      enabled: true
      secretName: "csghub-tls"

  postgresql:
    enabled: false
    external:
      host: "pg.company.com"
      port: 5432
      user: "csghub"
      password: "******"
      sslmode: "require"

externalUrl: "https://csghub.company.com"

ℹ️ chart v2.2.0 起 Dataflow 不再依赖 Redis 和 MongoDB。 当前 Dataflow chart 中已无 mongo.* / redis.* 配置块，仅需 PostgreSQL。

5. 配置说明

5.1 全局配置

参数	默认值	说明
global.gateway.external.domain	csghub.example.com	访问域名
global.image.tag	v2.5.0	镜像版本号
global.persistence.size	10Gi	默认持久化卷大小
global.postgresql.enabled	true	启用内置 PostgreSQL
global.postgresql.existingSecret	""	引用已有 Secret 提供 PostgreSQL 连接信息，仅在 enabled=false 时生效

💡 使用外部 PostgreSQL 时，也可以通过 global.postgresql.existingSecret 引用一个已存在的 Secret 来提供连接信息（无需把账号密码写进 values.yaml）。该 Secret 必须提前在 release 命名空间内创建，键名（需 base64 编码）支持：POSTGRES_HOST（必填）、POSTGRES_PORT、POSTGRES_USER、POSTGRES_PASSWORD、POSTGRES_SSLMODE。

5.2 服务配置

参数	默认值	说明
externalUrl	https://csghub.example.com	⚠️ 必填（standalone）。CSGHub 主系统访问地址
dataflow.image.repository	opencsghq/dataflow	Dataflow 镜像
dataflow.image.tag	v2.5.0-api	Dataflow 镜像 tag（v2.2.0 注意含 -api 后缀）
dataflow.persistence.size	50Gi	数据流持久化卷大小（v2.1.x 为 100Gi）
dataflow.persistence.accessModes	["ReadWriteOnce"]	PV 访问模式（v2.2.0 从 ReadWriteMany 改为）
dataflow.postgresql		可覆盖默认 PostgreSQL 配置

5.3 Label Studio配置

参数	默认值	说明
labelStudio.image.repository	opencsghq/label-studio	Label Studio 镜像
labelStudio.image.tag	v2.5.0	镜像版本
labelStudio.persistence.size	10Gi（继承 global.persistence.size）	标注数据持久化卷大小；如需更大请显式设置
labelStudio.securityContext.runAsUser	0	容器运行用户 UID
labelStudio.postgresql.database	"csghub_label_studio"	标注数据库名

5.4 内置第三方组件

组件	参数	默认值	说明
PostgreSQL	postgresql.image.repository	opencsghq/postgres	内置数据库镜像
	postgresql.databases	[csghub_dataflow, csghub_label_studio]	启动时自动创建的数据库
	postgresql.persistence.size	50Gi	持久化卷存储大小

ℹ️ v2.2.0 起 Dataflow 不再需要 Redis 和 MongoDB。 如需其他子 chart（如 csghub core）使用，通过 parent chart 的 global.redis.* / global.mongo.* 配置。

6. 验证部署

检查 Pod 状态：

kubectl get pods -n csghub

验证访问：

kubectl get svc -n csghub

功能验证需要对接到 CSGHub 。

7. 升级与卸载

7.1 升级 Chart

helm upgrade dataflow csghub/dataflow -n csghub -f custom-values.yaml

⚠️ 从 chart v2.1.x 升级到 v2.2.0 的 Breaking change：

1. StatefulSet → Deployment 迁移：Dataflow 工作负载从 StatefulSet 切换为 Deployment。旧 StatefulSet 的 PVC 不会被复用。升级前，备份数据库并删除旧 PVC：

   kubectl delete pvc data-<release-name>-dataflow-0 -n csghub

2. Pre-upgrade 迁移 Job：一个新的 pre-upgrade Helm hook Job 会自动运行。它通过 _migrations 表实现幂等追踪，执行 /scripts/*_dataflow_*.sql 中的脚本。初始迁移会快照并清空 6 张表（collection_tasks, data_format_tasks, datasources, deletion_status, job, workers）。升级前务必 dump csghub_dataflow 数据库。

7.2 卸载 Chart

helm uninstall dataflow -n csghub

8. 常见问题（FAQ）

问题	原因	解决方案
Dataflow 无法访问主系统	externalUrl 未正确配置	确认地址与 TLS 配置
Label Studio 启动失败	数据库或 PVC 配置错误	检查 PostgreSQL/Mongo 挂载路径
镜像拉取失败	私有仓库未配置凭据	添加 image.pullSecrets
升级卡住 / migration Job 失败	数据库迁移异常	查看 Job 日志（kubectl logs job -l app.kubernetes.io/name=dataflow -n csghub），从预升级 dump 恢复 csghub_dataflow 数据库