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 数据库

1. 打开终端，进入 PostgreSQL 命令行（以 postgres 用户为例）：

   psql -U postgres
   

2. 执行以下 SQL 命令：

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

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

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

⚠️ 如果提示 extension "vector" does not exist，说明未安装 pgvector。
安装方法（Ubuntu 示例）：

sudo apt install postgresql-15-pgvector

---

3.2 创建 MongoDB 数据库与用户

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

1. 打开 MongoDB Shell：

   mongosh
   

2. 在 admin 数据库中创建用户（替换 your_mongo_username 和 your_mongo_password 为你的实际凭证）：

use admin

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

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

use maxkb4j

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

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

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

---

3.3 配置应用参数

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

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

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 启动前端

1. 进入前端目录：

   cd ui
   

2. 安装依赖（首次运行需要）：

   npm install
   

3. 启动管理后台（默认模式）：

   npm run dev
   

4. 启动对话界面（聊天模式）：

   npm run dev -- --mode chat
   

🖥️ 成功启动后，终端会显示类似：

Local: http://localhost:3000/

打开浏览器即可访问对应页面。

默认账号：admin
默认密码：tarzan@123456

---

4.2 启动后端

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

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

1. 编译并打包项目（首次或代码变更后需要）：

   mvn clean compile
   

2. 启动 Spring Boot 应用：

   mvn spring-boot:run
   

✅ 成功启动后，日志中会显示：

	Application is running! Access URLs:
	Local: 		http://localhost:8080
	External: 	http://10.16.98.141:8080

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

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

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

---

5. 访问项目

当前后端均成功启动后：

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

🎉 恭喜！你已成功在本地运行 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 数据库。

---