This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

技术架构

本文所有事实均标注来源文件路径，可溯源核查。基于 deepdata-20260928 分支（commit ff22ed3）。

总体架构

DeepData 是双后端架构：Java 侧负责数据管理与 RAG 索引，Python 侧负责算子编排与任务调度，两者通过 HTTP 互调。

浏览器
  │
  ▼
前端 React18 + Vite7  (:30000)
  │ /api
  ▼
网关 Spring Cloud Gateway  (:8080)
  │ JWT / SSO 认证
  ├──▶ 主应用 Spring Boot 3.5.6  (context-path /api)
  │      ├── data-management-service
  │      ├── rag-indexer-service
  │      ├── domain-common / security-common
  │      └── actuator (health/info/metrics/prometheus)
  │
  └──▶ Python 后端 FastAPI  (:18000)
         ├── 归集 / 清洗 / 标注 / 采集/ 算子 / 评估 / 合成 / RAG
         └── MCP endpoint /mcp

存储层：PostgreSQL 15 · Milvus 2.6.5 · Redis 8.2.3 · MinIO
算子执行：Ray 2.7.0（可选） · DataJuicer v1.4.4（可选）

技术栈

后端（Java）

项	版本/实现	来源
Java	21	`backend/pom.xml` `maven.compiler.source/target`
Spring Boot	3.5.6	`backend/pom.xml` `spring-boot.version`
Spring Cloud	2025.0.0	`backend/pom.xml` `spring-cloud.version`
Spring AI	1.0.0-RC1（MCP starter 用 1.1.2）	`backend/pom.xml`、`backend/services/pom.xml`
MyBatis-Plus	3.5.14	`backend/pom.xml`
MapStruct	1.6.3	`backend/pom.xml`
Milvus SDK	`milvus-sdk-java` 2.6.6	`backend/pom.xml`
PostgreSQL 驱动	42.7.7	`backend/pom.xml` `postgresql.version`
JJWT（网关）	0.11.5	`backend/api-gateway/pom.xml`
Log4j2	2.21.1	`backend/pom.xml`
SpringDoc OpenAPI	2.2.0	`backend/pom.xml`

⚠️ 文档不一致：backend/README.md 写「Database: PostgreSQL 8.0.33」，但 8.0.33 实为 POM 里的 mysql.version 属性值，PostgreSQL 驱动是 42.7.7。该README 行不可直接引用。

后端（Python）

项	版本	来源
Python	`>=3.12,<4.0.0`	`runtime/deepdata-python/pyproject.toml`
FastAPI	`>=0.124.0,<0.125.0`	同上
fastapi-mcp	`>=0.4.0,<0.5.0`	同上（MCP 暴露）
SQLAlchemy	`>=2.0.45`（asyncpg 驱动）	同上
Pydantic	`>=2.12.5`	同上
Uvicorn	`>=0.38.0`	同上
APScheduler	`>=3.11.2`（任务调度）	同上
pymilvus	`>=2.6.0`	同上
LightRAG	`lightrag-hku==1.4.10`	同上
unstructured	0.18.21（文档解析）	同上
langchain4j	bom 1.8.0	`backend/services/rag-indexer-service/pom.xml`

版本差异：Python 服务声明 >=3.12，但 runtime 镜像基于 Python 3.11（ghcr.io/astral-sh/uv:python3.11-bookworm）。开发环境需注意。

前端

项	版本	来源
React	18.1.1	`frontend/package.json`
React Router	7.8.0（`createBrowserRouter`）	同上
Redux Toolkit	2.11.2 / react-redux 9.2.0	同上
Ant Design	5.27.0	同上
Tailwind CSS	4.1.12（`@tailwindcss/vite`）	同上
Vite	7.1.2	同上
TypeScript	~5.8.3	同上
xyflow（工作流画布）	`@xyflow/react` 12.8.3	同上
recharts（图表）	2.15.0	同上
3D 可视化	`react-force-graph-2d/3d`、`three-spritetext`	同上
文档预览	`react-pdf`、`mammoth`、`jszip`、`react-markdown`	同上
国际化	i18next 25.8.0 / react-i18next 16.5.4	同上

服务拆分

Java 侧模块

模块	职责	来源
`shared/domain-common`	DDD 构建块、异常处理	`backend/pom.xml`
`shared/security-common`	JWT 工具	同上
`services/data-management-service`	数据管理服务	`backend/services/data-management-service/pom.xml`
`services/rag-indexer-service`	RAG 文档索引（langchain4j + Milvus）	`backend/services/rag-indexer-service/pom.xml`
`services/main-application`	主启动应用，集成所有服务	`backend/services/main-application/pom.xml`
`api-gateway`	API 网关	`backend/api-gateway/pom.xml`

主应用端口：SERVER_PORT:8080，context-path /api（main-application/src/main/resources/application.yml）

Python 侧业务模块

runtime/deepdata-python/app/module/ 下的模块（来源 app/module/__init__.py 的 include_router）：

模块	注册到 API	说明
`system`	✅	系统设置（`t_sys_param`）
`annotation`	✅	标注
`cleaning`	✅	清洗
`collection`	✅	归集
`evaluation`	✅	评估
`generation`	✅	合成/生成
`ratio`	✅	配比
`operator`	✅	算子（含 operator_router + category_router）
`rag`	✅	知识库
`dataset`	❌	目录存在但未注册路由
`shared`	❌	内部公共库

Python 代码约定

来源 runtime/README.md：

路由放 interface/*.py
依赖注入用 Depends(get_db)
业务异常用 raise BusinessError(ErrorCodes.XXX)

Python 启动期行为

app/main.py 的 lifespan 中依次：

数据库连通性校验（SELECT 1，URL 密码打码）
打印 Label Studio 地址
启动collection 调度器
初始化任务执行器（max_workers=10, max_concurrent_tasks=5）
恢复清洗任务调度器
注册日志 PVC 监控定时任务

网关与认证

Spring Security 配置（重要）

backend/api-gateway/src/main/java/com/deepdata/gateway/common/config/SecurityConfig.java：

@EnableWebFluxSecurity
http.csrf(ServerHttpSecurity.CsrfSpec::disable)
    .authorizeExchange(exchange -> exchange.pathMatchers("**").permitAll());

类注释写明「安全配置 - 暂时禁用所有认证」，网关层全部放行。真正的鉴权由自定义 GlobalFilter 承担。

JWT 认证链路

AuthFilter.java（implements GlobalFilter, Ordered，getOrder()=2）流程：

公开路径放行：/api/user/login、/api/user/signup、/api/user/me
SSO 优先：请求头有 X-User-Name → 直接注入下游 User 头并放行
deepdata.jwt.enable=false（默认）→ 直接放行
Token 两种取法：Authorization: Bearer <token> 或 ?token=（注释说明用于 <a href>/预览场景避免 401）
校验失败返回 401
成功则注入 User header 给下游

JwtConfig.java：@ConfigurationProperties(prefix="deepdata.jwt")，字段 secret；@PostConstruct 校验 secret 非空，长度 < 32 打warn。过期 expiration-seconds: 604800（7 天）。

UserService.java：

签名算法 HS256，密钥 Keys.hmacShaKeyFor(secret.getBytes(UTF_8))
Claims：sub=username，附加 uid、role，含 iat/exp
密码 BCryptPasswordEncoder(10)
实现 register、changePassword

🔐 安全提示：JWT 认证在配置中默认关闭（deepdata.jwt.enable=false）。生产环境务必显式开启并设置足够强的 JWT_SECRET。

OMS 认证

OmsAuthFilter.java（getOrder()=1，优先级最高）：开关 oms.auth.enabled（默认 false）；从 Cookie __Host-X-Auth-Token / __Host-X-Csrf-Token 取令牌；真实 IP 依次从 X-Real-IP → X-Forwarded-For → Proxy-Client-IP → WL-Proxy-Client-IP → remoteAddress 解析；认证成功注入 X-User-Name。

服务发现

spring.cloud.nacos.discovery，server-addr: ${NACOS_ADDR:https://consulservice:18302}，cluster-name: DEFAULT（api-gateway/src/main/resources/application.yml）

⚠️ 未找到实际的 spring.cloud.gateway.routes 路由规则配置 —— README 中的路由示例仅为文档示例，yml 里没有。

算子执行引擎

双引擎设计

引擎	位置	说明
Ray 分布式执行	`runtime/python-executor/`	主路径，Ray 2.7.0
DataJuicer	compose profile `data-juicer`	容器 `datajuicer/data-juicer:v1.4.4`

`runtime/python-executor/` 结构

目录	职责
`deepdata/core/`	`base_op.py`（算子基类）、`dataset.py`、`constant.py`
`deepdata/scheduler/`	`scheduler.py`、`func_task_scheduler.py`、`cmd_task_scheduler.py`
`deepdata/wrappers/`	`executor.py`、`deepdata_wrapper.py`、`data_juicer_wrapper.py`
`deepdata/sql_manager/`	SQL 管理
`deepdata/operator_runtime.py`	运行时入口

算子基类

runtime/python-executor/deepdata/core/base_op.py：

基类	行号	语义
`OPERATORS = Registry("Operators")`	24	算子注册表
`BaseOp`	51	基类
`Mapper`	218	1:1 转换
`Slicer`	268	1:N 切片
`Filter`	370	返回布尔（true 保留/ false 剔除）
`LLM(Mapper)`	410	LLM 驱动，需实现 `build_llm_prompt`
`FileExporter`	499	文件导出

算子包规范

一个算子包 = 目录（来源 runtime/ops/README.md）：

<算子名>/
├── __init__.py      # 注册入口（必要）
├── metadata.yml     # 元数据 + UI 参数定义（必要）
├── process.py       # 逻辑实现（必要）
├── requirements.txt # 依赖（可选）
├── README.md        # 说明（可选）
└── sql/             # 可选：算子自带 SQL 配置

注册方式（runtime/ops/filter/remove_duplicate_file/__init__.py）：

from deepdata.core.base_op import OPERATORS
OPERATORS.register_module(module_name='DuplicateFilesFilter',
                          module_path="ops.filter.remove_duplicate_file.process")

打包上传规范：压缩包名（不含后缀）必须与 __init__.py 中 module_path 的包目录名一致，否则 ModuleNotFoundError。

算子执行时的 sample 字段约定

process.py 的 execute(sample: Dict) -> Dict 中 sample 结构：

字段	含义
`text`	文本内容
`data`	二进制/媒体数据
`fileName` / `fileType`	文件名/ 类型
`fileId` / `filePath` / `fileSize`	文件标识与存储信息
`export_path`	导出路径
`ext_params`	扩展参数
`target_type`	目标类型

runtime 镜像

scripts/images/runtime/Dockerfile：基于 ghcr.io/astral-sh/uv:python3.11-bookworm，安装系统依赖 libgl1、libmagic1、libreoffice、tesseract-ocr、poppler-utils，下载 PP-LCNet 文档方向检测模型到 /home/models。

算子目录拷入镜像：COPY runtime/ops /opt/runtime/deepdata/ops，ENV PYTHONPATH=/opt/runtime/deepdata/。

自定义算子开发

`my_ops/` 目录

仓库根级目录（与 runtime/ops/ 平级），平台方自建算子：

算子	raw_id	vendor	types	功能
`markitdown_parser`	`MarkItDownParser`	DeepData	collect	基于 MarkItDown 将docx/pptx/xlsx/pdf/html 等格式统一转 Markdown；支持图片上传/远程下载/Base64 内联
`mineru_pdf_parser`	`MinerUPdfParser`	DeepData	collect	调远端 MinerU FastAPI 解析 PDF 提取 Markdown + 图片；支持 Base64/本地保存/外传
`text_quality_evaluator`	`TextQualityEvaluator`	DeepData User	consolidate	LLM 多维度文本质量评分；支持自定义模型、分块策略、并发处理

my_ops/ 与 runtime/ops/ 分离：前者是自建算子（vendor: DeepData），后者是内置算子库（vendor: huawei）。

打包产物

my_ops/dist/ 下有已构建的 deepdata_mineru_pdf_parser-1.0.0-py3-none-any.{whl,zip}，命名带 deepdata_ 前缀，符合"压缩包名 = module_path 包目录名"规范。

数据模型

数据库

类型	版本/镜像	用途
PostgreSQL	`postgres:15-trixie`	主元数据库
Milvus	`milvusdb/milvus:v2.6.5`	向量库（:19530，管理 :9091）
Redis	`redis:8.2.3`	缓存/队列（:6379）
MinIO	`minio/minio:RELEASE.2024-12-18T13-15-44Z`	S3 兼容对象存储（Milvus 依赖）

初始化脚本创建两个库（scripts/db/00-database-init.sql）：deepdata、labelstudio（后者供 Label Studio 用）。

MySQL 仅作为 aiomysql/pymysql 依赖与配置项存在，部署 compose 中没有 MySQL 服务；默认 database_url 走 postgresql+asyncpg（app/core/config.py 的 build_database_url）。

表清单

模块	表
公共	`users`、`t_chunk_upload_request`（切片上传）、`t_lineage_node`、`t_lineage_edge`、`t_models`、`t_sys_param`
数据管理	`t_dm_datasets`、`t_dm_dataset_files`、`t_dm_dataset_statistics`、`t_dm_tags`、`t_dm_dataset_tags`
数据标注	`t_dm_annotation_templates`、`t_dm_labeling_projects`、`t_dm_auto_annotation_tasks`
数据清洗	`t_clean_template`、`t_clean_task`、`t_clean_result`
数据归集	`t_dc_collection_templates`、`t_dc_collection_tasks`、`t_dc_task_executions`
算子	`t_operator`、`t_operator_category`、`t_operator_category_relation`、`t_operator_instance`、`t_operator_release`
数据评估	`t_de_eval_task`、`t_de_eval_file`、`t_de_eval_item`
数据合成	`t_data_synth_instances`、`t_data_synthesis_file_instances`、`t_data_synthesis_chunk_instances`、`t_data_synthesis_data`
配比	`t_st_ratio_instances`、`t_st_ratio_relations`
知识库	`t_rag_knowledge_base`、`t_rag_file`

核心表：`t_dm_dataset_files`

来源 scripts/db/data-management-init.sql：

CREATE TABLE IF NOT EXISTS t_dm_dataset_files (
    id              VARCHAR(36) PRIMARY KEY,
    dataset_id      VARCHAR(36) NOT NULL,
    file_name       VARCHAR(255) NOT NULL,
    file_path       VARCHAR(1000) NOT NULL,
    file_type       VARCHAR(50),
    file_size       BIGINT DEFAULT 0,
    check_sum       VARCHAR(64),
    tags            JSONB,     -- 标注结果写入处
    tags_updated_at TIMESTAMP, -- 冲突消解用时间戳
    annotation      JSONB,
    metadata        JSONB,
    status          VARCHAR(50) DEFAULT 'ACTIVE',
    upload_time     TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    last_access_time TIMESTAMP,
    created_at      TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at      TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

ORM：runtime/deepdata-python/app/db/models/dataset_management.py:63

tags 写入路径（标签同步主体）：

文件	行为
`app/module/annotation/service/ls_annotation_sync.py:127,142`	直接更新 `tags` / `tags_updated_at` / `annotation`
`app/module/annotation/service/sync.py:606,629,800-809`	双向覆盖策略 `_should_overwrite_dm` / `_should_overwrite_ls` 比较时间戳决定谁覆盖
`app/module/dataset/service/service.py:197,460,538`	读写 `tags_updated_at`
`app/module/ratio/service/ratio_task.py:183,307,387`	写入并按时间区间筛选文件
`app/module/annotation/interface/task.py:252`	支持部分标签合并（只改提交的标签，其余保持）

数据库初始化机制

无 Flyway/Liquibase（未找到依赖与配置）
依赖 scripts/db/ 下 14 个幂等 DDL 脚本（CREATE TABLE IF NOT EXISTS）
由 scripts/images/database/Dockerfile 的 COPY scripts/db/ /docker-entrypoint-initdb.d/ 在容器首次初始化时执行
scripts/db/zz-final-task.sh 读取 HOME_PAGE_URL 环境变量，用 psql -v ON_ERROR_STOP=1 更新 t_sys_param.param_value where id='sys.home.page.url'

⚠️ 重要：docker-entrypoint-initdb.d 只在数据卷为空时执行一次。修改 SQL 后不会自动生效，需手工执行或重建卷。另注：调研发现 backend/api-gateway/migration/ 目录在当前分支不存在（在 main 分支存在）。

DataX 集成

runtime/datax/ 是精简版 DataX（groupId=com.alibaba.datax, artifactId=datax-all），完整源码在根目录 DataX/。

构建方式

scripts/images/backend-python/Dockerfile 第一阶段 datax-builder：

COPY DataX/ /DataX/
COPY runtime/datax/ DataX/（精简版覆盖部分路径）
mvn -U clean package assembly:assembly
sed 修复 MySQL 驱动名（com.mysql.jdbc.Driver → com.mysql.cj.jdbc.Driver）
第二阶段把 /DataX/target/datax/datax 拷到运行镜像 /opt/datax

调用方

runtime/deepdata-python/app/module/collection/client/datax_client.py：

self.datax_main = "/opt/datax/bin/datax.py"
subprocess.Popen 执行，支持超时、日志 tail/header 写入
目标类型白名单：{"nfswriter", "s3writer", "glusterfswriter"}；txtfilewriter 走单独分支

DataX 位于数据归集链路，不是通用算子执行链路。

deep-flow 子项目

DeepFlow（Deep Exploration and Efficient Research Flow）是内嵌的独立子项目，源自开源深度研究框架（README badge 指向 bytedance/deer-flow）。不是 git submodule（未找到 .gitmodules）。

关键文件：main.py、server.py、conf.yaml、langgraph.json、uv.lock、web/（前端）、src/、examples/、tests/

在平台中作为可选服务（compose profile deep-flow，服务 deep-flow-backend / deep-flow-frontend）。

Java → Python 调用桥：backend/services/rag-indexer-service/.../GraphRagClient.java 用 @FeignClient(name="rag-service", url="${collection.service.url:http://deepdata-backend-python:18000}")。

MCP 协议支持

侧	实现	Endpoint
Python	`fastapi-mcp`	`/mcp`
Java	`spring-ai-starter-mcp-server-webmvc` 1.1.2	`/mcp`，name `deepdata-mcp-server`，protocol `STATELESS`，tool capability 开启

前端路由表

来源 frontend/src/routes/routes.ts：

路径	页面
`/`	Home
`/chat`	Agent
`/orchestration`	SmartOrchestration
`/orchestration/create-workflow`	WorkflowEditor
`/data/collection`	数据归集
`/data/management`	数据管理
`/data/cleansing`	数据清洗
`/data/annotation`	数据标注
`/data/synthesis/task`	数据合成任务
`/data/synthesis/ratio-task`	配比任务
`/data/evaluation`	数据评估
`/data/knowledge-base`	知识库
`/data/operator-market`	算子市场

所有组件经 withErrorBoundary 包装。

上一页：产品功能｜ 下一页：部署指南