常见问题
常见问题
这一章分为两部分：
- 官方 FAQ：来自 RuoYi-Vue-Plus 5.X，原样保留，覆盖启动、登录、依赖、中间件、接口文档等通用问题；
- 平台 FAQ：无界平台自研功能相关的问题，见平台常见问题。
遇到报错时，先按下面的分类定位；找不到再用右上角搜索关键词（异常类名、配置项、报错原文通常最有效）。
环境与启动
| 问题 | 说明 |
|---|---|
| 打包 jar 运行报错 | jar 启动失败的常见原因 |
| Lombok 注解爆红 | IDEA 插件与编译配置 |
| 如何对接国产数据库 | 达梦、人大金仓等适配 |
| 关于 HTTPS 配置 | 证书与反向代理 |
| 无法读取 nacos 配置 | 命名空间、分组、DataId |
| Nacos 服务下线报错 | naming_instance_metadata Raft 报错 |
| 如何指定 dubbo 注册 IP | 多网卡环境 |
登录与权限
| 问题 | 说明 |
|---|---|
| 关于登录调试步骤 | 从账号密码到 token 的排查路径 |
| 放行接口提示认证失败 | 白名单配置未生效 |
| 不支持 ST 请求 | Sa-Token 会话模式 |
| Redis 报错 Permission denied | Redis 持久化目录权限 |
依赖与序列化
| 问题 | 说明 |
|---|---|
| JCE cannot authenticate the provider BC | BouncyCastle 签名校验失败 |
| 实体 bean 为空问题 | 拷贝、映射、序列化 |
| unable to read meta-data for class xxx | 注解处理器与依赖版本 |
| 导入 Excel 实体类为空 | EasyExcel 泛型与字段映射 |
| ParseException SQL 解析异常 | 多租户 SQL 解析失败 |
中间件与网关
| 问题 | 说明 |
|---|---|
| Only one connection receive subscriber allowed | Redis 响应式连接复用 |
| 为什么删除 sentinel | Sentinel 移除说明 |
| 如何使用 druid 连接池 | 替换 HikariCP |
接口文档与加密
| 问题 | 说明 |
|---|---|
| 接口文档对接 knife4j | 网关聚合文档 |
| swagger 相关问题 | 注解、分组、鉴权 |
| 前端加密请求 | 请求参数加解密与响应解密 |
项目维护
| 问题 | 说明 |
|---|---|
| 如何同步项目更新 | 上游代码同步策略 |
平台自有问题
插件安装、应用市场、可视化配置、消息中心、号码认证等平台能力的问题不在官方 FAQ 范围内，统一收录在平台常见问题。其中最常见的几类：
- 插件安装后菜单不显示、路由 404；
- 插件依赖没有用
provided导致类冲突； - 邮件 / 号码认证保存后不生效；
- 用户版看不到应用上架菜单；
- 迁移脚本被判定为「已执行脚本被修改」。
提问前建议附上：版本号、部署方式、完整异常栈、相关配置（隐去密钥），以及复现步骤。