Skip to content

Commit adbddcc

Browse files
hhhhsc701hhhhsc701
authored
丰富文档 (#451)
* 丰富文档 * docs: add high and medium priority documentation - Add comprehensive documentation for backend, runtime, and core modules - Add backend/README.md with architecture, services, and tech stack - Add runtime/README.md with components and architecture - Add DEVELOPMENT.md with local development setup guide - Add ARCHITECTURE.md with system architecture and data flow - Add backend/api-gateway/README.md with gateway configuration - Add backend/services/main-application/README.md with module overview - Add backend/shared/README.md with shared libraries documentation - Add runtime/datax/README.md with DataX framework guide - Add runtime/deer-flow/README.md with DeerFlow service guide - Add runtime/python-executor/README.md with Ray executor guide - Update README.md with documentation index - Update README-zh.md with documentation index Files: backend/README.md, runtime/README.md, DEVELOPMENT.md, ARCHITECTURE.md, backend/api-gateway/README.md, backend/services/main-application/README.md, backend/shared/README.md, runtime/datax/README.md, runtime/deer-flow/README.md, runtime/python-executor/README.md, README.md, README-zh.md * docs: 添加中文版文档 - 创建中文版 README 文件：backend/README-zh.md, runtime/README-zh.md, DEVELOPMENT-zh.md, ARCHITECTURE-zh.md - 更新主 README-zh.md 的文档索引，指向中文版文档 - 更新主 README.md 的文档索引，指向中文版文档 * 丰富文档 * 丰富文档 * 丰富文档
1 parent 5ea214d commit adbddcc

File tree

20 files changed

+2755
-1
lines changed

20 files changed

+2755
-1
lines changed

‎DEVELOPMENT-zh.md‎

Lines changed: 251 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,251 @@
1+
# 开发指南
2+
3+
本文档为 DataMate 提供全面的本地开发环境搭建和工作流程指南，涵盖 Java、Python、React 三种语言。
4+
5+
## 概述
6+
7+
DataMate 是由多语言（Java 后端、Python 运行时、React 前端）组成的微服务项目，通过 Docker Compose 进行本地开发协调。
8+
9+
## 前置条件
10+
11+
- Git (用于拉取源码)
12+
- Make (用于构建和安装)
13+
- Docker (用于构建镜像和部署服务)
14+
- Docker Compose (用于部署服务 - docker 方式)
15+
- Kubernetes (用于部署服务 - k8s 方式)
16+
- Helm (用于部署服务 - k8s 方式)
17+
18+
注意：
19+
- 确保 Java 和 Python 环境在系统 PATH 中（如适用）
20+
- Docker Compose 将编排本地开发栈
21+
22+
## 快速开始
23+
24+
### 1. 克隆仓库并安装依赖
25+
```bash
26+
git clone git@github.com:ModelEngine-Group/DataMate.git
27+
cd DataMate
28+
```
29+
30+
### 2. 启动基础服务
31+
```bash
32+
make install
33+
```
34+
35+
本项目支持 docker-compose 和 helm 两种方式部署，请在执行命令后输入部署部署方式的对应编号，命令回显如下所示：
36+
```shell
37+
Choose a deployment method:
38+
1. Docker/Docker-Compose
39+
2. Kubernetes/Helm
40+
Enter choice:
41+
```
42+
43+
若您使用的机器没有 make，您也可以执行如下命令部署：
44+
```bash
45+
REGISTRY=ghcr.io/modelengine-group/ docker compose -f deployment/docker/datamate/docker-compose.yml --profile milvus up -d
46+
```
47+
48+
当容器运行后，请在浏览器打开 http://localhost:30000 查看前端界面。
49+
50+
### 3. 本地开发部署
51+
本地代码修改后，请执行以下命令构建镜像并使用本地镜像部署：
52+
```bash
53+
make build
54+
make install dev=true
55+
```
56+
57+
### 4. 卸载服务
58+
```bash
59+
make uninstall
60+
```
61+
62+
在运行 `make uninstall` 时，卸载流程会只询问一次是否删除卷（数据），该选择会应用到所有组件。卸载顺序为：milvus -> label-studio -> datamate，确保在移除 datamate 网络前，所有使用该网络的服务已先停止。
63+
64+
## 项目结构
65+
66+
```
67+
DataMate/
68+
├── backend/ # Java 后端
69+
│ ├── api-gateway/ # API Gateway
70+
│ ├── services/ # 核心服务
71+
│ └── shared/ # 共享库
72+
├── runtime/ # Python 运行时
73+
│ ├── datamate-python/ # FastAPI 后端
74+
│ ├── python-executor/ # Ray 执行器
75+
│ ├── ops/ # 算子生态
76+
│ ├── datax/ # DataX 框架
77+
│ └── deer-flow # DeerFlow 服务
78+
├── frontend/ # React 前端
79+
├── deployment/ # 部署配置
80+
└── docs/ # 文档
81+
```
82+
83+
## 开发工作流程
84+
85+
### Java 后端开发
86+
```bash
87+
# 构建
88+
cd backend
89+
mvn clean install
90+
91+
# 运行测试
92+
mvn test
93+
94+
# 运行特定服务
95+
cd backend/services/main-application
96+
mvn spring-boot:run
97+
```
98+
99+
### Python 运行时开发
100+
```bash
101+
# 安装依赖
102+
cd runtime/datamate-python
103+
poetry install
104+
105+
# 运行服务
106+
poetry run uvicorn app.main:app --reload --port 18000
107+
108+
# 运行测试
109+
poetry run pytest
110+
```
111+
112+
### React 前端开发
113+
```bash
114+
# 安装依赖
115+
cd frontend
116+
npm ci
117+
118+
# 运行开发服务器
119+
npm run dev
120+
121+
# 构建生产版本
122+
npm run build
123+
```
124+
125+
### Docker Compose 开发
126+
```bash
127+
# 启动所有服务
128+
docker compose up -d
129+
130+
# 查看日志
131+
docker compose logs -f [service-name]
132+
133+
# 停止所有服务
134+
docker compose down
135+
```
136+
137+
## 环境配置
138+
139+
每个组件可以有自己的环境变量文件。不要提交包含密钥的 .env 文件。
140+
141+
### 后端（Java）
142+
- **路径**: `backend/.env`
143+
- **典型密钥**:
144+
- `DB_URL`: 数据库连接字符串
145+
- `DB_USER`: 数据库用户名
146+
- `DB_PASSWORD`: 数据库密码
147+
- `REDIS_URL`: Redis 连接字符串
148+
- `REDIS_PASSWORD`: Redis 密码
149+
- `JWT_SECRET`: JWT 密钥
150+
151+
### 运行时（Python）
152+
- **路径**: `runtime/datamate-python/.env`
153+
- **典型密钥**:
154+
- `DATABASE_URL`: PostgreSQL 连接字符串
155+
- `RAY_ENABLED`: 是否启用 Ray 执行器
156+
- `RAY_ADDRESS`: Ray 集群地址
157+
- `LABEL_STUDIO_BASE_URL`: Label Studio 基础 URL
158+
159+
### 前端（React）
160+
- **路径**: `frontend/.env`
161+
- **典型密钥**:
162+
- `VITE_API_BASE_URL`: API 基础 URL
163+
- `VITE_RUNTIME_API_URL`: 运行时 API 基础 URL
164+
165+
## 测试
166+
167+
### Java（JUnit 5）
168+
```bash
169+
cd backend
170+
mvn test
171+
```
172+
173+
### Python（pytest）
174+
```bash
175+
cd runtime/datamate-python
176+
poetry run pytest
177+
```
178+
179+
### 前端
180+
当前未配置测试框架。
181+
182+
## 调试
183+
184+
### Java 后端
185+
```bash
186+
# 启用 JDWP 调试端口 5005
187+
export JAVA_TOOL_OPTIONS='-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005'
188+
java -jar backend/main-application/target/*.jar
189+
```
190+
191+
### Python 运行时
192+
```bash
193+
# 启用 debugpy 监听端口 5678
194+
cd runtime/datamate-python
195+
python -m debugpy --listen 5678 --wait-for-client -m uvicorn app.main:app --reload --port 18000 --host 0.0.0.0
196+
```
197+
198+
### React 前端
199+
使用浏览器开发者工具或 VS Code 调试器。
200+
201+
## 常见问题
202+
203+
### 端口冲突
204+
检查哪个进程正在使用端口：
205+
```bash
206+
lsof -i TCP:8080
207+
lsof -i TCP:18000
208+
lsof -i TCP:5173
209+
```
210+
停止或重新配置冲突的服务。
211+
212+
### 数据库连接失败
213+
确保 `.env` 包含正确的 `DATABASE_URL` 和凭据；确保数据库服务在 Docker Compose 中已启动。
214+
215+
### Ray 集群问题
216+
确保 Ray 已正确启动；检查 Ray 工作进程日志；确保 `RAY_ADDRESS` 配置正确。
217+
218+
## 文档
219+
220+
- **核心文档**:
221+
- [ARCHITECTURE.md](./ARCHITECTURE.md) - 系统架构、微服务通信、数据流
222+
- [DEVELOPMENT.md](./DEVELOPMENT.md) - 本地开发环境搭建和工作流程
223+
- [AGENTS.md](./AGENTS.md) - AI 助手指南和代码规范
224+
225+
- **后端文档**:
226+
- [backend/README.md](./backend/README.md) - 后端架构、服务和技术栈
227+
- [backend/api-gateway/README.md](./backend/api-gateway/README.md) - API Gateway 配置和路由
228+
- [backend/services/main-application/README.md](./backend/services/main-application/README.md) - 主应用模块
229+
- [backend/shared/README.md](./backend/shared/README.md) - 共享库（domain-common, security-common）
230+
231+
- **运行时文档**:
232+
- [runtime/README.md](./runtime/README.md) - 运行时架构和组件
233+
- [runtime/datamate-python/README.md](./runtime/datamate-python/README.md) - FastAPI 后端服务
234+
- [runtime/python-executor/README.md](./runtime/python-executor/README.md) - Ray 执行器框架
235+
- [runtime/ops/README.md](./runtime/ops/README.md) - 算子生态
236+
- [runtime/datax/README.md](./runtime/datax/README.md) - DataX 数据框架
237+
- [runtime/deer-flow/README.md](./runtime/deer-flow/README.md) - DeerFlow LLM 服务
238+
239+
- **前端文档**:
240+
- [frontend/README.md](./frontend/README.md) - React 前端应用
241+
242+
## 贡献指南
243+
244+
感谢您对本项目的关注！我们非常欢迎社区的贡献，无论是提交 Bug 报告、提出功能建议，还是直接参与代码开发，都能帮助项目变得更好。
245+
246+
• 📮 [GitHub Issues](../../issues)：提交 Bug 或功能建议。
247+
• 🔧 [GitHub Pull Requests](../../pulls)：贡献代码改进。
248+
249+
## 许可证
250+
251+
DataMate 基于 [MIT](LICENSE) 开源，您可以在遵守许可证条款的前提下自由使用、修改和分发本项目的代码。

0 commit comments

Comments
 (0)