智能体项目MaxKB4J - 本地部署与开发完整指南

1. 项目结构概览

项目整体目录结构如下：

🚀 项目源码地址： https://gitee.com/taisan/MaxKB4j

💡 提示：首次克隆项目后，请确认目录结构是否完整。

2. 环境准备

在开始部署前，请确保你的开发机已安装以下软件：

✅ 前端环境

Node.js ：版本 16 或更高 验证命令：node -v

推荐从 https://nodejs.org 下载 LTS 版本。

✅ 后端环境

Java ：版本 17 或更高 （推荐 OpenJDK 17）验证命令：java -version
Maven ：版本 3.8 或更高 验证命令：mvn -v
IDEA（可选但推荐）：用于 Java 开发、调试和代码导航。

✅ 数据库环境

PostgreSQL ：版本 15.x 安装后请确保服务已启动，默认端口为 5432。
MongoDB ：版本 8.x 安装后请确保 mongod 服务正在运行，默认端口为 27017。

📌 注意：所有服务建议在本地 localhost 上运行，便于开发调试。

3. 本地配置

项目依赖两个数据库：PostgreSQL （主业务数据 + 向量存储）和 MongoDB（非结构化数据或日志等）。需分别创建并配置。

3.1 创建 PostgreSQL 数据库

打开终端，进入 PostgreSQL 命令行（以 postgres 用户为例）：
bash 复制代码
```
psql -U postgres
```
执行以下 SQL 命令：

sql 复制代码

-- 创建数据库
CREATE DATABASE "maxkb4j";

-- 切换到新创建的数据库
\c "maxkb4j";

-- 安装 vector 扩展（用于向量相似性搜索）
CREATE EXTENSION IF NOT EXISTS vector;

⚠️ 如果提示 extension "vector" does not exist，说明未安装 pgvector。

安装方法（Ubuntu 示例）：
bash 复制代码
sudo apt install postgresql-15-pgvector

3.2 创建 MongoDB 数据库与用户

MongoDB 默认在首次写入时自动创建数据库，但为了权限安全，建议手动创建专用用户和数据库。

打开 MongoDB Shell：
bash 复制代码
```
mongosh
```
在 admin 数据库中创建用户（替换 your_mongo_username 和 your_mongo_password 为你的实际凭证）：

js 复制代码

use admin

db.createUser({
  user: "your_mongo_username",
  pwd: "your_mongo_password",
  roles: [
    { role: "readWrite", db: "maxkb4j" },
    { role: "dbAdmin", db: "maxkb4j" }
  ]
})

创建 maxkb4j 数据库（通过写入触发创建）：

js 复制代码

use maxkb4j

// 插入一条临时文档以确保数据库被创建
db.init.insertOne({ created_at: new Date() })

// 可选：清理测试数据
db.init.drop()

✅ 此时 maxkb4j 数据库已存在，且你创建的用户拥有完整操作权限。

3.3 配置应用参数

编辑后端配置文件：
MaxKB4J/src/main/resources/application-default.yml

填入你的真实数据库连接信息：

yaml 复制代码

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/maxkb4j      # PostgreSQL 地址
    username: your_postgres_username                   # 替换为你的 PG 用户名
    password: your_postgres_password                   # 替换为你的 PG 密码
    driver-class-name: org.postgresql.Driver
  data:
    mongodb:
      uri: mongodb://your_mongo_username:your_mongo_password@localhost:27017/maxkb4j?authSource=admin

🔐 安全提醒：

不要将真实密码提交到 Git 仓库。

authSource=admin 表示用户是在 admin 数据库中创建的，这是 MongoDB 的标准做法。

4. 开发与调试

4.1 启动前端

进入前端目录：
bash 复制代码
```
cd ui
```
安装依赖（首次运行需要）：
bash 复制代码
```
npm install
```
启动管理后台（默认模式）：
bash 复制代码
```
npm run dev
```
启动对话界面（聊天模式）：
bash 复制代码
```
npm run dev -- --mode chat
```

🖥️ 成功启动后，终端会显示类似：
复制代码
Local: http://localhost:3000/
打开浏览器即可访问对应页面。

默认账号：admin

默认密码：tarzan@123456

4.2 启动后端

📁 请在 项目根目录 （含 pom.xml 的目录）操作。

方法一：命令行启动（推荐用于开发）

编译并打包项目（首次或代码变更后需要）：
bash 复制代码
```
mvn clean compile
```
启动 Spring Boot 应用：
bash 复制代码
```
mvn spring-boot:run
```

✅ 成功启动后，日志中会显示：
复制代码
	Application is running! Access URLs:
	Local: 		http://localhost:8080
	External: 	http://10.16.98.141:8080

方法二：使用 IDEA 启动（图形化调试）

用 IDEA 打开项目根目录。
等待 Maven 自动导入依赖。
找到主启动类（通常为 com.maxkb.Application 或类似名称，含 @SpringBootApplication 注解）。
右键 → Run 'Application.main()'。

💡 优势：支持断点调试、热加载（需配置 DevTools）。

5. 访问项目

当前后端均成功启动后：

打开浏览器。
访问前端提供的地址（如 http://localhost:3000）。
你将看到如下界面：

🎉 恭喜！你已成功在本地运行 MaxKB4J 项目！

常见问题（FAQ）

Q1：启动报错 "Connection refused"？

A：请检查 PostgreSQL（5432）和 MongoDB（27017）服务是否正在运行，防火墙是否放行端口。

Q2：前端页面空白或 API 返回 404？

A：确认后端已成功启动，并检查前端代理配置是否指向正确的后端地址（通常开发模式下已内置代理）。

Q3：如何停止服务？

A：在终端按 Ctrl + C 终止进程。若需彻底清理，可使用 jps 查看 Java 进程并 kill，或重启终端。

Q4：MongoDB 报错 "Authentication failed"？

A：请确认用户名、密码、authSource=admin 三者匹配，且用户角色已正确授权给 maxkb4j 数据库。