# data2ontology

**Repository Path**: wanghaowen2/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**: 3
- **Forks**: 6
- **Created**: 2026-01-29
- **Last Updated**: 2026-03-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# data2ontology 本地启动说明

本文档说明如何在本地完整启动项目（PostgreSQL + Neo4j + 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/*.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. 配置并启动后端

### 5.1 安装依赖

```powershell
cd backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
```

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

### 5.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
```

请确保 `NEO4J_USER/NEO4J_PASSWORD` 与 `db/neo4j/docker-compose.yml` 里的 `NEO4J_AUTH` 一致。

### 5.3 启动后端

```powershell
cd backend
.\.venv\Scripts\Activate.ps1
uvicorn app.main:app --host 0.0.0.0 --port 8001 --reload
```

后端文档地址：

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

## 6. 配置并启动前端

### 6.1 安装依赖

```powershell
cd front
npm install
```

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

```env
VITE_API_BASE_URL=http://127.0.0.1:8001
```

### 6.3 启动前端

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

前端默认地址：

- `http://127.0.0.1:5173`

## 7. 推荐启动顺序

1. 启动 PostgreSQL 并导入 SQL
2. 启动 Neo4j（确保 `7687` 可连接）
3. 启动后端（`8001`）
4. 启动前端（`5173`）

## 8. Neo4j 相关使用说明

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

## 9. 常见问题

- 后端连接 PostgreSQL 失败：
  - 确认 `postgres-db` 容器在运行
  - 确认 `backend/.env` 中 PostgreSQL 配置与容器一致
- 后端连接 Neo4j 失败：
  - 确认 Neo4j 服务已启动
  - 确认 `NEO4J_PASSWORD` 与 compose 中 `NEO4J_AUTH` 设置一致
- 前端请求接口失败：
  - 确认 `front/.env` 的 `VITE_API_BASE_URL` 指向 `http://127.0.0.1:8001`
  - 确认后端 `http://127.0.0.1:8001/docs` 可访问