快速开始

• 1: 安装部署指南
• 2: 系统架构
• 3: 开发环境搭建

git clone https://github.com/ModelEngine-Group/DataMate.git
cd DataMate

make install

Choose a deployment method:
1. Docker/Docker-Compose
2. Kubernetes/Helm
Enter choice:

docker ps

make install-milvus

make install-label-studio

make build-mineru
make install-mineru

make install-deer-flow

make build
make install dev=true

make download SAVE=true

make load-images

make uninstall

# 卸载 Label Studio
make uninstall-label-studio

# 卸载 Milvus
make uninstall-milvus

# 卸载 DeerFlow
make uninstall-deer-flow

# 检查端口占用
lsof -i :30000
lsof -i :8080

# 查看所有服务日志
docker compose -f deployment/docker/datamate/docker-compose.yml logs

# 查看特定服务日志
docker compose -f deployment/docker/datamate/docker-compose.yml logs -f datamate-backend

docker volume ls | grep datamate

1 - 安装部署指南

系统要求

最低配置

软件依赖

Docker Compose 部署

• Docker 20.10+
• Docker Compose 2.0+
• Git (可选，用于克隆代码)
• Make (可选，用于使用 Makefile)

Kubernetes 部署

• Kubernetes 1.20+
• Helm 3.0+
• kubectl (与集群版本匹配)
• Git (可选，用于克隆代码)
• Make (可选，使用 Makefile)

部署方式对比

Docker Compose 部署

基础部署

1. 准备工作

# 克隆代码仓库
git clone https://github.com/ModelEngine-Group/DataMate.git
cd DataMate

# 检查 Docker 和 Docker Compose 版本
docker --version
docker compose version

2. 使用 Makefile 部署

# 一键部署（包括 Milvus）
make install

在提示中选择 1. Docker/Docker-Compose。

3. 直接使用 Docker Compose

如果没有安装 Make，可以直接使用 Docker Compose：

# 设置镜像仓库（可选）
export REGISTRY=ghcr.io/modelengine-group/

# 启动基础服务
docker compose -f deployment/docker/datamate/docker-compose.yml --profile milvus up -d

4. 验证部署

# 检查容器状态
docker ps

# 查看服务日志
docker compose -f deployment/docker/datamate/docker-compose.yml logs -f

# 访问前端界面
open http://localhost:30000

可选组件部署

Milvus 向量数据库

Milvus 用于知识库的向量存储和检索。

# 使用 Makefile
make install-milvus

# 或使用 Docker Compose
docker compose -f deployment/docker/datamate/docker-compose.yml --profile milvus up -d

组件包括：

• milvus-standalone (19530, 9091)
• milvus-minio (9000, 9001)
• milvus-etcd

Label Studio 标注工具

# 使用 Makefile
make install-label-studio

# 或使用 Docker Compose
docker compose -f deployment/docker/datamate/docker-compose.yml --profile label-studio up -d

访问地址：http://localhost:30001

默认账号：

• 用户名：admin@demo.com
• 密码：demoadmin

MinerU PDF 处理服务

MinerU 提供增强的 PDF 文档解析能力，支持 NPU 加速。

# 构建 MinerU 镜像
make build-mineru

# 部署 MinerU
make install-mineru

支持的平台：

• mineru (默认，910B)
• mineru-910C
• mineru-310P

DeerFlow 工作流服务

# 使用 Makefile
make install-deer-flow

# 或使用 Docker Compose
docker compose -f deployment/docker/datamate/docker-compose.yml --profile deer-flow up -d

Redis 缓存

# 使用 Makefile
make install-redis

# 或使用 Docker Compose
docker compose -f deployment/docker/datamate/docker-compose.yml --profile redis up -d

环境变量配置

可以在 deployment/docker/datamate/docker-compose.yml 中配置以下环境变量：

数据卷管理

DataMate 使用以下 Docker 卷进行数据持久化：

# 查看所有卷
docker volume ls | grep datamate

# 查看卷详情
docker volume inspect datamate-dataset-volume

# 备份卷数据
docker run --rm -v datamate-dataset-volume:/data -v $(pwd):/backup \
  ubuntu tar czf /backup/dataset-backup.tar.gz /data

# 恢复卷数据
docker run --rm -v datamate-dataset-volume:/data -v $(pwd):/backup \
  ubuntu tar xzf /backup/dataset-backup.tar.gz -C /

Kubernetes/Helm 部署

前置准备

# 检查集群连接
kubectl cluster-info
kubectl get nodes

# 检查 Helm 版本
helm version

# 创建命名空间（可选）
kubectl create namespace datamate

使用 Makefile 部署

# 部署 DataMate
make install INSTALLER=k8s

# 或直接部署到指定命名空间
make install NAMESPACE=datamate INSTALLER=k8s

使用 Helm 部署

1. 部署基础服务

# 添加 Helm 仓库（如果需要）
# helm repo add datamate https://charts.datamate.io

# 部署 DataMate
helm upgrade datamate deployment/helm/datamate/ \
  --install \
  --namespace datamate \
  --create-namespace \
  --set global.image.repository=ghcr.io/modelengine-group/

# 查看部署状态
kubectl get pods -n datamate

2. 配置 Ingress（可选）

# 编辑 values.yaml
cat >> deployment/helm/datamate/values.yaml << EOF
ingress:
  enabled: true
  className: nginx
  hosts:
    - host: datamate.example.com
      paths:
        - path: /
          pathType: Prefix
EOF

# 重新部署
helm upgrade datamate deployment/helm/datamate/ \
  --namespace datamate \
  -f deployment/helm/datamate/values.yaml

3. 部署可选组件

# 部署 Milvus
helm upgrade milvus deployment/helm/milvus \
  --install \
  --namespace datamate

# 部署 Label Studio
helm upgrade label-studio deployment/helm/label-studio/ \
  --install \
  --namespace datamate

# 部署 DeerFlow
helm upgrade deer-flow deployment/helm/deer-flow \
  --install \
  --namespace datamate \
  --set global.image.repository=ghcr.io/modelengine-group/

Helm 配置选项

主要配置项（deployment/helm/datamate/values.yaml）：

# 镜像配置
global:
  image:
    repository: ghcr.io/modelengine-group/
    pullPolicy: IfNotPresent
    tag: latest

# 服务配置
services:
  frontend:
    port: 30000
  gateway:
    port: 8080
  backend:
    port: 8092

# 资源配置
resources:
  requests:
    memory: "512Mi"
    cpu: "500m"
  limits:
    memory: "2Gi"
    cpu: "2000m"

# 存储配置
persistence:
  enabled: true
  storageClass: standard
  size: 50Gi

查看日志和调试

# 查看 Pod 状态
kubectl get pods -n datamate

# 查看服务日志
kubectl logs -f deployment/datamate-backend -n datamate

# 查看所有资源
kubectl get all -n datamate

# 端口转发进行本地调试
kubectl port-forward svc/datamate-gateway 8080:8080 -n datamate

离线环境部署

准备离线镜像包

1. 下载镜像

# 下载所有镜像到本地
make download SAVE=true

# 下载指定版本
make download VERSION=v1.0.0 SAVE=true

# 指定平台下载
make download PLATFORM=linux/amd64 SAVE=true

镜像将保存在 dist/ 目录。

2. 打包传输

# 打包
tar czf datamate-images.tar.gz dist/

# 传输到目标服务器
scp datamate-images.tar.gz user@target-server:/tmp/

离线安装

1. 加载镜像

# 在目标服务器上解压
tar xzf datamate-images.tar.gz

# 加载所有镜像
make load-images

# 或手动加载
for img in dist/*.tar; do
  docker load -i $img
done

2. 修改配置

使用本地镜像时，设置 REGISTRY 为空：

# Docker Compose 部署
REGISTRY= docker compose -f deployment/docker/datamate/docker-compose.yml up -d

# 或使用 Makefile
make install dev=true

3. 离线依赖

某些组件可能需要额外的离线资源：

• Python 包：预装在运行时镜像中
• Node 包：预装在前端镜像中
• Java 包：预装在后端镜像中

升级指南

Docker Compose 升级

# 1. 备份数据
docker run --rm -v datamate-postgresql-volume:/data -v $(pwd):/backup \
  ubuntu tar czf /backup/postgres-backup.tar.gz /data

# 2. 拉取新镜像
docker pull ghcr.io/modelengine-group/datamate-backend:latest
docker pull ghcr.io/modelengine-group/datamate-frontend:latest
# ... 其他镜像

# 3. 停止服务
docker compose -f deployment/docker/datamate/docker-compose.yml down

# 4. 启动新版本
docker compose -f deployment/docker/datamate/docker-compose.yml up -d

# 5. 验证升级
docker ps
docker logs -f datamate-backend

或使用 Makefile：

make datamate-docker-upgrade

Kubernetes 升级

# 1. 备份数据
kubectl exec -n datamate deployment/datamate-database -- \
  pg_dump -U postgres datamate > backup.sql

# 2. 更新 Helm Chart
helm upgrade datamate deployment/helm/datamate/ \
  --namespace datamate \
  --set global.image.tag=new-version

# 3. 监控升级状态
kubectl rollout status deployment/datamate-backend -n datamate

# 4. 查看新 Pod 状态
kubectl get pods -n datamate

卸载

Docker Compose 完全卸载

# 使用 Makefile
make uninstall

# 选择删除数据卷以完全清理

或手动卸载：

# 停止并删除容器
docker compose -f deployment/docker/datamate/docker-compose.yml --profile milvus --profile label-studio down -v

# 删除所有卷
docker volume rm datamate-dataset-volume \
  datamate-postgresql-volume \
  datamate-log-volume \
  # ... 其他卷

# 删除网络
docker network rm datamate-network

Kubernetes 完全卸载

# 卸载所有组件
make uninstall INSTALLER=k8s

# 或使用 Helm
helm uninstall datamate -n datamate
helm uninstall milvus -n datamate
helm uninstall label-studio -n datamate
helm uninstall deer-flow -n datamate

# 删除命名空间
kubectl delete namespace datamate

# 删除 PV/PVC（根据存储类）
kubectl delete pvc -n datamate --all

故障排查

常见问题

1. 服务无法启动

# 检查端口占用
netstat -tlnp | grep -E '30000|8080|5432'

# 检查磁盘空间
df -h

# 检查内存使用
free -h

# 查看详细日志
docker logs datamate-backend --tail 100

2. 数据库连接失败

# 检查数据库容器
docker ps | grep database

# 测试数据库连接
docker exec -it datamate-database psql -U postgres -d datamate

# 检查数据库日志
docker logs datamate-database

3. 前端无法访问后端

# 检查网关配置
docker logs datamate-gateway

# 检查网络连接
docker network inspect datamate-network

# 测试 API 连接
curl http://localhost:8080/api/v1/health

4. Milvus 连接失败

# 检查 Milvus 状态
docker logs milvus-standalone

# 检查依赖服务
docker logs milvus-etcd
docker logs milvus-minio

# 测试 Milvus 连接
curl http://localhost:19530/healthz

日志位置

获取帮助

如果遇到问题：

1. 查看 故障排查文档
2. 搜索 GitHub Issues
3. 提交新的 Issue 并附上详细的错误日志

2 - 系统架构

整体架构

DataMate 采用微服务架构，将系统拆分为多个独立的服务，每个服务负责特定的业务功能。这种架构提供了良好的可扩展性、可维护性和容错性。

┌─────────────────────────────────────────────────────────────────┐
│                           前端层                                │
│                    (React + TypeScript)                         │
│                      Ant Design + Tailwind                      │
└────────────────────────┬────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│                        API 网关层                               │
│                    (Spring Cloud Gateway)                       │
│                      端口: 8080                                  │
└────────────────────────┬────────────────────────────────────────┘
                         │
         ┌───────────────┼───────────────┐
         ▼               ▼               ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│  Java 后端   │ │ Python 后端  │ │  运行时服务  │
│   服务组     │ │    服务      │ │   (Ray)      │
├──────────────┤ ├──────────────┤ ├──────────────┤
│· Main App    │ │· RAG Service │ │· Operator    │
│· Data Mgmt   │ │· LangChain   │ │  Execution  │
│· Collection  │ │· FastAPI     │ │              │
│· Cleaning    │ │              │ │              │
│· Annotation  │ │              │ │              │
│· Synthesis   │ │              │ │              │
│· Evaluation  │ │              │ │              │
│· Operator    │ │              │ │              │
│· Pipeline    │ │              │ │              │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
       │                │                │
       └────────────────┼────────────────┘
                        ▼
         ┌──────────────┴──────────────┐
         │                              │
    ┌────▼────┐    ┌─────────┐   ┌─────▼────┐
    │PostgreSQL│    │  Redis  │   │  Milvus  │
    │  (5432)  │    │ (6379)  │   │ (19530)  │
    └──────────┘    └─────────┘   └──────────┘
                                              │
                                        ┌─────▼─────┐
                                        │   MinIO   │
                                        │  (9000)   │
                                        └───────────┘

技术栈

前端技术栈

后端技术栈（Java）

后端技术栈（Python）

数据存储

微服务架构

服务列表

服务通信

同步通信

• API Gateway → 后端服务：HTTP/REST
• 前端 → API Gateway：HTTP/REST
• 后端服务之间：HTTP/REST (Feign Client)

异步通信

• 任务执行：通过数据库任务队列
• 事件通知：Redis Pub/Sub

服务发现与注册

DataMate 使用简单的服务注册机制：

• 服务启动时向数据库注册
• API Gateway 从数据库获取服务列表
• 支持服务的动态扩缩容

数据架构

数据流转

┌─────────────┐
│  数据采集   │ 采集任务配置
│  Collection │ → DataX → 原始数据
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  数据管理   │ 数据集管理、文件上传
│ Management  │ → 结构化存储
└──────┬──────┘
       │
       ├──────────────┐
       ▼              ▼
┌─────────────┐  ┌─────────────┐
│  数据清洗   │  │  知识库     │
│  Cleaning   │  │  Knowledge  │
│             │  │  Base       │
└──────┬──────┘  └──────┬──────┘
       │                │
       ▼                ▼
┌─────────────┐  ┌─────────────┐
│  数据标注   │  │  向量索引    │
│  Annotation │  │  Milvus      │
└──────┬──────┘  └──────┬──────┘
       │                │
       ▼                │
┌─────────────┐          │
│  数据合成   │          │
│  Synthesis  │          │
└──────┬──────┘          │
       │                │
       ▼                ▼
┌─────────────┐  ┌─────────────┐
│  数据评估   │  │  RAG 检索   │
│  Evaluation │  │  Retrieval  │
└─────────────┘  └─────────────┘

数据存储模型

PostgreSQL

• 业务数据：用户、数据集、任务、配置
• 关系数据：服务间的关联关系
• 事务数据：需要强一致性的数据

Redis

• 缓存数据：热点数据缓存
• 会话数据：用户会话信息
• 任务队列：异步任务队列

Milvus

• 向量数据：文档向量 embeddings
• 向量索引：高效的相似度搜索

MinIO

• 文件存储：原始文件、处理结果
• 大数据文件：不适合数据库存储的文件

部署架构

Docker Compose 部署

┌────────────────────────────────────────────────┐
│              Docker Network                    │
│            datamate-network                    │
│                                                │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │Frontend  │  │ Gateway  │  │ Backend  │   │
│  │ :30000   │  │  :8080   │  │          │   │
│  └──────────┘  └──────────┘  └──────────┘   │
│                                                │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │Backend   │  │ Runtime  │  │Database  │   │
│  │  Python  │  │  :8081   │  │  :5432   │   │
│  └──────────┘  └──────────┘  └──────────┘   │
│                                                │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │  Milvus  │  │  MinIO   │  │  etcd    │   │
│  │  :19530  │  │  :9000   │  │          │   │
│  └──────────┘  └──────────┘  └──────────┘   │
└────────────────────────────────────────────────┘

Kubernetes 部署

┌────────────────────────────────────────────────┐
│           Kubernetes Cluster                   │
│                                                │
│  Namespace: datamate                           │
│                                                │
│  ┌────────────┐  ┌────────────┐              │
│  │ Deployment │  │ Deployment │              │
│  │  Frontend  │  │  Gateway   │              │
│  │   (3 Pods) │  │  (2 Pods)  │              │
│  └─────┬──────┘  └─────┬──────┘              │
│        │                │                     │
│  ┌─────▼────────────────▼──────┐              │
│  │       Service (LoadBalancer) │              │
│  └──────────────────────────────┘              │
│                                                │
│  ┌────────────┐  ┌────────────┐              │
│  │ StatefulSet│  │ Deployment │              │
│  │  Database  │  │  Backend   │              │
│  └────────────┘  └────────────┘              │
└────────────────────────────────────────────────┘

安全架构

认证与授权

JWT 认证（可选）

datamate:
  jwt:
    enable: true  # 启用 JWT 认证
    secret: your-secret-key
    expiration: 86400  # 24 小时

API Key 认证

datamate:
  api-key:
    enable: false

数据安全

传输加密

• API Gateway 支持 HTTPS/TLS
• 内部服务通信可配置加密

存储加密

• 数据库支持透明数据加密 (TDE)
• MinIO 支持服务端加密
• Milvus 支持加密存储

网络隔离

• Docker Network 隔离
• Kubernetes Network Policy
• VPC 隔离（云环境）

访问控制

基于角色的访问控制 (RBAC)

• 管理员：所有权限
• 数据管理员：数据管理权限
• 标注员：标注权限
• 查看者：只读权限

数据权限

• 数据集级权限控制
• 文件级权限控制
• 任务级权限控制

扩展性设计

水平扩展

无状态服务

• 前端：支持多副本
• Gateway：支持多副本
• Backend 服务：支持多副本

有状态服务

• 数据库：主从复制、分库分表
• Milvus：分布式部署
• MinIO：分布式纠删码

垂直扩展

资源配置

resources:
  requests:
    memory: "1Gi"
    cpu: "500m"
  limits:
    memory: "4Gi"
    cpu: "2000m"

缓存策略

多级缓存

1. 浏览器缓存：静态资源
2. CDN 缓存：公共资源
3. Redis 缓存：热点数据
4. 数据库缓存：查询缓存

监控与可观测性

日志管理

日志级别

• DEBUG：详细调试信息
• INFO：一般信息
• WARN：警告信息
• ERROR：错误信息

日志存储

/var/log/datamate/
├── frontend/
├── backend/
├── database/
└── runtime/

性能监控

指标收集

• JVM 指标
• HTTP 指标
• 数据库指标
• 自定义业务指标

监控工具（可选）

• Prometheus + Grafana
• ELK Stack (Elasticsearch + Logstash + Kibana)

高可用设计

服务高可用

健康检查

livenessProbe:
  httpGet:
    path: /actuator/health
    port: 8080
  initialDelaySeconds: 30
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /actuator/health/readiness
    port: 8080
  initialDelaySeconds: 10
  periodSeconds: 5

自动重启

• Docker restart policy
• Kubernetes restart policy

数据高可用

数据库

• 主从复制
• 自动故障转移
• 定期备份

对象存储

• 纠删码
• 多区域复制

向量数据库

• 主从架构
• 灾备恢复

性能优化

前端优化

• 代码分割
• 懒加载
• CDN 加速
• 资源压缩

后端优化

• 连接池优化
• 查询优化
• 缓存策略
• 异步处理

数据库优化

• 索引优化
• 分区表
• 查询优化
• 连接池配置

下一步

• 开发环境搭建 - 本地开发环境配置
• 后端架构 - 详细的后端架构说明
• 前端架构 - 详细的前端架构说明

3 - 开发环境搭建

前置要求

必需软件

推荐软件

• IDE：IntelliJ IDEA (后端) + VS Code (前端/Python)
• 数据库客户端：DBeaver、pgAdmin
• API 测试工具：Postman、curl
• Git 客户端：GitKraken、SourceTree

代码结构

DataMate/
├── backend/                 # Java 后端
│   ├── services/           # 微服务模块
│   │   ├── main-application/
│   │   ├── data-management-service/
│   │   ├── data-cleaning-service/
│   │   ├── data-collection-service/
│   │   ├── data-annotation-service/
│   │   ├── data-synthesis-service/
│   │   ├── data-evaluation-service/
│   │   ├── operator-market-service/
│   │   └── rag-indexer-service/
│   ├── openapi/            # OpenAPI 规范
│   └── scripts/            # 构建脚本
├── frontend/               # React 前端
│   ├── src/
│   │   ├── components/    # 公共组件
│   │   ├── pages/         # 页面组件
│   │   ├── services/      # API 服务
│   │   ├── store/         # Redux store
│   │   └── routes/        # 路由配置
│   └── package.json
├── runtime/                # Python 运行时
│   ├── deer-flow/         # DeerFlow 集成
│   └── datamate/          # DataMate 运行时
└── deployment/             # 部署配置
    ├── docker/            # Docker 配置
    └── helm/              # Helm Charts

后端开发环境

1. 安装 Java 21

# macOS (使用 Homebrew)
brew install openjdk@21

# Linux (Ubuntu/Debian)
sudo apt update
sudo apt install openjdk-21-jdk

# 验证安装
java -version

2. 安装 Maven

# macOS
brew install maven

# Linux
sudo apt install maven

# 验证安装
mvn -version

3. 配置 IDE（IntelliJ IDEA）

安装插件

• Lombok Plugin
• MyBatis Plugin
• Rainbow Brackets
• GitToolBox

导入项目

1. 打开 IntelliJ IDEA
2. 选择 File → Open
3. 选择 backend 目录
4. 等待 Maven 依赖下载完成

配置运行配置

创建 Spring Boot 运行配置：

• 主类：对应服务的 Application 类
• 工作目录：服务模块目录
• VM 参数：-Dspring.profiles.active=dev

4. 配置数据库

启动本地数据库（Docker）

# 仅启动数据库
docker compose -f deployment/docker/datamate/docker-compose.yml up -d datamate-database

# 查看数据库连接信息
docker logs datamate-database

默认连接信息：

• 主机：localhost
• 端口：5432
• 数据库：datamate
• 用户名：postgres
• 密码：password

初始化数据库

# 使用 Flyway 迁移（如果配置）
mvn flyway:migrate

# 或执行 SQL 脚本
psql -h localhost -U postgres -d datamate -f schema.sql

5. 运行后端服务

使用 Maven 运行

cd backend/services/main-application
mvn spring-boot:run

使用 IDE 运行

1. 找到对应的 Application 类
2. 右键 → Run
3. 访问 http://localhost:8080

6. 开发配置

编辑 application-dev.yml：

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/datamate
    username: postgres
    password: password
  jpa:
    show-sql: true
    hibernate:
      ddl-auto: update

logging:
  level:
    com.datamate: DEBUG

前端开发环境

1. 安装 Node.js

# macOS (使用 Homebrew)
brew install node@18

# Linux (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# 验证安装
node -v
npm -v

2. 安装 pnpm

npm install -g pnpm

# 验证安装
pnpm -v

3. 安装依赖

cd frontend

# 安装依赖
pnpm install

4. 配置开发环境

创建 .env.development：

# API 地址
VITE_API_BASE_URL=http://localhost:8080
VITE_API_TIMEOUT=30000

# 其他配置
VITE_APP_TITLE=DataMate Dev

5. 启动开发服务器

# 启动开发服务器
pnpm dev

# 或指定端口
pnpm dev --port 3000

访问 http://localhost:3000

6. 构建生产版本

# 构建
pnpm build

# 预览构建结果
pnpm preview

7. 前端开发技巧

热更新

• 修改 .tsx 或 .css 文件会自动热更新
• 修改配置文件需要重启

代理配置

在 vite.config.ts 中配置代理：

server: {
  proxy: {
    '/api': {
      target: 'http://localhost:8080',
      changeOrigin: true,
    }
  }
}

路径别名

import MyComponent from '@/components/MyComponent';
import { useStore } from '@/store/hooks';

Python 服务开发环境

1. 安装 Python 3.11

# macOS
brew install python@3.11

# Linux
sudo apt install python3.11 python3.11-venv

# 验证安装
python3.11 --version

2. 创建虚拟环境

# 进入项目目录
cd runtime/datamate

# 创建虚拟环境
python3.11 -m venv venv

# 激活虚拟环境
source venv/bin/activate  # Linux/macOS
# venv\Scripts\activate   # Windows

3. 安装依赖

# 安装依赖
pip install -r requirements.txt

# 或使用 uv（更快）
pip install uv
uv pip install -r requirements.txt

4. 配置环境变量

创建 .env 文件：

# 数据库配置
PG_HOST=localhost
PG_PORT=5432
PG_USER=postgres
PG_PASSWORD=password
PG_DATABASE=datamate

# 日志级别
log_level=DEBUG

# JWT 配置
datamate_jwt_enable=false

5. 运行 Python 服务

# 运行运行时服务
python /opt/runtime/datamate/operator_runtime.py --port 8081

# 或使用 FastAPI
uvicorn main:app --reload --port 18000

6. Python 开发工具

推荐插件

• Python (VS Code)
• Pylance
• Python Test Explorer

代码格式化

# Black
pip install black
black .

# isort
pip install isort
isort .

# 自动格式化
pip install autopep8

本地调试

1. 启动所有服务

使用 Docker Compose

# 启动基础服务（数据库、Redis 等）
docker compose -f deployment/docker/datamate/docker-compose.yml up -d \
  datamate-database \
  datamate-redis

# 启动 Milvus（可选）
docker compose -f deployment/docker/datamate/docker-compose.yml --profile milvus up -d

启动后端服务

# 终端 1：启动 Main Application
cd backend/services/main-application
mvn spring-boot:run

# 终端 2：启动 Data Management Service
cd backend/services/data-management-service
mvn spring-boot:run

# ... 其他服务

启动前端

cd frontend
pnpm dev

启动 Python 服务

# 终端 N：启动运行时服务
cd runtime/datamate
python operator_runtime.py --port 8081

# 终端 N+1：启动后端 Python 服务
cd backend-python
uvicorn main:app --reload --port 18000

2. 调试技巧

后端调试

在 IntelliJ IDEA 中：

1. 在代码行号处点击设置断点
2. 右键 → Debug 运行配置
3. 发送请求触发断点

前端调试

在浏览器中：

1. 按 F12 打开开发者工具
2. 使用 console.log 或 debugger 语句
3. React DevTools 查看组件状态

Python 调试

在 VS Code 中：

1. 安装 Python 扩展
2. 创建 launch.json 配置
3. 设置断点并 F5 启动调试

3. 日志查看

# Docker 容器日志
docker logs -f datamate-backend

# 应用日志
tail -f /var/log/datamate/backend/app.log

# 只查看错误日志
tail -f /var/log/datamate/backend/app.log | grep ERROR

代码规范

Java 代码规范

命名规范

• 类名：大驼峰 UserService
• 方法名：小驼峰 getUserById
• 常量：全大写 MAX_SIZE
• 变量：小驼峰 userName

注释规范

/**
 * 用户服务
 *
 * @author Your Name
 * @since 1.0.0
 */
public class UserService {

    /**
     * 根据用户 ID 获取用户信息
     *
     * @param userId 用户 ID
     * @return 用户信息
     * @throws UserNotFoundException 用户不存在异常
     */
    public User getUserById(Long userId) {
        // ...
    }
}

TypeScript 代码规范

命名规范

• 组件：大驼峰 UserProfile
• 类型/接口：大驼峰 UserData
• 函数：小驼峰 getUserData
• 常量：全大写 API_BASE_URL

组件规范

interface UserProfileProps {
  userId: string;
  onUpdate?: () => void;
}

export const UserProfile: React.FC<UserProfileProps> = ({
  userId,
  onUpdate
}) => {
  // 组件逻辑
  return <div>...</div>;
};

export default UserProfile;

Python 代码规范

遵循 PEP 8

def get_user(user_id: int) -> dict:
    """
    获取用户信息

    Args:
        user_id: 用户 ID

    Returns:
        用户信息字典
    """
    # ...

测试

后端测试

# 单元测试
mvn test

# 集成测试
mvn verify

# 生成测试报告
mvn jacoco:report

前端测试

# 单元测试
pnpm test

# E2E 测试
pnpm test:e2e

# 测试覆盖率
pnpm test:coverage

常见问题

后端启动失败

1. 检查 Java 版本：java -version
2. 检查端口占用：lsof -i :8080
3. 查看详细日志
4. 清理并重新构建：mvn clean install

前端启动失败

1. 检查 Node 版本：node -v
2. 删除 node_modules 重新安装：rm -rf node_modules && pnpm install
3. 检查端口占用：lsof -i :3000
4. 清理缓存：pnpm store prune

数据库连接失败

1. 检查数据库是否启动：docker ps | grep postgres
2. 测试连接：psql -h localhost -U postgres -d datamate
3. 检查防火墙设置
4. 验证连接配置

下一步

• 后端架构 - 详细的后端架构说明
• 前端架构 - 详细的前端架构说明
• 贡献指南 - 如何贡献代码