252 lines
7.4 KiB
Markdown
252 lines
7.4 KiB
Markdown
# 开发指南
|
||
|
||
本文档为 DeepData 提供全面的本地开发环境搭建和工作流程指南，涵盖 Java、Python、React 三种语言。
|
||
|
||
## 概述
|
||
|
||
DeepData 是由多语言（Java 后端、Python 运行时、React 前端）组成的微服务项目，通过 Docker Compose 进行本地开发协调。
|
||
|
||
## 前置条件
|
||
|
||
- Git (用于拉取源码)
|
||
- Make (用于构建和安装)
|
||
- Docker (用于构建镜像和部署服务)
|
||
- Docker Compose (用于部署服务 - docker 方式)
|
||
- Kubernetes (用于部署服务 - k8s 方式)
|
||
- Helm (用于部署服务 - k8s 方式)
|
||
|
||
注意：
|
||
- 确保 Java 和 Python 环境在系统 PATH 中（如适用）
|
||
- Docker Compose 将编排本地开发栈
|
||
|
||
## 快速开始
|
||
|
||
### 1. 克隆仓库并安装依赖
|
||
```bash
|
||
git clone https://gitea.apescale.com/figmar/deepdata.git
|
||
cd deepdata
|
||
```
|
||
|
||
### 2. 启动基础服务
|
||
```bash
|
||
make install
|
||
```
|
||
|
||
本项目支持 docker-compose 和 helm 两种方式部署，请在执行命令后输入部署部署方式的对应编号，命令回显如下所示：
|
||
```shell
|
||
Choose a deployment method:
|
||
1. Docker/Docker-Compose
|
||
2. Kubernetes/Helm
|
||
Enter choice:
|
||
```
|
||
|
||
若您使用的机器没有 make，您也可以执行如下命令部署：
|
||
git clone https://gitea.apescale.com/figmar/deepdata.git
|
||
docker compose -f deployment/docker/deepdata/docker-compose.yml --profile milvus up -d
|
||
```
|
||
|
||
当容器运行后，请在浏览器打开 http://localhost:30000 查看前端界面。
|
||
|
||
### 3. 本地开发部署
|
||
本地代码修改后，请执行以下命令构建镜像并使用本地镜像部署：
|
||
git clone https://gitea.apescale.com/figmar/deepdata.git
|
||
make build
|
||
make install dev=true
|
||
```
|
||
|
||
### 4. 卸载服务
|
||
git clone https://gitea.apescale.com/figmar/deepdata.git
|
||
make uninstall
|
||
```
|
||
|
||
在运行 `make uninstall` 时，卸载流程会只询问一次是否删除卷（数据），该选择会应用到所有组件。卸载顺序为：milvus -> label-studio -> deepdata，确保在移除 deepdata 网络前，所有使用该网络的服务已先停止。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
DeepData/
|
||
├── backend/ # Java 后端
|
||
│ ├── api-gateway/ # API Gateway
|
||
│ ├── services/ # 核心服务
|
||
│ └── shared/ # 共享库
|
||
├── runtime/ # Python 运行时
|
||
│ ├── deepdata-python/ # FastAPI 后端
|
||
│ ├── python-executor/ # Ray 执行器
|
||
│ ├── ops/ # 算子生态
|
||
│ ├── datax/ # DataX 框架
|
||
│ └── deepflow # DeepFlow 服务
|
||
├── frontend/ # React 前端
|
||
├── deployment/ # 部署配置
|
||
└── docs/ # 文档
|
||
```
|
||
|
||
## 开发工作流程
|
||
|
||
### Java 后端开发
|
||
git clone https://gitea.apescale.com/figmar/deepdata.git
|
||
# 构建
|
||
cd backend
|
||
mvn clean install
|
||
|
||
# 运行测试
|
||
mvn test
|
||
|
||
# 运行特定服务
|
||
cd backend/services/main-application
|
||
mvn spring-boot:run
|
||
```
|
||
|
||
### Python 运行时开发
|
||
git clone https://gitea.apescale.com/figmar/deepdata.git
|
||
# 安装依赖
|
||
cd runtime/deepdata-python
|
||
poetry install
|
||
|
||
# 运行服务
|
||
poetry run uvicorn app.main:app --reload --port 18000
|
||
|
||
# 运行测试
|
||
poetry run pytest
|
||
```
|
||
|
||
### React 前端开发
|
||
git clone https://gitea.apescale.com/figmar/deepdata.git
|
||
# 安装依赖
|
||
cd frontend
|
||
npm ci
|
||
|
||
# 运行开发服务器
|
||
npm run dev
|
||
|
||
# 构建生产版本
|
||
npm run build
|
||
```
|
||
|
||
### Docker Compose 开发
|
||
git clone https://gitea.apescale.com/figmar/deepdata.git
|
||
# 启动所有服务
|
||
docker compose up -d
|
||
|
||
# 查看日志
|
||
docker compose logs -f [service-name]
|
||
|
||
# 停止所有服务
|
||
docker compose down
|
||
```
|
||
|
||
## 环境配置
|
||
|
||
每个组件可以有自己的环境变量文件。不要提交包含密钥的 .env 文件。
|
||
|
||
### 后端（Java）
|
||
- **路径**: `backend/.env`
|
||
- **典型密钥**:
|
||
- `DB_URL`: 数据库连接字符串
|
||
- `DB_USER`: 数据库用户名
|
||
- `DB_PASSWORD`: 数据库密码
|
||
- `REDIS_URL`: Redis 连接字符串
|
||
- `REDIS_PASSWORD`: Redis 密码
|
||
- `JWT_SECRET`: JWT 密钥
|
||
|
||
### 运行时（Python）
|
||
- **路径**: `runtime/deepdata-python/.env`
|
||
- **典型密钥**:
|
||
- `DATABASE_URL`: PostgreSQL 连接字符串
|
||
- `RAY_ENABLED`: 是否启用 Ray 执行器
|
||
- `RAY_ADDRESS`: Ray 集群地址
|
||
- `LABEL_STUDIO_BASE_URL`: Label Studio 基础 URL
|
||
|
||
### 前端（React）
|
||
- **路径**: `frontend/.env`
|
||
- **典型密钥**:
|
||
- `VITE_API_BASE_URL`: API 基础 URL
|
||
- `VITE_RUNTIME_API_URL`: 运行时 API 基础 URL
|
||
|
||
## 测试
|
||
|
||
### Java（JUnit 5）
|
||
git clone https://gitea.apescale.com/figmar/deepdata.git
|
||
cd backend
|
||
mvn test
|
||
```
|
||
|
||
### Python（pytest）
|
||
git clone https://gitea.apescale.com/figmar/deepdata.git
|
||
cd runtime/deepdata-python
|
||
poetry run pytest
|
||
```
|
||
|
||
### 前端
|
||
当前未配置测试框架。
|
||
|
||
## 调试
|
||
|
||
### Java 后端
|
||
git clone https://gitea.apescale.com/figmar/deepdata.git
|
||
# 启用 JDWP 调试端口 5005
|
||
export JAVA_TOOL_OPTIONS='-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005'
|
||
java -jar backend/main-application/target/*.jar
|
||
```
|
||
|
||
### Python 运行时
|
||
git clone https://gitea.apescale.com/figmar/deepdata.git
|
||
# 启用 debugpy 监听端口 5678
|
||
cd runtime/deepdata-python
|
||
python -m debugpy --listen 5678 --wait-for-client -m uvicorn app.main:app --reload --port 18000 --host 0.0.0.0
|
||
```
|
||
|
||
### React 前端
|
||
使用浏览器开发者工具或 VS Code 调试器。
|
||
|
||
## 常见问题
|
||
|
||
### 端口冲突
|
||
检查哪个进程正在使用端口：
|
||
git clone https://gitea.apescale.com/figmar/deepdata.git
|
||
lsof -i TCP:8080
|
||
lsof -i TCP:18000
|
||
lsof -i TCP:5173
|
||
```
|
||
停止或重新配置冲突的服务。
|
||
|
||
### 数据库连接失败
|
||
确保 `.env` 包含正确的 `DATABASE_URL` 和凭据；确保数据库服务在 Docker Compose 中已启动。
|
||
|
||
### Ray 集群问题
|
||
确保 Ray 已正确启动；检查 Ray 工作进程日志；确保 `RAY_ADDRESS` 配置正确。
|
||
|
||
## 文档
|
||
|
||
- **核心文档**:
|
||
- [ARCHITECTURE.md](./ARCHITECTURE.md) - 系统架构、微服务通信、数据流
|
||
- [DEVELOPMENT.md](./DEVELOPMENT.md) - 本地开发环境搭建和工作流程
|
||
- [AGENTS.md](./AGENTS.md) - AI 助手指南和代码规范
|
||
|
||
- **后端文档**:
|
||
- [backend/README.md](./backend/README.md) - 后端架构、服务和技术栈
|
||
- [backend/api-gateway/README.md](./backend/api-gateway/README.md) - API Gateway 配置和路由
|
||
- [backend/services/main-application/README.md](./backend/services/main-application/README.md) - 主应用模块
|
||
- [backend/shared/README.md](./backend/shared/README.md) - 共享库（domain-common, security-common）
|
||
|
||
- **运行时文档**:
|
||
- [runtime/README.md](./runtime/README.md) - 运行时架构和组件
|
||
- [runtime/deepdata-python/README.md](./runtime/deepdata-python/README.md) - FastAPI 后端服务
|
||
- [runtime/python-executor/README.md](./runtime/python-executor/README.md) - Ray 执行器框架
|
||
- [runtime/ops/README.md](./runtime/ops/README.md) - 算子生态
|
||
- [runtime/datax/README.md](./runtime/datax/README.md) - DataX 数据框架
|
||
- [runtime/deepflow/README.md](./runtime/deepflow/README.md) - DeepFlow LLM 服务
|
||
|
||
- **前端文档**:
|
||
- [frontend/README.md](./frontend/README.md) - React 前端应用
|
||
|
||
## 贡献指南
|
||
|
||
感谢您对本项目的关注！我们非常欢迎社区的贡献，无论是提交 Bug 报告、提出功能建议，还是直接参与代码开发，都能帮助项目变得更好。
|
||
|
||
• 📮 [GitHub Issues](../../issues)：提交 Bug 或功能建议。
|
||
• 🔧 [GitHub Pull Requests](../../pulls)：贡献代码改进。
|
||
|
||
## 许可证
|
||
|
||
DeepData 基于 [MIT](LICENSE) 开源，您可以在遵守许可证条款的前提下自由使用、修改和分发本项目的代码。
|