# data2ontology

**Repository Path**: fisher_zhu/data2ontology

## Basic Information

- **Project Name**: data2ontology
- **Description**: 知识工程工具，用于快速构建给Agent使用的Skills、RAG和本体
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: develop
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 11
- **Created**: 2026-03-20
- **Last Updated**: 2026-03-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# data2ontology 本地启动说明

本文档说明如何在本地完整启动项目（PostgreSQL + Neo4j + Milvus + FastAPI + Vite/React）。

## 1. 环境准备

- Docker Desktop（含 `docker compose`）
- Python 3.10+（建议 3.11）
- Node.js 18+（建议 20 LTS）
- npm

关键目录：

- `db/postgres-db/docker-compose.yml`：PostgreSQL 容器配置
- `db/neo4j/docker-compose.yml`：Neo4j 容器配置
- `db/milvus/docker-compose.yml`：Milvus 容器配置
- `db/*.sql`：数据库导出文件
- `backend/`：后端代码（FastAPI）
- `front/`：前端代码（Vite + React）

## 2. 启动 PostgreSQL（Docker Compose）

先检查 `db/postgres-db/docker-compose.yml`。

当前文件中挂载了 Linux 绝对路径：

- `/home/zhujunjie/postgres-docker/postgres-data`
- `/home/zhujunjie/postgres-docker/init-scripts`

如果你的机器没有这些目录，请改为你本机路径，或改成相对路径（例如 `./postgres-data`、`./init-scripts`）。

启动数据库：

```powershell
cd db/postgres-db
docker compose up -d
docker ps
```

确认容器 `postgres-db` 正在运行，且端口映射为 `5432:5432`。

## 3. 导入 SQL 数据

仓库内包含 3 个导出文件：

- `db/dump-dev-202602122015.sql`
- `db/dump-ontology-202602122015.sql`
- `db/dump-unstructured_data-202602122015.sql`

在项目根目录执行：

```powershell
docker cp db/dump-dev-202602122015.sql postgres-db:/tmp/dump-dev.sql
docker cp db/dump-ontology-202602122015.sql postgres-db:/tmp/dump-ontology.sql
docker cp db/dump-unstructured_data-202602122015.sql postgres-db:/tmp/dump-unstructured_data.sql

docker exec -i postgres-db psql -U root -d postgres -f /tmp/dump-dev.sql
docker exec -i postgres-db psql -U root -d postgres -f /tmp/dump-ontology.sql
docker exec -i postgres-db psql -U root -d postgres -f /tmp/dump-unstructured_data.sql
```

导入后检查：

```powershell
docker exec -it postgres-db psql -U root -d dev -c "\dt"
docker exec -it postgres-db psql -U root -d ontology -c "\dt"
docker exec -it postgres-db psql -U root -d unstructured_data -c "\dt"
```

如需重置并重新导入：

```powershell
cd db/postgres-db
docker compose down -v
docker compose up -d
```

然后再执行上面的导入命令。

## 4. 启动 Neo4j（Docker Compose）

本项目“部署本体 / 本体实例化”依赖 Neo4j。

先检查 `db/neo4j/docker-compose.yml`。

当前文件中挂载了 Linux 绝对路径：

- `/home/zhujunjie/neo4j-docker/logs`
- `/home/zhujunjie/neo4j-docker/config`
- `/home/zhujunjie/neo4j-docker/data`
- `/home/zhujunjie/neo4j-docker/plugins`

如果你的机器没有这些目录，请改为你本机路径，或改成相对路径。

启动 Neo4j：

```powershell
cd db/neo4j
docker compose up -d
docker ps
```

可选检查：

```powershell
docker logs neo4j --tail 50
```

默认端口：

- `7474`：Neo4j Browser（HTTP）
- `7687`：Bolt 协议（后端连接端口）

浏览器访问（可选）：

- `http://127.0.0.1:7474`

## 5. 启动 Milvus（RAG 向量库）

Milvus 当前使用 `db/milvus/docker-compose.yml` 直接启动 3 个服务：

- `etcd`
- `minio`
- `standalone`（container: `milvus-standalone`）

启动前请先检查 `db/milvus/docker-compose.yml` 中的宿主机挂载路径是否适合你的环境。当前文件里使用的是 Linux 绝对路径：

- `/home/milvus/milvus-docker/volumes/etcd`
- `/home/milvus/milvus-docker/volumes/minio`
- `/home/milvus/milvus-docker/volumes/milvus`

如果你的机器上没有这些目录，请改成你本机路径，或改成相对路径后再启动。

当前 compose 中的重要配置：

- Milvus 镜像：`milvusdb/milvus:v2.6.11`
- etcd 镜像：`quay.io/coreos/etcd:v3.5.25`
- MinIO 镜像：`minio/minio:RELEASE.2024-12-18T13-15-44Z`
- 鉴权已开启：
  - `MILVUS_COMMON_SECURITY_AUTHORIZATIONENABLED=true`
  - root 用户：`root`
  - root 密码：`Milvus`
- MinIO 默认账号：
  - access key：`minioadmin`
  - secret key：`minioadmin`

启动：

```powershell
cd db/milvus
docker compose up -d
docker ps
```

可选检查：

```powershell
docker logs milvus-standalone --tail 50
docker logs milvus-etcd --tail 50
docker logs milvus-minio --tail 50
```

当前对宿主机暴露的端口以 `db/milvus/docker-compose.yml` 为准：

- `19531:19530`：Milvus gRPC
- `9092:9091`：Milvus HTTP
- `9000:9000`：MinIO API
- `9001:9001`：MinIO Console

后端接入时请注意，宿主机端口是 `19531`，不是容器内的 `19530`：

```env
MILVUS_HOST=localhost
MILVUS_PORT=19531
MILVUS_USER=root
MILVUS_PASSWORD=Milvus
MILVUS_DATABASE=default
## 5. 配置并启动鉴权微服务

### 5.1 安装依赖
项目根目录执行
```powershell
cd authservice
python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
```

### 5.2 配置 `authservice/.env`
根据需要修改 `.env` 文件中的配置项。可参考.env.example文件。

### 5.3 启动鉴权微服务
项目根目录执行
```powershell
cd authservice
. .venv/bin/activate
uvicorn app.main:app --host 0.0.0.0 --port 9001 --reload
```

## 6. 配置并启动后端

### 6.1 安装依赖

```powershell
cd backend
python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
```

> `backend/requirements.txt` 已包含 `neo4j` Python 驱动，无需额外安装。

### 6.2 配置 `backend/.env`

参考模板（按实际环境修改）：

```env
OPENAI_API_KEY=your_key
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o-mini
CORS_ORIGINS=http://localhost:5173,http://127.0.0.1:5173

ONTOLOGY_DB_HOST=localhost
ONTOLOGY_DB_PORT=5432
ONTOLOGY_DB_NAME=ontology
ONTOLOGY_DB_USER=root
ONTOLOGY_DB_PASSWORD=root
ONTOLOGY_DB_SSLMODE=prefer
ONTOLOGY_DB_CONNECT_TIMEOUT=5
ONTOLOGY_DB_STARTUP_MAX_RETRIES=120
ONTOLOGY_DB_STARTUP_RETRY_INTERVAL=1.5

UNSTRUCTURED_DATA_TARGET_DB_NAME=unstructured_data

NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_password
NEO4J_DATABASE=neo4j
NEO4J_CONNECT_TIMEOUT=10
NEO4J_WRITE_BATCH_SIZE=500

MILVUS_HOST=localhost
MILVUS_PORT=19531
MILVUS_USER=root
MILVUS_PASSWORD=Milvus
MILVUS_DATABASE=default
```

请确认：

- `NEO4J_USER/NEO4J_PASSWORD` 与 `db/neo4j/docker-compose.yml` 中的 `NEO4J_AUTH` 一致
- `MILVUS_PORT` 使用宿主机映射端口 `19531`

### 6.3 启动后端

```powershell
cd backend
. .venv/bin/activate
uvicorn app.main:app --host 0.0.0.0 --port 8001 --reload
```

后端文档地址：

- `http://127.0.0.1:8001/docs`

## 7. 配置并启动前端

### 7.1 安装依赖
## 7. 配置并启动本体建模 Agent

### 7.1 安装依赖

```powershell
cd ontology_modeling_agent
python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
```

### 7.2 配置说明

本体建模 Agent 会复用 `backend` 目录下的配置与数据库连接。

- 请先按第 6 节完成 `backend/.env` 配置，确保 PostgreSQL、Neo4j、模型 API 等参数可用
- 前端如需直连本体建模 Agent，请将 `front/.env` 中的 `VITE_ONTOLOGY_MODELING_AGENT_BASE_URL` 配置为 `http://127.0.0.1:8002`

### 7.3 启动本体建模 Agent

```powershell
cd ontology_modeling_agent
. .venv/bin/activate
uvicorn server:app --host 0.0.0.0 --port 8002 --reload
```

本体建模 Agent 地址：

- `http://127.0.0.1:8002`
- 接口：
  - `POST /api/execute-agent`
  - `POST /api/resume-agent`
  - `POST /api/cancel-agent`

## 8. 配置并启动前端

### 8.1 安装依赖

```powershell
cd front
npm install
```

### 8.2 配置 `front/.env`
按照实际情况配置IP
```env
VITE_API_BASE_URL=http://127.0.0.1:8001
VITE_AUTH_API_URL=http://127.0.0.1:9001
VITE_AGENT_API_URL=http://127.0.0.1:7471
VITE_ONTOLOGY_MODELING_AGENT_BASE_URL=http://127.0.0.1:8002
```

### 8.3 启动前端

```powershell
cd front
npm run dev
```

前端默认地址：

- `http://127.0.0.1:5173`

## 9. 推荐启动顺序

1. 启动 PostgreSQL 并导入 SQL
2. 启动 Neo4j（确保 `7687` 可连接）
4. 启动 Milvus，确认 `19531` 可连接
5. 启动鉴权微服务（`9001`）
6. 启动后端（`8001`）
7. 启动本体建模 Agent（`8002`）
8. 启动前端（`5173`）

## 10. Neo4j 相关使用说明

- 在“本体建模”发布版本后，点击“部署本体”会将所选版本实例化并写入 Neo4j。
- “本体实例化”页面会从 Neo4j 查询图数据并渲染。
- 如果部署时报连接错误，优先检查：
  - `backend/.env` 中的 `NEO4J_URI / NEO4J_USER / NEO4J_PASSWORD`
  - Neo4j 容器是否正常运行
  - `7687` 端口是否被占用或被防火墙拦截

## 11. 常见问题

- 后端连接 PostgreSQL 失败
  - 确认 `postgres-db` 容器在运行
  - 确认 `backend/.env` 中 PostgreSQL 配置与容器一致
- 后端连接 Neo4j 失败
  - 确认 Neo4j 服务已启动
  - 确认 `NEO4J_PASSWORD` 与 compose 中 `NEO4J_AUTH` 设置一致
- 后端连接 Milvus 失败
  - 确认 `milvus-standalone`、`milvus-etcd`、`milvus-minio` 都已启动
  - 确认 `backend/.env` 中 `MILVUS_PORT=19531`
  - 确认 `MILVUS_USER=root`、`MILVUS_PASSWORD=Milvus` 与 compose 中一致
- 前端请求接口失败
  - 确认 `front/.env` 的 `VITE_API_BASE_URL` 指向 `http://127.0.0.1:8001`
  - 确认后端 `http://127.0.0.1:8001/docs` 可访问