企业官网建设流程全解析

1. 项目背景与整体设计思路

1.1 为什么要把 RuoYi、SSO、OAuth2 三者组合在一起

接手这个项目之前，我和大多数人一样觉得 RuoYi 就是个自带权限管理的后台脚手架，直接拿来改改界面、写几个业务表就能交差。但真到了要对接多个内部系统、还要统一登录入口的时候，RuoYi 自带的 Session 登录方案就不太够用了——每个系统各存各的登录态，用户切一次系统就要重新输一次账号，体验割裂，也难扩展。

所以这个项目的定位非常明确：以 RuoYi 的权限模型为基础，把登录认证层改造成符合 OAuth2 协议的授权服务，再结合 SSO 单点登录的思路做统一身份认证。换句话说，RuoYi 负责“用户管理和权限控制”，OAuth2 负责“令牌签发和资源校验”，SSO 负责“一次登录、多个系统通用”。

设计上并没有推翻 RuoYi 原有的用户表、角色表、菜单表体系，而是在这之上增加一条独立的认证链路：客户端跳转到认证中心，认证中心完成登录后签发授权码，再换取访问令牌，各业务系统拿着令牌去校验身份、拉取用户信息。RuoYi 原生的用户体系依然兜底，用来做后台管理端的账号授权和数据权限分配。这样一个改造方案，既不破坏现有业务，又能让多个独立系统共享一套登录态，整体开发量控制在可接受的范围内。

1.2 这个系列要解决什么问题

我打算把这个项目拆成几期来写，第一期就是本期的环境配置。环境配置听起来简单，但实际上这个项目的坑点大多集中在“版本匹配”和“依赖冲突”上。RuoYi 官方推荐的 JDK 版本和 Maven 插件版本，搭配上 OAuth2 相关的 Spring Security 5.7 依赖，如果哪一步选的版本不对，后面编译报错会让人一头雾水。

本系列最终要做的事包括：改造 RuoYi 为 OAuth2 授权服务器，提供统一的登录页和授权确认页；抽取一个独立的认证中心模块，业务系统通过配置 client-id 和 client-secret 接入；实现基于 Redis 的令牌存储和踢人下线逻辑；最后再加上一套简化版的 SSO 客户端示例，演示两个不同系统如何共享登录状态。前置条件就是把 RuoYi 的代码跑起来、前端控制台能登录、数据库和数据字典初始化干净，然后再动认证层的代码。

这一期适合三类人阅读：第一次接触 RuoYi 的 Java 后端开发者，想把 RuoYi 从“内置 Session 登录”改造成“标准 OAuth2 登录”的中间团队，以及正在做多系统统一登录选型、但还不确定技术路径的架构师。

2. 基础运行环境的版本选型与配置

2.1 JDK、Maven、MySQL、Redis 的版本搭配逻辑

RuoYi 的官方文档要求 JDK 1.8 以上，但这条要求现在已经有点模糊了，因为 RuoYi 在 2023 年之后的框架代码对 Spring Boot 2.x 和 Spring Boot 3.x 都做了适配。两者的区别非常大：Spring Boot 2.x 底层是 Spring Security 5.x，有很多网上现成的 OAuth2 授权服务器示例代码；Spring Boot 3.x 对应 Spring Security 6.x，OAuth2 授权服务器的配置方式完全换了一套写法，如果照着旧博客抄代码会直接编译不过。

我的选择是 JDK 8 + Spring Boot 2.7.x + Spring Security 5.7.x。原因很简单，网上关于 Spring Authorization Server 0.x 版本和 Spring Security OAuth2 的教程绝大多数建立在 JDK 8 的生态上，遇到问题好排查；另外公司内部存量系统的技术栈普遍还是 JDK 8，后面要接真实业务也没有升级压力。如果你确认要跑在新项目里，也可以用 JDK 17 配 RuoYi-Vue 的 Boot3 分支，但本系列的代码基于 JDK 8 开发，建议保持一致。

数据库选型上，RuoYi 官方默认支持 MySQL 和 Oracle，我们按 MySQL 来准备。版本用 5.7 或 8.0 都行，但强烈建议 8.0，因为 5.7 的驱动包和连接串写法与 8.0 有差异，后面集成 OAuth2 的 token 存储表时，8.0 支持的索引特性更友好。

Redis 在 RuoYi 里的作用不只是缓存，登录令牌、验证码、会话并发控制都依赖它。SSO 和 OAuth2 改造之后，Redis 还承担 token 的存取和过期刷新，建议直接用官方稳定版，不要用 Windows 官方未维护的旧版本。下表是我最终敲定的版本组合，直接照着配就可以：

提示：以上版本组合是经过实际验证的，尤其是 Node.js 16 这一点，很多新手直接用最新版 Node 20 装依赖，结果 node-sass 编译不过，卡了整整半天。如果遇到类似问题，先检查你用的 Node 版本。

2.2 Windows 下的 JDK 与 Maven 环境变量配置

环境变量配置是所有步骤里最枯燥、但最容易埋雷的一步。我经历过很多次“明明配了 JAVA_HOME 但 java -version 还是旧版本”的情况，后来养成了配完之后一定要执行mvn -v和java -version双重验证的习惯。

JDK 安装没什么可说的，直接解压到D:\dev\jdk1.8.0_202，然后在系统变量里新建JAVA_HOME，值为该路径；再编辑Path，新增%JAVA_HOME%\bin。注意一定不要直接在 Path 里写死D:\dev\jdk1.8.0_202\bin，因为后面调整 JDK 版本时会非常麻烦。

Maven 的配置稍微多一点：解压到D:\dev\apache-maven-3.8.8，新建MAVEN_HOME，设置 Path 值为%MAVEN_HOME%\bin。然后打开 Maven 安装目录下的conf/settings.xml，配置本地仓库路径和阿里云镜像，否则首次构建会慢到让人怀疑电脑坏了。

<localRepository>D:/dev/maven-repo</localRepository> <mirror> <id>aliyunmaven</id> <mirrorOf>central</mirrorOf> <name>阿里云公共仓库</name> <url>https://maven.aliyun.com/repository/public</url> </mirror>

这里要特别提醒：RuoYi 的工程里有多模块依赖，子模块之间的依赖不会走私服，但第三方组件如果从中央仓库拉取，没有镜像的情况下一次构建可能要下载两三百兆依赖，网络差一点基本就构建失败。配好镜像后，构建时长会从十几分钟缩到两三分钟，体验完全不一样。

Maven 的 JDK 编译版本也要顺手固定一下，在settings.xml里加上 profile，否则每个模块要反复指定编译级别。这一步经常被忽略，等到 IDE 里发现target目录的 class 文件版本不对再回过来找原因，浪费时间。

2.3 MySQL 初始化与 Redis 运行参数建议

MySQL 装好之后，先别急着导入 RuoYi 的 SQL。建议先创建一个统一的字符集库，避免后面出现中文乱码的隐性 bug。我用的是：

CREATE DATABASE IF NOT EXISTS ruoyi_sso DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

然后通过命令行或 Navicat 执行 RuoYi 源码sql目录下的ry_2024xxxx.sql。这个脚本里同时包含库表结构和初始数据，包括菜单、角色、部门等，后期 OAuth2 需要新增的 client 表和 token 表，我们会在第二期再补，不用现在手工折腾。

Redis 这边，我要强调一个不算坑但很烦的问题：Windows 系统如果使用 tporadowski 维护的 Redis 5.0 版本，默认配置里protected-mode yes会导致 IDEA 启动项目时 Redis 连接被拒。我建议直接用 Docker 跑 Redis 7.0 容器，或者下载较新的 Windows Redis 发行包，然后至少把这两项改掉：

bind 127.0.0.1 protected-mode no

如果是生产环境，这样配置是绝对不行的，但本地开发环境为了图省事可以放宽限制。项目真正上线之前，一定要把 Redis 密码加上、把 bind 改回内网地址，保证安全合规。

3. 后端工程导入与启动前的关键配置

3.1 克隆 RuoYi 源码并切换分支

工程结构上，RuoYi 官方有两个主分支，一个叫 master，一个叫 master-vue，前者是不带前端代码的纯后端结构，后者配的是若依前后端分离版本。我们这个项目需要改登录认证流程，前后端分离是基础，所以直接拉取 master-vue。

git clone https://gitee.com/y_project/RuoYi-Vue.git cd RuoYi-Vue git checkout master-vue

拉下来之后你会看到多模块结构：ruoyi-admin、ruoyi-framework、ruoyi-quartz、ruoyi-generator、ruoyi-system、ruoyi-common。这套结构覆盖了启动入口、框架配置、定时任务、代码生成、业务模块和公共组件，职责分得比较清爽。

本项目的改造思路是在ruoyi-framework层引入 OAuth2 相关依赖，在ruoyi-admin层编写授权接口，其余模块尽量不动。所以克隆完成后，先熟悉一下ruoyi-framework/src/main/java/com/ruoyi/framework/config/SecurityConfig.java这个文件，它是 RuoYi 登录安全配置的核心，后续所有认证改造都会围绕它展开。

3.2 修改 application-druid.yml 等配置文件

RuoYi-Vue 的配置集中在ruoyi-admin/src/main/resources/目录下，最核心的配置文件有三个：application.yml、application-druid.yml、application-druid.yml（数据源配置）。我们要改的主要是数据库连接串和 Redis 连接串。

数据库部分的配置长这样，注意 URL 末尾要加上characterEncoding=utf8和serverTimezone=Asia/Shanghai，没有这两个参数，高版本 MySQL 驱动连上后会出现时区报错和中文乱码：

spring: datasource: type: com.alibaba.druid.pool.DruidDataSource druid: master: url: jdbc:mysql://127.0.0.1:3306/ruoyi_sso?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&useSSL=false username: root password: your_password

Redis 的配置也在application.yml的spring.redis节点下。默认的 host 是localhost，port 是6379，如果 Redis 设置了密码，就加一行password: xxx。特别注意数据库编号默认值是 0，后面做 token 存储时，我会建议单独给 OAuth2 相关的 key 设置一个独立的 db index，避免和 RuoYi 的验证码、登录状态混淆。

注意：这一期的目标是让原始 RuoYi 工程启动成功，所以先不要急着改 SecurityConfig，等整套环境验证通过后，第二期再来动认证逻辑。这样做的好处是问题定位清晰：现在出的问题属于环境问题，改完代码之后再出的问题属于代码问题，不会互相干扰。

3.3 Maven 构建命令与 IDEA 启动参数设置

进入项目根目录后，在命令行执行：

mvn clean install -Dmaven.test.skip=true

这一步会先把公共模块安装到本地仓库，供其他模块引用。如果构建过程中出现某些 jar 包下载失败，先检查第一步配置的阿里云镜像是否生效，再检查本地仓库有没有残留的半成品目录。常见的情况是中央仓库连接超时导致.lastUpdated缓存文件残留，此时需要手动删除本地仓库中对应目录，然后重新执行构建。

构建成功之后，用 IDEA 打开项目，等待 Maven 面板刷新依赖。有个很重要的设置：ruoyi-admin模块是启动类所在模块，而 IDEA 默认的启动配置可能需要手动添加。在RuoYiApplication.java上右键运行之前，要确认 Project SDK 是 1.8，Module SDK 也是 1.8，Maven 的 Runner 设置里 JRE 也要选 1.8，这三处不一致的话，运行时会直接抛UnsupportedClassVersionError。

启动参数里还需要加一个-Dfile.encoding=UTF-8，否则 Windows 控制台日志会乱码。这不算配置上的硬性问题，但日志可读性是排查后续 OAuth2 调试问题的基础。

4. 前端环境搭建与本地调试准备

4.1 Node.js 和依赖安装的正确姿势

RuoYi-Vue 的前端放在ruoyi-ui目录，基于 Vue 2 和 Element UI。Vue2 生态的依赖安装对 Node 版本极其敏感，webpack 4 和 node-sass 对 Node 16 的支持是稳定的，但如果你装的是 Node 17 以上版本，构建时大概率会报Error: Node Sass does not yet support your current environment。

我的建议是不要犹豫，直接用 Node 16.20.2。Windows 上可以直接去官网下载二进制包解压，把node.exe所在目录加到 Path 里，命令行执行node -v && npm -v验证版本。然后进入ruoyi-ui目录执行依赖安装：

npm install --registry=https://registry.npmmirror.com

这里用 npmmirror 是国内源，速度比 npm 官方源快很多，也是一个非常常规的操作。执行过程如果卡住不动，多半是某个依赖包有 postinstall 脚本在下载二进制文件，耐心等几分钟，不要频繁 Ctrl+C 中断，中断后容易留下残缺的 node_modules，后面反复 install 都不干净。

前端依赖装完跑起来的方式是：

npm run dev

默认会在localhost:80启动开发服务器，端口不对的话可以在vue.config.js里调整。前端通过代理访问后端localhost:8080，所以只要后端起得来、前端代理配置没问题，登录页面能刷出来，就说明环境基本打通了。

4.2 验证验证码登录流程是否走通

首次启动后不要急着点登录，先看两个内容。第一，打开浏览器访问http://localhost，确认能出现 RuoYi 的登录页；第二，检查 DevTools 的 Network 面板，看一下验证码接口/captchaImage返回的图片是否渲染成功，以及登录接口/login是否能正常拿到 token。

如果验证码图片渲染不出来，优先排查 Redis 连接。RuoYi 的验证码生成后是存在 Redis 里的，key 的格式大概长这样：captcha_codes:xxxx-xxxx。一旦 Redis 挂了，页面上的验证码会一直转圈或直接提示验证码过期，这个现象非常经典。

登录成功之后，左侧菜单能正常加载出来，说明 RuoYi 后端拿到 token 后成功调用了/getRouters接口获取动态路由，权限框架和数据字典都工作正常。到这里，原始 RuoYi 的核心链路已经验证完毕，可以放心进入 OAuth2 改造阶段。

这里我给一个小建议：在浏览器 F12 里观察一下登录接口返回的数据结构，保存好这个结果，因为下一期做 OAuth2 登录时，我们需要对比原始/login接口和标准 OAuth2 授权接口返回的 token 结构差异，那是理解认证流程改造的钥匙。

4.3 IDE 与调试工具的额外准备

前后端联调阶段，我习惯额外准备两个工具：Postman（或 Apifox）和 Redis Desktop Manager（或其他 Redis 可视化客户端）。

Postman 在 OAuth2 调试中的价值非常大。标准的 OAuth2 授权码模式要经历：请求授权码、回调解码、换取 token、校验 token 四步，每一步都得手工构造请求，靠浏览器操作效率太低。用 Postman 的 Authorization 面板选择 OAuth 2.0 类型，填入客户端 ID、密钥、回调地址、授权 URL、token URL，可以一键生成完整授权链路的请求，后续每改一次配置，都能快速复查。

Redis 可视化客户端则用来实时观察令牌的存储结构。OAuth2 改造完成后，Redis 里会出现类似oauth2:access_token:xxxx的键值，点开能看到令牌的过期时间和绑定的用户信息。这一步在纯命令行 redis-cli 里也能做，但有图形化界面的话，理解 token 生命周期会更直观。

5. 环境配置常见问题与排查技巧实录

5.1 版本冲突与依赖下载失败的处理思路

我把自己在部署过程中踩过的坑整理成了一张速查表，方便遇到问题时直接对照处理：

依赖下载失败是我见过最缠人的问题。有一次因为网络波动，中央仓库的某个包下载到一半断了，Maven 生成的.lastUpdated文件失效后并不会自动重试，需要手动删除本地仓库对应路径下的目录。在实际定位时，可以先看报错信息里缺少哪个 jar，再通过 IDE 的 Maven 面板单独刷那个模块，效率更高。

5.2 启动顺序与端口占用问题备忘

RuoYi 全家桶启动时有个隐形的顺序要求：先启动 MySQL 和 Redis，再启动后端，最后启动前端。如果顺序反了，后端启动时会因为连不上 Redis 而快速失败，虽然 Spring Boot 默认会重试，但日志会被一堆连接异常刷屏，干扰判断真正的启动问题。

端口方面要留意三个：后端默认 8080，前端默认 80，Redis 默认 6379。Windows 下 80 端口很有可能会被 IIS 或者其他软件占用，我遇到过 Http.sys 默认抢占 80 端口的情况，导致前端起不来。解决方案是修改vue.config.js里的 devServer.port 为其他端口，比如 8081，然后在浏览器里访问http://localhost:8081。

提示：还有一个容易被忽略的端口问题，如果 MySQL 用的不是默认 3306 端口，application-druid.yml里的连接串必须写对端口号。很多从别人那里复制工程的人，配置里的数据库端口和本机实际端口不一致，启动报错后查了半天才发现是这种低级问题。

5.3 从环境检查到 OAuth2 开发的过渡建议

这期内容到这里，环境已经全部就绪。在开始第二期的 OAuth2 改造之前，我强烈建议多做一件事：把 RuoYi 框架自带的登录流程完整梳理一遍，画一张粗略的逻辑图，标清/login接口调用了哪些 service、token 存到了哪里、SecurityUtils和SecurityContextHolder是怎么取用户信息的。

这个过程看似跟 OAuth2 没关系，实际上是在为后面的“接入外部认证”打基础。OAuth2 授权服务器的本质是：把 RuoYi 原来的“用户名密码换 token”这一步，升级成“重定向到认证中心、认证中心换授权码、再用授权码换 token”的标准流程。如果对原始流程不熟，改完代码之后会分不清哪些环节是 RuoYi 自带的，哪些是新加的，排错的时候会非常痛苦。

我个人在实际操作中的体会是，环境配置这个环节花的功夫绝对不是在浪费生命。很多项目开发到一半卡住，回头查才发现是 Redis 序列化方式不一致、数据库字符集不对、Node 版本不匹配这类基础问题。把这一步做扎实了，后续的认证改造才能顺畅推进。