JchatMind 系统启动与调试教程

一、如何打开 PowerShell

后续启动命令都需要在 Windows PowerShell 中执行。

最简单的方法是：

1. 点击电脑左下角 开始菜单
2. 在搜索框输入：

PowerShell

3. 点击打开：

Windows PowerShell

打开后会出现一个黑色或蓝色的命令窗口，后续命令都可以在这里输入。

例如，打开后可以先输入：

cd D:\毕业\JchatMind\JchatMind

进入项目目录，然后继续执行后面的启动命令。

---

二、启动前需要确认的内容

系统运行前需要保证以下服务正常：

1. Docker Desktop 已启动
2. PostgreSQL 数据库容器已启动
3. Ollama 服务正常
4. bge-m3 模型已下载
5. 后端 Spring Boot 项目正常启动
6. 前端项目正常启动

---

三、启动 Docker 和数据库

1. 打开 Docker Desktop

在 Windows 开始菜单搜索并打开：

Docker Desktop

等待 Docker Desktop 完全启动。

然后打开 PowerShell，执行：

docker version

如果能看到：

Client:
Server:

说明 Docker 正常。

如果只看到 Client，没有 Server，说明 Docker Desktop 还没有完全启动。

---

2. 进入项目目录

在 PowerShell 中执行：

cd D:\毕业\JchatMind\JchatMind

注意：这里要进入包含 docker-compose.yml 的目录。

---

3. 启动 PostgreSQL 数据库容器

执行：

docker compose up -d

然后查看容器是否启动成功：

docker ps

正常情况下应该能看到类似内容：

jchatmind-postgres    0.0.0.0:5432->5432/tcp

只要看到 jchatmind-postgres，并且有 5432->5432，说明数据库容器启动成功。

---

4. 检查数据库是否可用

执行：

docker exec -it jchatmind-postgres psql -U postgres -d jchatmind

进入数据库后，执行：

\dt

如果能看到数据库表，说明数据库正常。

再检查知识库向量数据：

SELECT COUNT(*) FROM chunk_bge_m3;

如果结果大于 0，说明知识库文档已经成功入库。

退出数据库可以输入：

\q

---

四、检查 Ollama 和 bge-m3 模型

1. 检查 Ollama 是否正常

打开 PowerShell，执行：

ollama list

如果能正常显示模型列表，说明 Ollama 服务正常。

如果提示：

could not connect to a running Ollama instance

可以执行：

ollama serve

然后不要关闭这个窗口。

重新打开一个新的 PowerShell，再执行：

ollama list

---

2. 检查 bge-m3 模型是否存在

执行：

ollama list

如果模型列表里能看到：

bge-m3

说明模型已经下载。

如果没有，需要执行：

ollama pull bge-m3

下载完成后再次执行：

ollama list

确认 bge-m3 出现在列表中。

---

五、启动后端 Spring Boot

1. 进入后端项目目录

打开 PowerShell，执行：

cd D:\毕业\JchatMind\JchatMind\jchatmind

---

2. 启动后端

可以直接在 IDEA 中运行 Spring Boot 启动类。

也可以在 PowerShell 中执行：

mvn spring-boot:run

后端启动成功后，一般访问地址是：（忽略）

http://localhost:8080

---

3. 后端常见报错检查 （忽略）

如果后端控制台出现：

Connection to localhost:5432 refused

说明数据库没有启动成功，需要检查：

docker ps

如果没有看到 jchatmind-postgres，重新执行：

cd D:\毕业\JchatMind\JchatMind
docker compose up -d

如果后端出现和下面地址相关的错误：

localhost:11434

一般说明 Ollama 或 bge-m3 没有正常启动，需要检查：

ollama list

---

六、启动前端项目

1. 进入前端目录

打开新的 PowerShell，进入前端项目目录，例如：

cd D:\毕业\JchatMind\JchatMind\ui

如果前端目录名字不是 frontend，就进入实际的前端目录。

---

2. 第一次启动需要安装依赖（忽略）

如果是第一次运行前端，执行：

npm install

---

3. 启动前端

执行：

npm run dev

启动成功后，终端一般会显示类似：

http://localhost:5173

在浏览器中打开这个地址即可进入系统页面。

---

七、系统启动后的调试流程

系统启动后，建议按照下面顺序测试。

---

测试 1：检查页面是否能正常打开

浏览器访问前端地址，例如：

http://localhost:5173

如果页面能正常显示，说明前端启动成功。

如果页面打不开，需要检查前端 PowerShell 窗口中是否有报错。

---

测试 2：检查智能体是否能加载

进入系统页面后，查看是否能看到智能体，例如：

agent

如果智能体加载失败，一般说明后端或数据库有问题。

可以检查：

docker ps

确认 jchatmind-postgres 是否正在运行。

---

测试 3：检查知识库数据是否存在（忽略）

打开 PowerShell，进入数据库：

docker exec -it jchatmind-postgres psql -U postgres -d jchatmind

执行：

SELECT COUNT(*) FROM chunk_bge_m3;

如果结果大于 0，说明知识库有数据。

如果是 0，说明知识库文档还没有成功入库，需要重新上传或重新处理知识库文档。

---

八、推荐调试问题

下面这些问题可以用于系统启动后的演示和调试。

---

问题 1：测试基础知识库问答

在聊天框输入：

请根据知识库内容，回答一下明天天气如何？

正常效果：

系统会调用 KnowledgeTool
从知识库中检索相关内容
然后回答：根据知识库信息，明天可能下雨。

这是最推荐给老师演示的问题。

---

问题 2：测试明确的知识库调用

输入：

请基于知识库告诉我明天天气如何。

正常效果：

系统优先调用 KnowledgeTool
然后根据知识库内容生成回答

示例回答：

根据知识库信息，明天可能下雨。

---

问题 3：测试城市和日期工具

输入：

请告诉我当前城市和今天日期。

正常效果：

系统会调用 getCity 和 getDate 工具
返回当前城市和日期

示例回答：

当前城市是深圳，今天是2026年5月19日。

---

问题 4：测试多工具协同

输入：

请根据当前日期和知识库内容，告诉我明天天气如何。

正常流程应该是：

1. 调用 getCity
2. 调用 getDate
3. 调用 KnowledgeTool
4. 根据知识库内容生成最终回答

示例回答：

根据知识库信息，明天是2026年5月20日，深圳的天气可能下雨。

这个问题适合汇报时展示系统的多工具调用能力。

---

问题 5：测试知识库无相关内容

输入：

请根据知识库内容，回答一下今天中午吃什么？

理想结果：

知识库中没有检索到相关信息。

如果系统乱回答，说明需要继续优化 Agent 的系统提示词，让它不要编造知识库中没有的内容。

---

九、汇报时推荐演示顺序

给老师汇报时，可以按这个顺序演示：

1. 打开 PowerShell
2. 执行 docker ps，展示 PostgreSQL 容器正在运行
3. 执行 ollama list，展示 bge-m3 模型已经存在
4. 启动后端 Spring Boot
5. 启动前端 npm run dev
6. 浏览器打开前端页面
7. 输入问题：
   请根据知识库内容，回答一下明天天气如何？
8. 展示系统调用 KnowledgeTool
9. 展示系统根据知识库内容生成最终回答

十、系统成功启动的标志

如果系统启动后，输入：

请根据知识库内容，回答一下明天天气如何？

系统能够完成以下流程：

KnowledgeTool 被调用
↓
知识库返回相关内容，例如“明天可能下雨”
↓
系统最终回答“根据知识库信息，明天可能下雨”

说明：

前端启动成功
后端启动成功
数据库连接成功
Ollama 模型正常
知识库检索成功
Agent 回答正常

至此，系统启动和调试完成。