前言

咱们的企业知识库系统已经开发得比较完整了,包含了用户认证、文档管理、AI助手、知识图谱、文件管理、搜索、统计等核心功能。

今天专门写了这篇文章,跟大家介绍一下如何在本地环境中运行企业知识库系统项目。

1. 环境准备

在开始之前,请确保你的本地环境已经安装了以下软件:

  • JDK: 21
  • Maven: 3.8+
  • MySQL: 8.0+
  • Node.js: 18+
  • npm: 9+
  • IDE: IntelliJ IDEA(推荐,用于运行后端 Spring Boot 项目)

以下中间件已部署在远程服务器上,本地无需安装,直接连接即可使用:

  • Redis: 远程服务器 117.72.88.11:6379
  • Elasticsearch: 远程服务器 117.72.88.11:9200
  • RabbitMQ: 远程服务器 117.72.88.11:5672
  • Nacos: 远程服务器 117.72.88.11:8848(服务注册和配置中心)
  • MongoDB: 远程服务器 117.72.88.11:27017

1.1 安装JDK21

我们需要在本地安装JDK21。

直接从官网下载非常慢。

为了方便大家直接下载,苏三已经将常用的JDK安装包上传到了我们的网盘上,地址:https://pan.quark.cn/s/8e9c302e3f64

里面包含了:JDK8、JDK11、JDK17和JDK21。

这里使用的都是openJDK,它是开源的版本,没有版权问题,不是直接使用的oracle的JDK。

windows电脑安装JDK21,并且配置环境变量教程:https://cloud.tencent.com/developer/article/2498215

mac电脑安装JDK21,并且配置环境变量教程:https://zhengzhaoxiang.blog.csdn.net/article/details/137168341

1.2 安装MySQL

之前为了防止一些核心数据,比如:用户账号密码,手机号,或者商品数据等,被随意篡改。

在本地开发环境中,没有给大家提供专门的远程数据库,因为数据库保存的是我们的核心数据,每个人可能都不一样。

如果一个人修改了admin的密码,可能会导致,其他的所有人都正常登录。

而像一些保存非核心数据的中间件,比如:Redis、RabbitMQ、ElasticSearch等,我给大家提供了远程的服务。

这些环境,大家不必重新搭建一遍。

因此,我们需要在本地安装MySQL。

MySQL的版本是8以上。

下载地址:https://dev.mysql.com/downloads/mysql/

你可以根据你操作系统的版本,选择下载不同的MySQL数据库。

具体安装过程,可以参考这篇文章:https://blog.csdn.net/z18769643585/article/details/134186070

1.3 安装Neo4j

Neo4j是图数据库,用来保存数据直接关系的数据库,也是核心数据之一,用来保存企业知识库项目中知识图谱数据的。

因此,也需要在本地部署。

Neo4j下载和安装教程:https://cloud.tencent.com/developer/article/2537036

2. 获取代码

打开终端或命令行工具,克隆项目代码到本地(获取最新的 master 分支的代码):

git clone https://gitcode.com/dv-susan/knowledge-base-backend.git
cd knowledge-base-backend

git clone https://gitcode.com/dv-susan/knowledge-base-frontend.git
cd knowledge-base-frontend

本项目采用前后端分离架构:

project/
├── knowledge-base-backend/     # 后端 Spring Boot 微服务项目
│   ├── kb-common/              # 公共模块
│   ├── kb-gateway/             # API 网关(端口 8080)
│   ├── kb-user-auth/           # 用户认证服务(端口 8081)
│   ├── kb-document/            # 文档管理服务(端口 8082)
│   ├── kb-search/              # 搜索服务(端口 8083)
│   ├── kb-file/                # 文件管理服务(端口 8084)
│   ├── kb-statistics/          # 统计服务(端口 8085)
│   ├── kb-ai/                  # AI 服务(端口 8086)
│   ├── kb-graph/               # 知识图谱服务(端口 8088)
│   ├── kb-foundation/          # 基础服务(端口 8089)
│   ├── sql/                    # 数据库脚本
│   └── docs/                   # 项目文档
│
└── knowledge-base-frontend/    # 前端 React + TypeScript 项目
    ├── src/                    # 源代码
    ├── public/                 # 静态资源
    └── dist/                   # 构建产物

3. 数据库初始化

项目使用 MySQL 作为主数据库,采用微服务分库架构,每个服务有独立的数据库。

数据库脚本地址:https://pan.quark.cn/s/ceb164fc4df7

3.1 创建数据库

连接到你的本地 MySQL 数据库,执行以下 SQL 创建所有数据库:

CREATE DATABASE IF NOT EXISTS `kb_user` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE DATABASE IF NOT EXISTS `kb_document` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE DATABASE IF NOT EXISTS `kb_search` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE DATABASE IF NOT EXISTS `kb_file` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE DATABASE IF NOT EXISTS `kb_ai` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE DATABASE IF NOT EXISTS `kb_statistics` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE DATABASE IF NOT EXISTS `kb_foundation` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

3.2 导入数据

推荐方案:使用全量导出脚本(一键初始化)

项目 sql/ 目录下提供了最新的全量导出脚本,包含建表语句和初始化数据:

cd knowledge-base-backend/sql
mysql -u root -p < knowledge_base_export_2026-06-23.sql
如果文件名的日期不同,请使用 sql/ 目录下最新的 knowledge_base_export_*.sql 文件。

执行成功后会看到类似如下的输出:

数据库总数: 10
kb_user:      6 tables
kb_document:  10 tables
kb_foundation: 6 tables
...
所有初始化数据已导入完成!

备用方案:分别执行脚本

如果全量脚本执行有问题,可以依次执行以下脚本:

cd knowledge-base-backend/sql
mysql -u root -p < 00_create_databases.sql
mysql -u root -p < create_tables.sql
mysql -u root -p < init_data.sql

3.3 确认数据库配置

检查你的 MySQL 用户名和密码是否与项目配置一致。各服务的配置文件位于:

kb-{模块名}/src/main/resources/application.yml

默认的数据库配置:

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/kb_user?useUnicode=true&characterEncoding=UTF-8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
    username: root
    password: 123456
    driver-class-name: com.mysql.cj.jdbc.Driver
如果你的 MySQL 用户名/密码与默认值不同,请修改所有模块 application.yml 中 spring.datasource.username 和 spring.datasource.password。

4. 中间件配置

4.1 Redis(必须,远程连接)

  • 远程地址:117.72.88.11:6379
  • 密码:susan123
  • 数据库编号:2
Redis 已部署在远程服务器上,本地无需安装。如果你的网络无法连接远程 Redis,可以在本地安装 Redis 并修改所有模块的 application.yml 中的 spring.data.redis.host 为 localhost。

4.2 Nacos(必须,远程连接)

  • 远程地址:117.72.88.11:8848
  • 命名空间:knowledge
  • 账户:nacos / susan123
Nacos 用于服务注册发现和配置管理。所有模块启动时会自动注册到 Nacos。本地无需安装 Nacos。

4.3 Elasticsearch(可选,远程连接)

  • 远程地址:117.72.88.11:9200
  • 账户:elastic / susan123
搜索服务(kb-search)需要 Elasticsearch。如果不使用搜索功能,可以暂时不启动 kb-search 服务。

4.4 RabbitMQ(可选,远程连接)

  • 远程地址:117.72.88.11:5672
  • 账户:admin / susan123
用于服务间的异步消息通信。部分模块(如 kb-ai、kb-search)会使用 RabbitMQ。

4.5 大模型(可选,远程API调用)

系统的 AI 助手、AI 写作、知识图谱(RAG + KAG)等功能需要大模型支持。

目前配置了两种大模型:

模型API地址说明
通义千问(Qwen)https://dashscope.aliyuncs.com/compatible-mode/v1默认模型,同时用于 Embedding 和 Chat
DeepSeekhttps://api.deepseek.com/v1备选模型,仅用于 Chat
大模型通过远程 API 调用,本地无需安装任何模型运行环境,只需要有可用的 API Key。

4.5.1 获取 API Key

通义千问(推荐):

  1. 访问 阿里云百炼平台
  2. 注册/登录阿里云账号
  3. 进入「模型广场」→ 选择「通义千问-Max」→ 点击「API调用」
  4. 在「API Key」页面创建新的 API Key
  5. 复制保存 API Key

DeepSeek(备选):

  1. 访问 DeepSeek 开放平台
  2. 注册/登录账号
  3. 进入「API Keys」页面创建新的 API Key
  4. 复制保存 API Key

4.5.2 配置 API Key

在使用 AI 功能的 IDE 中设置环境变量(IDEA → Run/Debug Configurations → Environment variables):

# 通义千问(必填,至少配置一个)
QWEN_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# DeepSeek(可选,备选模型)
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

4.5.3 AI 相关配置说明

kb-ai 模块的 application.yml 中的关键配置:

# 通义千问配置
qwen:
  api-key: ${QWEN_API_KEY:}                          # 从环境变量读取
  base-url: ${QWEN_BASE_URL:https://dashscope.aliyuncs.com/compatible-mode/v1}
  chat:
    options:
      model: ${QWEN_MODEL:qwen3-max}                 # 模型名称
      temperature: 0.3                                # 创造性控制(0-1)
      max-tokens: 4000                                # 单次最大输出token数

# DeepSeek 配置
deepseek:
  api-key: ${DEEPSEEK_API_KEY:}
  model: deepseek-chat
  base-url: https://api.deepseek.com/v1
  max-tokens: 4096
  temperature: 0.7

# 默认使用的模型
ai:
  default-model: qwen                                 # qwen 或 deepseek

# RAG 检索增强配置
rag:
  enabled: ${RAG_ENABLED:true}                        # 是否启用RAG
  chunking:
    chunk-size: ${RAG_CHUNK_SIZE:512}                 # 文档分块大小
    chunk-overlap: ${RAG_CHUNK_OVERLAP:64}            # 分块重叠大小
  embedding:
    model: ${RAG_EMBEDDING_MODEL:text-embedding-v3}   # Embedding模型
    dimension: 1024
  retrieval:
    default-top-k: 5                                  # 默认返回Top-K文档

# KAG 知识增强配置
kag:
  enabled: ${KAG_ENABLED:true}                        # 是否启用KAG
  extraction:
    model: qwen                                       # 实体关系抽取模型
    max-entities-per-chunk: 10
    max-relations-per-chunk: 15
  graph:
    database: neo4j                                   # 知识图谱存储
提示:如果不配置 API Key,AI 相关功能(AI助手、AI写作、知识图谱)将不可用,但不影响文档管理、用户认证等其他核心功能。启动时会输出 warn 日志,可以安全忽略。

4.5.4 模型切换

系统默认使用通义千问(Qwen),如需切换到 DeepSeek:

ai:
  default-model: deepseek

或在启动时通过环境变量覆盖:AI_DEFAULT_MODEL=deepseek。

4.6 邮件(可选)

系统的注册账号邮件激活、密码重置验证码等功能需要邮件服务。

4.6.1 获取 SMTP 授权码

系统默认使用 163邮箱 SMTP 服务:

  1. 登录 mail.163.com
  2. 点击「设置」→「POP3/SMTP/IMAP」
  3. 开启「SMTP服务」(IMAP/SMTP服务 或 POP3/SMTP服务)
  4. 按提示发送短信验证后,获取授权码(非邮箱登录密码)
  5. 复制保存授权码
也可以使用 QQ邮箱(smtp.qq.com,端口 465)或其他支持 SMTP 的邮箱服务。

4.6.2 配置邮件参数

在 IDEA 中设置环境变量(Run/Debug Configurations → Environment variables):

# 邮件发送账号(163邮箱地址)
MAIL_USERNAME=your_email@163.com

# SMTP授权码(非邮箱密码)
MAIL_PASSWORD=XXXXXXXXXXXX

或者直接修改 kb-user-auth 模块的 application.yml:

spring:
  mail:
    host: ${MAIL_HOST:smtp.163.com}
    port: ${MAIL_PORT:465}
    username: ${MAIL_USERNAME:your_email@163.com}    # 你的163邮箱
    password: ${MAIL_PASSWORD:XXXXXXXXXXXX}           # 你的SMTP授权码
    properties:
      mail:
        smtp:
          auth: true
          ssl:
            enable: true

4.6.3 使用其他邮箱服务

QQ邮箱:

spring:
  mail:
    host: smtp.qq.com
    port: 465
    username: your_email@qq.com
    password: XXXXXXXXXXXX    # QQ邮箱SMTP授权码

企业微信邮箱:

spring:
  mail:
    host: smtp.exmail.qq.com
    port: 465
    username: your_email@company.com
    password: XXXXXXXXXXXX
提示:如果不配置邮件,注册功能仍然可以正常使用,只是用户注册后不会收到激活邮件,需要管理员在后台手动激活账号。密码重置功能将不可用。

5. 启动后端服务

5.1 安装依赖

首先确保 Maven 能正常拉取依赖。在项目根目录执行:

cd knowledge-base-backend
mvn clean compile -DskipTests

(注意:初次编译可能需要下载大量依赖,请耐心等待,大约需要 5-10 分钟)

5.2 启动顺序

后端有 9 个微服务模块,建议按以下顺序在 IDEA 中分别启动:

序号模块启动类端口说明
1kb-user-authUserAuthApplication8081用户认证,需要最先启动
2kb-foundationFoundationApplication8089基础服务(配置、字典、通知)
3kb-documentDocumentApplication8082文档管理,核心服务
4kb-fileFileApplication8084文件管理
5kb-searchSearchApplication8083搜索服务
6kb-aiAiApplication8086AI 助手
7kb-statisticsStatisticsApplication8085统计服务
8kb-graphGraphApplication8088知识图谱
9kb-gatewayGatewayApplication8080API 网关,最后启动

在 IDEA 中启动步骤:

  1. 用 IntelliJ IDEA 打开 knowledge-base-backend 目录(即包含 pom.xml 的根目录)
  2. 等待 IDEA 自动识别 Maven 项目并下载依赖
  3. 找到各模块的 Application 类(例如 kb-user-auth/src/main/java/com/knowledge/base/userauth/UserAuthApplication.java)
  4. 右键点击类名 → Run 'UserAuthApplication'
  5. 按上述顺序依次启动每个模块

5.3 最少启动方案

如果你只是想快速体验核心功能,最少只需要启动 3 个服务:

序号模块端口说明
1kb-user-auth8081登录认证
2kb-document8082文档管理
3kb-gateway8080API 网关(最后启动)
注意:kb-document 服务启动时可能需要 kb-foundation 中的部分接口,如果报错再启动 kb-foundation。

5.4 确认启动成功

每个服务启动成功后,控制台会输出类似以下日志:

Started UserAuthApplication in 8.5 seconds

确认以下端口都已正常监听:

# 查看端口占用情况
lsof -i :8080
lsof -i :8081
lsof -i :8082

也可以通过 Nacos 控制台查看服务注册状态:http://117.72.88.11:8848/nacos(账户:nacos / susan123)。

6. 启动前端

6.1 安装依赖

打开新的终端窗口,进入前端项目目录:

cd knowledge-base-frontend
npm install

(注意:初次安装可能需要 3-5 分钟)

6.2 启动开发服务器

npm run dev

启动成功后,终端会输出:

  ➜  Local:   http://localhost:3002/
  ➜  Network: use --host to expose

前端开发服务器运行在 3002 端口,会自动将 /api 请求代理到后端的网关服务(http://localhost:8080)。

6.3 前端配置说明

前端的配置文件 .env.development 中的关键配置:

VITE_API_BASE_URL=/api
VITE_APP_NAME=企业知识库
VITE_APP_DEBUG=true
VITE_REQUEST_TIMEOUT=30000

一般情况下不需要修改这些配置。

7. 访问系统

当后端和前端都启动成功后,在浏览器中访问:

首页地址:http://localhost:3002

打开后会自动跳转到登录页面:

登录页面:http://localhost:3002/login

图片.png

账号:admin 密码:123456

登录成功之后,主页面如下:

图片.png

主要功能页面

页面地址说明
首页/仪表盘/dashboard系统概览和统计数据
文档中心/documents浏览和搜索文档
AI助手/aiAI 对话和文档问答
AI写作/ai-writingAI 辅助写作
知识图谱/knowledge-graph知识图谱可视化
文件管理/files文件上传和管理
个人中心/profile个人信息和设置
系统管理/admin用户、角色、权限管理

Swagger 接口文档

启动后可以通过以下地址访问各服务的 API 文档:

8. 常见问题排查

8.1 数据库连接失败

错误信息:CommunicationsException: Communications link failure

排查步骤:

  1. 确认 MySQL 服务已启动
  2. 确认用户名密码正确(默认 root / 123456)
  3. 确认 3306 端口未被防火墙拦截
  4. 确认所有数据库已创建(10 个 kb_* 数据库)
  5. 如果密码不同,修改所有模块 application.yml 中的 spring.datasource.password
# 测试 MySQL 连接
mysql -u root -p -e "SHOW DATABASES LIKE 'kb_%';"

8.2 Redis 连接失败/超时

错误信息:RedisConnectionFailureException 或 RedisCommandTimeoutException

原因:远程 Redis 间歇性超时(已在最新代码中优化,确保拉取最新代码)

解决:

  1. 确认网络能访问 117.72.88.11:6379
  2. 如果无法连接远程 Redis,可以在本地安装 Redis 并修改所有模块的配置

在本地安装 Redis 后,修改各模块 application.yml:

spring:
  data:
    redis:
      host: localhost
      port: 6379
      password:          # 本地 Redis 一般无密码
      database: 0

8.3 Nacos 连接失败

错误信息:com.alibaba.nacos.api.exception.NacosException

解决:

  1. 确认 117.72.88.11:8848 网络可达
  2. 如果 Nacos 不可用,可以在各模块的 application.yml 中注释掉 Nacos 配置,改用本地配置启动

8.4 前端页面能打开但数据不显示

原因:通常是因为后端服务未完全启动或跨域问题

排查:

  1. 打开浏览器开发者工具(F12)
  2. 查看 Network 标签页中的 API 请求是否有报错
  3. 查看 Console 标签页是否有 JavaScript 错误
  4. 确认至少启动了 kb-gateway(8080)、kb-user-auth(8081)、kb-document(8082)三个服务

8.5 IDEA 中启动报 "端口被占用"

错误信息:Port 8080 is already in use

解决:

# 查找占用端口的进程
lsof -i :8080
# 杀死进程(将 PID 替换为实际进程号)
kill -9 <PID>

8.6 前端启动报错 "Cannot find module"

解决:重新安装依赖

cd knowledge-base-frontend
rm -rf node_modules package-lock.json
npm install
npm run dev

8.7 Maven 依赖下载慢或失败

解决:配置阿里云 Maven 镜像。

编辑 ~/.m2/settings.xml,添加:

<mirrors>
  <mirror>
    <id>aliyun</id>
    <mirrorOf>central</mirrorOf>
    <name>Aliyun Maven</name>
    <url>https://maven.aliyun.com/repository/public</url>
  </mirror>
</mirrors>

8.8 注册功能不可用

如果发现登录页面没有"注册"入口,说明系统配置中的注册功能可能未开启。

解决:登录管理员账户后,进入系统管理 → 系统配置,确认 user.registration.enabled 为 true。

也可以用 SQL 直接修改:

USE kb_foundation;
UPDATE kb_system_config SET config_value = 'true' WHERE config_key = 'user.registration.enabled';

8.9 文件上传失败

文件上传功能依赖远程 RustFS 服务(117.72.88.11:9091)。如果无法连接:

解决:配置本地存储路径。修改 kb-file 和 kb-document 服务的 application.yml,将上传路径改为本地目录。

9. 快速启动命令速查

# === 后端 ===
cd knowledge-base-backend

# 编译所有模块
mvn clean compile -DskipTests

# 在 IDEA 中按顺序启动:
# 1. UserAuthApplication (kb-user-auth)
# 2. FoundationApplication (kb-foundation)
# 3. DocumentApplication (kb-document)
# 4. FileApplication (kb-file)
# 5. SearchApplication (kb-search)
# 6. AiApplication (kb-ai)
# 7. StatisticsApplication (kb-statistics)
# 8. GraphApplication (kb-graph)
# 9. GatewayApplication (kb-gateway) ← 最后启动

# === 前端 ===
cd knowledge-base-frontend
npm install
npm run dev

# === 浏览器访问 ===
# http://localhost:3002
# 账户: admin / 123456
最后修改:2026 年 10 月 24 日
如果觉得我的文章对你有用,请随意赞赏