前言
咱们的企业知识库系统已经开发得比较完整了,包含了用户认证、文档管理、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.sql3.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 |
| DeepSeek | https://api.deepseek.com/v1 | 备选模型,仅用于 Chat |
大模型通过远程 API 调用,本地无需安装任何模型运行环境,只需要有可用的 API Key。
4.5.1 获取 API Key
通义千问(推荐):
- 访问 阿里云百炼平台
- 注册/登录阿里云账号
- 进入「模型广场」→ 选择「通义千问-Max」→ 点击「API调用」
- 在「API Key」页面创建新的 API Key
- 复制保存 API Key
DeepSeek(备选):
- 访问 DeepSeek 开放平台
- 注册/登录账号
- 进入「API Keys」页面创建新的 API Key
- 复制保存 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-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx4.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 服务:
- 登录 mail.163.com
- 点击「设置」→「POP3/SMTP/IMAP」
- 开启「SMTP服务」(IMAP/SMTP服务 或 POP3/SMTP服务)
- 按提示发送短信验证后,获取授权码(非邮箱登录密码)
- 复制保存授权码
也可以使用 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: true4.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 中分别启动:
| 序号 | 模块 | 启动类 | 端口 | 说明 |
|---|---|---|---|---|
| 1 | kb-user-auth | UserAuthApplication | 8081 | 用户认证,需要最先启动 |
| 2 | kb-foundation | FoundationApplication | 8089 | 基础服务(配置、字典、通知) |
| 3 | kb-document | DocumentApplication | 8082 | 文档管理,核心服务 |
| 4 | kb-file | FileApplication | 8084 | 文件管理 |
| 5 | kb-search | SearchApplication | 8083 | 搜索服务 |
| 6 | kb-ai | AiApplication | 8086 | AI 助手 |
| 7 | kb-statistics | StatisticsApplication | 8085 | 统计服务 |
| 8 | kb-graph | GraphApplication | 8088 | 知识图谱 |
| 9 | kb-gateway | GatewayApplication | 8080 | API 网关,最后启动 |
在 IDEA 中启动步骤:
- 用 IntelliJ IDEA 打开
knowledge-base-backend目录(即包含pom.xml的根目录) - 等待 IDEA 自动识别 Maven 项目并下载依赖
- 找到各模块的 Application 类(例如
kb-user-auth/src/main/java/com/knowledge/base/userauth/UserAuthApplication.java) - 右键点击类名 → Run 'UserAuthApplication'
- 按上述顺序依次启动每个模块
5.3 最少启动方案
如果你只是想快速体验核心功能,最少只需要启动 3 个服务:
| 序号 | 模块 | 端口 | 说明 |
|---|---|---|---|
| 1 | kb-user-auth | 8081 | 登录认证 |
| 2 | kb-document | 8082 | 文档管理 |
| 3 | kb-gateway | 8080 | API 网关(最后启动) |
注意: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/login

账号:admin 密码:123456
登录成功之后,主页面如下:

主要功能页面
| 页面 | 地址 | 说明 |
|---|---|---|
| 首页/仪表盘 | /dashboard | 系统概览和统计数据 |
| 文档中心 | /documents | 浏览和搜索文档 |
| AI助手 | /ai | AI 对话和文档问答 |
| AI写作 | /ai-writing | AI 辅助写作 |
| 知识图谱 | /knowledge-graph | 知识图谱可视化 |
| 文件管理 | /files | 文件上传和管理 |
| 个人中心 | /profile | 个人信息和设置 |
| 系统管理 | /admin | 用户、角色、权限管理 |
Swagger 接口文档
启动后可以通过以下地址访问各服务的 API 文档:
- 用户认证服务:http://localhost:8081/doc.html
- 文档管理服务:http://localhost:8082/doc.html
- 基础服务:http://localhost:8089/doc.html
8. 常见问题排查
8.1 数据库连接失败
错误信息:CommunicationsException: Communications link failure
排查步骤:
- 确认 MySQL 服务已启动
- 确认用户名密码正确(默认
root/123456) - 确认 3306 端口未被防火墙拦截
- 确认所有数据库已创建(10 个
kb_*数据库) - 如果密码不同,修改所有模块
application.yml中的spring.datasource.password
# 测试 MySQL 连接
mysql -u root -p -e "SHOW DATABASES LIKE 'kb_%';"8.2 Redis 连接失败/超时
错误信息:RedisConnectionFailureException 或 RedisCommandTimeoutException
原因:远程 Redis 间歇性超时(已在最新代码中优化,确保拉取最新代码)
解决:
- 确认网络能访问
117.72.88.11:6379 - 如果无法连接远程 Redis,可以在本地安装 Redis 并修改所有模块的配置
在本地安装 Redis 后,修改各模块 application.yml:
spring:
data:
redis:
host: localhost
port: 6379
password: # 本地 Redis 一般无密码
database: 08.3 Nacos 连接失败
错误信息:com.alibaba.nacos.api.exception.NacosException
解决:
- 确认
117.72.88.11:8848网络可达 - 如果 Nacos 不可用,可以在各模块的
application.yml中注释掉 Nacos 配置,改用本地配置启动
8.4 前端页面能打开但数据不显示
原因:通常是因为后端服务未完全启动或跨域问题
排查:
- 打开浏览器开发者工具(F12)
- 查看 Network 标签页中的 API 请求是否有报错
- 查看 Console 标签页是否有 JavaScript 错误
- 确认至少启动了 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 dev8.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