mall-swarm 微服务商城系统架构与部署实践指南：基于 Spring Cloud Alibaba、Sa-Token 与 Kubernetes 的电商技术栈解析

• 后端
• 电商
• 微服务
• API网关

mall-swarm是一套基于微服务架构的电商商城系统，在完整电商业务（商品、订单、会员、促销、搜索）之上集成了注册中心（Nacos）、配置中心、监控中心（Spring Boot Admin）与 API 网关（Spring Cloud Gateway）等微服务基础设施。本文以仓库根目录的 README.md 为骨架，结合 pom.xml、config 目录配置、document/docker 与 document/k8s 部署清单，系统梳理其模块划分、技术选型、环境搭建、配置中心结构、鉴权机制与容器化部署方案。读完本文，你将掌握 mall-swarm 的完整架构脉络，并能够按步骤完成从开发环境搭建到 Docker/Kubernetes 部署的全过程。

一、项目定位与核心特性

mall-swarm在功能上是经典电商商城的微服务化版本：后台管理系统（商品、订单、会员、促销、内容、权限）、前台商城系统（搜索、购物车、下单、支付、会员中心）一应俱全；在基础设施层面，它集成了微服务体系中常见的注册中心、配置中心、监控中心和网关，形成了“业务微服务 + 基础设施微服务”的完整闭环。

README 中明确给出了两个分支的定位：

• master分支：基于 Spring Cloud 2025 + Spring Boot 3.5；
• dev-v2分支：基于 Spring Cloud 2021 + Spring Boot 2.7。

从根 pom.xml 可以精确看到 master 分支的版本矩阵：spring-boot.version=3.5.14、spring-cloud.version=2025.0.2、spring-cloud-alibaba.version=2025.0.0.0、java.version=17，同时集成了 Sa-Token 1.42.0、MyBatis 3.5.19、Knife4j 4.5.0、SpringDoc OpenAPI 2.8.17、MinIO 8.6.0、Spring Boot Admin 3.5.6 等组件。这说明当前仓库代码运行在 Java 17 与 Spring Boot 3.x 时代，与旧版基于 OAuth2 的认证中心方案（README 组织结构中mall-auth的旧描述）已有明显差异，实际鉴权已切换为 Sa-Token 体系（详见下文第五节）。

二、项目架构与组织结构

2.1 系统架构与业务架构

README 将架构分为系统架构与业务架构两层。系统架构层面，所有微服务统一注册到 Nacos 注册中心、从 Nacos 配置中心拉取配置，外部流量经 Nginx 进入 Spring Cloud Gateway 网关，再由网关按路由规则分发到 mall-admin、mall-portal、mall-search 等业务服务；监控中心（Spring Boot Admin）与 ELK 日志体系（Logstash → Elasticsearch → Kibana）作为旁路支撑。业务架构层面则覆盖商城典型域：商品（PMS）、订单（OMS）、会员（UMS）、促销（SMS）、内容（CMS）。

2.2 模块组织结构

README 给出了完整的模块树，与仓库实际目录完全对应：

mall ├── mall-common -- 工具类及通用代码模块 ├── mall-mbg -- MyBatisGenerator生成的数据库操作代码模块 ├── mall-auth -- 统一认证中心（Sa-Token 体系下的登录认证） ├── mall-gateway -- 基于Spring Cloud Gateway的微服务API网关服务 ├── mall-monitor -- 基于Spring Boot Admin的微服务监控中心 ├── mall-admin -- 后台管理系统服务 ├── mall-search -- 基于Elasticsearch的商品搜索系统服务 ├── mall-portal -- 移动端商城系统服务 ├── mall-demo -- 微服务远程调用测试服务 └── config -- 配置中心存储的配置

根 pom.xml 的<modules>声明与上述结构一一对应，其中mall-common承载通用能力：统一返回体 CommonResult、分页封装 CommonPage、全局异常处理 GlobalExceptionHandler、Redis 服务封装 RedisServiceImpl 以及 Web 日志切面 WebLogAspect。mall-mbg则存放 MyBatis Generator 生成的全部 Mapper 与 Model（如 PmsProductMapper、UmsAdmin），是各业务服务的数据访问基座。

三、技术选型全景

3.1 后端技术栈

README 的后端技术表如下（官网列省略，保留技术与用途说明）：

结合 pom.xml 的依赖管理，可补充更精确的版本信息：PageHelper Starter 2.1.1 + PageHelper 6.1.1、Druid 1.2.24（druid-spring-boot-3-starter，适配 Spring Boot 3）、MySQL Connector/J 9.3.0、Aliyun OSS SDK 3.18.5、logstash-logback-encoder 8.0、支付宝 SDK 4.40.630.ALL。依赖仓库同时配置了阿里云 Maven 镜像与 Maven Central（pom.xml），可提升依赖下载速度。

3.2 前端与移动端技术栈

• 后台管理前端：Vue + Vue-router + Vuex + Element + Axios + v-charts（基于 ECharts 的图表框架）；
• 前台商城移动端：Vue + Vuex + uni-app（跨端框架）+ mix-mall（电商项目模板）+ luch-request（HTTP 请求框架）。

后台与前台前端项目分别对应mall-admin-web与mall-app-web，README 提供了各自的项目演示地址（后台管理系统与前台商城系统，前台建议将浏览器切换为手机模式体验更佳）。

四、环境搭建与基础设施部署

4.1 开发环境版本要求

README 给出的开发环境版本要求如下：

注意：Docker Compose 环境清单（见 4.2）中 MongoDB 镜像为mongo:4、RabbitMQ 镜像为rabbitmq:3.9.11-management，与上表略有出入；以你实际使用的部署方式（本机安装或容器化）对应的版本为准。这是 README 中一个值得留意的版本细节。

4.2 Docker Compose 一键搭建基础设施

仓库在 document/docker/docker-compose-env.yml 中提供了基础设施的容器化编排，包含 9 个服务，全部挂载了宿主机数据/日志目录，便于持久化：

• MySQL 5.7：设置utf8mb4字符集，root 密码为root，数据挂载至/mydata/mysql/data/db；
• Redis 7：以--appendonly yes开启 AOF 持久化，数据挂载至/mydata/redis/data；
• nginx 1.22：配置、静态资源、日志分别挂载至/mydata/nginx/conf、/mydata/nginx/html、/mydata/nginx/log；
• RabbitMQ 3.9.11-management：暴露 5672（AMQP）与 15672（管理台）；
• Elasticsearch 7.17.3：discovery.type=single-node单节点模式，ES_JAVA_OPTS=-Xms512m -Xmx1024m，暴露 9200/9300；
• Logstash 7.17.3：挂载/mydata/logstash/logstash.conf到 pipeline 目录，暴露 4560~4563 端口；
• Kibana 7.17.3：通过elasticsearch.hosts=http://es:9200关联 ES（利用容器links别名es），暴露 5601；
• MongoDB 4：数据挂载至/mydata/mongo/db，暴露 27017；
• Nacos Server v2.1.0：MODE=standalone单机模式，暴露 8848（同时作为注册中心与配置中心）。

而 document/docker/docker-compose-app.yml 负责编排 6 个业务服务镜像（mall/mall-*:1.0-SNAPSHOT），端口映射为：mall-admin 8080、mall-search 8081、mall-portal 8085、mall-auth 8401、mall-gateway 8201、mall-monitor 8101。应用容器通过external_links以别名方式访问基础设施容器，例如 mall-admin 通过mysql:db访问 MySQL、mall-search 通过elasticsearch:es访问 ES、mall-portal 同时关联 redis/mongo/mysql/rabbitmq/nacos-registry。

4.3 镜像构建方式

根 pom.xml 通过io.fabric8:docker-maven-plugin在package阶段自动构建镜像：基础镜像openjdk:17，镜像名格式mall/${project.name}:${project.version}，容器启动命令为java -jar -Dspring.profiles.active=prod /${project.build.finalName}.jar，默认以prod环境启动。构建目标 Docker 主机通过<docker.host>（默认http://192.168.3.101:2375）指定，说明镜像构建需要可访问的 Docker 远程地址。

4.4 Windows 环境部署参考

仓库提供了 document/reference/deploy_windows.md，其部署流程与注意事项可作为所有本机部署的通用参考：

1. 安装 IDEA 并导入项目源码；
2. 安装 MySQL，创建mall数据库并导入 document/sql/mall.sql；
3. 安装 Redis、Elasticsearch、MongoDB、RabbitMQ 等环境；
4. 按顺序启动各服务：监控中心 mall-monitor（8101）→ 网关 mall-gateway（8201，可通过http://localhost:8201/actuator/gateway/routes查看动态路由）→ 后台 mall-admin → 前台 mall-portal → 搜索 mall-search → 测试 mall-demo。

业务接口统一通过网关 8201 端口访问，例如http://localhost:8201/mall-admin/admin/login、http://localhost:8201/mall-portal/sso/login，登录获取 token 后放入认证头即可访问需要登录的接口。

五、配置中心：config 目录结构详解

所有服务配置统一存放在 config 目录，由 Nacos 配置中心管理，每个服务按 dev/prod 两套环境拆分。各配置文件均以spring.profiles.active激活，通过spring.cloud.nacos.config拉取。逐文件说明如下。

5.1 mall-admin（后台管理服务）

config/admin/mall-admin-dev.yaml 是最完整的一份配置，包含四类核心配置：

• 数据源：MySQL 连接jdbc:mysql://localhost:3306/mall，附带useUnicode=true&characterEncoding=utf-8&serverTimezone=Asia/Shanghai&useSSL=false参数（UTF-8 编码、上海时区、关闭 SSL），默认账号 root/root；
• Redis：spring.data.redis下 host/database/port/password/timeout 全量参数（默认库 0、端口 6379、超时 3000ms）；
• 对象存储双通道：
  • 阿里云 OSS：endpoint、accessKeyId、accessKeySecret、bucketName（macro-oss）、签名有效期policy.expire=300（秒）、上传大小上限maxSize=10（MB）、回调地址 callback、目录前缀dir.prefix=mall/images/；
  • MinIO：endpointhttp://localhost:9000、bucketNamemall、默认凭据 minioadmin/minioadmin；
• 日志：logging.level.com.macro.mall: debug（开发环境调试级别），Logstash 主机localhost，enableInnerLog: false控制是否输出内部日志。

5.2 mall-portal（前台商城服务）

config/portal/mall-portal-dev.yaml 在数据源、Redis、Logstash 之外，还包含：

• MongoDB：host/port/database（mall-port，用于会员足迹、收藏等场景，对应mall-portal模块中的 repository 层实现）；
• RabbitMQ：host、port 5672、virtual-host: /mall、用户名密码均为mall（与QueueEnum延迟队列/订单超时取消等异步场景配合，相关实现见 mall-portal 的 component 包 中CancelOrderSender、CancelOrderReceiver等类）；
• 支付宝沙箱配置：gatewayUrl（沙箱网关）、appId、alipayPublicKey、appPrivateKey、支付成功 returnUrl、异步 notifyUrl——appId与密钥均需替换为你自己的沙箱/正式环境凭据。

5.3 mall-search 与 mall-gateway

• config/search/mall-search-dev.yaml：MySQL 数据源 + Elasticsearch 地址localhost:9200（对应spring.elasticsearch.uris），用于将商品数据从 MySQL 同步/检索至 ES；
• config/gateway/mall-gateway-dev.yaml：Redis 配置（网关层使用 Redis 缓存接口权限规则）与日志配置。

配置文件中的localhost仅适用于本机开发；Docker 部署时需将主机名替换为 docker-compose 中定义的容器别名（如db、es、redis），Kubernetes 部署则通过环境变量注入 Nacos 地址（见第七节）。

六、Sa-Token 认证鉴权与网关安全实现

README 技术栈中明确采用 Sa-Token 作为认证与授权框架，这在网关与业务服务源码中有完整落地，是理解 mall-swarm 安全体系的关键。

6.1 网关全局过滤器与路由级鉴权

mall-gateway 的 SaTokenConfig.java 注册了响应式过滤器SaReactorFilter，实现了一套“白名单 + 路由匹配 + 接口权限”的三层鉴权逻辑：

1. 拦截与放行：addInclude("/**")拦截全部请求，通过IgnoreUrlsConfig配置的白名单 URL 列表直接放行；
2. 预检请求：SaRouter.match(SaHttpMethod.OPTIONS).stop()直接放行 CORS 预检；
3. 登录认证：/mall-portal/**走前台会员认证（StpMemberUtil.checkLogin()，前台会员体系），/mall-admin/**走后台用户认证（StpUtil.checkLogin()，后台管理员体系）；
4. 接口级权限校验：从 Redis 哈希AuthConstant.PATH_RESOURCE_MAP读取“接口路径 → 所需权限”的映射，用AntPathMatcher将当前请求路径与映射中的 pattern 匹配，命中后执行StpUtil.checkPermissionOr(...)——即一个路径对应多个资源时，拥有任意一个权限即可访问；
5. 统一异常处理：NotLoginException返回未授权、NotPermissionException返回禁止访问、其余返回失败信息，均以 JSON 格式输出。

6.2 自定义权限数据源

StpInterfaceImpl.java 实现了 Sa-Token 的StpInterface接口：后台用户从会话中取出AuthConstant.STP_ADMIN_INFO对应的UserDto并返回其permissionList作为权限码集合，前台会员则不返回权限码。这是 Sa-Token 权限框架与 mall 后台 RBAC（角色-权限-资源）模型对接的桥梁：管理员登录后，其权限码被写入会话，网关据此完成细粒度接口鉴权。

6.3 统一认证中心 mall-auth

mall-auth模块（mall-auth）提供登录接口与UmsAdminService、UmsMemberService等认证服务，负责发放会话凭证；网关与业务服务共享 Sa-Token + Redis 的会话存储（sa-token-redis-jackson序列化方式），从而实现一次登录、全局鉴权。

七、监控、日志与 API 文档

7.1 监控中心 mall-monitor

mall-monitor基于 Spring Boot Admin 3.5.6 构建（依赖spring-boot-admin-starter-server，见 pom.xml），提供各微服务的健康状态、指标与在线实例监控。README 给出的访问地址为http://192.168.3.101:8101（本机部署为http://localhost:8101）。

7.2 ELK 日志体系

• 服务端：各服务通过logstash-logback-encoder将日志以 JSON 格式发送到 Logstash（配置见 document/elk/logstash.conf），Logstash 清洗后写入 Elasticsearch，最终由 Kibana（5601 端口）可视化查询；
• 应用侧：业务服务的日志输出格式与 Logstash 采集约定在 document/elk/logback-spring.xml 中定义；
• 配置侧：各 yaml 中的logstash.host指定了 Logstash 地址，enableInnerLog控制日志内部开关。

7.3 API 文档聚合

网关层集成了knife4j-gateway-spring-boot-starter（pom.xml），可对下游服务的 OpenAPI 文档进行聚合展示；各业务服务则使用knife4j-openapi3-jakarta-spring-boot-starter与springdoc-openapi-starter-webmvc-ui生成接口文档（版本兼容性已在依赖管理中显式处理，见 pom.xml）。开发环境可通过网关统一访问各服务文档，如 README 所列http://192.168.3.101:8201下的文档聚合入口。

八、Kubernetes 部署

仓库在 document/k8s 中为每个服务提供了 Deployment 与 Service 两类 YAML 清单。以 mall-gateway-deployment.yaml 为例，其关键设计如下：

• 镜像mall/mall-gateway:1.0-SNAPSHOT，容器端口 8201；
• 通过环境变量注入运行时配置：spring.profiles.active=prod（生产环境）、TZ=Asia/Shanghai（时区）、Nacos 注册与配置中心地址spring.cloud.nacos.discovery.server-addr/spring.cloud.nacos.config.server-addr（http://192.168.3.101:8848）；
• 日志通过hostPath卷挂载到宿主机/mydata/app/mall-gateway/logs（type: DirectoryOrCreate自动创建目录）。

该模式在 mall-admin、mall-auth、mall-monitor、mall-portal、mall-search 的 deployment 清单 中保持一致，配合各自的 service 清单 完成集群内服务发现与对外暴露。README 指出，使用 Kubernetes 部署后可通过http://192.168.3.101:30880查看项目运行状态。Nacos 注册中心在容器化环境中同样由环境变量指定地址，这也是为什么配置中心 yaml 中的localhost在集群部署时必须被覆盖。

九、运行效果与验证入口

README 提供了部署完成后的关键验证地址（均为 README 原文所列）：

• 注册中心：http://192.168.3.101:8848/nacos/，查看各服务注册信息；
• 监控中心：http://192.168.3.101:8101，查看应用健康与指标；
• API 文档：http://192.168.3.101:8201，通过网关访问聚合文档；
• 日志系统：http://192.168.3.101:5601，Kibana 中检索业务日志；
• Kubernetes 集群：http://192.168.3.101:30880，查看容器编排运行状态。

本机开发时对应地址为localhost加上述端口。建议按 4.4 节的启动顺序依次拉起服务，再通过注册中心确认各服务均已上线，这是排查“服务间调用失败”类问题的最快捷路径。

十、总结

mall-swarm 的价值在于将一套真实可用的电商业务与主流微服务基础设施完整打通：

• 业务层面：后台管理（mall-admin）、前台商城（mall-portal）、商品搜索（mall-search）三块业务覆盖了商城全链路；
• 基础设施层面：Nacos（注册 + 配置）、Spring Cloud Gateway（路由 + Sa-Token 鉴权）、Spring Boot Admin（监控）、ELK（日志）、Docker Compose / Kubernetes（部署）形成闭环；
• 实践层面：从 config 的配置中心体系，到 document/docker 与 document/k8s 的两套部署方案，再到 mall-gateway 的网关安全实现，均可作为微服务商城系统的可直接参考模板。

对于希望学习 Spring Cloud Alibaba 微服务落地的开发者，建议按照“先读 README 架构 → 再看 config 配置 → 跟踪一次网关鉴权调用 → 最后用 Docker Compose 复现环境”的路径入手；对于希望快速搭建商城的团队，则可直接复用 document/sql/mall.sql 的库表结构与本仓库的模块划分，在其基础上做业务裁剪与二次开发。

• 后端
• 电商
• 微服务
• API网关