03 本地开发启动

← 返回本课教程 · 系列目录

RuoYi Office 客户操作手册 · 2026年10月版

1. 目标与启动顺序

本篇面向开发人员，在自己的电脑上启动单体后端和PC管理端，并通过登录、读取列表确认前后端连通。本篇不是生产部署指南，不配置公网访问或生产密钥。

环境检查 → 获取源码 → MySQL与Redis → 数据初始化 → IDEA后端 → VS Code前端 → 浏览器验证。

浏览器访问前端开发服务；前端通过接口地址与代理访问后端；后端连接MySQL和Redis。数据库与缓存没有就绪时，不能仅启动前端就判定项目已经运行。

请使用独立开发目录和获授权的开发数据库。不要把本篇初始化操作用于已有业务数据的库，也不要为释放端口而停止不属于自己的进程。

2. 准备开发工具

2.1 版本与用途

工具	本课参考	用途与核对方式
JDK	17	后端编译运行；IDE项目SDK和运行JRE都需核对
Maven	3.9.x；教学使用IDEA内置3.9.11	构建多模块后端；独立命令行与IDE内置Maven可以不同
Node.js	教学24.16.0	当前教学前端要求`^22.18.0
pnpm	教学11.7.0	按根package.json的packageManager选择版本
Git	可正常使用的版本	获取源码并识别分支
MySQL	教学8.4	存储业务及基础数据，按交付版本兼容要求选择
Redis	教学7.4	提供缓存等支持
IDEA	支持JDK17与Maven的版本	导入和运行Java后端
VS Code或Cursor	二选一	编辑和启动前端；不要求购买Cursor

在新打开的终端执行以下只读检查，命令应返回版本，而不是“找不到命令”：

java -version
mvn -version
node --version
pnpm --version
git --version
docker version

若只用IDEA内置Maven，mvn未加入系统PATH不代表IDE不能构建；在IDEA设置中核对Maven Home即可。其余工具缺失时先按各工具安装说明补齐，重开终端再检查。

图03-01：核对Java、Maven与Node输出。路径由本机安装位置决定，不需要与截图相同。

可将下面的提示交给AI协助检查，但不要直接让它清空数据库或重配已有环境：

请只读检查本机Java、Maven、Node、pnpm和Docker，对照当前仓库声明的版本要求列出缺少项；检查前后端及数据库缓存端口。不要安装软件、修改环境变量、停止进程或初始化数据库。先给出检查结果与最小处理建议。

3. 获取匹配的源码与数据库材料

本课以商业版仓库演示。开源版可参考同样的启动顺序，但源码分支、数据库脚本和交付功能必须使用各自版本，不能混用。

1. 向交付方取得后端、PC前端和数据库材料的仓库地址及分支。只有取得仓库授权后才能克隆。
2. 在新的开发父目录打开终端，按下面格式替换地址和分支后执行。尖括号内容是需要替换的说明，不能原样运行。

git clone --branch <后端交付分支> <后端仓库地址> ruoyi-office
git clone --branch <前端交付分支> <PC前端仓库地址> ruoyi-office-vben
git clone --branch <数据库交付分支> <数据库仓库地址> ruoyi-office-db

3. 认证由仓库账号本人完成，不把访问令牌放进克隆URL、截图或共享文档。
4. 检查后端目录含根pom.xml和yudao-server，前端目录含根package.json及apps/web-antd。
5. 数据库材料若通过压缩包交付，则按交付清单解压，无需额外克隆；对应商业版脚本从dump/latest选取匹配的schema与static_data文件。

建议目录结构：

开发父目录/
  ruoyi-office/        后端，在此打开IDEA
  ruoyi-office-vben/   前端，在此打开VS Code
  ruoyi-office-db/     配套数据库材料

不要只打开后端的yudao-server或前端的apps/web-antd，否则容易遗漏多模块构建或工作区依赖。

4. 先准备数据库和缓存

4.1 使用Docker或已有独立服务

Docker在本课只承载MySQL与Redis，不负责运行Java后端和PC前端。已有独立可用服务时，核对版本、地址和权限后可以直接使用，无需重复安装。

如需新建服务，在Docker Desktop启动并确认引擎运行后，按交付提供的容器配置创建MySQL与Redis。配置时至少核对以下项目：

项目	MySQL	Redis
镜像版本	与交付脚本兼容的8.x版本	与项目兼容的7.x版本
容器端口	3306	6379
宿主机映射	示例3306；占用时选择空闲端口	教学映射36379，不是产品固定要求
数据持久化	挂载独立数据卷至/var/lib/mysql	按用途设置持久化及独立卷
认证	设置自己的数据库口令	按企业开发规则配置认证
网络范围	本地练习仅绑定本机回环地址	本地练习仅绑定本机回环地址

不要将无认证服务暴露到公网。若交付材料未包含容器配置，请先由环境管理员准备符合上述要求的服务，再继续本篇；本篇不提供生产容器安全方案。

使用docker ps确认容器运行，再核对Ports列中的实际宿主机端口。“容器Running”只说明进程存在，后续还需验证数据库登录和后端连接。

4.2 初始化一个新的空库

以下操作只适用于新建的独立开发库。已有业务库请停止，按升级文档处理，不重复导入全量结构。

1. 使用数据库客户端连接实际MySQL地址，确认当前实例是开发环境，并准备一个新空库。也可在已安装MySQL客户端工具的终端中创建；下面示例库名可按环境替换：

mysqladmin -h 127.0.0.1 -P 3306 -u YOUR_DB_USER -p create ruoyi_office_local

将YOUR_DB_USER换成有建库权限的用户；-p后不直接写密码，按提示输入。端口不是3306时改为实际映射。若提示库已存在，先核实内容，不自动删除重建。

2. 启动MySQL客户端并明确指定新库：

mysql -h 127.0.0.1 -P 3306 -u YOUR_DB_USER -p ruoyi_office_local

3. 在MySQL交互提示符中，先导入结构文件，再导入静态数据。下面文件路径需替换为本机对应文件；这是MySQL客户端命令，不是在PowerShell里执行：

SOURCE C:/your-db-files/schema_对应版本.sql;
SOURCE C:/your-db-files/static_data_对应版本.sql;
SHOW TABLES;

4. 每次导入检查是否有错误；发现错误先处理，不继续把部分导入当作成功。不要在schema与static_data之后再叠加含全量数据的dump。
5. 检查系统基础表存在，确认初始化账号及菜单等基础数据已按交付说明导入。表数量随版本变化，不用截图中的固定数量判断其他版本。

图03-02：教学环境展示结构与静态数据分别导入后的检查结果。实际库名、文件名和记录数量以你的版本为准。

若MySQL提示SET SESSION max_allowed_packet相关错误，不要忽略继续；取得兼容脚本或由维护人员确认实例参数设置。也不要复制其他环境的邮件、短信、AI或外部数据源密钥到开发库。

5. 在IDEA中启动后端

5.1 导入与构建模式

1. 打开后端根pom.xml所在目录，按Maven项目导入。
2. 在Project Structure中选择JDK17作为Project SDK；检查模块SDK没有指向其他大版本。
3. 在IDEA设置的Maven项核对Maven Home及使用的JDK。等待依赖下载和项目索引完成。
4. 打开Maven面板，在Profiles中选择boot。本篇是单体启动，不选择cloud；其他可选构建配置按交付说明处理。
5. 若出现Lombok或生成类缺失，先检查注解处理配置及Maven导入状态，不直接修改业务源码规避编译错误。

图03-03：从完整后端工程检查SDK及构建配置，窗口布局可随IDEA版本变化。

5.2 准备本地连接配置

打开yudao-server/src/main/resources/application-local.yaml。在项目已有配置结构内调整下列项目，不用一个极简示例覆盖整个配置文件：

配置位置	含义	本地示例或填写方法
server.port	后端端口	48080
spring.datasource.dynamic.datasource.master.url	主库JDBC地址	指向刚初始化的开发库，主机、端口、库名必须一致
同级username与password	数据库认证	自己的数据库账号和口令
spring.data.redis.host	Redis地址	本机使用127.0.0.1
spring.data.redis.port	Redis映射端口	教学为36379，按实际环境填写
spring.data.redis.database	Redis逻辑库	使用已规划的开发逻辑库，不占用其他项目数据
spring.data.redis.password	Redis认证	与实例配置一致；无认证时按项目配置约定处理

JDBC地址示意：jdbc:mysql://127.0.0.1:3306/ruoyi_office_local。保留交付配置要求的连接参数，不只替换主机却忘了库名。

数据库口令可通过环境变量注入。若配置使用${变量名}，必须在IDEA运行配置的环境变量中设置同名值；占位符本身不是密码。不要把真实口令提交到Git。

5.3 启动并判断成功

1. 找到cn.iocoder.yudao.server.YudaoServerApplication主类。
2. 建立Application运行配置，Main class使用该类，classpath选择yudao-server，JRE使用JDK17。
3. 在Program arguments中填写--spring.profiles.active=local。
4. 点击运行。等待编译、数据库连接和模块初始化完成。
5. 查看日志中的Started YudaoServerApplication，确认没有随后发生启动失败。端口监听、日志和后续接口验证应相互印证，不能只看到Tomcat初始化就继续。

boot是Maven构建模式，local是Spring运行配置，两个都需要正确设置，不能互相替代。

图03-04：后端完成启动后再启动前端；耗时受机器和首次依赖下载影响。

6. 在VS Code或Cursor中启动前端

6.1 安装依赖

1. 打开ruoyi-office-vben根目录。信任提示只针对自己确认来源的项目，不扩大信任到整个磁盘。
2. 检查根package.json的engines和packageManager，确认Node和pnpm版本匹配。
3. 在编辑器终端中确认当前目录包含根package.json和锁文件，再执行：

pnpm install --frozen-lockfile

命令成功结束后再继续。首次安装可能较久；不要为了消除错误删除锁文件或升级全部依赖。如果出现版本不匹配，先纠正工具版本。

6.2 配置前后端连接

打开apps/web-antd/.env.development，核对以下值：

VITE_PORT=5800
VITE_BASE_URL=http://127.0.0.1:48080
VITE_GLOB_API_URL=/admin-api

配置	用途	常见错误
VITE_PORT	前端开发端口	把后端48080写到这里
VITE_BASE_URL	后端基础地址，部分嵌入页、上传或连接功能使用	重复添加/admin-api或仍指向远程环境
VITE_GLOB_API_URL	普通接口请求前缀	与代理配置不一致

同时检查apps/web-antd/vite.config.ts内/admin-api的代理配置，确认请求最终转发到本机后端48080。只修改基础地址而不检查代理，可能仍连到错误服务。

图03-05：生效的是未注释的配置行。后端基础地址不重复拼接接口前缀。

6.3 启动开发服务

在前端根目录终端执行：

pnpm dev:antd

看到Vite的ready提示和Local地址后，打开实际输出的地址。本课为http://localhost:5800/，不要凭框架默认端口猜测。修改环境文件后应停止并重启自己的前端开发服务。

图03-06：以终端给出的地址为准，保持前端进程运行。

7. 登录与读取验证

1. 在浏览器打开前端地址，使用配套初始化说明中的企业和账号登录，不使用其他环境的凭据。
2. 确认首页正常显示，再进入“系统管理 → 字典管理”等有基础数据的只读列表。
3. 输入一个已存在的查询条件并搜索，确认记录可读取；重置后列表恢复。
4. 若需排查，在开发者工具Network中查看真实接口是否返回业务成功结果。HTTP200也可能携带业务错误，不能只看状态码。

图03-07：登录后读取基础数据，验证浏览器、前端、后端与数据库这条链路；不需要为检查启动而新建业务单据。

本地登录和查询成功，不等于短信、文件、第三方登录或所有业务模块已完成配置。对将使用的功能分别验证。

8. 常见问题与再次启动

现象	检查顺序	处理与再验证
后端连接数据库失败	服务运行、映射端口、库名、账号口令	修正连接后重启，检查完成启动日志
Redis连接失败	实际宿主机端口、认证、逻辑库	不把容器6379直接当宿主机端口；重启后检查日志
无法解析环境变量	YAML占位名与运行环境变量	设置同名变量，不把占位符当口令
前端依赖安装失败	根目录、Node/pnpm版本、网络	按锁文件重新安装，不无依据删除锁文件
页面能打开但登录失败	后端就绪、代理、企业与初始化账号	查看业务错误信息，再执行登录与列表验证
其他电脑访问失败	localhost指向访问者本机	由环境管理员配置可达地址及网络访问；不能只改浏览器URL
端口被占用	当前端口所属进程	确认是否自己启动的重复进程，再停止或按方案调整端口

再次启动按MySQL/Redis、后端、前端的顺序进行。库已初始化且依赖未变化时，不重复导库、克隆或安装。退出时在对应IDE或终端停止自己的进程；需要停止容器时只停止本项目容器，不删除数据卷。

9. 练习与完成标准

关闭自己启动的前后端，再按顺序启动一次。能解释后端基础地址与接口前缀的区别；能从日志确认后端启动；能打开前端、登录并查询基础数据；没有重复导入数据库或向仓库提交口令，即完成本课基础任务。

官方说明：快速启动。仓库升级后，以当前交付版本的声明和配套文档为准。