✅本地运行派聪明指南（新人必看）

前置环境准备妥当后，接下来就需要从 GitCode 上拉取源码，然后在本地跑起来派聪明了。

一、拉取源码

拉取源码我个人比较喜欢的方式是，使用 GitHub 桌面版，图形化操作起来比较丝滑。

GitCode 地址：https://gitcode.com/qing_gee/PaiSmart

这次代码采用的是邀请审核机制，获取邀请方法，请戳👉星球里这个帖子：https://paicoding.com/article/detail/2602100040108033

如果你已经在本地安装了 GitHub 桌面版，可以直接点击 file 这里 clone 仓库。

然后填写前面的 GitHub 地址或者码云地址，选择 URL 这个 tab。

我本地已经 download 了。

点击【show in finder】这里可以看到下面的目录仓库。

前端的 vue 代码在 frontend 目录在，后端的 Java 代码在 src 目录下。

二、启动后端

后端代码，建议用 IntelliJ IDEA 打开。

现在本地开发建议按“准备 .env -> 启基础服务 -> 启后端 -> 启前端”的顺序启动，不再需要把一堆环境变量手动 export 到终端。

1. 准备项目根目录 .env

项目根目录的 .env 用于保存后端本地运行和部署相关配置。首次使用时先复制模板：

cp .env.example .env

后端启动时会通过 DotenvEnvironmentPostProcessor 自动读取项目根目录 .env，所以无论是 IDE 直接运行 SmartPaiApplication，还是在项目根目录执行 mvn spring-boot:run，都会优先使用这里的配置。

.env 里当前主要有三类配置：

• 应用运行配置：MySQL、Redis、Kafka、MinIO、Elasticsearch、JWT、AI Provider 等
• 初始化与安全配置：如 ADMIN_BOOTSTRAP_*、APP_AUTH_REGISTRATION_MODE、SECURITY_ALLOWED_ORIGINS
• 前端部署配置：如 DEPLOY_SERVER_HOST、DEPLOY_SERVER_USER、DEPLOY_SERVER_KEY、DEPLOY_TARGET_DIR、DEPLOY_HEALTHCHECK_URL

几个关键项建议优先确认：

• SPRING_PROFILES_ACTIVE=dev：本地源码启动默认使用 dev
• SPRING_DATASOURCE_*、SPRING_DATA_REDIS_*：数据库和 Redis 连接
• SPRING_KAFKA_BOOTSTRAP_SERVERS、MINIO_*、ELASTICSEARCH_*：基础依赖地址
• JWT_SECRET_KEY：必须是 Base64 字符串，可用 openssl rand -base64 32 生成
• ADMIN_BOOTSTRAP_ENABLED：仅首次创建管理员时临时改为 true，创建完成后改回 false

说明：

• .env 是后端和部署脚本共用的根配置
• 前端自己的 Vite 变量仍放在 frontend/.env、frontend/.env.test、frontend/.env.prod
• pnpm run dev 实际使用的是 vite --mode test，默认会读取 frontend/.env.test

2. 启动本地基础服务

infra.sh 是现在推荐的本地基础设施启动入口，用来统一管理 minio、kafka、elasticsearch。

infra.sh

用于在本机启动、停止和查看基础依赖服务，目前支持 minio、kafka、elasticsearch。

# 启动全部基础服务
./infra.sh start

# 启动指定服务
./infra.sh start minio kafka

# 查看状态
./infra.sh status

# 查看某个服务日志
./infra.sh logs elasticsearch

# 输出本地访问地址
./infra.sh urls

如果只想启动部分依赖，也可以按服务名传参：

./infra.sh start minio kafka

3. 启动后端

基础服务就绪后，在项目根目录启动 Spring Boot：

mvn spring-boot:run

也可以直接在 IDE 中运行 src/main/java/com/yizhaoqi/smartpai/SmartPaiApplication.java，效果一样，都会自动读取根目录 .env。

直接点击运行/debug 按钮，或者直接 run main 方法，都可以。

这里注意，前置环境 MySQL、Redis、ES、MinIO、Kafka 的配置信息都是对应上的。

如果有遇到任何 sql 相关的错误，很有可能是数据库结构发生了变化。

这个时候可以拉取最新的代码，并且把本地的 paismart 数据库删除，重新新建一个空的数据库。

再次运行 SmartPaiApplication，让 sql 重新执行（我们已经让数据文件自动执行了），如果这次没有 sql 相关的报错，像下面这样，一般是可以正常启动的。

如果在后续上传文件时发现索引创建失败，那么可以执行 curl -X DELETE 'http://localhost:9200/knowledge_base' 删除，重新启动项目，保证索引是最新的，HTTPS 模式下的方法请参考：https://t.zsxq.com/JTTyV

后端启动成功的标志就是 Tomcat started on port 8081。

三、启动前端

前端的话，推荐用 Trae、VSCode 或者 Cursor 打开，我这里用的是 Trae。启动非常简单，切换到 frontend 目录，然后先执行 pnpm i 安装依赖，然后执行 pnpm run dev就可以启动前端了。

前端启动成功后，会自动在浏览器打开。