上一篇我们定了技术选型：pig 4.0 + UniApp + Element Plus + Spring AI 2.0。这一篇开始动手——把 pig 4.0 源码拉下来、跑起来，然后改造它。

但跑起来之前，有一件事必须先说清楚：pig 团队自己做了一个叫 PIG AI 的产品。很多人会问：「既然 pig 官方都做了 AI 平台，为什么还要自己集成 Spring AI？」这篇会先回答这个问题，然后再讲怎么把 pig 拉下来、配好、启动、验证。

一、先认清 PIG AI：为什么我不直接用它

1.1 PIG AI 是什么

PIG AI 是 pig 团队推出的企业级大语言模型（LLM）应用开发平台，结合了后端即服务（Backend as Service）和 LLMOps 的理念，目标是让开发者快速搭建生产级的生成式 AI 应用。

PIG AI 内置了构建 LLM 应用所需的关键技术栈，包括对数十个模型的支持、高质量的 RAG 引擎以及灵活的 Agent 框架，并提供了一套易用的界面和 API。

简单说，它是一个开箱即用的 AI 中台——自带模型管理、RAG 引擎、Agent 编排、可视化界面。

1.2 PIG AI 要解决的三大挑战

官方总结了企业 AI 落地的三大痛点，以及 PIG AI 的对应方案：

核心定位是两条：链接模型和应用层（作为桥梁连接底层大模型与上层业务应用）、服务 Java 开发者（提供功能全面、生产就绪的 AI 应用开发平台）。

1.3 为什么我不用 PIG AI

听起来很美好对吧？但我没用它。三个原因：

① PIG AI 不是开源的

这是最关键的一点。我整个项目是开源的，不可能把一个闭源商业组件塞进去。Spring AI 是 Apache 2.0 协议，可以随意集成、修改、商用。

② 功能太重，我用不到

PIG AI 是面向企业的「AI 中台」，自带模型管理、RAG 引擎、Agent 编排、可视化运营界面。但我这个独立开发者项目只需要：调一个 LLM 做对话、Function Calling 调用业务接口、简单的对话上下文记忆。引入 PIG AI 等于用大炮打蚊子，运维成本远超收益。

③ 学习成本与项目目标不匹配

我的目标是「3 个月内独立完成 App 上架」，不是「搭建企业 AI 平台」。Spring AI 的 ChatClient + @Tool + Advisors 三件套，已经够我用了。

1.4 结论：用 Spring AI 自己集成

最终决定：pig 负责脚手架，Spring AI 负责 AI 能力，两者通过 Spring Boot 4.0 天然集成。整个技术栈全部开源，AI 能力按需引入，不背任何「中台」包袱。

后面的「集成 Spring AI」会单独开一篇讲，这篇只讲 pig 的初始化和运行。

二、基础环境准备

官方文档明确列了环境要求，我实测过的版本如下：

特别提醒：Node 版本不要图新上 23+，pig-ui 在 23 上偶尔会报 ERESOLVE 错误。20.19.0 是经过验证的甜点版本。

Maven 不在 PATH 里，按项目约定必须用全路径调用：D:\base\apache-maven-3.8.1\bin\mvn.cmd -version。settings.xml 配置阿里云镜像加速。

项目硬约束：不要用 PowerShell 的 Get-Content | mysql 管道导入 SQL，中文会乱码。必须用 mysql --execute="source file.sql"。

三、项目下载与模块拓扑

git clone https://gitee.com/log4j/pig.git

pig 的模块分三层：pig-register（基础设施）、pig-auth（认证授权）、pig-upms-biz（业务服务）、pig-gateway（网关）、pig-visual（工具，可选）、pig-boot（单体启动器）。

pig-boot 就是「单体启动器」——把所有业务模块的依赖塞到一个工程里，用 PigBootApplication 一个 main 方法启动，省去网关路由、服务注册的复杂度。我的选择是：开发阶段用 pig-boot 单体启动，部署时再考虑切回微服务模式。具体的单体模式用法在第八章详细讲。

四、初始化数据库（微服务模式）

mysql -uroot -p  mysql> use pig_config; mysql> source db/pig_config.sql;  mysql> use pig; mysql> source db/pig.sql;

验证：SELECT COUNT(*) FROM sys_user; 应该返回 2（admin + test）。字符集必须是 utf8mb4。

五、配置文件修改（微服务模式）

修改 pig-register/src/main/resources/application.properties 中的 pig_config 数据库连接信息。

Nacos 3.0 端口变更：开源版 pig-register 控制台端口是 18080。访问 http://127.0.0.1:18080，默认账号密码 nacos/nacos。服务注册端口仍是 8848。

启动 pig-register 后，在 Nacos 控制台修改以下 Data Id 的配置：

六、启动顺序（微服务模式）

1. pig-register/PigNacosApplication.java     // 必须第一个，Nacos 注册中心2. pig-auth/PigAuthApplication.java          // 认证服务3. pig-upms-biz/PigAdminApplication          // 用户权限服务4. pig-gateway/PigGatewayApplication.java    // 网关# 可选模块：用到代码生成 / 监控 / 定时任务时再启动5. pig-codegen/PigCodeGenApplication 6. pig-monitor/PigMonitorApplication 7. pig-quartz/PigDaemonQuartzApplication

验证：访问 http://localhost:9999 拿到 404 说明网关在跑；访问 http://localhost:18080/nacos 看到服务列表有 pig-auth、pig-upms-biz 说明注册成功。

七、部署前端 pig-ui（微服务模式）

git clone https://gitee.com/log4j/pig-ui.git cd pig-ui# 检查 node 版本，必须是 20.19.0 或附近偶数 LTS 版本node -v  npm install --registry=https://registry.npmmirror.com npm run dev

如果报 ERESOLVE 错误，删掉 node_modules 和 package-lock.json 重试。

启动成功后，浏览器访问 http://localhost:8888，默认账号 admin / 默认密码 123456。

八、单体模式快速启动（pig-boot）

上面讲的微服务模式（register + auth + upms + gateway 四个进程）是 pig 的完整形态。但独立开发时，每个进程都启动太重了。pig 官方专门为这种场景提供了单体模式。

官方建议：单体模式和微服务模式共用主体业务代码。首次使用建议先按快速开始文档跑通微服务模式，再切换到 boot profile。我反过来——开发阶段全程用单体模式，部署时再切回微服务。

8.1 单体模式的特点

8.2 运行服务端

① 初始化数据库（单体模式只用核心业务库，不需要 pig_config）：

mysql -uroot -proot mysql> source db/pig.sql;

② 启用 boot profile：

mvn clean install -Pboot -DskipTests

项目硬约束：Maven 不在 PATH 里，必须用全路径：D:\base\apache-maven-3.8.1\bin\mvn.cmd clean install -Pboot -DskipTests

③ 修改本地配置（pig-boot/src/main/resources/application-dev.yml）：

spring:   datasource:     master:       url: jdbc:mysql://127.0.0.1:3306/pig?characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=false&serverTimezone=GMT%2B8       username: root       password: root       driver-class-name: com.mysql.cj.jdbc.Driver   data:     redis:       host: 127.0.0.1       port: 6379       database: 0       password:

单体模式默认端口 9999，上下文路径 /admin。

④ 启动服务（IDEA 里运行 PigBootApplication.java，或直接跑 jar）：

java -Dfile.encoding=utf-8 -jar pig-boot/target/pig-boot.jar

8.3 运行前端（单体模式专用配置）

前端代码跟微服务模式是同一套，但要改两个环境变量来关闭微前端配置：

git clone https://gitee.com/log4j/pig-ui.git -b master cd pig-ui npm install --registry=https://registry.npmmirror.com

修改 .env 文件：

VITE_IS_MICRO=false VITE_ADMIN_PROXY_PATH=http://127.0.0.1:9999

npm run dev

8.4 访问与接口文档

浏览器访问 http://localhost:8888，默认账号 admin / 默认密码 123456。

单体模式下网关上下文是 /admin（微服务模式没有这个前缀），接口文档地址不同：

• Swagger UI：http://127.0.0.1:9999/admin/swagger-ui.html

• Knife4j：http://127.0.0.1:9999/admin/doc.html

8.5 Docker 单体模式

pig 仓库自带 docker-compose-boot.yml，作为单体模式的参考部署方案：

mvn clean install -Pboot -DskipTests docker compose -f docker-compose-boot.yml build docker compose -f docker-compose-boot.yml up -d

8.6 我的实际选择

开发阶段我全程用单体模式，原因：

• 启动快（5 秒 vs 30 秒+），改完代码重启不痛苦

• 调试断点不需要跨进程，IDEA 一个窗口搞定

• 不用维护 Nacos 配置，application-dev.yml 改完即生效

• 不用先启 register 再启 auth 再启 upms 那一套启动顺序

部署上线时再切回微服务模式，用 Docker Compose 编排。

九、创建 pig-note 模块

到这一步 pig 已经能跑了。但我们要写自己的业务，不能往 pig-upms-biz 里塞代码——那样升级 pig 时会冲突。

在 pig 根目录下新建 pig-note/ 模块，结构：

pig-note/ ├── pom.xml └── src/main/java/com/brainypipe/note/     ├── PigNoteApplication.java        # 启动类     ├── controller/                   # 控制层     ├── service/                      # 业务层     │   └── impl/     ├── mapper/                       # MyBatis Plus Mapper     ├── entity/                       # 实体类     ├── config/                       # 配置类     └── common/                       # 业务常量、枚举

包路径统一用 com.brainypipe.note.*，不用 pig 默认的 com.pig4cloud.pig.*，原因：业务代码跟 pig 框架代码物理隔离，升级 pig 时一眼能看出哪些是我自己的；后续如果要拆分独立项目，包路径不用大改。

pom.xml 依赖 pig-common-feign / pig-common-mybatis / pig-common-security。后续要集成 Spring AI 时再加 spring-ai-openai-spring-boot-starter 依赖。

在 pig 根目录的 pom.xml 的 <modules> 中加入 <module>pig-note</module>。

项目硬约束：pig-upms-biz 模块必须用普通 JAR 打包（不是 Spring Boot fat JAR），否则 pig-boot 依赖不到。这点官方默认配置就是对的，不要乱改。

十、第一行可运行代码

在 IDEA 里找到 pig-boot/src/main/java/com/pig4cloud/pig/PigBootApplication.java，右键 Run。控制台输出：

o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat initialized with port 9999 (http) com.pig4cloud.pig.PigBootApplication     : Started PigBootApplication in 5.234 seconds

用 admin/123456 登录，POST http://localhost:9999/auth/oauth2/token：

curl -X POST http://localhost:9999/auth/oauth2/token \   -H "Authorization: Basic cGlnOnBpZw==" \   -d "username=admin&password=123456&grant_type=password&scope=server"

返回 access_token，说明 pig 的 OAuth2 认证链路通了。把 pig-note 作为依赖加到 pig-boot 的 pom.xml，重新启动，如果 pig-note 模块的 @SpringBootApplication 被扫到，就说明集成成功。

十一、写在最后

这一篇讲完了 pig 4.0 的初始化与运行：

• 认清 PIG AI：pig 团队的商业版 AI 平台，功能强但不开源、太重，独立开发者用 Spring AI 自己集成更合适

• 基础环境：JDK 21 / MySQL 8 / Redis 7+ / Node 20 / Maven 3.8+

• 项目下载与模块拓扑：理解 register / auth / upms / gateway / boot 五大模块

• 微服务模式：数据库初始化 + Nacos 配置分层 + 启动顺序 register → auth → upms-biz → gateway

• 单体模式：pig-boot + boot profile + 本地 application-dev.yml，一个进程跑全部，开发丝滑

• 前端 pig-ui：微服务模式直接 npm run dev，单体模式要设 VITE_IS_MICRO=false

• 创建 pig-note：自己的业务模块，包路径用 com.brainypipe.note

• 第一行可运行代码：PigBootApplication 启动成功，OAuth2 链路打通

pig 跑起来之后，下一步是 fork pig-ui，把它改造成我们自己的后台。第 8 篇会写管理后台的初始化——但我先跳过去写第 7 篇 App 端的 UniApp 项目骨架，因为后端骨架搭完了，App 端可以并行推进。

下一篇预告

第 07 篇：《App 端初始化：UniApp 项目骨架与目录约定》——用 HBuilderX 创建 uni-preset-vue 项目，引入 uview-plus，定下 pages/api/components/store/composables/types 的目录约定。重点讲 pages.json 的「地图即路由」哲学，以及 config.js 的 baseUrl 怎么切换开发/生产环境。