# Graph Explorer

**Repository Path**: xiangli22/graph-explorer

## Basic Information

- **Project Name**: Graph Explorer
- **Description**: 类似 Neo4j Bloom 的图形可视化工具
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-10-09
- **Last Updated**: 2025-10-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 图形可视化工具 - Graph Explorer

一款高性能、现代化的图形数据可视化工具，专为复杂关系网络分析和展示设计，类似 Neo4j Bloom 的功能体验。

## 🚀 主要功能

- **交互式图形可视化**: 支持大型网络图的流畅渲染和交互操作
- **智能布局算法**: 提供多种布局算法，自动优化节点排布
- **实时搜索与过滤**: 支持按属性、类型等多维度搜索和过滤节点、关系
- **自定义样式配置**: 允许用户自定义节点、关系的颜色、形状和大小
- **详细信息展示**: 点击节点或关系可查看其详细属性信息
- **图形分析工具**: 提供基本的图论分析功能，如最短路径、连通分量等
- **数据导出**: 支持将可视化结果导出为图片或数据格式

## 🎯 设计理念

### 1. 工业级稳定性
- 基于现代前端技术栈构建，确保在处理大规模图数据时的性能和稳定性
- 采用分层架构设计，便于维护和扩展
- 严格的错误处理和边界条件检查

### 2. 极简主义UI
- 简洁、直观的用户界面，减少学习成本
- 重点突出核心功能，避免不必要的视觉干扰
- 控制面板设计紧凑，最大化画布空间
- **控制面板**: 直接显示所有功能，无折叠操作

### 3. 严肃动效
- 减少悬停缩放比例（1.05x）
- 快速过渡动画（0.2s）
- 轻量阴影效果
- 统一边框样式

## 🎨 界面预览

应用包含以下主要界面：

- **主画布**: 交互式图形可视化区域（工业风格）
- **搜索面板**: 智能搜索和过滤功能
- **控制面板**: 画布控制和布局算法选择
- **信息面板**: 选中节点和关系的详细信息
- **分析面板**: 图谱统计和分析功能

## 📖 文档

- [用户指南](docs/user-guide.md) - 详细的使用说明
- [API 文档](docs/api.md) - 后端 API 接口文档
- [开发指南](docs/development.md) - 开发环境搭建和贡献指南

## 🔧 安装教程

详细的安装步骤请查看[开发指南](docs/development.md)文件。

## 📝 使用说明

使用方法和操作技巧请参考[用户指南](docs/user-guide.md)文件。

## 🤝 贡献

欢迎提交 Issue 和 Pull Request 来改进项目！贡献流程：

1. Fork 本仓库
2. 新建 Feat_xxx 分支
3. 提交代码
4. 新建 Pull Request

## 🌍 多语言支持

项目支持通过 Readme_XXX.md 文件来支持不同的语言，例如 Readme_en.md, Readme_zh.md。

## 📄 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件

# Graph Explorer

一个类似 Neo4j Bloom 的图形可视化探索工具，基于 React 和 Node.js 构建，支持 Neo4j 数据库连接。

## ✨ 主要功能

- 🎯 **交互式图形可视化** - 基于 ReactFlow 的流畅图形操作，工业风格设计
- 🔍 **智能搜索和过滤** - 全文搜索节点、标签和属性
- 🛤️ **路径分析** - 查找节点间的所有路径
- 📊 **实时数据更新** - WebSocket 实时同步
- 💾 **数据导入导出** - 支持 JSON 和 CSV 格式
- 🎨 **现代化界面** - 深色/浅色主题，响应式设计
- 🗄️ **数据库支持** - 支持 Neo4j 和内存数据库

## 🛠️ 技术栈

### 前端
- **React 18** + **TypeScript** - 现代化前端框架
- **React Flow** - 强大的图形可视化库
- **Tailwind CSS** - 实用优先的 CSS 框架
- **Zustand** - 轻量级状态管理

### 后端
- **Node.js** + **Express.js** - 服务端框架
- **Socket.io** - 实时双向通信
- **Neo4j JavaScript Driver** - Neo4j 数据库连接
- **内存数据库** - 快速图数据存储（备用方案）

## 🚀 快速开始

### 方法一：使用启动脚本（Windows）
```bash
# 双击运行启动脚本
start.bat
```

### 方法二：手动启动（推荐开发者）

#### 步骤 1：环境准备
```bash
# 确保已安装 Node.js (v16+)
node --version

# 确保已安装 npm
npm --version
```

#### 步骤 2：安装依赖
```bash
# 进入项目目录
cd graph-explorer

# 安装根目录依赖
npm install

# 安装前端依赖
cd frontend && npm install && cd ..

# 安装后端依赖
cd backend && npm install && cd ..
```

#### 步骤 3：数据库配置（可选）

**使用 Neo4j 数据库（推荐生产环境）：**
1. 下载并安装 Neo4j Desktop：https://neo4j.com/download/
2. 创建新的数据库项目
3. 启动数据库，默认用户名：`neo4j`，密码：在创建时设置
4. 修改配置文件 `backend/config.js`：
```javascript
module.exports = {
  // Neo4j 数据库配置
  neo4j: {
    uri: 'bolt://localhost:7687',  // Neo4j 连接地址
    user: 'neo4j',                  // 数据库用户名
    password: 'your-password'       // 数据库密码
  },
  // 其他配置...
  development: {
    useMemoryDatabase: false  // 设置为 false 使用 Neo4j
  }
};
```

**使用内存数据库（推荐开发测试）：**
```javascript
// 修改 backend/config.js
module.exports = {
  // 其他配置...
  development: {
    useMemoryDatabase: true  // 设置为 true 使用内存数据库
  }
};
```

#### 步骤 4：启动服务

**启动后端服务：**
```bash
# 在项目根目录
cd backend

# 启动后端开发服务器
npm start
# 或
npm run dev

# 后端将在 http://localhost:3008 启动
```

**启动前端服务：**
```bash
# 新开一个终端，在项目根目录
cd frontend

# 启动前端开发服务器
npm run dev

# 前端将在 http://localhost:5173 启动（如果端口被占用会自动切换）
```

#### 步骤 5：访问应用
- **前端界面**: http://localhost:5173
- **后端API**: http://localhost:3008
- **API文档**: http://localhost:3008/api/graph

### 🎯 验证安装

1. **检查前端**：在浏览器访问 http://localhost:5173，应该能看到图形界面
2. **检查后端**：访问 http://localhost:3008/api/graph/nodes，应该返回示例数据
3. **检查数据库连接**：查看后端控制台输出，确认数据库连接状态

## 🔧 开发命令

### 前端开发
```bash
cd frontend
npm run dev              # 启动前端开发服务器
npm run build            # 构建前端生产版本
npm run preview          # 预览生产版本
```

### 后端开发
```bash
cd backend
npm start                # 启动后端服务器
npm run dev              # 开发模式启动（自动重启）
npm run test             # 运行后端测试
```

### 批量命令（在根目录）
```bash
npm run install:all      # 安装所有依赖
npm run dev              # 同时启动前后端开发服务器
npm run dev:frontend     # 仅启动前端
npm run dev:backend      # 仅启动后端
```

## 📁 项目结构

```
graph-explorer/
├── frontend/                 # React 前端应用
│   ├── src/
│   │   ├── components/      # React 组件
│   │   │   ├── GraphCanvas.tsx      # 图形画布组件
│   │   │   ├── NodeComponent.tsx    # 节点组件（工业风格）
│   │   │   ├── EdgeComponent.tsx    # 边组件（工业风格）
│   │   │   ├── SearchPanel.tsx      # 搜索面板
│   │   │   ├── GraphControls.tsx    # 控制面板
│   │   │   └── GraphAnalytics.tsx   # 分析面板
│   │   ├── store/           # Zustand 状态管理
│   │   │   └── graphStore.ts       # 图数据状态管理
│   │   ├── utils/           # 工具函数
│   │   │   ├── visualUtils.ts       # 视觉工具（工业配色）
│   │   │   └── layoutUtils.ts       # 布局算法
│   │   └── types/           # TypeScript 类型定义
│   └── package.json
├── backend/                 # Node.js 后端服务
│   ├── src/
│   │   ├── index.js         # 主服务文件
│   │   └── neo4j-database.js # Neo4j 数据库连接
│   ├── config.js            # 配置文件（数据库配置）
│   └── package.json
├── shared/                  # 前后端共享代码
│   └── types/
│       └── graph.ts         # 图数据类型定义
├── docs/                    # 项目文档
├── start.bat               # Windows 启动脚本
└── package.json            # 根配置文件
```

## 🗄️ 数据库配置

### Neo4j 数据库集成

本项目支持与 Neo4j 图数据库的完整集成，提供企业级的数据存储和查询能力。

#### 安装 Neo4j

1. **下载 Neo4j Desktop**：
   - 访问 https://neo4j.com/download/
   - 下载适用于您操作系统的 Neo4j Desktop
   - 创建账户并登录

2. **创建数据库项目**：
   - 在 Neo4j Desktop 中创建新项目
   - 添加本地数据库（推荐版本：Neo4j 5.x）
   - 设置数据库密码

3. **启动数据库**：
   - 点击数据库的"Start"按钮
   - 确认数据库运行在 `bolt://localhost:7687`

#### 配置项目连接

编辑 `backend/config.js` 文件：

```javascript
module.exports = {
  // Neo4j 数据库配置
  neo4j: {
    uri: 'bolt://localhost:7687',    // Neo4j 连接地址
    user: 'neo4j',                   // 数据库用户名
    password: 'your-neo4j-password'  // 您设置的数据库密码
  },

  // 服务器配置
  server: {
    port: 3008,
    cors: {
      origin: ["http://localhost:5173"],
      methods: ["GET", "POST"]
    }
  },

  // 开发环境配置
  development: {
    useMemoryDatabase: false  // false = 使用 Neo4j, true = 使用内存数据库
  }
};
```

### 内存数据库模式

对于快速开发和测试，项目内置了内存数据库模式：

**启用内存数据库**：
```javascript
// backend/config.js
module.exports = {
  development: {
    useMemoryDatabase: true  // 使用内存数据库
  }
};
```

**内存数据库特点**：
- 🚀 快速启动，无需额外配置
- 🔄 数据仅在会话期间保存
- 🧪 适合开发和演示
- 📊 内置示例数据

## 🎮 操作指南

### 基本操作
- **拖拽画布**: 按住鼠标左键拖拽
- **缩放视图**: 使用鼠标滚轮或控制面板缩放按钮
- **选择节点**: 单击节点查看详情
- **搜索内容**: 在左侧面板输入关键词
- **布局切换**: 使用控制面板切换不同的布局算法

### 路径分析
1. 启用路径选择模式（在搜索面板）
2. 在画布上选择起始节点
3. 选择目标节点
4. 设置最大深度（可选，默认3层）
5. 查看所有找到的路径

### 控制面板功能
- **视图控制**: 适应视图、放大、缩小
- **显示控制**: 显示/隐藏节点标签
- **布局算法**: 智能布局、力导向、分层、圆形、网格

## 🚨 故障排除

### 常见问题

**1. 前端无法连接后端**
```bash
# 检查后端是否运行
curl http://localhost:3008/api/graph/nodes

# 如果连接失败，检查后端控制台错误信息
cd backend && npm start
```

**2. Neo4j 连接失败**
```bash
# 检查 Neo4j 是否启动
# 在 Neo4j Desktop 中确认数据库状态为 "Started"

# 检查配置文件
cat backend/config.js
```

**3. 端口占用问题**
```bash
# Windows 查找端口占用
netstat -ano | findstr :3008
netstat -ano | findstr :5173

# 终止占用进程
taskkill /F /PID <进程ID>
```

**4. 依赖安装问题**
```bash
# 清除缓存重新安装
npm cache clean --force
rm -rf node_modules package-lock.json
npm install
```

**5. 前端构建错误**
```bash
# 清除 Vite 缓存
cd frontend
rm -rf .vite dist
npm run dev -- --force
```

### 性能优化

**大数据量优化建议**：
- 使用 Neo4j 数据库而非内存数据库
- 在搜索时使用标签过滤
- 限制显示的节点数量
- 使用分层布局查看大型图结构

## 🎯 工业风格设计特色

### 1. 专业配色方案
- **深蓝色系**: 设备和系统节点
- **深红色系**: 故障和问题节点
- **深橙色系**: 故障症状节点
- **深绿色系**: 维护操作节点
- **灰色系**: 文档和默认节点

### 2. 简约组件设计
- **节点**: 圆角矩形，纯色填充，文字标识
- **边**: 简洁线条，小写标签
- **悬停信息**: 紧凑信息卡片，无多余装饰
- **控制面板**: 直接显示所有功能，无折叠操作

### 3. 严肃动效
- 减少悬停缩放比例（1.05x）
- 快速过渡动画（0.2s）
- 轻量阴影效果
- 统一边框样式

## 🎨 界面预览

应用包含以下主要界面：

- **主画布**: 交互式图形可视化区域（工业风格）
- **搜索面板**: 智能搜索和过滤功能
- **控制面板**: 画布控制和布局算法选择
- **信息面板**: 选中节点和关系的详细信息
- **分析面板**: 图谱统计和分析功能

## 📖 文档

- [用户指南](docs/user-guide.md) - 详细的使用说明
- [API 文档](docs/api.md) - 后端 API 接口文档
- [开发指南](docs/development.md) - 开发环境搭建和贡献指南

## 🤝 贡献

欢迎提交 Issue 和 Pull Request 来改进项目！

## 📄 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件