从 0 到 1 搭建 RuoyiOffice：30 分钟跑通后端+前端+移动端

从 0 到 1 搭建 RuoyiOffice30 分钟跑通后端前端移动端演示地址http://ruoyioffice.com | 源码1https://gitcode.com/zhouzhongyan/ruoyi-office-vben.git | 源码2https://gitcode.com/zhouzhongyan/ruoyi-office.git | 源码3https://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启动移动端 H5ruoyi-office-uniapp/pnpm dev:h5或pnpm dev查看文档ruoyi-office-doc/pnpm docs:dev这个目录边界非常重要。企业系统最怕“还没理解工程结构就开始修改配置”。二、环境准备先检查版本建议环境如下环境建议版本说明JDK17后端以 Java 17 编译Maven3.8后端依赖管理与编译Node.js20.19Vben 工程要求 ^20.19.0pnpm10.x前端 Monorepo 使用 pnpmMySQL5.7 / 8.0本地建议库名ruoyi-officeRedis5.0默认127.0.0.1:6379Nacos2.x仅微服务模式需要首次启动可先不碰可以先执行java-version mvn-version node-v pnpm-v如果只是第一次体验建议优先单体模式。微服务模式需要 Gateway、Nacos、多个业务服务一起协调适合第二阶段再验证。三、初始化数据库先创建数据库CREATEDATABASEIFNOTEXISTSruoyi-officeDEFAULTCHARACTERSETutf8mb4COLLATEutf8mb4_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?useSSLfalseserverTimezoneAsia/ShanghaiallowPublicKeyRetrievaltruenullCatalogMeansCurrenttruerewriteBatchedStatementstrueusername:rootpassword:123456如果启动失败优先核对 4 件事数据库名是不是ruoyi-office。MySQL 端口是不是3306Docker 映射端口不要混淆。用户名和密码是否与application-local.yaml一致。SQL 是否只导了结构没有导静态数据。四、启动 RedisRedis 默认配置通常是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代理不对页面空白前端依赖、构建缓存、环境变量异常菜单加载失败登录接口正常但系统权限或菜单接口异常请求 404Vite 代理路径或后端上下文路径不一致请求 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 分钟检查清单为了不在第一次启动时迷路可以按下面清单逐项打勾。步骤检查项通过标准1JDK / Maven / Node / pnpm 版本命令行能输出正确版本2MySQL 数据库ruoyi-office已创建SQL 已导入3Redis本机6379可连接4后端yudao-server正常启动48080可访问5PC 前端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 分钟快速启动只是开发体验不等于生产上线。生产环境至少还要补齐类别要做什么域名与 HTTPSNginx 反向代理、证书、静态资源路径配置隔离dev / test / prod 配置拆分敏感信息用环境变量文件存储本地、MinIO、S3、OSS 等存储方案确认数据备份MySQL、附件、日志定期备份和恢复演练安全密码策略、权限审计、接口限流、网络隔离日志监控应用日志、错误告警、慢 SQL、资源监控版本升级SQL 增量、代码合并、兼容性测试移动端发布H5、APP、小程序按目标平台分别构建和审核这也是为什么源码型平台更适合有技术团队或有实施服务配合的企业。它给你控制权也要求你有承接控制权的能力。十一、常见问题 FAQ1. 后端启动一定要先跑微服务吗不建议。第一次启动优先用单体模式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 支持一下