从 0 到 1 搭建 RuoyiOffice：30 分钟跑通后端+前端+移动端
🌐 演示地址：http://ruoyioffice.com | 📦 源码1：https://gitcode.com/zhouzhongyan/ruoyi-office-vben.git | 📦 源码2：https://gitcode.com/zhouzhongyan/ruoyi-office.git | 📦 源码3：https://github.com/yuqing2026/ruoyi-office.git | 💬 微信：17156169080（备注「RuoYi Office」）
▲ 这张路线图的重点是“先跑通链路”：环境、数据库、后端、PC 管理端、移动端依次验证，不要一开始就把生产运维和微服务治理全部混在一起。
引言：第一次启动，目标不要设太大
很多人第一次接触企业级项目，会把“跑起来”和“部署好”混在一起。
但对 RuoyiOffice 这种包含后端、PC 前端、移动端、数据库、Redis、BPM、AI、文件、权限、多租户能力的平台来说，第一次启动最应该做的不是生产部署，而是完成一个最小闭环：
数据库可连接 -> 后端可启动 -> PC 可登录 -> 移动端可打开 -> API 链路可访问
只要这个闭环打通，后面再处理 Nginx、Docker、域名、HTTPS、对象存储、微服务、监控、备份，都会清楚很多。
这篇文章就按 30 分钟验证路线写：面向开发者、实施人员、技术负责人，不追求“一篇文章解决所有生产运维问题”，只追求快速把 RuoyiOffice 在本地跑起来。
一、项目目录先看清楚
在工作区里，RuoyiOffice 通常拆成几个工程：
ruoyi-office/ # Java 后端，Spring Boot / Spring Cloud
ruoyi-office-vben/ # PC 管理端，Vue3 + TypeScript + Vben Admin
ruoyi-office-uniapp/ # 移动端，UniApp + Vue3 + wot-design-uni
ruoyi-office-doc/ # 文档站，VitePress
ruoyi-office-db/ # 数据库 dump 与增量 SQL
快速启动时不要在根目录乱跑命令。不同命令要进入对应工程：
| 要做什么 | 进入目录 | 常用命令 |
|---|---|---|
| 编译 / 启动后端 | ruoyi-office/ |
mvn -P boot -DskipTests compile |
| 启动 PC 前端 | ruoyi-office-vben/ |
pnpm dev:antd |
| 启动移动端 H5 | ruoyi-office-uniapp/ |
pnpm dev:h5 或 pnpm dev |
| 查看文档 | ruoyi-office-doc/ |
pnpm docs:dev |
这个目录边界非常重要。企业系统最怕“还没理解工程结构，就开始修改配置”。
二、环境准备：先检查版本
建议环境如下：
| 环境 | 建议版本 | 说明 |
|---|---|---|
| JDK | 17 | 后端以 Java 17 编译 |
| Maven | 3.8+ | 后端依赖管理与编译 |
| Node.js | 20.19+ | Vben 工程要求 `^20.19.0 |
| pnpm | 10.x | 前端 Monorepo 使用 pnpm |
| MySQL | 5.7 / 8.0+ | 本地建议库名 ruoyi-office |
| Redis | 5.0+ | 默认 127.0.0.1:6379 |
| Nacos | 2.x | 仅微服务模式需要，首次启动可先不碰 |
可以先执行：
java -version
mvn -version
node -v
pnpm -v
如果只是第一次体验，建议优先单体模式。微服务模式需要 Gateway、Nacos、多个业务服务一起协调，适合第二阶段再验证。
三、初始化数据库
先创建数据库：
CREATE DATABASE IF NOT EXISTS `ruoyi-office`DEFAULT CHARACTER SET utf8mb4COLLATE utf8mb4_unicode_ci;
初始化 SQL 按你拿到的版本选择：
| 场景 | SQL 来源 | 执行顺序 |
|---|---|---|
| 商业版 / 完整交付 | ruoyi-office-db/dump/ 下最新的 schema_*.sql、static_data_*.sql |
先结构，后静态数据 |
| 开源体验 | ruoyi-office/sql/mysql/ 或交付包内初始化 SQL |
按文件说明执行 |
| 增量升级 | ruoyi-office-db/{YYYYMMDD}_update/ |
按日期顺序执行 |
默认本地连接一般类似：
spring:datasource:dynamic:datasource:master:url: jdbc:mysql://127.0.0.1:3306/ruoyi-office?useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true&nullCatalogMeansCurrent=true&rewriteBatchedStatements=trueusername: rootpassword: 123456
如果启动失败，优先核对 4 件事：
- 数据库名是不是
ruoyi-office。 - MySQL 端口是不是
3306，Docker 映射端口不要混淆。 - 用户名和密码是否与
application-local.yaml一致。 - SQL 是否只导了结构，没有导静态数据。
四、启动 Redis
Redis 默认配置通常是：
spring:data:redis:host: 127.0.0.1port: 6379database: 0
如果 Redis 有密码，要在对应环境配置里补充 password。本地体验阶段不建议一开始就引入复杂 Redis 集群，先让单机 Redis 跑通即可。
五、启动后端：先用单体模式
后端主工程在：
ruoyi-office/
单体启动模块是：
ruoyi-office/yudao-server/
主类是：
YudaoServerApplication
命令行先做一次编译：
cd ruoyi-office
mvn -P boot -DskipTests compile
如果使用 IDEA：
- 打开
ruoyi-office/。 - 等 Maven 依赖下载完成。
- 运行
yudao-server/src/main/java/cn/iocoder/yudao/server/YudaoServerApplication.java。 - 访问
http://127.0.0.1:48080，能返回服务信息即代表后端启动成功。
后端本地日志通常在：
C:\Users\Administrator\logs\yudao-server.log
如果启动失败，建议按这个顺序排查：
| 错误类型 | 先看哪里 |
|---|---|
| 数据库连接失败 | MySQL 地址、库名、账号、密码 |
| Redis 连接失败 | Redis 是否启动、密码是否一致 |
| 端口占用 | 48080 是否被占用 |
| Bean 初始化失败 | 最近改动的模块依赖、配置项 |
| SQL 表不存在 | 初始化 SQL 是否导完整 |
六、启动 PC 管理端
PC 管理端在：
ruoyi-office-vben/
首次启动：
cd ruoyi-office-vben
pnpm install
pnpm dev:antd
如果依赖已经安装，可以直接：
pnpm dev:antd
默认开发端口以 Vite 输出为准。你的本地预览地址如果是：
http://localhost:5800
就可以用它验证登录、菜单、列表、表单、接口代理是否正常。
▲ PC 管理端启动后，先看首页、菜单和接口请求是否正常，再去验证具体业务模块。
常见问题：
| 现象 | 可能原因 |
|---|---|
| 登录页打开但登录失败 | 后端没启动，或 /admin-api 代理不对 |
| 页面空白 | 前端依赖、构建缓存、环境变量异常 |
| 菜单加载失败 | 登录接口正常但系统权限或菜单接口异常 |
| 请求 404 | Vite 代理路径或后端上下文路径不一致 |
| 请求 500 | 后端业务接口报错，去看后端日志 |
七、启动移动端 H5
移动端工程在：
ruoyi-office-uniapp/
常用命令：
cd ruoyi-office-uniapp
pnpm install
pnpm dev:h5
如果项目脚本里 dev 默认就是 H5，也可以：
pnpm dev
你的本地移动端预览地址如果是：
http://localhost:9000
就可以先验证移动端登录、工作台、待办、基础列表是否正常。
移动端启动的重点不是把所有业务都测一遍，而是确认：
- H5 能打开。
- 登录接口能通。
- Token 能保存。
/admin-api请求能打到同一个后端。- 待办、审批、表单等高频入口能正常加载。
八、30 分钟检查清单
为了不在第一次启动时迷路，可以按下面清单逐项打勾。
| 步骤 | 检查项 | 通过标准 |
|---|---|---|
| 1 | JDK / Maven / Node / pnpm 版本 | 命令行能输出正确版本 |
| 2 | MySQL 数据库 | ruoyi-office 已创建，SQL 已导入 |
| 3 | Redis | 本机 6379 可连接 |
| 4 | 后端 | yudao-server 正常启动，48080 可访问 |
| 5 | PC 前端 | http://localhost:5800 或 Vite 输出地址可打开 |
| 6 | 移动端 | http://localhost:9000 或 H5 输出地址可打开 |
| 7 | 登录 | PC 和移动端都能请求后端登录接口 |
| 8 | 菜单 | PC 菜单和移动端工作台能加载 |
| 9 | 业务页 | 至少打开一个列表页和一个详情/表单页 |
| 10 | 日志 | 后端无持续刷屏异常 |
第一次跑通时不要贪多。只要 PC、移动端、后端、数据库链路打通，就已经完成最重要的 70%。
九、什么时候切微服务模式
RuoyiOffice 支持单体和微服务，但不代表第一次启动就必须微服务。
微服务模式适合：
- 团队规模更大，需要不同模块独立开发和部署。
- 访问量较高，需要服务独立扩缩容。
- 需要网关、服务注册发现、灰度、链路追踪等治理能力。
- 企业已经有成熟 DevOps 和运维体系。
微服务模式通常涉及：
| 服务 | 说明 |
|---|---|
| Gateway | 统一入口 |
| Nacos | 注册发现与配置中心 |
| System | 用户、角色、菜单、权限 |
| Infra | 文件、配置、代码生成、任务、日志 |
| BPM / OA / CRM / ERP | 业务服务按需启动 |
命令行编译可以使用：
cd ruoyi-office
mvn -P cloud -DskipTests compile
建议路线是：单体跑通业务，微服务验证架构。否则你可能会把数据库问题、配置问题、网关问题、服务注册问题、前端代理问题混在一起排查。
十、从体验到生产，还差哪些事
30 分钟快速启动只是开发体验，不等于生产上线。
生产环境至少还要补齐：
| 类别 | 要做什么 |
|---|---|
| 域名与 HTTPS | Nginx 反向代理、证书、静态资源路径 |
| 配置隔离 | dev / test / prod 配置拆分，敏感信息用环境变量 |
| 文件存储 | 本地、MinIO、S3、OSS 等存储方案确认 |
| 数据备份 | MySQL、附件、日志定期备份和恢复演练 |
| 安全 | 密码策略、权限审计、接口限流、网络隔离 |
| 日志监控 | 应用日志、错误告警、慢 SQL、资源监控 |
| 版本升级 | SQL 增量、代码合并、兼容性测试 |
| 移动端发布 | H5、APP、小程序按目标平台分别构建和审核 |
这也是为什么源码型平台更适合有技术团队或有实施服务配合的企业。它给你控制权，也要求你有承接控制权的能力。
十一、常见问题 FAQ
1. 后端启动一定要先跑微服务吗？
不建议。第一次启动优先用单体模式，yudao-server 跑通后再看微服务。
2. 前端地址一定是 5800 吗？
不一定。Vite 会输出实际端口。如果本地配置或端口占用不同，以终端输出为准。本文使用 http://localhost:5800 是为了对应常见本地预览入口。
3. 移动端地址一定是 9000 吗？
也不一定。UniApp H5 的端口以启动输出为准。本文使用 http://localhost:9000 作为本地验证示例。
4. 登录失败先看前端还是后端？
先看后端是否启动，再看浏览器 Network 里的 /admin-api 请求是否打到后端，最后看后端日志。
5. 数据库 SQL 应该从哪里拿？
按版本来源选择。商业版或完整交付一般看 ruoyi-office-db/dump/；开源体验看交付说明或 ruoyi-office/sql/mysql/。
结论：先让系统“活起来”
RuoyiOffice 的工程体量不小，但第一次启动的逻辑并不复杂：
MySQL + Redis 准备好
-> yudao-server 启动
-> PC web-antd 打开并登录
-> UniApp H5 打开并访问同一后端
-> 业务页面和待办链路验证
跑通这条链路之后，你再去研究 OA、HRM、CRM、ERP、BPM、AI、单体/微服务切换，心里会稳很多。
系统先活起来，复杂度才有地方安放。
💡 想要体验 RuoYi Office 的强大功能？
🌐 在线演示：http://ruoyioffice.com/web/（账号：admin / admin123）
📦 源码仓库：GitCode | GitHub
💬 技术咨询：添加微信 17156169080，备注「RuoYi Office」
⭐ 如果觉得不错，请给个 Star 支持一下！