2.1-RAG-Agent环境搭建指南（新人必看）Java 17、MySQL、Elasticsearch、Redis、MinIO、Kafka

查看源文件

一、安装 Java 17

macOS 安装方式

可以直接使用 Warp 终端工具中的 agent 安装，但没有创建符号链接，因为电脑上还安装了其他 JDK 版本。

可以安装 jenv 在 macOS 上管理多个版本的 JDK，参考： https://javabetter.cn/overview/jdk-install-config.html#_03%E3%80%81macos-%E5%AE%89%E8%A3%85-jdk

执行 jenv add /opt/homebrew/opt/openjdk@17 将 JDK17 添加到 jenv，再运行 jenv versions && echo "Setting global version to 17..." && jenv global 17 将 JDK17 设为全局默认版本。配置成功后，可以通过 java -version 确认。

然后在 IntelliJ IDEA 中把 paismart 项目的编译版本设置为 JDK17

Windows 用户可以直接下载安装包，再在 PATH 命令中设置路径。参考这个链接： 手把手教你在 Windows 和 macOS 下安装 JDK

Lan 的 macOS 安装步骤

# 使用 Homebrew 安装 OpenJDK 17
brew install openjdk@17
 
# 创建符号链接以使系统可以找到 java 可执行文件
sudo ln -sfn $(brew --prefix)/opt/openjdk@17/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk-17.jdk
 
# 添加到 ~/.zshrc 或 ~/.bash_profile 中
echo 'export PATH="$(brew --prefix)/opt/openjdk@17/bin:$PATH"' >> ~/.zshrc

验证安装

java -version

应显示类似以下输出：

openjdk version "17.0.x" 2023-xx-xx
OpenJDK Runtime Environment (build 17.0.x+x-xxxx)
OpenJDK 64-Bit Server VM (build 17.0.x+x-xxxx, mixed mode, sharing)

二、安装 MySQL

安装步骤

可以直接下载安装包，具体步骤可参考： MySQL 的安装、启动、连接(Windows、macOS 和 Linux)

Lan 的 安装步骤

# 安装 MySQL 8.0
brew install mysql@8.0
 
# 启动 MySQL 服务
brew services start mysql
 
# 设置 root 密码
mysql_secure_installation
复制代码

在安全设置向导中，设置 root 密码并按照提示完成其他安全设置。

验证安装

# 使用 root 用户登录 MySQL
mysql -uroot -p
复制代码

成功登录后，应该看到 MySQL 命令行界面。

创建数据库和用户

-- 创建数据库CREATE DATABASE PaiSmart CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

三、安装 Elasticsearch

Elasticsearch 安装相对复杂，我们单独写了一篇说明，可以通过链接查看： 【飞书文档】未命名文档

四、安装 Redis

参考这篇帖子： Redis 的安装，macOS、Windows 和 Linux 里面有详细讲安装方式。

安装完成后，可以通过 redis-cli 测试一下。

# 连接到 Redis
redis-cli
 
# 测试 Redis 是否正常工作
SET test "Hello PaiSmart"
GET test复制代码

应该能看到 Redis 返回 “Hello PaiSmart”。

五、安装 MinIO

关于 MinIO 可以参考教程《Spring Boot 整合 MinIO 自建对象存储服务》，里面有 MinIO 的介绍和在 Linux 上的安装部署，以及和 Spring Boot 的前后打通。

【飞书文档】 Spring Boot 整合 MinIO自建对象存储服务

安装步骤

可以先通过 Homebrew 安装：

# 安装 MinIO
brew install minio/stable/minio
 
# 安装 MinIO 客户端
brew install minio/stable/mc
复制代码

如果因命令行工具过时而安装失败，可以换一种方式。

访问这个链接： https://dl.min.io/server/minio/release/

根据操作系统选择对应版本。比如我用的是 Apple 芯片，就选第二个；Windows 用户选倒数第一个。下载完成后，需要在 macOS 上为文件添加执行权限。

执行 chmod +x minio ，然后为 MinIO 创建一个数据目录 data，之后执行 ./minio server data/ 就可以启动了。

Windows 下载后得到的是 exe 文件，可以直接运行；也要记得创建数据目录。正常情况下会输出以下信息：

完事直接点击 webui 的访问地址 http://192.168.0.113:55624 启动。注意这个端口号是会变化的，看自己的控制台就好了。

输入用户名和密码 minioadmin，就可以看到 MinIO 的管理端主页了。

Lan 的安装步骤

# 创建数据目录mkdir -p ~/minio/data
复制代码

# 设置环境变量export MINIO_ROOT_USER=minioadmin
export MINIO_ROOT_PASSWORD=minioadmin
 
# 启动 MinIO 服务
minio server ~/minio/data --console-address ":9001"

启动后查看日志中 API 地址访问 MinIO 控制台： http://192.168.31.227:9000 使用凭据登录：

• 用户名：minioadmin

• 密码：minioadmin

创建 MinIO 的 Bucket

MinIO 中的 **Bucket（桶）**是对象存储的核心概念之一，它相当于传统文件系统中的“文件夹”或“目录”，是存储对象（Object）的容器。

我们可以创建一个 uploads 的桶，它的名字和 yml 配置文件中 bucketName 相同就可以了。

权限设置为 Public

六、安装 Kafka

Kafka 是一个消息中间件，最初由 LinkedIn 开发，后来成为 Apache 的开源项目，主打一个高吞吐、低延迟。

RAG-Agent安装的是 Kafka 3.9 版本，支持 KRaft 模式，不再必须 zookeeper。相当于说以后大小事宜都由我 Kafka 来决定，不再需要 zookeeper 这个外援了。

下载 Kafka

可以通过 官网直接下载 src 压缩包解压。

也可以直接通过 curl 下载到本地，用 tar 命令解压。

curl -O https://downloads.apache.org/kafka/3.9.0/kafka_2.13-3.9.0.tgz
复制代码

配置 KRaft 模式

# 生成集群 ID
KAFKA_CLUSTER_ID="$(bin/kafka-storage.sh random-uuid)"echo $KAFKA_CLUSTER_ID# 格式化存储目录
bin/kafka-storage.sh format -t $KAFKA_CLUSTER_ID -c config/kraft/server.properties
复制代码

如果这一步出现这个问题 Invalid cluster.id

请直接删除 rm -rf /tmp/kraft-combined-logs 对应的日志，主要是因为 cluster ID 不匹配。

启动 Kafka 服务器

# 使用 KRaft 模式启动 Kafka
bin/kafka-server-start.sh config/kraft/server.properties
复制代码

如果启动过程中出现这个问题：

是因为 KRaft 模式需要在启动前初始化，可以使用 Warp 等智能终端来辅助排查。

启动 Kafka 脚本

我这里创建了一个脚本，命名为：start-kafka.sh

#!/bin/bash
 
# Kafka KRaft模式启动脚本
# 自动处理cluster ID冲突问题
 
set -e  # 遇到错误立即退出
 
LOG_DIR="/tmp/kraft-combined-logs"
CONFIG_FILE="config/kraft/server.properties"
 
echo "=== Kafka KRaft Mode Startup Script ==="
echo "当前时间: $(date)"
echo "工作目录: $(pwd)"
echo
 
# 函数：清理日志目录
cleanup_logs() {
    if [ -d "$LOG_DIR" ]; then
        echo "检测到现有日志目录，正在清理..."
        rm -rf "$LOG_DIR"
        echo "✓ 日志目录已清理: $LOG_DIR"
    else
        echo "日志目录不存在，无需清理"
    fi
}
 
# 函数：生成并格式化存储
format_storage() {
    echo
    echo "=== 第1步：生成集群ID ==="
    KAFKA_CLUSTER_ID="$(bin/kafka-storage.sh random-uuid)"
    echo "生成的集群ID: $KAFKA_CLUSTER_ID"
 
    echo
    echo "=== 第2步：格式化存储目录 ==="
    if bin/kafka-storage.sh format -t "$KAFKA_CLUSTER_ID" -c "$CONFIG_FILE"; then
        echo "✓ 存储格式化成功"
        return 0
    else
        echo "✗ 存储格式化失败，可能是cluster ID冲突"
        return 1
    fi
}
 
# 函数：启动Kafka服务器
start_kafka() {
    echo
    echo "=== 第3步：启动Kafka服务器 ==="
    echo "配置文件: $CONFIG_FILE"
    echo "正在启动Kafka..."
    echo "提示: 使用 Ctrl+C 停止服务器"
    echo
 
    bin/kafka-server-start.sh "$CONFIG_FILE"
}
 
# 主逻辑
main() {
    # 尝试格式化存储
    if ! format_storage; then
        echo
        echo "⚠️  检测到cluster ID冲突，正在清理并重试..."
        cleanup_logs
 
        echo
        echo "=== 重新尝试格式化 ==="
        if ! format_storage; then
            echo "✗ 重试后仍然失败，请检查配置"
            exit 1
        fi
    fi
 
    # 启动Kafka
    start_kafka
}
 
# 捕获中断信号
trap 'echo -e "\n\n🛑 接收到停止信号，正在关闭Kafka..."; exit 0' INT TERM
 
# 检查必要文件是否存在
if [ ! -f "$CONFIG_FILE" ]; then
    echo "✗ 配置文件不存在: $CONFIG_FILE"
    exit 1
fi
 
if [ ! -f "bin/kafka-storage.sh" ]; then
    echo "✗ kafka-storage.sh 不存在，请确认在正确的Kafka目录中运行"
    exit 1
fi
 
# 执行主逻辑
main

执行主逻辑

main

为脚本添加执行权限：

chmod +x start-kafka.sh
复制代码

运行脚本：

./start-kafka.sh
复制代码

验证安装

# 创建主题
bin/kafka-topics.sh --create --topic quickstart-events --bootstrap-server localhost:9092
 
# 查看主题列表
bin/kafka-topics.sh --list --bootstrap-server localhost:9092
 
# 查看主题详情
bin/kafka-topics.sh --describe --topic quickstart-events --bootstrap-server localhost:9092

应该能看到刚创建的测试主题。

发送测试消息：

# 启动生产者控制台
bin/kafka-console-producer.sh --topic quickstart-events --bootstrap-server localhos

接收消息：

# 启动消费者控制台
bin/kafka-console-consumer.sh --topic quickstart-events --from-beginning --bootstrap-server localhost:9092
复制代码

创建RAG-Agent所需主题

# 创建文件处理主题
bin/kafka-topics.sh --create --bootstrap-server localhost:9092 --replication-factor 1 --partitions 1 --topic file-processing
 
# 创建向量化主题
bin/kafka-topics.sh --create --bootstrap-server localhost:9092 --replication-factor 1 --partitions 1 --topic vectorization
 
# 创建死信队列
bin/kafka-topics.sh --create --bootstrap-server localhost:9092 --replication-factor 1 --partitions 1 --topic file-processing-dlt

七、初始化项目

第一步，申请RAG-Agent源码权限

申请方式查看这个帖子： https://paicoding.com/column/10/3

第二步，用 IntelliJ IDEA 导入项目

第三步，在 application-dev.yml 中更改 MySQL 的配置连接和用户名密码。

第四步，配置 Elasticsearch 索引

参考【 ✅Elasticsearch 8.10 安装 】启动 ES 后，启动项目后，会在控制台看到这样一条信息：

可以通过 curl -X GET 'http://localhost:9200/knowledge_base/_mapping?pretty' 来查看索引（http 模式下），如果是 HTTPS 模式，请查看： HTTPS 模式下 ES 索引的获取和删除

确认 application-dev.yml 中的配置是正确的。

第五步，确认自己的 Redis 是启动的

application-dev.yml 中的配置也是正确的。

第六步，确认自己的 MinIO 是启动的

并且 application-dev.yml 中的配置是匹配的

第七步，确认 Kafka 是启动的

并且 application-dev.yml 中的配置也是匹配的

第八步，确认 DeepSeek API 填写正确

本地参考： 【飞书文档】Ollama+DeepSeek本地部署（新人必看）

官方 api 参考： 【飞书文档】✅DeepSeek API申请（新人必看）

第九步，确认向量 API 填写正确

【飞书文档】✅阿里向量化 API 申请，附豆包 embedding ，目前已经改用阿里的 embedding 模型，支持 2048 维，可以和 ES 8.10 兼容，豆包竟然下架了 2048 维模型，垃圾，不向下兼容。

八、功能测试

1.运行后端项目

在 IDEA 中打开项目并启动 main 类 SmartPaiApplication。控制台没有报错时，后台服务即启动成功。

如果遇到错误，请检查控制台日志和配置信息。

如果 8081 端口被占用导致服务无法启动，请结束占用端口的进程。

Lan 在开发模式下运行的方式：

# 如果要在开发环境中运行
./mvnw spring-boot:run

2.访问前端测试页面

如果你暂时还没有拉取 web 端，那么可以直接通过测试页面确认服务是否启动成功： http://localhost:8081/test.html

项目登录账号和密码：admin admin123

3.运行 Web 前端

可以用 VSCode 或者 Cursor 导入前端项目，在 frontend 目录下。

然后在终端执行 pnpm i 命令安装依赖，注意切到 frontend 目录下（首先要有 Node.js 环境）：

注意 Node.js 不要用太新的版本，我本地是 20。

然后执行 pnpm run dev 命令启动前端：

然后直接点击控制台的链接就可以访问前端了：