qKnow 知识平台【开源版】安装与部署全指南

本文详细介绍 qKnow 知识平台开源版的安装与部署流程，涵盖环境准备、代码结构、数据库配置、DeepKE 知识抽取工具设置、以及前后端启动步骤。系统采用 前后端分离架构 ，分为 后端运行部分 与 前端运行部分。

一、准备工作（环境要求）

在部署系统之前，请确保以下运行环境已正确安装。推荐在 Linux 或 macOS 下进行部署，Windows 环境请使用 WSL2 或 Docker 环境。

软件 / 工具	版本要求	推荐版本	用途说明
☕ JDK	≥ 1.8	1.8	运行后端服务
🐬 MySQL	≥ 5.7	5.7	关系型数据库
🕸 Neo4j	4.x	4.4.40	图数据库，用于知识图谱存储
🔥 Redis	≥ 5.0	5.0	缓存与消息队列
⚙️ Maven	≥ 3.6	3.6	Java 构建工具
💚 Node.js	≥ 16	16	前端构建与运行

💡 加速提示：设置 npm 镜像
bash 复制代码
npm config set registry https://registry.npmmirror.com
⚠️ 不推荐使用 cnpm，可能导致依赖冲突或构建失败。

二、获取项目代码

访问 qKnow Gitee 官方仓库。
下载项目 ZIP 包或使用 Git 克隆：
bash 复制代码
```
git clone https://gitee.com/qiantongtech/qKnow.git
```
将项目解压 / 克隆到您的工作目录，例如：
bash 复制代码
```
/opt/qknow/
```

三、目录结构说明

1. 后端目录结构

bash 复制代码

├─ qknow-framework/           # 公共配置模块（核心依赖）
│  ├─ qknow-auth              # OAuth2 授权模块
│  ├─ qknow-common            # 公共工具类模块
│  ├─ qknow-config            # 全局配置模块
│  ├─ qknow-es                # ElasticSearch 模块
│  ├─ qknow-file              # 文件管理服务
│  ├─ qknow-generator         # 代码生成器
│  ├─ qknow-mybatis           # MyBatis 数据层配置
│  ├─ qknow-neo4j             # Neo4j 图数据库模块
│  ├─ qknow-pay               # 支付模块
│  ├─ qknow-quartz            # 定时任务模块
│  ├─ qknow-redis             # Redis 缓存模块
│  ├─ qknow-security          # 安全认证模块
│  ├─ qknow-websocket         # WebSocket 实时通信模块
├─ qknow-module-app/          # 知识应用模块
├─ qknow-module-dm/           # 数据管理模块
├─ qknow-module-ext/          # 知识抽取模块
├─ qknow-module-kmc/          # 知识中心模块
├─ qknow-module-system/       # 系统管理模块
├─ qknow-server/              # 项目启动服务（主入口）
├─ qknow-ui/                  # 前端模块
├─ sql/                       # SQL 初始化脚本
├─ README.md
├─ QUICKSTART.md

2. 前端目录结构

bash 复制代码

├─ qknow-ui/
│  ├─ public/                 # 静态资源目录
│  ├─ src/
│  │  ├─ api/                 # 接口定义
│  │  ├─ assets/              # 图片与样式资源
│  │  ├─ components/          # 通用组件
│  │  ├─ layout/              # 页面布局
│  │  ├─ plugins/             # 插件
│  │  ├─ router/              # 路由配置
│  │  ├─ store/               # 状态管理
│  │  ├─ utils/               # 工具类函数
│  │  ├─ views/               # 页面视图
│  │  │  ├─ app/              # 知识应用模块
│  │  │  ├─ dm/               # 数据管理模块
│  │  │  ├─ ext/              # 知识抽取模块
│  │  │  ├─ kmc/              # 知识中心模块
│  │  │  ├─ system/           # 系统管理模块
│  ├─ .env.development        # 开发环境配置
│  ├─ .env.production         # 生产环境配置
│  ├─ vite.config.js          # Vite 构建配置

四、后端配置步骤

1. 创建并导入 MySQL 数据库

创建数据库：

sql 复制代码

CREATE DATABASE qknow_dev CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

导入 SQL 文件：

bash 复制代码

mysql -u root -p qknow_dev < sql/qknow_20250522.sql
mysql -u root -p qknow_dev < sql/quartz.sql

2. 修改数据库连接配置

路径：qknow-server/src/main/resources/application-dev.yml

yaml 复制代码

datasource:
  type: mysql

mysql:
  driver-class-name: com.mysql.cj.jdbc.Driver
  url: jdbc:mysql://127.0.0.1:3306/qknow_dev?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai
  username: root
  password: 123456

3. Neo4j 图数据库配置

步骤 1：关闭 Neo4j 服务

bash 复制代码

cd /usr/local/neo4j/bin
./neo4j stop

步骤 2：导入数据库

bash 复制代码

./neo4j-admin load --from=/opt/qknow/sql/neo4j/neo4j.dump --database=qknow --force

修改配置文件（conf/neo4j.conf）：

ini 复制代码

dbms.default_database=qknow

步骤 3：启动 Neo4j

bash 复制代码

./neo4j start

步骤 4：修改连接配置

路径：qknow-framework/qknow-neo4j/src/main/resources/application-neo4j-dev.yml

yaml 复制代码

neo4j:
  uri: bolt://127.0.0.1:7687
  user: neo4j
  password: neo4j密码

4. Redis 配置

Redis 使用默认 6379 端口即可。如有修改，请在以下路径更新：

css 复制代码

qknow-server/src/main/resources/application.yml

5. 配置服务端口与访问路径

路径：qknow-server/src/main/resources/application.yml

yaml 复制代码

server:
  port: 8090
  servlet:
    context-path: /qknow

五、知识抽取工具配置（DeepKE）

开源版采用 DeepKE-cnSchema 作为知识抽取引擎。建议使用 Docker 一键安装，更便于隔离环境与 GPU 加速。

1. 修改实体类型配置

路径：DeepKE/example/ner/standard/conf/train.yaml

yaml 复制代码

# DeepKE 实体抽取配置文件
learning_rate: 1e-3
num_train_epochs: 3
train_batch_size: 128
use_gpu: True

# 修改抽取实体类型
labels: ['LOC', 'ORG', 'PER']
# 若需自定义类型请参考官方文档重新训练模型

2. 修改 DeepKE 执行脚本（Docker 容器 ID）

路径：qKnow/bin/DeepKE/start.sh

bash 复制代码

#!/bin/bash
docker exec -it <your_container_id> /bin/bash

✅ 建议：使用 docker ps 命令查看 DeepKE 容器 ID。若需在宿主机调用 DeepKE API，可在容器端口映射配置中添加： -p 9000:9000。

六、后端启动

进入项目根目录：

bash 复制代码

cd qknow-server
mvn clean install -DskipTests
java -jar target/qknow-server.jar --spring.profiles.active=dev

启动后端后，默认访问地址：

bash 复制代码

http://localhost:8090/qknow

七、前端运行

1. 安装依赖

bash 复制代码

cd qknow-ui
npm install

2. 启动开发环境

bash 复制代码

npm run dev

默认访问地址：

arduino 复制代码

http://localhost:8080

3. 打包生产环境

bash 复制代码

npm run build

生成文件位于 dist/ 目录，可部署至 Nginx 或任意静态服务器。

八、常见问题与建议

问题	可能原因	解决方案
前端请求后端接口失败	CORS 或端口配置错误	检查 `vite.config.js` 中的代理设置
Neo4j 无法连接	用户名密码或端口错误	修改 `application-neo4j-dev.yml` 并确认数据库运行正常
Redis 报错连接拒绝	Redis 未启动或端口错误	确认 Redis 服务开启并监听正确端口
DeepKE API 抽取结果为空	模型未加载或实体类型配置错误	检查 `train.yaml` 与 `docker logs` 日志