本地后端环境与前端联调总结（前端小白视角）

这份文档是按"对后端一无所知的前端开发"视角整理的，用来记录本机 MySQL、Nacos、后端服务、前端代理之间的关系，以及这次接口 500 的排查过程。发布说明：本文档已做脱敏处理，涉及人员、账号、密码、内网 IP、本机用户名、项目路径等均使用占位符表示。

1. 这次我们到底解决了什么问题？

你之前作为前端开发，本地开发时通常是：

text 复制代码

前端本地启动
↓
接口代理到别人电脑上的后端
↓
别人电脑上的后端连接别人电脑上的数据库 / Nacos / Redis 等环境

这种方式有几个明显问题：

依赖别人电脑
- 别人后端没启动，你的接口就挂。
- 别人数据库改了，你本地表现就变。
- 网络不通时你无法开发。
你不知道后端环境到底依赖什么
- MySQL 是否需要启动？
- Nacos 是否需要启动？
- Redis / Kafka 是否需要？
- 哪个服务跑哪个端口？
- 前端代理应该指向谁？
接口报错时不好判断是谁的问题
- 是前端参数错？
- 是代理配置错？
- 是网关没启动？
- 是后端服务没注册？
- 是数据库没数据？
- 是 Nacos 配置不对？

所以这次做的事情，本质上是：

把原来依赖别人电脑的后端开发环境，尽量迁移到你自己电脑上，让你本地可以独立启动后端服务，前端直接连你自己的本地后端。

2. 现在本机环境长什么样？

现在你的电脑上大概是这个结构：

text 复制代码

浏览器
  ↓
前端开发服务 ruoyi-ui
  ↓ 代理 /dev-api
本机后端网关 ruoyi-gateway
  ↓
本机后端服务：
  - ruoyi-auth
  - ruoyi-system
  - ruoyi-ai
  ↓
本机 Nacos 配置中心 / 注册中心
  ↓
本机 MySQL 8 数据库

更具体一点：

组件	作用	当前端口
前端 ruoyi-ui	你写页面的项目	80
MySQL 8	存业务数据、Nacos 配置数据	3306
Nacos API	后端服务读取配置、服务注册	8848
Nacos 控制台	网页管理界面	8080
ruoyi-gateway	后端网关，前端接口入口	8088
ruoyi-auth	登录、鉴权服务	9200
ruoyi-system	系统管理、用户、菜单等服务	9201
ruoyi-ai	AI 相关业务服务	9204

最关键的一句话：

前端接口不要打 Nacos，也不要直接打 auth/system/ai，前端应该打 gateway。

也就是：

text 复制代码

前端代理 target 应该是：http://127.0.0.1:8088

3. JDK 是什么？为什么前端也要管它？

你是前端，平时可能只关心：

text 复制代码

Node.js
npm
Vue
Webpack / Vite

但是后端是 Java 写的，所以要在你电脑上启动后端服务，就必须有 Java 运行环境。

这次项目父工程里配置的是：

xml 复制代码

<java.version>21</java.version>

意思是：

这个后端项目最好用 Java 21 跑。

之前安装过 JDK 17，但后来发现 IDEA 自带了一个 JBR 21，也就是 JetBrains Runtime 21。它可以用来跑这个项目。

可以简单理解为：

text 复制代码

JDK / JBR = Java 世界里的 Node.js 运行环境

前端跑项目需要：

text 复制代码

node
npm

后端跑项目需要：

text 复制代码

java
maven

4. Maven 是什么？

Maven 对 Java 后端的作用，类似前端里的 npm / pnpm / yarn。

前端项目里有：

text 复制代码

package.json
node_modules
npm install
npm run dev

Java 后端项目里对应的是：

text 复制代码

pom.xml
.m2 仓库
mvn install
mvn spring-boot:run

这次项目是一个多模块后端项目，里面有很多服务：

text 复制代码

ruoyi-gateway
ruoyi-auth
ruoyi-system
ruoyi-ai
ruoyi-agent
ruoyi-hub
...

一开始从项目根目录尝试启动某个服务时，遇到过错误：

text 复制代码

Unable to find a suitable main class

翻译成人话就是：

Maven 把启动命令跑到了父工程上，但父工程只是一个聚合工程，没有 main 方法，不能启动。

类似前端 monorepo：

text 复制代码

你在 monorepo 根目录跑 dev，但根目录本身不是一个应用。

所以后来改成：

先编译安装依赖；
再用每个服务模块自己的 jar 启动。

5. MySQL 是干什么的？

MySQL 是数据库。

你前端看到的用户、菜单、权限、AI 会话、业务数据，很多都来自数据库。

之前你依赖同事的数据库。

这次我们把他电脑上的数据库同步到了你本机。

同步过来的主要有两个库：

来源	本机库	用途
`ry-cloud`	`ry-cloud`	业务数据库
`nacos_config`	`ry-config`	Nacos 配置数据库

你本机 MySQL 信息是：

text 复制代码

host: localhost / 127.0.0.1
port: 3306
username: <数据库用户名>
password: <数据库密码>

也就是说，后端以后读业务数据，优先读你自己电脑的 MySQL。

6. Nacos 是什么？为什么它很重要？

对前端小白来说，Nacos 可以先理解成两个东西：

6.1 配置中心

后端服务启动时，不会把所有配置都写死在代码里，而是从 Nacos 拉配置。

比如：

text 复制代码

数据库地址
Redis 地址
Kafka 地址
服务开关
AI 接口地址
上传配置
业务参数

所以如果 Nacos 没启动，后端服务可能直接起不来。

6.2 注册中心

每个后端服务启动后，会告诉 Nacos：

text 复制代码

我是 ruoyi-auth，我在 9200 端口
我是 ruoyi-system，我在 9201 端口
我是 ruoyi-ai，我在 9204 端口
我是 ruoyi-gateway，我在 8088 端口

这样网关或者服务之间互相调用时，才知道去哪找对方。

你可以把 Nacos 想象成：

text 复制代码

后端服务通讯录 + 配置仓库

Nacos 控制台地址：

text 复制代码

http://localhost:8080/index.html

账号密码：

text 复制代码

<Nacos账号> / <Nacos密码>

注意：Nacos 有两个端口：

端口	用途
8848	后端服务访问 Nacos 的 API 端口
8080	浏览器访问 Nacos 控制台的端口

7. 为什么 8080 会冲突？

这是这次接口 500 的关键点。

原来后端网关 ruoyi-gateway 配置里写的是：

yaml 复制代码

server:
  port: 8080

也就是说，默认网关想占用 8080。

但是 Nacos 3.0 的控制台也占用了：

text 复制代码

http://localhost:8080/index.html

所以你电脑上：

text 复制代码

8080 已经被 Nacos 占用了

如果这时网关也想用 8080，就会冲突。

于是网关临时启动在：

text 复制代码

也就是：

text 复制代码

ruoyi-gateway -> http://127.0.0.1:8088

8. 前端代理到底是什么？

你的前端配置里有这个：

js 复制代码

proxy: {
  '/dev-api': {
    target: 'http://127.0.0.1:8080',
    changeOrigin: true,
    pathRewrite: {
      '^/dev-api': ''
    }
  }
}

这段的意思是：

当前端请求：

text 复制代码

/dev-api/auth/login

开发服务器会帮你转发成：

text 复制代码

http://127.0.0.1:8080/auth/login

但是问题是：

现在 8080 是 Nacos，不是后端网关。

所以你的请求实际变成了：

text 复制代码

前端请求 /dev-api/xxx
↓
代理到 http://127.0.0.1:8080/xxx
↓
打到了 Nacos
↓
当然不对，可能 404 / 500 / 权限错误 / 接口异常

正确应该是：

js 复制代码

target: 'http://127.0.0.1:8088'

这样请求会变成：

text 复制代码

前端请求 /dev-api/auth/login
↓
代理到 http://127.0.0.1:8088/auth/login
↓
进入 ruoyi-gateway
↓
gateway 再转发给 ruoyi-auth / ruoyi-system / ruoyi-ai

这才是正确链路。

9. 这次修改了哪个前端文件？

修改文件：

text 复制代码

D:\your-project\BiwinAi\ruoyi-ui\vue.config.js

把：

js 复制代码

target: 'http://127.0.0.1:8080'

改成：

js 复制代码

target: 'http://127.0.0.1:8088'

这是解决当前"前端代理打错端口"的关键。

10. 为什么改了 vue.config.js 还要重启前端？

因为 vue.config.js 是前端开发服务器启动时读取的配置。

类似你改了：

js 复制代码

devServer.proxy

这个配置通常不会自动热更新。

所以改完：

js 复制代码

target: 'http://127.0.0.1:8088'

之后，前端 dev server 必须重启：

bash 复制代码

npm run dev

否则它内存里可能还在用旧的：

js 复制代码

target: 'http://127.0.0.1:8080'

一句话：

页面代码热更新，代理配置不一定热更新。改代理后要重启前端服务。

11. 这次实际启动了哪些后端服务？

最终确认这些服务已经启动：

text 复制代码

ruoyi-gateway  8088
ruoyi-auth     9200
ruoyi-system   9201
ruoyi-ai       9204

并且都注册到了 Nacos。

也就是说，Nacos 里可以看到类似：

text 复制代码

ruoyi-gateway -> <内网IP>:8088
ruoyi-auth    -> <内网IP>:9200
ruoyi-system  -> <内网IP>:9201
ruoyi-ai      -> <内网IP>:9204

这说明：

服务进程起来了；
端口在监听；
服务已经告诉 Nacos 自己在哪里；
网关理论上可以通过 Nacos 找到这些服务。

12. 为什么全量 Maven install 失败了，但服务还能启动？

执行过一次：

bash 复制代码

mvn -DskipTests install

它最后在 ruoyi-agent 的测试编译阶段失败了。

失败原因大概是：

text 复制代码

测试代码里引用的包不存在
com.ruoyi.agent.hook.metrics 不存在

但是注意：失败发生在比较后面的模块：

text 复制代码

ruoyi-modules-agent

而我们要启动的核心服务：

text 复制代码

ruoyi-auth
ruoyi-gateway
ruoyi-system
ruoyi-ai

已经在失败之前成功编译好了。

所以它们的 jar 已经生成：

text 复制代码

ruoyi-auth/target/ruoyi-auth.jar
ruoyi-gateway/target/ruoyi-gateway.jar
ruoyi-modules/ruoyi-system/target/ruoyi-modules-system.jar
ruoyi-modules/ruoyi-ai/target/ruoyi-modules-ai.jar

因此：

全量构建失败，不代表所有服务都不能启动。只要目标服务已经编译成功，就可以先跑起来。

对于前端开发来说，这种情况类似：

text 复制代码

monorepo 里某个非当前应用的包测试失败了，
但你当前要跑的 web app 已经 build 成功。

13. 接口 500 时应该怎么排查？

以后遇到接口 500，不要一上来就怀疑前端代码，也不要只说"后端挂了"。可以按下面顺序排查。

第一步：看前端请求实际打到哪里

浏览器 F12 → Network → 点接口 → 看 Request URL。

比如你看到：

text 复制代码

http://localhost/dev-api/auth/login

这只是前端看到的地址。

真正代理到哪里，要看 vue.config.js：

js 复制代码

target: 'http://127.0.0.1:8088'

如果 target 是错的，比如：

js 复制代码

target: 'http://127.0.0.1:8080'

那就是代理错。

第二步：确认 gateway 是否启动

前端一般不直接访问 auth/system/ai，而是访问 gateway。

所以先确认：

text 复制代码

ruoyi-gateway 是否启动？
端口是不是 8088？

本次正确网关地址：

text 复制代码

http://127.0.0.1:8088

第三步：确认业务服务是否启动

比如登录接口通常需要：

text 复制代码

ruoyi-auth
ruoyi-system

AI 页面通常需要：

text 复制代码

ruoyi-ai

如果 gateway 起了，但 auth/system 没起，也会报错。

第四步：确认服务是否注册到 Nacos

服务启动不等于网关能找到它。

必须注册到 Nacos。

如果 Nacos 里没有：

text 复制代码

ruoyi-auth
ruoyi-system
ruoyi-ai
ruoyi-gateway

说明服务注册失败，网关转发可能失败。

第五步：看后端日志

500 是服务端内部错误，需要看具体哪个服务报错。

比如：

接口类型	应该看哪个日志
登录报错	`ruoyi-auth.log`
菜单 / 用户 / 权限报错	`ruoyi-system.log`
AI 相关接口报错	`ruoyi-ai.log`
路由转发错误	`ruoyi-gateway.log`

前端看到的 500 只是结果，真正原因在后端日志。

14. 这次最容易搞混的几个地址

14.1 前端页面地址

text 复制代码

http://localhost

或者：

text 复制代码

http://127.0.0.1

因为前端 dev server 端口是 80。

14.2 前端代理目标

text 复制代码

http://127.0.0.1:8088

这是后端网关。

14.3 Nacos 控制台

text 复制代码

http://localhost:8080/index.html

这是看配置、看服务注册的地方，不是接口代理目标。

14.4 Nacos API

text 复制代码

http://localhost:8848

这是后端服务连接 Nacos 用的，不是平时打开网页用的。

14.5 MySQL

text 复制代码

localhost:3306
<数据库用户名> / <数据库密码>

数据库地址。

15. 现在本地开发的正确链路

以后本地开发应该是：

text 复制代码

1. MySQL 启动
2. Nacos 启动
3. 后端服务启动：
   - ruoyi-auth
   - ruoyi-system
   - ruoyi-ai
   - ruoyi-gateway
4. 前端 ruoyi-ui 启动
5. 前端代理 target 指向 gateway：
   http://127.0.0.1:8088

请求链路是：

text 复制代码

浏览器
↓
前端 dev server
↓ /dev-api 代理
ruoyi-gateway:8088
↓
ruoyi-auth / ruoyi-system / ruoyi-ai
↓
MySQL / Redis / Kafka / 其他依赖

16. 如果重启电脑，要怎么恢复环境？

可以按这个顺序检查。

16.1 检查 MySQL

端口：

text 复制代码

如果没启动，需要启动 MySQL。

16.2 启动 Nacos

桌面上有启动脚本：

text 复制代码

C:\Users\<本机用户名>\Desktop\nacos-server-3.0.0\start-nacos-standalone.cmd

控制台地址：

text 复制代码

http://localhost:8080/index.html

16.3 启动后端服务

核心服务：

text 复制代码

ruoyi-gateway
ruoyi-auth
ruoyi-system
ruoyi-ai

端口分别是：

text 复制代码

16.4 启动前端

进入：

text 复制代码

D:\your-project\BiwinAi\ruoyi-ui

然后运行：

bash 复制代码

npm run dev

16.5 确认前端代理

确认 vue.config.js 里是：

js 复制代码

target: 'http://127.0.0.1:8088'

17. 从前端角度，需要建立的后端基本认知

17.1 gateway 是接口入口

前端一般只连 gateway。

text 复制代码

前端 → gateway → 具体服务

不要乱连：

text 复制代码

auth
system
ai
Nacos
MySQL

17.2 Nacos 不是业务接口

Nacos 是后端服务用的配置和注册中心。

你浏览器访问 Nacos 是为了看服务有没有注册，不是为了让前端接口代理过去。

17.3 MySQL 是数据来源

接口返回的数据很多来自 MySQL。

如果数据库没同步、表缺失、数据不对，接口也会报错。

17.4 500 不一定是前端问题

500 意思是：

text 复制代码

服务端内部错误

前端最多能看到错误结果。真正原因要看后端日志。

17.5 端口非常重要

端口错了，请求就会打到完全不同的东西上。

这次就是典型案例：

text 复制代码

8080 = Nacos 控制台
8088 = 后端网关

你前端配成 8080，就相当于把业务接口打给了 Nacos。

18. 以后遇到"接口 500"的标准排查模板

可以直接按这个模板问自己：

text 复制代码

1. 前端代理 target 是不是 gateway？
   当前应该是 http://127.0.0.1:8088

2. gateway 是否启动？
   端口 8088 是否存在？

3. auth/system/ai 是否启动？
   9200/9201/9204 是否存在？

4. Nacos 是否启动？
   8848 和 8080 是否存在？

5. 服务是否注册到 Nacos？
   Nacos 控制台能否看到 ruoyi-gateway、ruoyi-auth、ruoyi-system、ruoyi-ai？

6. MySQL 是否启动？
   3306 是否存在？

7. 是哪个接口 500？
   登录？菜单？AI？文件？不同接口看不同服务日志。

8. 后端日志里真正报错是什么？

19. 这次最大的教训

这次问题表面上是：

text 复制代码

接口报 500

但真正原因之一是：

text 复制代码

前端代理 target 配错了，打到了 Nacos 的 8080，而不是后端网关。

这说明前端开发本地联调时，最重要的是搞清楚：

text 复制代码

我的请求到底发给谁？

不是看到：

text 复制代码

/dev-api/xxx

就以为它一定去了后端。

它实际去哪，取决于：

js 复制代码

vue.config.js 里的 proxy.target

20. 最短记忆版

如果只想记最重要的内容：

text 复制代码

1. Nacos 控制台是 8080，不是后端接口。
2. 后端网关现在是 8088。
3. 前端 vue.config.js 代理要配：
   target: 'http://127.0.0.1:8088'
4. 改完 vue.config.js 要重启前端。
5. 前端请求链路是：
   前端 → gateway → auth/system/ai → MySQL/Nacos
6. 接口 500 要看后端日志，不要只看前端报错。

当前正确代理配置：

js 复制代码

target: 'http://127.0.0.1:8088'

当前后端入口：

text 复制代码

http://127.0.0.1:8088

当前 Nacos 控制台：

text 复制代码

http://localhost:8080/index.html

账号：

text 复制代码

<Nacos账号>

密码：

text 复制代码

<Nacos密码>