docs: 建立 DeepData 完整百科（需求/产品/技术/部署/运维/使用）

以 deepdata-20260928 分支 (ff22ed3) 为基准建立六章百科，所有技术细节标注来源文件路径，可溯源核查。页面清单 - Home 架构总览、八大模块速览、快速上手 - 需求与定位痛点场景、目标角色、典型流程、选型判断 - 产品功能八大模块功能边界、算子分类清单 - 技术架构技术栈版本、服务拆分、算子执行引擎、数据模型 - 部署指南 Compose/K8s 双形态、端口矩阵、Makefile 目标 - 运维手册健康检查、日志体系、数据库机制、已知坑、排障 - 使用说明界面操作 + 完整收录 DeepData/CVAT 标注作业 SOP 内容要点 - 完整收录飞书《DeepData/CVAT的标注作业流程SOP》四阶段全文（任务发起/团队组建与分发/标注审核循环/结果回收）+ 状态机图 - 核实并记录 9 处文档与代码不一致（版本号、Makefile 目标、 README 描述与实际实现偏差等），标注为已知坑 - 标注安全风险：JWT 认证默认关闭、Spring Security 全放行作者: 沃巴蒂 <figmar@ccoop.cc>
2026-10-04 00:41:45 +08:00
parent 270189f5a1
commit f07f9c700d
7 changed files with 1763 additions and 1 deletions
@@ -1 +1,120 @@
-欢迎来到百科。
+# DeepData 一站式数据工作平台
+
+> 面向模型微调与 RAG 检索的企业级数据处理平台。覆盖数据归集、数据管理、算子市场、数据清洗、数据合成、数据标注、数据评估、知识生成八大核心模块。
+
+本百科随代码演进，内容以 `deepdata-20260928` 分支（commit `ff22ed3`）为基准。所有技术细节均标注来源文件路径，可溯源核查。
+
+---
+
+## 一句话定位
+
+DeepData 把「原始数据」变成「可训练、可检索的语料」——中间的清洗、标注、增强、评估全部在平台内编排完成。
+
+对比自建流水线：不需要自己拼 DataX + Spark清洗脚本 + Label Studio + 向量库 + 调度器，DeepData 提供的是**可视化编排 + 算子生态 + 一体化存储**。
+
+---
+
+## 八大核心模块
+
+| 模块 | 作用 | 主要入口 |
+|---|---|---|
+| 数据归集 | 从 NFS/S3/API/数据库拉数据入库 | `/data/collection` |
+| 数据管理 | 数据集、文件、标签、血缘管理 | `/data/management` |
+| 算子市场 | 算子注册、打包、上传、复用 | `/data/operator-market` |
+| 数据清洗 | 可视化编排清洗流水线 | `/data/cleansing` |
+| 数据合成 | 指令数据合成、配比任务 | `/data/synthesis/task`、`/data/synthesis/ratio-task` |
+| 数据标注 | 标注项目、自动标注、对接 Label Studio/CVAT | `/data/annotation` |
+| 数据评估 | 质量与效果评估 | `/data/evaluation` |
+| 知识生成 | RAG 知识库构建、索引 | `/data/knowledge-base` |
+
+另有可视化编排（`/orchestration`）与 Agent 对话入口（`/chat`）。
+
+---
+
+## 系统架构一览
+
+```
+                    ┌─────────────────────────┐
+   浏览器 ─────────▶ │  前端 React18 + Vite7│  :30000
+                    └───────────┬─────────────┘
+                                │ /api
+                    ┌───────────▼─────────────┐
+                    │  网关 Spring Cloud GW   │  :8080
+                    │  JWT 认证 / SSO / 限流   │
+                    └───────────┬─────────────┘
+             ┌──────────────────┴──────────────────┐
+┌────────────▼─────────────┐        ┌───────────────▼──────────────┐
+│  主应用 Spring Boot 3.5│        │  Python 后端 FastAPI        │
+│  集成所有业务服务       │        │  :18000                      │
+│  data-management       │◀──────▶│  归集/清洗/标注/算子调度    │
+│  rag-indexer           │        │  MCP endpoint /mcp          │
+└──────┬──────────┬───────┘        └────────┬──────────────┬───────┘
+       │          │                          │              │
+  ┌────▼────┐ ┌───▼────────┐          ┌──────▼─────┐  ┌────▼─────┐
+  │PostgreSQL│ │  Milvus    │          │   Redis    │  │Ray 集群  │
+  │  :5432  │  │  :19530    │          │   :6379    │  │ 算子执行  │
+  │ 主元数据 │  │ 向量索引   │          │            │  │(可选)    │
+  └─────────┘  └────────────┘          └────────────┘  └──────────┘
+                  ▲
+            ┌─────┴──────┐
+            │   MinIO    │ S3 兼容对象存储
+            └────────────┘
+```
+
+**关键特征**：主应用与 Python 后端是**双后端**架构 —— Java 侧做数据管理与 RAG 索引，Python 侧做算子编排与调度，两者通过 HTTP 互调。
+
+---
+
+## 核心概念
+
+| 概念 | 定义 | 说明 |
+|---|---|---|
+| 数据集 Dataset | 一批文件的集合 | UUID 主键，存于 `t_dm_datasets` |
+| 算子 Operator | 单一处理能力的最小单元 | 有 metadata.yml 描述，支持打包上传 |
+| 算子实例 Operator Instance | 算子在具体任务中的一次配置 | 存于 `t_operator_instance` |
+| 任务 Task | 一次数据处理执行 | 清洗/标注/合成/评估各自有任务表 |
+| Job | CVAT 侧的标注工作切片 | 大任务必须切分才能并行 |
+| 血缘 Lineage | 数据加工的上下游关系 | `t_lineage_node` + `t_lineage_edge` |
+
+---
+
+## 百科目录
+
+| 章节 | 内容 |
+|---|---|
+| [需求与定位](需求与定位) | 谁在用、解决什么问题、典型场景与选型判断 |
+| [产品功能](产品功能) | 八大模块的功能边界与设计意图 |
+| [技术架构](技术架构) | 技术栈、服务拆分、算子执行引擎、数据模型 |
+| [部署指南](部署指南) | Docker Compose 与 Helm K8s 两种形态 |
+| [运维手册](运维手册) | 日志、健康检查、备份、排障、已知坑 |
+| [使用说明](使用说明) | 界面操作指南、CVAT 标注 SOP |
+
+---
+
+## 快速上手
+
+```bash
+# 1. 准备环境变量
+cp deployment/docker/deepdata/.env.example deployment/docker/deepdata/.env
+# 编辑 .env，至少填写 DB_PASSWORD / JWT_SECRET / MINIO_* / LABEL_STUDIO_*
+
+# 2. 启动核心服务
+docker compose -f deployment/docker/deepdata/docker-compose.yml up -d
+
+# 3. 访问
+#    前端http://<host>:30000
+#    网关   http://<host>:8080
+```
+
+**首次部署注意**：PostgreSQL 初始化脚本只在**数据卷为空时**执行一次（`docker-entrypoint-initdb.d` 机制）。修改 `scripts/db/*.sql` 后不会自动生效，需手工执行或重建数据卷。
+
+---
+
+## 版本与分支
+
+| 分支 | 说明 | commit |
+|---|---|---|
+| `main` | 早期基线（含 Casdoor SSO 认证与 GitHub Actions CI） | `cbb1048` |
+| `deepdata-20260928` | 当前开发基线，本次代码与功能变更所在分支 | `ff22ed3` |
+
+`main` 上的 `.github/workflows/` CI 与 Casdoor SSO 模块在 `deepdata-20260928` 中不存在 —— 后者基于国内交付版本（走自建镜像仓库）。详见 [运维手册](运维手册#分支差异)。
@@ -0,0 +1,221 @@
+# 产品功能
+
+> 本文说明八大模块的**功能边界**与**设计意图**。具体操作步骤见[使用说明](使用说明)，技术实现见[技术架构](技术架构)。
+
+---
+
+## 模块总览
+
+```
+数据归集 → 数据管理 → 数据清洗 → 数据评估 → 数据合成 → 知识生成
+                ↓         ↓
+              数据标注  算子市场（支撑清洗/合成/评估）
+```
+
+算子市场是**横向支撑**模块 —— 清洗、合成、评估都依赖算子；归集与管理是**纵向主线**。
+
+---
+
+## 1. 数据归集（Collection）
+
+### 能力
+把外部数据源搬进平台，统一管理来源与归集状态。
+
+### 支持的数据源
+
+| 类型 | 实现 | 说明 |
+|---|---|---|
+| NFS | `runtime/datax/nfswriter` | 支持 MountUtil挂载 |
+| S3/对象存储 | `runtime/datax/s3reader`、`s3writer` | 含 `HttpEndpointSecurity` |
+| GlusterFS | `runtime/datax/glusterfsreader` / `writer` | 分布式文件系统 |
+| HTTP API | `runtime/datax/apireader` | 含端点安全校验 |
+| 数据库 | `DataX/` 完整插件集 | mysql/postgresql/milvus/hdfs 等近百个 |
+| 文件数据库 | `txtfilewriter` | 单独分支处理 |
+
+### 归集方式
+- **归集模板**：可复用的归集配置（`t_dc_collection_templates`）
+- **归集任务**：基于模板发起执行（`t_dc_collection_tasks`）
+- **执行明细**：每次执行的日志与结果（`t_dc_task_executions`）
+
+### 设计意图
+归集是链路的**入口**，设计上强调"来源可追溯"。每条数据都能回溯到是从哪个源、按什么配置采来的。
+
+---
+
+## 2. 数据管理（Management）
+
+### 能力
+平台的数据资产中心，管理数据集、文件、标签、血缘。
+
+### 核心概念
+- **数据集（Dataset）**：UUID 主键，文件集合的容器（`t_dm_datasets`）
+- **数据集文件**：每行一个文件记录，含路径、类型、大小、校验和（`t_dm_dataset_files`）
+- **标签体系**：可复用的标签定义（`t_dm_tags`）与数据集标签关联（`t_dm_dataset_tags`）
+- **统计信息**：文件数、总量等汇总（`t_dm_dataset_statistics`）
+
+### 关键字段：`tags`
+
+`t_dm_dataset_files.tags` 是**JSONB 字段**，承载标注结果（类别、坐标等结构化数据）。配套的 `tags_updated_at` 时间戳用于**双向同步的冲突消解** —— 同步时比较两边时间戳，谁新谁覆盖谁。
+
+详见[技术架构 · 数据模型](技术架构#数据模型) 与 [标注 SOP 第四阶段](使用说明#阶段-4结果回收deepdata)。
+
+### 血缘
+`t_lineage_node`（实体对象）+ `t_lineage_edge`（处理流程）记录数据加工链路，支持追溯"这个文件是怎么来的"。
+
+---
+
+## 3. 算子市场（Operator Market）
+
+### 能力
+算子的注册、打包、上传、分发与版本管理。
+
+### 算子分类
+
+| 类别 | 数量 | 作用 | 示例 |
+|---|---|---|---|
+| `filter` | 10 | 过滤/剔除 | `remove_duplicate_file`（MinHash+Jaccard 相似文档去除）、`remove_file_with_many_sensitive_words`、`img_blurred_images_cleaner` |
+| `mapper` | 33 | 1:1 转换 | `content_cleaner`、`email_cleaner`/`phone_cleaner`/`id_number_cleaner`（PII 清洗）、`traditional_chinese`、`img_enhanced_brightness`（图像增强） |
+| `slicer` | 3 | 1:N 切片 | `slide_annotation_slicer`、`slide_simple_slicer` |
+| `formatter` | 2 | 格式转换 | `mineru_formatter`、`slide_formatter` |
+| `llms` | 2 | LLM 驱动 | `qa_condition_evaluator`、`text_quality_evaluation` |
+| `annotation` | 0 | 预留 | 目录存在但暂无实现 |
+| `user` | 0 | 自定义算子落地点 | 算子市场上传的算子落在这里 |
+| `examples` | 1 | 示例模板 | `test_operator` |
+
+### 算子元数据（`metadata.yml`）
+
+关键字段：
+
+| 字段 | 作用 | 注意 |
+|---|---|---|
+| `raw_id` | 算子唯一标识 | **必须与 `process.py` 里的类名完全一致** |
+| `types` | 适用场景 | cleanse/cleaning/annotation/collect/consolidate |
+| `modal` / `inputs` / `outputs` | 数据模态 | text/image/audio/video |
+| `runtime` | 资源声明 | memory/cpu/gpu/npu/storage |
+| `settings` | UI 渲染定义 | slider/switch/select/inputNumber/multiSelect 等 |
+
+`settings` 直接决定前端参数面板怎么渲染 —— 这是算子"零代码可配"的关键。
+
+### 内置算子来源
+
+内置算子的 `vendor` 为 `huawei`（`runtime/ops/` 下），而 `my_ops/` 下的自建算子 `vendor` 为 `DeepData` / `DeepData User`，两者分离。详见[自定义算子开发](技术架构#自定义算子开发)。
+
+---
+
+## 4. 数据清洗（Cleansing）
+
+### 能力
+可视化编排的数据清洗流水线，支持 DataJuicer 引擎。
+
+### 核心流程
+1. 从数据集选择待清洗数据
+2. 拖拽算子到画布，连线成流水线
+3. 配置每个算子的参数（来自 `settings`）
+4. 提交任务，由Ray 集群（或本地 runtime）执行
+5. 清洗结果写入新数据集或原地更新
+
+### 关键表
+`t_clean_template`（模板）、`t_clean_task`（任务）、`t_clean_result`（结果）
+
+### 执行引擎
+- 主路径：Ray 分布式执行（`runtime/python-executor`，Ray 2.7.0）
+- 可选：DataJuicer 容器（compose profile `data-juicer`，镜像 `datajuicer/data-juicer:v1.4.4`）
+
+### 设计意图
+清洗是**最需要反复调参**的环节，所以做成可视化编排 —— 改参数不需要改代码，流水线拓扑一眼可见。
+
+---
+
+## 5. 数据合成（Synthesis）
+
+### 能力
+基于 LLM 生成指令数据，并支持多数据集按配比混合。
+
+### 两种任务
+| 任务 | 表 | 说明 |
+|---|---|---|
+| 合成任务 | `t_data_synth_instances`、`t_data_synthesis_file_instances`、`t_data_synthesis_chunk_instances`、`t_data_synthesis_data` | 单个合成任务，按 chunk 分块执行 |
+| 配比任务 | `t_st_ratio_instances`、`t_st_ratio_relations` | 多数据集按比例混合 |
+
+### 设计意图
+微调数据往往需要"通用指令 + 领域指令 + 安全指令"按特定比例混合。配比任务让这个比例**可配置、可复用**，而不是靠人工拼文件。
+
+---
+
+## 6. 数据标注（Annotation）
+
+### 能力
+标注项目管理，支持对接外部标注平台。
+
+### 支持的标注平台
+
+| 平台 | 对接方式 | 特点 |
+|---|---|---|
+| **Label Studio** | 内置双向同步服务 | 原生集成，支持自动标注、标签双向合并 |
+| **CVAT** | 任务创建时指定平台 | 适合大批量图像标注，支持 Job 切分分工 |
+
+### 核心表
+`t_dm_annotation_templates`（标注模板）、`t_dm_labeling_projects`（标注项目）、`t_dm_auto_annotation_tasks`（自动标注任务）
+
+### 标注结果同步
+Label Studio 侧通过 `ls_annotation_sync.py` / `sync.py` 双向同步，写入 `t_dm_dataset_files.tags`，用 `tags_updated_at` 做冲突消解。
+
+CVAT 侧由用户在界面上点击"同步到数据库"触发拉取，详见 [CVAT 标注 SOP](使用说明#六deepdatacvat-标注作业流程sop)。
+
+### 自动标注
+`AUTO_ANNOTATION_ENABLED` 开关 + `ANNOTATION_MODEL_ENDPOINT` 配置模型端点，可先用模型跑一遍生成预标注（Pre-annotations），人工只需修正 —— **提效显著**（见 SOP 避坑建议）。
+
+---
+
+## 7. 数据评估（Evaluation）
+
+### 能力
+对数据集或合成结果做质量/效果评估。
+
+### 核心表
+`t_de_eval_task`（评估任务）、`t_de_eval_file`（文件级）、`t_de_eval_item`（条目级）
+
+### 评估方式
+- 规则类算子：如`text_quality_evaluation`（LLM 多维度打分）
+- QC 流程：`QC_ENABLED` / `QC_THRESHOLD` 配置阈值后可触发拦截
+
+---
+
+## 8. 知识生成（Knowledge Base / RAG）
+
+### 能力
+把处理好的语料转成可检索的向量知识。
+
+### 技术路径
+```
+文档 → 解析(MinerU / unstructured) → 切片(slicer) → 向量化(langchain)
+→ Milvus 索引 → rag-indexer-service 提供检索
+```
+
+### 关键组件
+| 组件 | 作用 |
+|---|---|
+| `rag-indexer-service` | Java 侧 RAG 索引服务，用 langchain4j |
+| `Milvus` | 向量库（`milvusdb/milvus:v2.6.5`，端口 19530） |
+| `MinIO` | Milvus 的对象存储层 |
+| `LightRAG` | GraphRAG增强（`lightrag-hku==1.4.10`） |
+| `GraphRagClient` | Java → Python 的 GraphRAG 调用桥 |
+
+### 核心表
+`t_rag_knowledge_base`（知识库）、`t_rag_file`（知识库文件）
+
+### 解析器依赖
+`unstructured 0.18.21`、langchain4j 的 pdfbox/tika/poi/markdown 解析器
+
+---
+
+## 跨模块：Agent 与编排
+
+| 能力 | 入口 | 说明 |
+|---|---|---|
+| Agent 对话 | `/chat` | 前端 Agent 页，配合 MCP 协议 |
+| 可视化编排 | `/orchestration` | 基于 `@xyflow/react` 的工作流画布，用于多步骤任务编排 |
+
+---
+
+**上一页**：[需求与定位](需求与定位) ｜ **下一页**：[技术架构](技术架构)
@@ -0,0 +1,321 @@
+# 使用说明
+
+> 界面操作指南 + 完整标注作业 SOP。
+
+---
+
+## 一、登录与首页
+
+访问 `http://<host>:30000`，使用平台账号登录。首页提供各模块入口与统计概览。
+
+**修改密码**：右上角头像 → 修改密码，需提供旧密码，新密码最少 6 位（后端 `ChangePasswordRequest` 约束：旧密码非空、新密码非空且长度 ≥ 6）。
+
+---
+
+## 二、数据归集
+
+`数据归集` → 新建归集模板 → 配置数据源 → 创建归集任务。
+
+支持 NFS / S3 / GlusterFS / HTTP API / 数据库（DataX 全插件）/ 文件数据库。选择源时需填写连接参数与目标路径。
+
+任务执行状态存于 `t_dc_collection_tasks`，明细在 `t_dc_task_executions`。
+
+---
+
+## 三、数据管理
+
+`数据管理` → 创建数据集 → 上传/导入文件。
+
+**上传方式**：直接上传 / 归集导入 / 分片上传（大文件走 `t_chunk_upload_request`）。
+
+**标签体系**：在数据集上配置标签（`t_dm_tags`），支持 `t_dm_dataset_tags` 关联。
+
+**血缘追溯**：`t_lineage_node` + `t_lineage_edge` 记录加工链路，可查"这个文件怎么来的"。
+
+---
+
+## 四、数据清洗
+
+`数据清洗` → 创建清洗模板 → 拖拽算子到画布 → 连线编排 → 配置参数 → 提交。
+
+### 参数面板说明
+
+算子的参数面板由`metadata.yml` 的 `settings` 字段驱动，零代码生成：
+
+```yaml
+settings:
+  fileDuplicateThreshold:
+    type: slider
+    label: 相似度阈值
+    defaultVal: 0.5
+    min: 0
+    max: 1
+    step: 0.1
+```
+
+支持的控件类型：`slider` / `switch` / `select` / `radio` / `range` / `checkbox` / `input` / `textarea` / `inputNumber` / `multiSelect`。
+
+### 常用算子速查
+
+| 需求 | 算子 |
+|---|---|
+| 去除相似文档 | `remove_duplicate_file`（MinHash + Jaccard） |
+| 过滤敏感词 | `remove_file_with_many_sensitive_words` |
+| 文本清洗 | `content_cleaner`、`extra_space_cleaner`、`garble_characters_cleaner` |
+| 全半角统一 | `full_width_characters_cleaner` |
+| 简繁转换 | `traditional_chinese` |
+| PII 清洗 | `email_cleaner`、`phone_number_cleaner`、`id_number_cleaner`、`ip_address_cleaner`、`url_cleaner`、`credit_card_number_cleaner` |
+| 图像增强 | `img_enhanced_brightness` / `contrast` / `saturation` / `sharpness` |
+| 图像纠偏 | `img_direction_correct`、`img_perspective_transformation` |
+| 模糊图剔除 | `img_blurred_images_cleaner` |
+| 广告图剔除 | `img_advertisement_images_cleaner` |
+| 文档解析 | `mineru_formatter`、`MarkItDownParser`（自建）、`MinerUPdfParser`（自建） |
+| 质量评分 | `text_quality_evaluation`、`TextQualityEvaluator`（自建） |
+
+### 文档解析算子配置
+
+**MarkItDownParser**（`my_ops/markitdown_parser`）：支持 `doc_formats` 多选（docx/doc/xlsx/pptx/txt/csv/xml/html/htm 等）、`download_remote_images`（远程图片下载）、`embed_images_base64`（Base64 内联）、`max_image_width`、`upload_images`。
+
+**MinerUPdfParser**（`my_ops/mineru_pdf_parser`）：需配置 `mineruApi`（远端服务地址）、`server_url`、`backend`（pipeline / vlm-http-client / hybrid-http-client）、`lang_list`（默认 `ch`）、`parse_method`（auto/ocr/txt）、`formula_enable`、`table_enable`、`return_images`、`timeout`（60~3600秒，默认 900）。需确保 MinerU 服务已启动（compose profile `mineru`，需 Ascend NPU）。
+
+> ⚠️ 两个算子的 API 地址与图床地址默认值指向内网地址，部署到新环境时**必须修改**。
+
+---
+
+## 五、数据标注
+
+### 5.1 创建标注任务
+
+`数据标注` → 创建标注任务：
+
+1. 选择数据集
+2. **平台选择**：Label Studio 或 CVAT
+3. 选择标注模板（如目标检测）
+4. 确定
+
+创建后在任务列表可见，Label Studio 侧显示"前往 CVAT/LS"，且外部平台后台已生成对应任务。
+
+### 5.2 Label Studio 同步特点
+
+Label Studio 走**内置双向同步服务**：
+- `ls_annotation_sync.py` 更新 `tags` / `tags_updated_at` / `annotation`
+- `sync.py` 实现双向覆盖，按 `tags_updated_at` 比较决定谁覆盖谁
+- `interface/task.py` 支持部分标签合并（只改提交的标签，其余保持）
+
+自动标注：开启 `AUTO_ANNOTATION_ENABLED` + 配置 `ANNOTATION_MODEL_ENDPOINT` 后，可先由模型生成预标注。
+
+### 5.3 CVAT 作业流程
+
+见[下一节](#六deepdatacvat-标注作业流程sop)。
+
+---
+
+## 六、DeepData/CVAT 标注作业流程SOP
+
+> 本节完整收录《DeepData/CVAT的标注作业流程SOP》，核心原则：**DeepData 负责"管数据（发起与回收）"，CVAT 负责"管人与流程（分配、标注、审核）"**。
+>
+> 以下为针对**图片**标注任务的完整实操流程（示例：1000 张图）。
+
+### 阶段 1：任务发起（DeepData）
+
+**操作人**：数据管理员
+
+1. **创建标注任务：**
+   - 登录 DeepData → 进入"数据标注" → 点击"创建标注任务"。
+   - 选择包含 1000 张图的数据集。
+   - 关键设置：平台选择 **CVAT**，选择合适的标注模板（如"目标检测"）。
+   - 点击确定。
+
+2. **确认状态：**
+   - 在任务列表中看到新任务，显示"前往 CVAT"。
+   - 此时 CVAT 后台已生成了一个包含 1000 张图的任务（Task）。
+
+### 阶段 2：团队组建与任务分发（CVAT）
+
+**操作人**：项目经理（Supervisor/Admin）
+
+#### 1. 组建团队（Organization）
+
+如果是第一次使用，需先建组；已建组可跳过。
+
+- 登录 CVAT，点击右上角头像 → Settings → Organizations。
+- 点击 Create Organization（如命名为 `DeepData_Label_Team`）。
+- 点击 Invite，输入标注员和审核员的邮箱，邀请他们加入。
+- **分配角色**：
+  - 标注人员设置为 **Worker**（只能标注）。
+  - 审核人员设置为 **Reviewer** 或 **Supervisor**（能审核）。
+
+#### 2. 任务切分（Segmentation）—— 关键步骤
+
+1000 张图太大，必须拆分成小块（Jobs）才能分给多人同时做。
+
+- 在 CVAT 左侧菜单点击 **Tasks**，找到 DeepData 创建的任务（通常以 DeepData 任务名命名，如 `cvat8-检测`）。
+- 进入任务详情页，找到 **Jobs** 标签页。
+- 点击右上角 **Edit** 或 **Settings**。
+- 设置 **Job Size**（切分粒度）：
+  - 建议设置为 **20-50 张图/Job**。
+  - 例如：设为 50，系统会自动将 1000 张图切分为 **20 个 Job**。
+  - 保存设置（系统可能需要一点时间处理切片）。
+
+#### 3. 分配工作（Assignment）
+
+- 在 Jobs 列表中，你会看到 20 个 Job。
+- **指派标注员（Assignee）**：
+  - 点击 Job 1 → Assignee 下拉框 → 选择标注员 A。
+  - 依次将 20 个 Job 分配给组内的 Worker。
+- **指派审核员（Reviewer）**：
+  - 点击 Job 1 → Reviewer 下拉框 → 选择审核员 B。
+  - 建议一人审核多个 Job。
+
+### 阶段 3：标注与审核执行（CVAT）
+
+**操作人**：标注员 & 审核员
+
+#### 1. 标注员工作（Worker）
+
+- 登录 CVAT，点击左侧 **Jobs → Assigned to me**。
+- 打开分配的 Job，进入标注界面。
+- 操作：
+  - 根据模板要求画框/选标签。
+  - 完成后点击工具栏的 **Save** 和 **Submit** 按钮。
+- **状态流转**：Job 状态从 `annotation` 变为 `validation`（待审核）。
+
+#### 2. 审核员工作（Reviewer）
+
+- 登录 CVAT，点击左侧 **Jobs → Validation**（待我审核）。
+- 打开状态为 `validation` 的 Job。
+- 检查标注质量：
+  - ✅ **通过**：点击 **Accept** → Job 状态变为 `completed`。
+  - ❌ **驳回**：点击 **Reject** 并在评论区写明原因（如"漏标"、"框不准"）→ Job 状态**回退为 `annotation`**，标注员收到通知需重新修改。
+- **循环**：标注员修改后再次提交，直到所有 Job 状态均为 `completed`。
+
+### 阶段 4：结果回收（DeepData）
+
+**操作人**：数据管理员
+
+1. **确认完工：**
+   - 在 CVAT 任务列表中，确认该 Task 进度为 **100%**，所有 Job 状态为 `completed`。
+
+2. **同步回 DeepData：**
+   - 回到 DeepData 平台 → "标注任务列表"。
+   - 找到对应任务，点击 **"同步到数据库"** 按钮。
+   - **系统行为**：DeepData 会连接 CVAT，拉取所有图片对应的最终 JSON 标注数据，并写入 `t_dm_dataset_files` 表的 `tags` 字段。
+
+3. **验证数据：**
+   - 进入"数据管理" → 找到原始数据集。
+   - 查看文件列表的"标签/标注"列，应显示具体的类别名称（如 Person, Car）。
+   - 点击文件预览，右侧信息栏应显示结构化的标注详情。
+
+4. **归档/导出（可选）：**
+   - 点击任务右侧的"导出标注结果"，将最终成果打包下载或存入数据集归档。
+
+### 流程总结图解
+
+| 步骤 | 平台 | 动作 | 状态变化 |
+|---|---|---|---|
+| 1 | DeepData | 创建任务，选定数据集 | 数据进入 CVAT |
+| 2 | CVAT | 切分 Job（1000→20 个） | Task 拆分为 Job 列表 |
+| 3 | CVAT | 分配人员（Assignee/Reviewer） | Job 关联到具体用户 |
+| 4 | CVAT | 工人标注 → 提交 | `annotation` → `validation` |
+| 5 | CVAT | 审核员验收 → 通过 | `validation` → `completed` |
+| 6 | DeepData | 点击"同步到数据库" | JSON 数据写入 DeepData |
+
+### 针对 1000 张图的建议
+
+- ⚠️ **务必切分**：千万不要让一个人标 1000 张图，必须切成 20-50 张一组。
+- 💡 **预标注（进阶）**：如果想提效，可以在 DeepData 侧先用模型跑一遍"自动标注"，同步到 CVAT 作为初始数据（Pre-annotations），工人只需要修正错误，**速度会快 3 倍以上**。
+
+### 角色速查
+
+| 角色 | 平台 | 能做什么 |
+|---|---|---|
+| 数据管理员 | DeepData | 创建任务、同步结果、导出归档 |
+| Supervisor/Admin | CVAT | 建组、邀请、切分 Job、分配人员 |
+| Worker | CVAT | 标注、提交 |
+| Reviewer/Supervisor | CVAT | 审核、Accept/Reject |
+
+### Job 状态机
+
+```
+annotation ──Submit──▶ validation ──Accept──▶ completed
+     ▲                        │
+     └────────Reject──────────┘
+```
+
+---
+
+## 七、数据评估
+
+`数据评估` → 创建评估任务 → 选择待评估文件 → 配置评估维度 → 执行。
+
+常用评估方式：
+- LLM 多维度评分：`text_quality_evaluation` 算子 / `TextQualityEvaluator` 自建算子
+- QC 拦截：配置 `QC_ENABLED` + `QC_THRESHOLD`
+
+评估结果分三级落库：任务（`t_de_eval_task`）→ 文件（`t_de_eval_file`）→ 条目（`t_de_eval_item`）。
+
+---
+
+## 八、数据合成
+
+### 合成任务
+
+`数据合成` → 创建合成任务 → 配置数据源与提示词 → 执行。
+
+任务按 chunk 分块执行，明细见 `t_data_synthesis_file_instances`、`t_data_synthesis_chunk_instances`。
+
+### 配比任务
+
+用于多数据集按比例混合（如通用指令 50% + 领域指令 30% + 安全指令 20%）。
+
+配置见 `t_st_ratio_instances` / `t_st_ratio_relations`。
+
+---
+
+## 九、知识生成（RAG）
+
+`知识库` → 创建知识库 → 上传文档 → 解析切片 → 向量化 → 完成。
+
+**技术链路**：
+
+```
+文档 → MinerU / unstructured 解析 → slicer 切片
+     → 向量化(langchain) → Milvus 索引 → rag-indexer-service 提供检索
+```
+
+**依赖服务**：Milvus（:19530）、MinIO（Milvus 存储层）、GraphRAG（LightRAG 增强）
+
+> 可用 LLM 评分相关配置：`t_rag_knowledge_base`、`t_rag_file`
+
+---
+
+## 十、算子市场
+
+`算子市场` → 上传自定义算子 → 配置参数 → 在清洗/合成流程中使用。
+
+### 上传规范
+
+压缩包名（不含后缀）**必须**与 `__init__.py` 中 `module_path` 的包目录名一致，否则 `ModuleNotFoundError`。
+
+包内必需文件：`__init__.py`、`metadata.yml`、`process.py`。
+
+### 常见上传失败
+
+| 报错 | 原因 |
+|---|---|
+| `ModuleNotFoundError` | 压缩包名与 `module_path` 包目录名不一致 |
+| 算子不出现在列表 | `metadata.yml` 中 `raw_id` 与 `process.py` 类名不一致 |
+| 参数面板空白 | `settings` 字段缺失或格式错误 |
+
+---
+
+## 十一、可视化编排与 Agent
+
+| 入口 | 用途 |
+|---|---|
+| `/orchestration` | 基于 xyflow 的工作流画布，多步骤任务编排 |
+| `/chat` | Agent 对话入口，配合 MCP 协议（Python 侧 `/mcp`、Java 侧 `/mcp`） |
+
+---
+
+**上一页**：[运维手册](运维手册) ｜ **返回**：[首页](Home)
@@ -0,0 +1,440 @@
+# 技术架构
+
+> 本文所有事实均标注来源文件路径，可溯源核查。基于 `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 中依次：
+1. 数据库连通性校验（`SELECT 1`，URL 密码打码）
+2. 打印 Label Studio 地址
+3. 启动collection 调度器
+4. 初始化任务执行器（`max_workers=10, max_concurrent_tasks=5`）
+5. 恢复清洗任务调度器
+6. 注册日志 PVC 监控定时任务
+
+---
+
+## 网关与认证
+
+### Spring Security 配置（重要）
+
+`backend/api-gateway/src/main/java/com/deepdata/gateway/common/config/SecurityConfig.java`：
+
+```java
+@EnableWebFluxSecurity
+http.csrf(ServerHttpSecurity.CsrfSpec::disable)
+    .authorizeExchange(exchange -> exchange.pathMatchers("**").permitAll());
+```
+
+类注释写明「安全配置 - 暂时禁用所有认证」，**网关层全部放行**。真正的鉴权由自定义 `GlobalFilter` 承担。
+
+### JWT 认证链路
+
+**`AuthFilter.java`**（`implements GlobalFilter, Ordered`，`getOrder()=2`）流程：
+
+1. 公开路径放行：`/api/user/login`、`/api/user/signup`、`/api/user/me`
+2. **SSO 优先**：请求头有 `X-User-Name` → 直接注入下游 `User` 头并放行
+3. `deepdata.jwt.enable=false`（默认）→ 直接放行
+4. Token 两种取法：`Authorization: Bearer <token>` 或 `?token=`（注释说明用于 `<a href>`/预览场景避免 401）
+5. 校验失败返回 401
+6. 成功则注入 `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`）：
+
+```python
+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`：
+
+```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`：
+
+1. `COPY DataX/ /DataX/`
+2. `COPY runtime/datax/ DataX/`（精简版覆盖部分路径）
+3. `mvn -U clean package assembly:assembly`
+4. sed 修复 MySQL 驱动名（`com.mysql.jdbc.Driver` → `com.mysql.cj.jdbc.Driver`）
+5. 第二阶段把 `/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` 包装。
+
+---
+
+**上一页**：[产品功能](产品功能) ｜ **下一页**：[部署指南](部署指南)
@@ -0,0 +1,278 @@
+# 运维手册
+
+> 基于 `deepdata-20260928` 分支（commit `ff22ed3`）。本文记录**日常运维操作**与**已核实的已知问题**。
+
+---
+
+## 一、健康检查
+
+### Actuator（Java 主应用）
+
+`backend/services/main-application/src/main/resources/application.yml`：
+
+```yaml
+management:
+  endpoints:
+    web:
+      exposure:
+        include: health,info,metrics,prometheus
+  endpoint:
+    health:
+      show-details: when-authorized
+  health:
+    elasticsearch:
+      enabled: false      # 显式禁用 ES 健康检查
+```
+
+访问路径（主应用 context-path 为 `/api`）：
+
+```
+http://<host>:8080/api/actuator/health
+http://<host>:8080/api/actuator/info
+http://<host>:8080/api/actuator/metrics
+http://<host>:8080/api/actuator/prometheus
+```
+
+### Compose healthcheck
+
+**只有 Milvus profile 的三个服务配了 healthcheck**（`deployment/docker/deepdata/docker-compose.yml`）：
+
+| 服务 | 检查命令 | 参数 |
+|---|---|---|
+| `etcd` | `etcdctl endpoint health` | interval 30s / timeout 20s / retries 3 |
+| `minio` | `curl -f http://localhost:9000/minio/health/live` | 30s / 20s / 3 |
+| `milvus` | `curl -f http://localhost:9091/healthz` | 30s / 20s / 3，**start_period 90s** |
+
+> ⚠️ **注意**：核心业务服务（backend / backend-python / gateway / frontend / runtime）**都没有 healthcheck**，Dockerfile 里也没有 `HEALTHCHECK` 指令。容器"running"不代表服务可用 —— 需靠外部探针或人工确认。
+
+### Python 启动期检查
+
+`app/main.py` lifespan 中会做数据库连通性校验（`SELECT 1`，URL 密码打码），失败则启动失败。这属于**启动期一次性检查**，非常驻健康端点。
+
+---
+
+## 二、日志
+
+### Java侧（Log4j2）
+
+`backend/services/main-application/src/main/resources/log4j2.xml`：
+
+| 项 | 值 |
+|---|---|
+| `LOG_PATH` | `/var/log/deepdata/backend` |
+| 日志文件 | `${LOG_PATH}/app.log` |
+| 轮转文件名 | `app-%d{yyyy-MM-dd}-%i.log` |
+| `MAX_FILE_SIZE` | `${LOG_ROTATION_MAX_SIZE:-100MB}` |
+| `MAX_HISTORY` | `${LOG_ROTATION_BACKUP_COUNT:-30}` |
+| 格式 | `%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{50} - %msg%n` |
+| `LOG_LEVEL` | INFO |
+| `SQL_LOG_LEVEL` | WARN |
+
+通过 `logging.config: classpath:log4j2.xml` 启用。网关有独立 log4j2 配置（`backend/api-gateway/src/main/resources/log4j2.xml`）。
+
+### Python 侧（标准库 logging）
+
+`runtime/deepdata-python/app/core/logging.py` 的 `setup_logging()`：
+
+- 双handler：`StreamHandler(sys.stdout)` + `RotatingFileHandler(log_dir/"python-backend.log")`
+- 默认 `log_file_dir = /var/log/deepdata/backend-python`（`app/core/config.py` 第 29 行；`.env.example` 覆盖为 `./logs`）
+- 自定义 `CenteredLevelNameFormatter` 与 `_rotated_log_namer`
+- 显式调低 `httpx`/`httpcore` 与 `sqlalchemy.engine` 为 ERROR；接管 uvicorn 三类日志
+
+### 日志卷挂载
+
+| 卷 | 路径 | 使用方 |
+|---|---|---|
+| `deepdata-log-volume` | `/var/log/deepdata` | backend / backend-python / gateway / runtime |
+| `deepdata-frontend-log-volume` | `/var/log/deepdata/frontend` | frontend |
+| `deepdata-database-log-volume` | `/var/log/deepdata/database` | database |
+| `deep-flow-log-volume` | `/var/log/deep-flow` | deep-flow |
+| `deepdata-ray-log-volume` | `/tmp/ray` | ray |
+
+### 日志 PVC 监控（自动清理）
+
+Python 侧实现了 PVC 磁盘水位监控（`app/module/system/service/log_pvc_monitor.py`）：
+
+| 配置 | 默认 | 作用 |
+|---|---|---|
+| `LOG_PVC_MONITOR_ENABLED` | true | 开关 |
+| `LOG_PVC_MONITOR_PATH` | `./logs` | 监控路径 |
+| `LOG_PVC_MONITOR_THRESHOLD` | 0.9 | 水位阈值（90% 触发清理） |
+| `LOG_PVC_MONITOR_INTERVAL_SECONDS` | 300 | 检查间隔 |
+| `LOG_PVC_MONITOR_DELETE_BATCH_SIZE` | 10 | 单次删除文件数 |
+| `LOG_PVC_MONITOR_FILE_SUFFIXES` | `log,out,err` | 匹配后缀 |
+
+测试覆盖：`tests/test_log_pvc_monitor.py`、`tests/test_logging_rotation.py`
+
+### 轮转脚本
+
+| 脚本 | 用途 |
+|---|---|
+| `scripts/images/common/log-rotate-copytruncate.sh` | 拷入 runtime 镜像 `/usr/local/bin/` |
+| `scripts/images/database/prune-postgres-logs.sh` | PostgreSQL 日志清理 |
+
+---
+
+## 三、数据库运维
+
+### 初始化机制
+
+**无 Flyway/Liquibase**。数据库变更依赖 `scripts/db/` 下 14 个幂等 DDL 脚本，由数据库镜像的 `/docker-entrypoint-initdb.d/` 执行。
+
+```dockerfile
+# scripts/images/database/Dockerfile
+COPY scripts/db/ /docker-entrypoint-initdb.d/
+```
+
+> ⚠️ **关键机制**：`docker-entrypoint-initdb.d` **只在数据卷为空时执行一次**。
+> - 改 `scripts/db/*.sql` 后**不会自动生效**
+> - 需要手工执行：`docker exec -i deepdata-database psql -U postgres -d deepdata < scripts/db/xxx-init.sql`
+> - 或重建数据卷（**会丢数据，慎用**）
+
+### 迁移脚本位置问题
+
+`backend/api-gateway/migration/` 在 `deepdata-20260928` 分支**不存在**（存在于 `main` 分支的 09-01 基线中）。当前分支的DDL 统一在 `scripts/db/`。
+
+### 主库与初始化
+
+| 项 | 值 |
+|---|---|
+| 镜像 | `postgres:15-trixie` |
+| 启动脚本 | `/usr/local/bin/deepdata-database-start.sh` |
+| 配置 | `scripts/images/database/postgresql.cnf` |
+| 初始化库 | `deepdata`、`labelstudio` |
+| JDBC | `jdbc:postgresql://deepdata-database:5432/deepdata` |
+| 连接池 | HikariCP（max 20 / min 5） |
+| Redis 池| Lettuce（max-active 20） |
+
+### 首页 URL 联动
+
+`scripts/db/zz-final-task.sh` 读取 `HOME_PAGE_URL` 环境变量：
+
+```bash
+psql -v ON_ERROR_STOP=1 -U "$POSTGRES_USER" -d deepdata
+# UPDATE t_sys_param SET param_value = :url WHERE id = 'sys.home.page.url'
+```
+
+未设置则跳过。
+
+### 备份建议
+
+| 数据 | 位置 | 备份方式 |
+|---|---|---|
+| 元数据 | `deepdata-postgresql-volume` | `pg_dump` |
+| 数据集文件 | `deepdata-dataset-volume` / MinIO | 卷快照或对象存储同步 |
+| 算子包 | `deepdata-operator-packages-volume` | 卷快照 |
+| 向量数据 | `milvus-milvus-volume` + `milvus-minio-volume` | Milvus 官方备份工具 |
+
+---
+
+## 四、已知坑（已核实）
+
+### 🔴 P0 · JWT 认证默认关闭
+
+`deepdata.jwt.enable` 默认值为 `false`（`backend/api-gateway/.../JwtConfig.java` 的 `@Value("${deepdata.jwt.enable:false}")`），`.env.example` 中也是 `DEEPDATA_JWT_ENABLE=false`。
+
+同时网关的 `SecurityConfig` 是 `pathMatchers("**").permitAll()`（类注释：暂时禁用所有认证）。
+
+**影响**：若不改配置，接口层无认证保护。
+**处置**：生产环境显式设 `DEEPDATA_JWT_ENABLE=true`，并设置足够强的 `JWT_SECRET`（`JwtConfig` 在长度 < 32 时仅打warn，不报错 —— 短密钥不会被拒绝）。
+
+### 🟡 Makefile 目标与 README 不匹配
+
+| README 写的 | 实际情况 |
+|---|---|
+| `make install` / `make uninstall` | ❌ 无无后缀目标 |
+| `make build` | ❌ 无此目标 |
+| `make install-mineru` | ❌ `mineru` 不在 `VALID_SERVICE_TARGETS` |
+| `make install-deep-flow` | ❌ `deep-flow` 不在合法目标 |
+| `make install-label-studio` | ✅ 可用 |
+
+**根因**：`Makefile` 的 `install-%` 规则指向目录 `deployment/compose`，而**该目录不存在**（实际为 `deployment/docker/deepdata`）。
+
+### 🟡 数据库 SQL 修改不生效
+
+见[前文](#三数据库运维)。改 `scripts/db/*.sql` 后必须手工执行。
+
+### 🟡 core 服务无 healthcheck
+
+backend / backend-python / gateway / frontend / runtime 均无 healthcheck 与 Dockerfile `HEALTHCHECK`。编排系统无法据此判断服务真实状态。
+
+### 🟡 两份 compose 端口不同
+
+混用`docker/docker-compose.yml`（开发）与 `deployment/docker/deepdata/docker-compose.yml`（部署）会撞端口。差异见[部署指南](部署指南#开发版-compose-的端口差异)。
+
+### 🟢 backend 无对外端口
+
+`deepdata-backend` 在两份 compose 中都**没有对外端口映射**，只能通过 `deepdata` 内部网络访问。前端只暴露 30000（开发版 40000）。外部调用一律走网关。
+
+### 🟢 前置 Nacos
+
+`NACOS_ADDR` 默认值是 `https://consulservice:18302`（端口 18302 是 Consul 的典型端口，与 Nacos 默认 8848 不符）。纯 Compose 部署不需要服务发现，此配置无实际作用；但若误配会导致网关启动异常。
+
+---
+
+## 五、分支差异
+
+| 分支 | commit | 内容 |
+|---|---|---|
+| `main` | `cbb1048` | 早期基线，**含 Casdoor SSO 与 GitHub Actions CI** |
+| `deepdata-20260928` | `ff22ed3` | 当前开发基线 |
+
+`deepdata-20260928` 相对 `main`：
+
+| 缺失项 | 文件数 |
+|---|---|
+| `deepflow/`（已改名 `deep-flow/`） | 396（重命名） |
+| `.github/workflows/` CI | 14 |
+| Casdoor SSO 认证模块（Java） | 11 |
+| `.gitattributes` | 1 |
+
+**原因**：zip 交付包（09-28）不含这些文件。Casdoor SSO 与 GitHub Actions 属于早期国际版基线的内容。
+
+**影响**：切回 `main` 可找回 CI 与 SSO。若两条线都需要，需人工合并。
+
+---
+
+## 六、常见排障
+
+| 现象 | 排查方向 |
+|---|---|
+| 网关启动即失败 | `JWT_SECRET` 未配置（`JwtConfig` `@PostConstruct` 抛 `IllegalStateException`） |
+| 接口全 401 | `deepdata.jwt.enable=false` 时不会 401；若出现说明认证已开但 Token 无效/过期（默认 7 天） |
+| 前端能开但数据为空 | 检查 backend / backend-python 容器状态（无 healthcheck，只能看日志） |
+| 算子报错 `ModuleNotFoundError` | 上传包名与 `__init__.py` 中 `module_path` 包目录名不一致 |
+| 清洗任务卡在调度 | 查 `LOG_LEVEL=DEBUG` 下的 asyncio 日志；检查 `TASK_SCHEDULING_POOL_SIZE` |
+| 向量检索为空 | 确认 Milvus profile 已启用、`MILVUS_URI` 指向正确容器名（非 localhost） |
+| 磁盘写满 | 检查日志 PVC 水位；确认 `LOG_PVC_MONITOR_ENABLED=true` |
+| 数据库无表 | 数据卷非首次启动，初始化脚本未执行（见"数据库 SQL 修改不生效"） |
+| 标注结果不同步 | 检查 `t_dm_dataset_files.tags_updated_at`，同步按时间戳做冲突消解 |
+
+---
+
+## 七、日常巡检清单
+
+```bash
+# 1. 容器状态
+docker compose ps
+
+# 2. 后端健康
+curl -s http://<host>:8080/api/actuator/health | jq .
+
+# 3. 磁盘水位（数据卷+ 日志卷）
+docker exec deepdata-database df -h /var/lib/postgresql/data
+docker exec <python后端容器> df -h /var/log/deepdata
+
+# 4. 数据库关键表增长
+psql -U postgres -d deepdata -c "
+  SELECT relname, n_live_tup FROM pg_stat_user_tables
+  WHERE relname LIKE 't_dm_%' OR relname LIKE 't_clean_%'
+  ORDER BY n_live_tup DESC LIMIT 10;"
+
+# 5. 清理陈旧算子包（operator-packages 卷）
+docker exec <runtime容器> du -sh /opt/runtime/deepdata/ops/user
+```
+
+---
+
+**上一页**：[部署指南](部署指南) ｜ **下一页**：[使用说明](使用说明)
@@ -0,0 +1,256 @@
+# 部署指南
+
+> 基于 `deepdata-20260928` 分支。所有配置项名称来自实际配置文件，敏感值一律不列出。
+
+---
+
+## 前置条件
+
+| 依赖 | 用途 | 必需性 |
+|---|---|---|
+| Git | 拉取源码 | 必需 |
+| Make | 构建与安装 | 必需 |
+| Docker | 构建镜像 | 必需 |
+| Docker Compose | Compose 部署 | Compose 方式必需 |
+| Kubernetes + Helm | K8s 部署 | K8s 方式必需 |
+| Sealed Secrets Controller | 加密管理敏感配置 | 仅 K8s 部署 |
+
+---
+
+## 部署形态对比
+
+| 维度 | Docker Compose | Helm / K8s |
+|---|---|---|
+| 配置文件 | `deployment/docker/deepdata/docker-compose.yml` | `deployment/helm/deepdata/` |
+| 适合场景 | 单机/小规模、快速验证 | 生产、多副本、弹性伸缩 |
+| 敏感配置 | `.env` 文件 | Bitnami Sealed Secrets（密文入库） |
+| Ray 集群 | 单容器内启动 | 独立 `kuberay-operator` + `ray-cluster` chart |
+| 外部依赖 | 需手动起Redis/Milvus/Label Studio | 独立 chart管理 |
+
+---
+
+## 一、Docker Compose 部署
+
+### 步骤 1：准备环境变量
+
+```bash
+cp deployment/docker/deepdata/.env.example deployment/docker/deepdata/.env
+```
+
+**必填项**（`.env.example` 中均以 `${VAR:?...}` 形式引用，不含明文）：
+
+| 变量 | 说明 |
+|---|---|
+| `DB_PASSWORD` | PostgreSQL 密码 |
+| `JWT_SECRET` | JWT 签名密钥 |
+| `MINIO_ACCESS_KEY` / `MINIO_SECRET_KEY` | MinIO 凭据（Milvus 依赖） |
+| `LABEL_STUDIO_USERNAME` / `LABEL_STUDIO_PASSWORD` / `LABEL_STUDIO_USER_TOKEN` | Label Studio 凭据 |
+| `DEEPDATA_JWT_ENABLE` | JWT 开关，示例默认 `false` |
+
+可选：`CERT_PASS`（加密私钥口令）、`DOMAIN`（HTTPS 域名）。
+
+### 步骤 2：启动
+
+```bash
+docker compose -f deployment/docker/deepdata/docker-compose.yml up -d
+```
+
+### 核心服务与端口
+
+| 服务 | 镜像 | 端口映射 | 说明 |
+|---|---|---|---|
+| `deepdata-frontend` | `deepdata-frontend` | **30000:3000** | 用户界面入口 |
+| `deepdata-gateway` | `deepdata-gateway` | **8080:8080** | API 网关 |
+| `deepdata-backend-python` | `deepdata-backend-python` | **18000:18000** | Python 后端 |
+| `deepdata-database` | `deepdata-database` | **5432:5432** | PostgreSQL 15 |
+| `deepdata-backend` | `deepdata-backend` | 无对外端口 | 仅内部网络访问 |
+| `deepdata-runtime` | `deepdata-runtime` | 无（容器内 8081） | 算子执行 |
+
+### 可选服务（按 profile启用）
+
+| profile | 服务 | 端口 |
+|---|---|---|
+| `redis` | `deepdata-redis`（redis:8.2.3） | 6379:6379 |
+| `milvus` | `etcd` + `minio` + `milvus` | minio 9000/9001，milvus 19530/9091 |
+| `label-studio` | `label-studio-pgbouncer` + `label-studio` | 30001:8000 |
+| `data-juicer` | `deepdata-data-juicer`（datajuicer/data-juicer:v1.4.4） | 无 |
+| `deep-flow` | `deep-flow-backend` / `deep-flow-frontend` | 无 |
+| `mineru` | `deepdata-mineru`（vLLM引擎，需 Ascend NPU） | 容器内 8000 |
+
+示例：
+
+```bash
+#启用向量库 + 缓存
+docker compose -f deployment/docker/deepdata/docker-compose.yml --profile milvus --profile redis up -d
+
+# 启用标注（Label Studio）
+docker compose -f deployment/docker/deepdata/docker-compose.yml --profile label-studio up -d
+```
+
+### 数据卷
+
+`compose` 定义了 17 个卷，重要的有：
+
+| 卷 | 用途 |
+|---|---|
+| `deepdata-postgresql-volume` | PostgreSQL 数据（**删卷即丢全部元数据**） |
+| `deepdata-dataset-volume` | 数据集文件 |
+| `deepdata-operator-*-volume` | 算子包/运行时/上传（3 个） |
+| `deepdata-log-volume` | 后端日志 |
+| `deepdata-graph-data-volume` | 图数据 |
+| `milvus-milvus-volume` / `milvus-minio-volume` / `milvus-etcd-volume` | 向量库 |
+
+### 开发版 compose 的端口差异
+
+`docker/docker-compose.yml`（本地开发用）与主部署 compose 端口**不同**，注意区分：
+
+| 服务 | 开发版 | 部署版 |
+|---|---|---|
+| gateway | 8085:8080 | 8080:8080 |
+| frontend | 40000:3000 | 30000:3000 |
+| database | **5442**:5432 | 5432:5432 |
+| redis | 6339:6379 | 6379:6379 |
+| milvus 管理口 | 19091:9091 | 9091:9091 |
+| label-studio | 38000:8000 | 30001:8000 |
+
+开发版独有 `deepdata-ray-head` / `deepdata-ray-worker`（profile `ray`，Ray Dashboard `:8265`、客户端 `:10001`，`shm_size` 6-8GB）。
+
+---
+
+## 二、Helm / K8s 部署
+
+### Chart 结构
+
+`deployment/helm/` 下 4 个 chart：
+
+| chart | 名称/版本 | 说明 |
+|---|---|---|
+| `deepdata` | `deepdata` 0.0.1 | 主chart，依赖 9 个子chart |
+| `milvus` | `milvus` 5.0.7（appVersion 2.6.5） | Milvus 官方 chart |
+| `label-studio` | `label-studio` 0.1.0 | 镜像 compose 行为 |
+| `deep-flow` | `deep-flow` 0.0.1 | DeepFlow 服务 |
+
+主 chart 子依赖（`deployment/helm/deepdata/charts/`）：
+
+`backend`、`backend-python`、`database`、`frontend`、`gateway`、`kuberay-operator`（1.4.2，condition `ray-cluster.enabled`）、`ray-cluster`（1.4.2，同 condition）、`runtime`（condition `runtime.enabled`）、`public`
+
+### 安装
+
+```bash
+make k8s-install-deepdata
+# 等价于：helm upgrade --install deepdata ./charts/deepdata -n deepdata
+```
+
+> ⚠️ **Makefile 路径问题**：`Makefile` 中 `k8s-install-deepdata` 引用 `./charts/deepdata`，需在 `deployment/helm/deepdata/` 目录下执行，或自行调整路径。
+
+### 密钥管理
+
+K8s 部署使用 **Bitnami Sealed Secrets**，密文存于 `deployment/kubernetes/sealed-secrets/`（README 自述）。安装 Controller：
+
+```bash
+helm repo add sealed-secrets https://bitnami-labs.github.io/sealed-secrets
+helm install sealed-secrets sealed-secrets/sealed-secrets -n kube-system
+```
+
+---
+
+## 三、Makefile 目标
+
+> ⚠️ **README 与 Makefile 不一致**（调研发现，详见下方"已知坑"）
+
+### 构建镜像
+
+每个镜像的 Dockerfile 统一在 `scripts/images/<name>/Dockerfile`：
+
+```
+frontend-docker-build / backend-docker-build / database-docker-build
+gateway-docker-build / runtime-docker-build / runtime-ray-docker-build
+backend-python-docker-build
+deep-flow-backend-docker-build / deep-flow-frontend-docker-build / deep-flow-docker-build
+label-studio-docker-build
+mineru-docker-build / mineru-910B-docker-build / mineru-910C-docker-build / mineru-310P-docker-build
+```
+
+全局变量：`REGISTRY=ghcr.io/modelengine-group/`、`VERSION=latest`、`BUILD_PLATFORM=linux/amd64`、`NAMESPACE=deepdata`
+
+### Compose 安装
+
+模式规则 `install-%` / `uninstall-%`，合法服务目标（`VALID_SERVICE_TARGETS`）：
+
+```
+deepdata  backend  frontend  runtime  runtime-ray  backend-python
+database  gateway  redis  milvus  label-studio  data-juicer
+```
+
+例：`make install-deepdata`、`make install-label-studio`、`make uninstall-redis`
+
+> ❌ **`make install-mineru` / `make install-deep-flow` 会失败** —— `mineru` 和 `deep-flow` 不在合法目标列表。
+
+### 其他目标
+
+| 目标 | 说明 |
+|---|---|
+| `help` | 默认目标，列出所有目标 |
+| `download` | 交互选择 amd64/arm64，pull + save 镜像到 `dist/` |
+| `load-images` | 加载离线镜像 |
+| `create-namespace` | 创建 K8s namespace |
+| `node-setup` / `node-cleanup` | Ray 节点管理 |
+
+---
+
+## 四、关键环境变量
+
+### Python 后端（`runtime/deepdata-python/.env.example`）
+
+| 类别 | 变量 |
+|---|---|
+| 服务 | `HOST`（0.0.0.0）、`PORT`（18000）、`DEBUG` |
+| 数据库 | `PGSQL_HOST`、`PGSQL_PORT`、`PGSQL_USER`、`PGSQL_PASSWORD`、`PGSQL_DATABASE` |
+| 标注 | `LABEL_STUDIO_BASE_URL`、`LABEL_STUDIO_USER_TOKEN` |
+| 向量库 | `MILVUS_URI`（生产写法 `http://milvus:19530`）、`MILVUS_TOKEN` |
+| 日志 | `LOG_LEVEL`、`LOG_FILE_DIR`、`LOG_ROTATION_MAX_SIZE`（100MB）、`LOG_ROTATION_BACKUP_COUNT`（30） |
+| 日志PVC监控 | `LOG_PVC_MONITOR_ENABLED`、`LOG_PVC_MONITOR_THRESHOLD`（0.9）、`LOG_PVC_MONITOR_INTERVAL_SECONDS`（300）、`LOG_PVC_MONITOR_DELETE_BATCH_SIZE`（10） |
+| 存储 | `RAG_STORAGE_DIR` |
+| 认证 | `DEEPDATA_jwt_enable` |
+
+### Java 主应用（`main-application/application.yml`）
+
+| 类别 | 变量 |
+|---|---|
+| 数据库 | `DB_USERNAME`、`DB_PASSWORD`、`REDIS_PASSWORD` |
+| 存储 | `STORAGE_TYPE`（local/minio/s3）、`STORAGE_LOCAL_PATH` |
+| Ray | `RAY_ENABLED`（默认 false）、`RAY_ADDRESS`、`RAY_WORKING_DIR` |
+| 算子 | `OPERATOR_REPO_PATH`、`OPERATOR_REGISTRY_URL`、`OPERATOR_MAX_UPLOAD_SIZE` |
+| 限制 | `MAX_FILE_SIZE`、`TEMP_DIR`、`BATCH_SIZE` |
+| 标注 | `AUTO_ANNOTATION_ENABLED`、`ANNOTATION_MODEL_ENDPOINT` |
+| 质检 | `QC_ENABLED`、`QC_THRESHOLD` |
+| 任务 | `TASK_EXECUTION_CORE_SIZE`、`TASK_EXECUTION_MAX_SIZE`、`TASK_EXECUTION_QUEUE_CAPACITY`、`TASK_SCHEDULING_POOL_SIZE` |
+| 集成 | `NACOS_ADDR`、`OMS_AUTH_ENABLED`、`OMS_SERVICE_URL` |
+
+---
+
+## 五、验证部署
+
+```bash
+# 1. 容器状态
+docker compose ps
+
+# 2. 后端健康检查
+curl http://<host>:8080/api/actuator/health
+
+# 3. Actuator 暴露的端点
+# health / info / metrics / prometheus
+# show-details: when-authorized
+
+# 4. 前端可访问
+curl -I http://<host>:30000
+
+# 5. Python 后端
+curl http://<host>:18000/docs    # FastAPI 自动文档
+```
+
+> 注意：Actuator 挂在主应用的 `/api` context-path 下。
+
+---
+
+**上一页**：[技术架构](技术架构) ｜ **下一页**：[运维手册](运维手册)
@@ -0,0 +1,127 @@
+# 需求与定位
+
+## 一、DeepData 解决什么问题
+
+### 典型的痛点场景
+
+做模型微调或 RAG 的团队，都绕不开同一条流水线：**数据从哪来 → 怎么洗干净 → 缺标注怎么办 → 质量够不够 → 能不能进知识库**。
+
+自建这套东西的典型代价：
+
+| 环节 | 自建方案 | 问题 |
+|---|---|---|
+| 数据归集 | 写 DataX 调度脚本 + 手工执行 | 失败了只能靠日志；无重试、无状态记录 |
+| 数据清洗 | PySpark脚本串成一条链 | 参数一改要改代码；无法可视化调参 |
+| 数据标注 |自建 Label Studio + CVAT | 两套系统数据对不上；标注结果回不去 |
+| 算子管理 | 脚本堆成 utils.py | 谁写的、什么版本、怎么复用，没人说得清 |
+| 质量评估 | 人工抽查 | 不系统，无法量化 |
+| 知识构建 | 另写一套向量化脚本 | 与上游数据脱节，语料更新无法感知 |
+
+DeepData 的价值就是**把这条链路上的人力搬运全部收进一个平台**。
+
+### 核心主张
+
+> **数据处理的成本应该集中在算法本身，而不是在胶水脚本上。**
+
+平台提供：可视化拖拽编排 + 标准化算子 + 一体化元数据存储，让数据工程师只关注"用什么算子、参数怎么调"，而不是"怎么把这20 个脚本串起来跑"。
+
+---
+
+## 二、目标用户与角色
+
+| 角色 | 用DeepData 做什么 | 常用模块 |
+|---|---|---|
+| 数据管理员 | 建数据集、发起标注任务、回收结果 | 数据管理、数据标注 |
+| 数据工程师 | 编排清洗流水线、调算子参数 | 数据清洗、算子市场 |
+| 算法工程师 | 合成指令数据、质量评估 | 数据合成、数据评估 |
+| 知识库工程师 | 构建 RAG 知识库、管向量索引 | 知识生成 |
+| 标注团队 | 在 CVAT 里标图、审核、验收 | 见[标注作业 SOP](使用说明#六deepdatacvat-标注作业流程sop) |
+
+**注意**：DeepData 与 CVAT/Label Studio 的职责是**分离**的 —— DeepData 管数据（发起与回收），CVAT/Label Studio 管人与流程（分配、标注、审核）。理解这个边界是理解整个系统的前提。
+
+---
+
+## 三、典型使用场景
+
+### 场景 1：大模型训练语料准备
+
+```
+原始PDF/图片 → 数据归集 → 解析算子(MarkItDown/MinerU) → 清洗(去重/去噪/PII)
+→ 质量评估 → 合成指令数据(qwen2.5 蒸馏) → 入库 → 微调
+```
+对应模块：归集 → 管理 → 清洗 → 评估 → 合成
+
+### 场景 2：RAG 知识库构建
+
+```
+文档 → 解析(MinerU 提取图文) → 切片(slicer 算子) → 向量化(知识生成)
+→ Milvus 索引 → 提供检索 API
+```
+对应模块：知识生成 + RAG 索引服务
+
+### 场景 3：图像目标检测标注
+
+```
+数据集(1000 张图) → 创建标注任务(平台选 CVAT) → CVAT 侧切 Job 分工
+→ 标注审核 → 同步回 DeepData → 标签落入 t_dm_dataset_files.tags
+```
+详见[标注作业 SOP](使用说明#六deepdatacvat-标注作业流程sop)
+
+### 场景 4：多源数据归集
+
+```
+NFS/S3/HDFS/数据库/API → DataX 统一 reader → 归集模板 → 数据集
+```
+对应模块：数据归集 + `runtime/datax`
+
+---
+
+## 四、选型判断：什么时候该用、什么时候不该用
+
+### 适合用DeepData 的情况
+
+- 需要**端到端**流水线，且团队里有人负责数据而非只做算法
+- 语料需要**反复迭代**（改一个参数重跑全链路是常态）
+- 需要让**非工程角色**（标注团队、数据管理员）参与流程
+- 多模态数据（图片、PDF、音频）需要统一管理
+- 需要在 RAG 与微调之间**复用同一套数据底座**
+
+### 不建议用的情况
+
+- 数据量小、流程固定、一次跑完就结束（杀鸡用牛刀）
+- 强依赖 Hadoop 生态做超大规模批处理（DeepData 的调度是轻量的，不适合 PB 级离线批）
+- 需要严格的实时/流式处理（平台以任务制为主，无流式调度）
+- 团队只有算法工程师、无数据工程支持（学习成本高于收益）
+
+---
+
+## 五、与相邻方案的关系
+
+| 方案 | 定位差异 |
+|---|---|
+| CVAT / Label Studio | **只做标注**，不做数据底座。DeepData 负责与它们对接 |
+| DataX | **只做数据传输**，无编排无元数据。DeepData 内置集成 |
+| Data-Juicer | 侧重**数据清洗算法本身**。DeepData 通过容器集成（profile `data-juicer`） |
+| MinerU | **只做 PDF 解析**。DeepData 通过远端 API 调用 |
+| Milvus | **只做向量存储检索**。DeepData 负责喂数据进去 |
+| DeepFlow | **只做深度研究 Agent**。作为可选组件挂在 `deep-flow` profile |
+
+DeepData 的定位是**把这些工具串起来的中枢**，而非替代它们。
+
+---
+
+## 六、需求到功能的映射
+
+| 原始需求 | 平台能力 | 实现载体 |
+|---|---|---|
+| 数据要有地方放 | 数据集 + 对象存储 | `t_dm_datasets` + MinIO/S3 |
+| 清洗要能调参重跑 | 可视化编排 + 算子参数化 | `runtime/ops` 算子 + settings 定义 |
+| 标注要能协作分工 | 对接 CVAT/Label Studio | 标注模块 + 双向同步服务 |
+| 算子要能复用共享 | 算子市场 | `t_operator` + 上传打包机制 |
+| 质量要能量化评估 | 数据评估模块 | `t_de_eval_task` / `_file` / `_item` |
+| 要能追溯数据怎么来的 | 血缘管理 | `t_lineage_node` / `t_lineage_edge` |
+| 语料要能给 RAG 用 | 知识生成 + 向量索引 | Milvus + rag-indexer-service |
+
+---
+
+**下一页**：[产品功能](产品功能) —— 八大模块的具体能力边界