# central-platform **Repository Path**: rainxw/central-platform ## Basic Information - **Project Name**: central-platform - **Description**: 前后端分离的企业级微服务架构--后端。 springboot 3.5.9、spring cloud 2025、spring cloud alibaba 2025 、Spring Authorization Server oatuh2 鉴权。 基于zlt框架，实现后微服务框架的脚手架（可以学习，参考，相互交流，应对AI崛起） - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 5 - **Forks**: 2 - **Created**: 2026-01-29 - **Last Updated**: 2026-07-10 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README

Central-Platform

Version JDK Spring Boot Spring Cloud Spring Cloud Alibaba Spring Authorization Server License

**中文** | [English](./README.en.md) --- ## 一、项目简介 Central-Platform 是一套基于 **Spring Boot 3.5.9 + Spring Cloud 2025 + Spring Cloud Alibaba 2025** 的前后端分离企业级微服务后端脚手架。 项目核心聚焦于以下能力： - **标准 OAuth2/OIDC 认证体系**：基于 Spring Authorization Server 1.5.5，支持密码模式、验证码模式、手机号模式、OpenID Connect，并集成 Redis 分布式 Session 与 Opaque Token（不透明令牌/引用令牌）。 - **统一 API 网关**：Spring Cloud Gateway（WebFlux 响应式），实现鉴权、限流、动态路由、接口聚合文档。 - **可插拔微服务架构**：12 个 Spring Boot Starter 封装横切关注点，业务模块开箱即用。 - **多维度可观测性**：Spring Boot Admin 监控 + 集中日志中心 + Prometheus 指标采集。 - **弹性设计**：Sentinel 熔断限流 + Feign 服务降级 + Nacos 动态配置。 - **消息驱动与实时推送**：RabbitMQ 消息驱动 + SSE 长连接实时推送。 > 本项目基于 [zlt/microservices-platform](https://gitee.com/zlt2000/microservices-platform) 升级演进而来，适用于学习、参考及二次开发。 --- ## 二、技术栈 ## 总体架构图 ![framework.png](https://gitee.com/rainxw/central-resouce/raw/master/image/platform.png)! ### 核心框架 | 组件 | 版本 | 说明 | |-----------------------------|------------|----------------------| | JDK | 17+ | 运行时 | | Spring Boot | 3.5.9 | 基础框架 | | Spring Cloud | 2025.0.0 | 微服务套件 | | Spring Cloud Alibaba | 2025.0.0.0 | Nacos 注册/配置、Sentinel | | Spring Authorization Server | 1.5.5 | OAuth2 / OIDC 授权服务器 | | Spring Cloud Gateway | 2025.0.0 | 响应式 API 网关（WebFlux） | ### 存储与缓存 | 组件 | 版本 | 说明 | |---------------|--------|-------------------------| | MySQL | 8.x | 主数据库 | | MyBatis-Plus | 3.5.12 | ORM 框架，支持逻辑删除 | | Druid | 1.2.23 | 数据库连接池，含 SQL 监控 | | Redis | 8.2.1 | Redis server | | Redisson | 3.52.0 | Redis 客户端，分布式缓存/Session | | Elasticsearch | 9.x | 全文搜索与日志分析 ### 消息队列 | 组件 | 版本 | 说明 | |------|------|------| | RabbitMQ | 4.x+ | 消息代理，支持 DLX 重试、延迟消息、死信队列监控 | ### 服务治理 | 组件 | 版本 | 说明 | |------|------|------| | Nacos | 3.x（8848） | 服务注册、配置中心 | | Sentinel | 2025.0.0 | 熔断、限流、流量控制 | | Spring Cloud OpenFeign | 2025.0.0 | 声明式 HTTP 客户端 | | Apache Dubbo | 3.3.5 | RPC 框架（Starter 集成，可选启用） | | Apache Curator | 5.9.0 | ZooKeeper 分布式协调 | ### 安全与认证 | 组件 | 说明 | |------|------| | Spring Security | 权限模型与 Filter Chain | | Spring Security OpaqueTokenIntrospector | 网关统一鉴权，Token 为 Opaque Token（不透明令牌/引用令牌，非 JWT 自包含令牌），通过调用 UAA 内省端点验证 | | Spring Security OAuth2 | 各微服务内部安全上下文解析（内网隔离，无需二次验签） | ### 对象存储 | 组件 | 说明 | |------|------| | AWS SDK S3 2.41.5 | S3 兼容存储（MinIO / 阿里云 OSS / AWS） | ### 工具与文档 | 组件 | 说明 | |------|------| | Knife4j 4.5.0 + SpringDoc 2.8.15 | OpenAPI 3 接口文档，网关聚合 | | Spring Boot Admin 3.5.6 | 应用监控面板 | | Micrometer Prometheus | Metrics 指标采集 | | HuTool 5.8.42 | Java 工具库 | | Transmittable ThreadLocal | 跨线程上下文传递（链路追踪） | --- ## 三、系统架构 ### 整体调用关系 ``` ┌────────────────────────────────────────────────────────────────────┐ │ 客户端 (Browser / App) │ └────────────────────────────┬───────────────────────────────────────┘ │ HTTPS（唯一对外入口） ▼ ┌────────────────────────────────────────────────────────────────────┐ │ sc-gateway (9900) ← 唯一对外暴露服务 │ │ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ │ │ Opaque Token鉴权 │ │ PermissionAuth │ │ Sentinel 限流/熔 │ │ │ │ (内省端点验证) │ │ Manager │ │ 断 (Nacos规则) │ │ │ └──────────────────┘ └──────────────────┘ └──────────────────┘ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ 动态路由 (Nacos) + 静态路由 (application.yml) │ │ │ └─────────────────────────────────────────────────────────────┘ │ └──────┬──────────┬───────────┬──────────┬──────────┬────────────────┘ │ │ │ │ │（内网隔离，不对外） ▼ ▼ ▼ ▼ ▼ ┌──────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌──────────┐ │ uaa │ │system │ │file │ │search │ │log │ │ (8000) │ │(7000) │ │(5000) │ │(7100) │ │(7200) │ └──────────┘ └────────┘ └────────┘ └────────┘ └──────────┘ │ │ │ │ │ │ Feign调用 │ ▲ ▼ │ (权限菜单) │ │ Elasticsearch（9.x） │ └──────────┘ │ (日志/审计) ▼ │ Redis Feign(search-client SDK) (Session/Token缓存) │ system-center(日志查询) ┌──────────────────────────────────────────────────────────────────────────────────────────┐ │ 基础设施层（内网） │ │ Nacos(8848) MySQL(各库独立) Redis Elasticsearch(9.x) MinIO RabbitMQ(5672) │ │ │ └──────────────────────────────────────────────────────────────────────────────────────────┘ ``` ### SSE 实时推送流程 ``` ┌────────────────────────────────────────────────────────────────────┐ │ central-sse (9300) ← SSE 长连接网关 │ │ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ │ │ WebFlux SSE │ │ RabbitMQ 通知 │ │ 网关 Header 透传 │ │ │ │ 多端连接管理 │ │ 监听 │ │ (x-user-id) │ │ │ └──────────────────┘ └──────────────────┘ └──────────────────┘ │ │ ┌──────────────────┐ ┌──────────────────┐ │ │ │ 心跳保活(15s) │ │ 空闲清理(90s) │ │ │ └──────────────────┘ └──────────────────┘ │ └──────────────────────────────┬─────────────────────────────────────┘ │ 监听 RabbitMQ 事件 ▼ ┌────────────────────────────────────────────────────────────────────┐ │ RabbitMQ (5672) │ │ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ │ │ 消息交换机 │ │ DLX 死信交换机 │ │ 延迟消息交换机 │ │ │ │ (central.mq) │ │ (central.dlx) │ │ (central.delay) │ │ │ └──────────────────┘ └──────────────────┘ └──────────────────┘ │ └────────────────────────────────────────────────────────────────────┘ ``` ``` 前端 sc-gateway central-sse RabbitMQ 业务服务 | | | | | |-- GET /api-sse/subscribe -->| | | | | |------- 路由转发 ----->| | | | | |----- 监听队列 ---->| | | | | | | | | | |<--- 事件发布 --| | | |<----- 消费事件 ----| | |<- SSE 事件流 ----------------|<------ 推送事件 -------| | | | | | | | | 客户端收到实时推送(notify 事件) | | | ``` ### 认证流程 > **核心原则**：网关（sc-gateway）是唯一对外入口，统一负责 Opaque Token 鉴权（通过 `OpaqueTokenIntrospector` 调用 UAA 内省端点）。内部微服务处于网络隔离状态，不直接对外暴露，无需独立验签 Token。 ``` 客户端 Gateway(唯一出口) UAA(8000) Redis │ │ │ │ │──POST /oauth2/token──►│ │ │ │ │──透传(PreserveHost)──────►│ │ │ │ │──验证User+Client──►│ │ │ │◄──Session Context──│ │ │◄──Opaque Token───────────│ │ │◄──Opaque Token────────│ │ │ │ │ │ │ │──GET /api-system/xx──►│ │ │ │ │──Opaque Token 鉴权（OpaqueTokenIntrospector→UAA /oauth2/introspect） │ │ │──查菜单权限(Feign)──────►system-center(内网) │ │ │◄──允许/拒绝────────────────│ │ │ │──转发请求（已鉴权）──────►下游微服务(内网隔离) │ │◄──业务响应─────────────│ │ │ ``` --- ## 四、模块结构说明 ``` central-platform/ ├── central-commons/ # 通用 Starter 层（横切关注点） │ ├── central-common-core/ # 基础工具：安全工具类、MyBatis Base Mapper、Jackson 配置 │ ├── central-common-spring-boot-starter/ # Web 通用配置 │ ├── central-db-spring-boot-starter/ # Druid + MyBatis-Plus 自动配置 │ ├── central-redis-spring-boot-starter/ # Redisson 自动配置 │ ├── central-log-spring-boot-starter/ # AOP 日志拦截、链路追踪、Feign/Dubbo 透传 │ ├── central-auth-client-spring-boot-starter/ # OAuth2 Resource Server 自动配置 │ ├── central-loadbalancer-spring-boot-starter/ # Feign + LoadBalancer + OKHttp 配置 │ ├── central-sentinel-spring-boot-starter/ # Sentinel Nacos 数据源 + Gateway 集成 │ ├── central-elasticsearch-spring-boot-starter/ # ES 9.x Java Client（`co.elastic.clients:elasticsearch-java`） │ ├── central-oss-spring-boot-starter/ # 对象存储抽象（S3/other 策略模式） │ ├── central-zookeeper-spring-boot-starter/ # Curator ZooKeeper 连接管理 │ └── central-rabbitmq-spring-boot-starter/ # RabbitMQ 企业级 Starter（DLX 重试、幂等消费、延迟消息） │ ├── central-uaa/ # OAuth2 授权服务器 [:8000] │ ├── central-gateway/ │ └── sc-gateway/ # Spring Cloud Gateway [:9900] │ ├── central-sse/ # SSE 推送服务 [:9300]（WebFlux + RabbitMQ 事件驱动） │ ├── central-business/ # 业务服务层 │ ├── system-center/ # 系统管理中心 [:7000]（用户/角色/菜单/部门/字典） │ ├── file-center/ # 文件管理中心 [:5000]（S3/other 上传下载） │ └── search-center/ # 搜索中心（ ES 9.x） │ ├── search-client/ # Feign SDK（供其他模块引用） │ └── search-server/ # ES 搜索服务 [:7100] │ ├── central-monitor/ # 监控层 │ ├── sc-admin/ # Spring Boot Admin [:6500] │ └── log-center/ # 日志中心 [:7200]（ES 9.x） │ └── central-config/ # Nacos 配置集成入口 ``` | 模块 | 端口 | 数据库 | 职责 | |------|------|--------|-------------------------------| | sc-gateway | 9900 | 无 | 路由转发、Opaque Token 鉴权、权限鉴定、限流 | | central-sse | 9300 | 无 | SSE 推送服务，通知消息实时推送（WebFlux + RabbitMQ） | | central-uaa | 8000 | oauth-center | OAuth2/OIDC 授权服务器，Token 颁发与校验 | | system-center | 7000 | system-center | 用户、角色、菜单、权限、部门、字典管理 | | file-center | 5000 | file-center | 文件上传/下载，S3/other 双后端 | | search-server | 7100 | Elasticsearch | 全文搜索、聚合查询、索引管理（ES 9.x） | | log-center | 7200 | Elasticsearch | 操作日志收集、慢 SQL 日志、请求统计（ES 9.x） | | sc-admin | 6500 | 无 | 应用实例健康监控（JVM/线程/内存） | ### 公共 Starter 一览（12 个） | Starter | 配置前缀 | 说明 | |---------|----------|------| | central-common-core | - | 基础工具类、统一响应体 `Result`、实体基类 | | central-common-spring-boot-starter | - | Web 通用配置 | | central-db-spring-boot-starter | `central.db` | Druid + MyBatis-Plus 自动配置、多租户隔离 | | central-redis-spring-boot-starter | `central.redis` | Redisson 分布式锁 + Spring Cache + Lua 限流 | | central-log-spring-boot-starter | `central.log` | AOP 日志拦截、链路追踪、审计日志 | | central-auth-client-spring-boot-starter | `central.security.auth` | OAuth2 资源服务器客户端（Opaque Token 本地内省） | | central-loadbalancer-spring-boot-starter | `central.loadbalancer` | Feign + LoadBalancer + OKHttp 配置 | | central-sentinel-spring-boot-starter | `central.sentinel` | Sentinel Nacos 数据源 + Gateway 集成（⚠待重构） | | central-elasticsearch-spring-boot-starter | `central.elasticsearch` | ES 9.x Java Client，注解驱动映射、Lambda 查询构造器 | | central-oss-spring-boot-starter | `central.oss` | 对象存储抽象（S3/other 策略模式） | | central-zookeeper-spring-boot-starter | `central.zookeeper` | Curator ZooKeeper 连接管理 | | central-rabbitmq-spring-boot-starter | `central.rabbitmq` | RabbitMQ DLX 重试、幂等消费、延迟消息、链路追踪 | --- ## 五、核心功能拆解 ### 5.1 认证与授权（central-uaa） **认证模式**（扩展 Spring Authorization Server）： | 模式 | Converter | Provider | 说明 | |------|-----------|----------|------| | 密码模式 | `PasswordAuthenticationConverter` | `PasswordAuthenticationProvider` | 用户名+密码 | | 密码+验证码 | `PasswordCodeAuthenticationConverter` | `PasswordCodeAuthenticationProvider` | MFA 场景 | | OpenID Connect | `OpenIdAuthenticationConverter` | `OpenIdAuthenticationProvider` | OIDC 隐式流 | | 手机号 | `MobileAuthenticationConverter` | `MobileAuthenticationProvider` | 手机验证码登录 | **Token 特性**： - 类型：**Opaque Token**（不透明令牌/引用令牌，非 JWT 自包含令牌），由网关通过 `OpaqueTokenIntrospector` 调用 UAA 内省端点（`/oauth2/introspect`）验证 - 鉴权边界：**仅在 sc-gateway 层完成 Token 验证**，内部微服务处于网络隔离状态，不直接对外暴露 - 分布式 Session：`RedisSecurityContextRepository`（Cookie: `OAUTH2SESSION`） - 支持 Token 自动续签（Gateway 层拦截器处理） - 单点登录：同账号互踢（强制下线已有 Session） ### 5.2 API 网关（sc-gateway） **Gateway 处理链**： ``` 请求入口（唯一对外暴露） ↓ 全局 Filter（RequestId 注入 / TraceId 透传） ↓ Opaque Token 鉴权（OpaqueTokenIntrospector 调用 UAA 内省端点，内部服务无需再验证） ↓ PermissionAuthManager（调用 system-center Feign 查菜单权限） ↓ Sentinel 限流（Nacos 动态规则 {appName}-sentinel-gw-flow） ↓ 路由匹配（静态 YAML + Nacos 动态路由） ↓ StripPrefix Filter → 下游微服务（内网隔离） ``` **路由规则**： | 前缀 | 目标服务 | Filter | |------|----------|--------| | `/oauth2/**` | uaa-server | PreserveHostHeader | | `/api-uaa/**` | uaa-server | StripPrefix=1, PreserveHostHeader | | `/api-system/**` | system-center | StripPrefix=1 | | `/api-file/**` | file-center | StripPrefix=1 | | `/api-log/**` | log-center | StripPrefix=1 | | `/api-search/**` | search-center | StripPrefix=1 | | `/api-sse/**` | central-sse | StripPrefix=1 | **免鉴权白名单**（代码中配置）： ``` /oauth2/** /api-uaa/validate/** /api-uaa/tokens/key /api-uaa/css/**、/images/**、/js/** /*/v3/api-docs/**（接口文档） /api-system/language/findLanguageForWeb ``` ### 5.3 权限模型（system-center） ``` User (sys_user) └─► UserRole (sys_user_role) └─► Role (sys_role) └─► RoleMenu (sys_role_menu) └─► Menu (sys_menu) ──► URL 路径 + 请求方式 ``` - 网关通过 `PermissionAuthManager` 调用 `GET /menus/{roleCodes}` 获取当前用户可访问 URL 列表 - 菜单权限缓存：Redis，TTL 300s（菜单）/ 1800s（用户信息） - URL 权限校验开关：`central.security.auth.urlPermission.enable`（默认 false） ### 5.4 统一日志（log-center + central-log-starter） - 请求/响应日志通过 AOP（`central-log-starter`）在各服务本地采集 - 日志目标写入 Elasticsearch（索引规划：`sys-log-*`、`audit-log-*`、`mysql-slowlog-*`） - `log-center` 提供查询接口，依赖 `search-client` Feign SDK 查询 ES - 跨线程日志上下文：Transmittable ThreadLocal 保证 async 任务继承 TraceId ### 5.5 搜索服务（search-center） - `search-server`：封装 ES 客户端，支持通用查询/聚合/索引管理 - `search-client`：Feign 客户端 SDK，其他模块直接引入 Maven 依赖即可调用 - 降级策略：`SearchServiceFallbackFactory` 返回空 PageResult ### 5.6 文件服务（file-center） - 抽象接口 `IFileService`（策略模式） - S3 实现：`S3Service`（支持 MinIO / 阿里云 OSS / AWS S3） - 限制：单文件 10MB，单次请求 20MB，缓冲阈值 512KB - 异步上传：`AsyncTaskExecutor` 线程池 ### 5.7 消息队列（central-rabbitmq-spring-boot-starter） **核心特性**： | 特性 | 说明 | |------|------| | DLX 原生重试 | 基于 RabbitMQ Dead Letter Exchange 的 Broker 级重试，无需客户端轮询 | | 幂等消费 | Redis 状态机实现，消费前检查消息 ID，防止重复消费 | | 自动拓扑声明 | 启动时自动创建 Exchange、Queue、Binding，无需手动配置 | | 延迟消息 | 支持 `rabbitmq_delayed_message_exchange` 插件 | | DLQ 监控 | 死信队列消息自动记录，便于问题排查 | | 链路追踪 | 消息 Header 自动注入 TraceId、租户 ID 等上下文 | | 生产者确认 | Publisher Confirm 机制，确保消息到达 Broker | | 健康检查 | Spring Actuator 集成，监控连接和通道状态 | **配置示例**： ```yaml central: rabbitmq: exchange: central.mq.exchange # 默认交换机 routing-key: central.mq.routing.key # 默认路由键 retry: max-attempts: 3 # 最大重试次数 initial-interval: 1000 # 初始重试间隔(ms) multiplier: 2.0 # 间隔倍数 idempotent: enable: true # 启用幂等消费 ttl: 86400 # 幂等记录 TTL(秒) ``` **核心类**： - `MessagePublisher`：消息生产者，支持同步/异步发送、延迟消息 - `AbstractMessageListener`：消息消费者基类，子类实现 `onMessage()` 即可 - `MessageIdempotentService`：幂等消费服务，基于 Redis 状态机 **依赖关系**： - 依赖：central-common-core, spring-boot-starter-amqp - 被依赖：central-sse ### 5.8 SSE 实时推送（central-sse） **核心特性**： | 特性 | 说明 | |------|------| | WebFlux SSE | 基于 Spring WebFlux 的响应式 SSE 实现 | | 多端连接 | 每用户最多 5 个并发连接（不同设备/浏览器） | | RabbitMQ 通知监听 | 监听通知队列，自动路由到对应用户的 SSE 连接 | | 网关认证 | 通过网关 Header 透传用户信息（x-user-id），无本地认证逻辑 | | 心跳保活 | 每 15 秒发送心跳事件，防止连接超时断开 | | 空闲清理 | 90 秒无活动自动关闭连接，释放资源 | | 背压缓冲 | 每个连接最多缓冲 100 条事件，防止内存溢出 | | 优雅关闭 | 服务关闭时通知所有客户端重连 | **事件类型**： | 事件 | 说明 | |------|------| | `connected` | 连接建立成功 | | `task-completed` | 任务完成通知 | | `task-failed` | 任务失败通知 | | `device-status-changed` | 设备状态变更通知 | **配置示例**： ```yaml server: port: 9300 central: rabbitmq: exchange: central.notify.exchange queues: system-notify-events: main: system-notify.events.main retry: system-notify.events.retry dlq: system-notify.events.dlq routingKey: system-notify.# device-notify-events: main: device-notify.events.main retry: device-notify.events.retry dlq: device-notify.events.dlq routingKey: device-notify.# sse: heartbeat-interval-ms: 15000 cleanup-interval-ms: 60000 system-notify: max-connections-per-user: 5 backpressure-buffer-size: 500 idle-timeout-ms: 300000 device-notify: max-connections-per-user: 10 idle-timeout-ms: 60000 ``` **依赖关系**： - 依赖：central-config, central-log-spring-boot-starter, central-common-spring-boot-starter, central-rabbitmq-spring-boot-starter, spring-boot-starter-webflux, spring-cloud-starter-alibaba-nacos-discovery **路由**：网关 `/api-sse/**` → central-sse ### 5.9 搜索引擎（central-elasticsearch-spring-boot-starter） **核心特性**： | 特性 | 说明 | |------|------| | 注解驱动映射 | `@EsIndex` 定义索引名、分片数；`@EsField` 定义字段类型；`@EsId` 标记主键 | | 自动建索引 | 应用启动时自动检测并创建缺失索引 | | Lambda 查询构造器 | `LambdaEsQueryWrapper` 支持类型安全的链式查询构建 | | 模板化 CRUD | `EsTemplate` 提供 save/update/delete/search 等标准操作 | | Basic Auth | 支持 Elasticsearch 安全认证 | | 多节点支持 | 支持配置多个 ES 节点，自动负载均衡 | **配置示例**： ```yaml central: elasticsearch: nodes: - host: 127.0.0.1 port: 9200 username: elastic password: ${ES_PASSWORD} connect-timeout: 5000 socket-timeout: 60000 ``` **核心类**： - `EsTemplate`：ES 操作模板，封装 CRUD、批量操作、聚合查询 - `LambdaEsQueryWrapper`：Lambda 查询构造器，支持链式调用 - `EsIndexManager`：索引管理器，负责索引创建、映射更新 **依赖关系**： - 依赖：central-common-core, co.elastic.clients:elasticsearch-java:9.2.6 - 被依赖：search-center/search-server, log-center --- ## 六、项目启动方式 ### 6.1 依赖组件 启动前确保以下中间件已运行： | 组件 | 版本要求 | 默认端口 | 说明 | |------|------|----------|------| | MySQL | 8.x | 3306 | 需初始化各模块 SQL 脚本 | | Nacos | 3.x | 8848 | 注册中心 + 配置中心 | | Redis | 8.x+ | 6379 | Session / 缓存 | | Elasticsearch | 9.x | 9200 | 日志 + 搜索 | | RabbitMQ | 4.x+ | 5672 | 消息队列（SSE 推送） | | MinIO（可选） | 最新版 | 9000 | 文件存储（或使用阿里云 OSS） | ### 6.2 数据库初始化 ``` sql/ ├── oauth-center.sql # OAuth2 客户端、授权数据表 ├── system-center.sql # 用户、角色、菜单、部门等 ├── file-center.sql # 文件元数据表 └── logger-center.sql # 审计日志表（如独立部署） ``` ### 6.3 Nacos 配置导入 将 `central-config/` 下各模块配置导入 Nacos，或直接在各模块 `application-dev.properties` 中覆盖。 ### 6.4 启动顺序 ``` 1. Nacos（central-register 或独立部署） 2. central-uaa # 认证服务必须最先启动 3. system-center # 网关权限检查依赖此服务 4. sc-gateway # 统一入口 5. file-center / search-server / log-center # 业务服务 6. central-sse # SSE 长连接网关（依赖 RabbitMQ） 7. sc-admin # 最后启动监控 ``` ### 6.5 构建命令 & Docker 构建（可选） ```bash # 全量构建（跳过测试） mvn clean package -Dmaven.test.skip=true # 全量构建（含测试） mvn clean install # 单模块构建 mvn clean package -Dmaven.test.skip=true -pl central-uaa mvn clean package -Dmaven.test.skip=true -pl central-gateway/sc-gateway # 版本号变更 mvn versions:set -DnewVersion= && mvn versions:commit # Docker 镜像构建（各模块目录下执行） mvn clean package -pl central-uaa spring-boot:build-image # 运行docker容器 docker run -d -p 8080:8080 \ --name central-uaa \ kicksharkie/central-platform/central-uaa # Docker 镜像构建（构建整个项目（所有模块）） mvn clean package spring-boot:build-image # 注意：Docker 镜像构建采用 Spring Boot 3 + Cloud Native Buildpacks 构建 Docker 镜像，替代传统： ❌ Dockerfile ❌ Spotify docker-maven-plugin 实现： ✅ 无需 Dockerfile ✅ 自动分层镜像（Layered） ✅ JVM 容器优化 ✅ 更高构建效率与缓存利用率 ✅ 官方支持，长期可维护 #注意:需要本地有docker环境， 如 Docker Desktop ``` ## 七、关键配置说明 ### 7.1 数据源配置（各模块共用模板） ```properties # 通过 Nacos 配置中心统一管理，以下为本地 Dev 覆盖示例 central.datasource.ip=127.0.0.1 spring.datasource.url=jdbc:mysql://${central.datasource.ip}:3306/{module-db}?useUnicode=true&characterEncoding=UTF-8 # Druid 连接池 spring.datasource.druid.initial-size=10 spring.datasource.druid.max-active=500 spring.datasource.druid.min-idle=10 spring.datasource.druid.max-wait=60000 spring.datasource.druid.validation-query=SELECT 1 ``` ### 7.2 认证服务关键配置（central-uaa） ```properties # OAuth2 客户端注册存储：MySQL + Redis 缓存 # Opaque Token 内省端点：/oauth2/introspect（网关通过此端点验证令牌有效性及关联信息） # Token 存储：Redis（令牌与用户信息映射关系，由 UAA 维护） # Session Cookie server.servlet.session.cookie.name=OAUTH2SESSION # Token 自动续签（Gateway 侧配置） central.security.auth.tokenRenew.enable=true central.security.auth.tokenRenew.clientIds=webApp ``` ### 7.3 网关安全配置（sc-gateway） ```properties # URL 权限校验开关（默认关闭，开启后通过菜单 URL 校验权限） central.security.auth.urlPermission.enable=false central.security.auth.urlPermission.ignoreUrls=/api-system/menus/current,... # 动态路由（Nacos 数据源） central.gateway.dynamicRoute.enabled=false central.gateway.dynamicRoute.dataType=nacos ``` ### 7.4 Sentinel 配置 ```properties # Dashboard 地址 spring.cloud.sentinel.transport.dashboard=127.0.0.1:8080 spring.cloud.sentinel.eager=true # Nacos 数据源（流控规则） # 配置 ID：{spring.application.name}-sentinel-gw-flow ``` ### 7.5 MyBatis-Plus 公共策略 ```properties # 逻辑删除：deleted=1 已删除，deleted=0 正常 mybatis-plus.global-config.db-config.logic-delete-value=1 mybatis-plus.global-config.db-config.logic-not-delete-value=0 # 字段更新策略：仅更新非 null 字段 mybatis-plus.global-config.db-config.update-strategy=NOT_NULL ``` ### 7.6 RabbitMQ 配置 ```properties # 连接配置 spring.rabbitmq.host=127.0.0.1 spring.rabbitmq.port=5672 spring.rabbitmq.username=guest spring.rabbitmq.password=guest # 生产者确认 spring.rabbitmq.publisher-confirm-type=correlated spring.rabbitmq.publisher-returns=true # 消费者配置 spring.rabbitmq.listener.simple.acknowledge-mode=manual spring.rabbitmq.listener.simple.prefetch=10 ``` --- ## 八、服务间通信 ### 8.1 同步调用（OpenFeign） | 调用方 | 被调用方 | 接口 | 用途 | |--------|----------|------|------| | sc-gateway | system-center | `GET /menus/{roleCodes}` | 网关权限校验 | | system-center | search-center | `POST /search/{indexName}` | 系统内搜索 | | log-center | search-center | `POST /search/{indexName}` | 日志查询 | **Feign 公共配置**（`central-loadbalancer-starter`）： ```yaml feign: httpclient: enabled: false okhttp: enabled: true # 使用 OKHttp compression: request.enabled: true response.enabled: true request.min-request-size: 2048 client: config: default: connect-timeout: 30000 read-timeout: 30000 ``` ### 8.2 异步调用（RabbitMQ） | 生产方 | 消费方 | Exchange | Routing Key | 用途 | |--------|--------|----------|-------------|------| | 业务服务 | central-sse | `central.notify.exchange` | `system-notify.#` | 消息通知事件 | | 设备服务 | central-sse | `central.notify.exchange` | `device-notify.#` | 设备状态事件 | **事件推送流程**： 1. 业务服务通过 `MessagePublisher` 发布通知事件 2. RabbitMQ 将事件路由到订阅队列 3. central-sse 消费事件，查找用户 SSE 连接，实时推送 4. 客户端通过 SSE 连接接收通知消息 ### 8.3 SSE 事件推送流程 ``` ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ 业务服务 │ │ RabbitMQ │ │ central-sse │ │ 客户端 │ │ │ │ │ │ │ │ (Browser) │ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ │ │ │ │ 1.发布通知事件 │ │ │ │───────────────────►│ │ │ │ │ 2.路由到队列 │ │ │ │───────────────────►│ │ │ │ │ 3.查找用户连接 │ │ │ │───────────────────►│ │ │ │ 4.发送SSE事件 │ │ │ │───────────────────►│ │ │ │ │ ``` ### 8.4 服务发现 - 注册中心：Nacos（`spring.cloud.nacos.discovery.enabled=true`） - 负载均衡：Spring Cloud LoadBalancer（客户端），Caffeine 实例列表缓存 - 服务 ID 小写：`spring.cloud.gateway.discovery.locator.lower-case-service-id=true` ### 8.5 降级策略 | Feign Client | Fallback | 降级返回值 | |---|---|---| | `MenuService` | `MenuServiceFallbackFactory` | 空列表（`Collections.emptyList()`） | | `SearchService` | `SearchServiceFallbackFactory` | 空 `PageResult` | | `AggregationService` | `AggregationServiceFallbackFactory` | 空聚合结果 | ### 8.6 链路上下文传播 - `Transmittable ThreadLocal`：跨线程（线程池、@Async）传递 TraceId、租户等上下文 - Feign 拦截器：`RequestHeaderInterceptor` 将上下文注入 HTTP Header 传递至下游 - RabbitMQ：消息 Header 自动注入 TraceId，消费端自动恢复上下文 --- ## 九、安全机制分析 ### 9.1 纵深防御体系 ``` Layer 1: TLS/HTTPS（Nginx 或 Gateway 终止） Layer 2: Gateway Opaque Token 鉴权（OpaqueTokenIntrospector 调用 UAA /oauth2/introspect，唯一对外入口） Layer 3: Gateway 权限校验（URL 级别，基于菜单权限） Layer 4: 内网隔离（微服务不对外暴露，仅接受来自 Gateway 的内部流量） Layer 5: 方法级鉴权（@PreAuthorize，可选） ``` > **设计说明**：Token 为 Opaque Token（不透明令牌/引用令牌，非 JWT 自包含令牌），所有鉴权逻辑集中在 Gateway 完成。内部微服务因处于网络隔离状态，不需要也不应该暴露在公网，无需进行二次 Token 验签。 ### 9.2 Opaque Token 设计（OpaqueTokenIntrospector） - **Token 类型**：Opaque Token（不透明令牌/引用令牌），令牌本身是无意义的随机字符串，不携带任何用户信息 - **验证机制**：网关使用 Spring Security `OpaqueTokenIntrospector`，向 UAA 内省端点（`POST /oauth2/introspect`）发请求，由 UAA 查询 Redis/DB 返回令牌关联的用户信息和权限 - **与 JWT 的区别**：JWT 可本地验签（自包含），Opaque Token 每次验证都需回调 UAA（中心化校验），但更易实现令牌即时撤销 - **鉴权位置**：**仅限 sc-gateway**，内部服务信任网关转发的请求 - **刷新令牌**：支持（配置 `OAuth2RefreshTokenGenerator`） - **Gateway 令牌续签**：拦截器检测过期时间阈值，自动请求刷新 ### 9.3 分布式 Session 安全 - Session 存储：Redis（`RedisSecurityContextRepository`） - Cookie 名称：`OAUTH2SESSION` - 单点登出：同账号登录时踢掉已有 Session（防重复登录） ### 9.4 安全注意事项（代码审查发现） 1. **sc-admin 默认凭据**：用户名 `admin`/密码 `admin`，生产必须修改 2. **Docker 镜像内存**：已采用 Cloud Native Buildpacks 的 `BP_JVM_HEAP_RATIO=75`（JVM 堆内存 = 容器内存限制的 75%），生产环境建议容器内存至少 512MB-2GB 3. **URL 权限校验默认关闭**：`urlPermission.enable=false`，建议生产开启 4. **Opaque Token 内省端点安全**：网关调用 UAA 内省端点所用的客户端凭据（client-id/client-secret）建议通过安全渠道（Nacos 加密配置 / Vault）管理，避免明文存储 --- ## 十、存在的问题与优化建议 ### 10.1 架构层面 | 问题 | 现状 | 建议 | |------|------|------| | 无分布式事务 | 跨服务写操作无 Saga/TCC 保障 | 涉及多服务数据一致性场景需引入 Seata | | Gateway 单点 | 未见 Gateway 集群配置示例 | 生产需多实例 + Nginx 前置，避免单点故障 | ### 10.2 性能层面 | 问题 | 说明 | 建议 | |------|------|------| | 权限校验 N+1 | 每次请求都 Feign 调用 system-center 查菜单 | 网关侧增加菜单权限本地缓存（Caffeine），TTL 30-60s | | 连接池偏大 | Druid maxActive=500，OKHttp 全局 1000 连接 | 根据实际 QPS 调整，避免资源浪费 | | Docker 内存配置 | 已采用 CNB `BP_JVM_HEAP_RATIO=75`，堆内存自适应容器限制 | 生产容器内存建议 512MB-2GB，CNB 自动启用 `-XX:+UseContainerSupport` | ### 10.3 工程化层面 | 问题 | 说明 | 建议 | |------|------|------| | 配置凭据安全 | 数据库密码、Redis 密码通过 Nacos 明文存储 | 集成 Spring Cloud Vault 或加密配置（Jasypt） | | 缺少 CI/CD 配置 | 无 `.github/workflows` 或 Jenkinsfile | 补充流水线，自动化测试 + 镜像构建 | | 缺少单元测试 | 代码中未见测试用例 | 对 Service 层和安全逻辑补充单元测试 | | 日志索引无生命周期 | ES 日志索引无 ILM 策略 | 配置 Index Lifecycle Management，避免磁盘无限增长 | --- ## 十一、项目亮点总结 ### 架构亮点 1. **完整 OAuth2/OIDC 实现**：基于最新 Spring Authorization Server 1.5.5，支持 4 种认证流程，采用 Opaque Token（不透明令牌/引用令牌）+ Redis 分布式 Session，令牌即时撤销能力强，是学习 OAuth2 实战的高质量参考。 2. **12 个可插拔 Starter**：将数据库、缓存、日志、认证、搜索、对象存储、消息队列等横切关注点封装为独立 Starter，新业务模块引入即用，遵循 Spring Boot 自动配置最佳实践。 3. **响应式网关 + 声明式权限**：sc-gateway 基于 WebFlux，`PermissionAuthManager` 以响应式方式集成 Feign 权限查询，在不阻塞 Netty 线程的前提下实现细粒度鉴权。 4. **策略模式对象存储**：`IFileService` 抽象 + `S3Service`/`ohterService` 双实现，切换存储后端无需修改业务代码，扩展性佳。 5. **Nacos 全面集成**：注册发现、配置中心、Sentinel 流控规则、Gateway 动态路由全部对接 Nacos，运维变更无需重启服务。 6. **Knife4j 网关聚合文档**：所有微服务 API 文档统一通过网关聚合展示，开发联调体验友好。 7. **企业级消息队列**：central-rabbitmq-starter 封装 DLX 原生重试、幂等消费、延迟消息、链路追踪等企业级特性，开箱即用，无需手动配置拓扑。 8. **SSE 实时推送**：central-sse 基于 WebFlux 响应式编程，通过 RabbitMQ 事件驱动实现通知消息实时推送到客户端，支持多端连接、心跳保活、背压缓冲等生产级特性。 ### 技术选型亮点 - 使用当前最新稳定版本（Spring Boot 3.5、Spring Cloud 2025），技术栈前沿 - 引入 Redisson（而非 Spring Data Redis）处理分布式场景，功能更丰富 - Feign + OKHttp + 连接池 + 压缩，HTTP 客户端调优完整 - Transmittable ThreadLocal 解决异步链路上下文丢失问题，细节到位 - RabbitMQ + DLX 重试机制，避免了传统客户端轮询重试的复杂性 - WebFlux SSE 替代传统轮询，实现真正的服务端推送，降低网络开销 --- ## 十二、端口速查 | 服务 | 端口 | |------|------| | Nacos | 8848 | | uaa-server（认证） | 8000 | | sc-gateway（网关） | 9900 | | central-sse（SSE 网关） | 9300 | | system-center | 7000 | | file-center | 5000 | | search-server | 7100 | | log-center | 7200 | | sc-admin | 6500 | --- ## 许可证 [Apache License 2.0](./LICENSE)