简介：gulimall（谷粒商城）是一套覆盖电商全流程的Java微服务实战项目资料包，面向具备JavaWeb基础、希望掌握Spring Cloud Alibaba、分布式事务与高并发集群方案的开发者。资源将完整笔记、配套资料、可运行代码整合在一起，集群篇已更新完成，可对照服务注册、配置中心、网关路由、集群容灾等真实生产场景逐段学习。压缩包共4429个文件、约287.77MB，既有711个Java源码和126个Vue组件构成的业务代码，也有大量图片素材辅助界面说明，配合SQL脚本、YML配置、Dockerfile、Nginx与Registry集群配置，以及贯穿全阶段的MD笔记，便于按模块查阅和二次开发。目前已有2910人学习下载，对于正在系统梳理微服务技术栈或准备分布式相关面试的后端开发者来说，是一份可操作性很强的参考资料。
1. 集群篇：谷粒商城从单机到集群，先想清楚这三件事
拿到这套「gulimall（谷粒商城）」资料包，我最先翻的不是业务代码，而是集群篇。微服务项目教程遍地都是，但能把注册中心、配置中心、网关、中间件集群和 Nginx 编排串成一条完整链路的资料很少。资料包里笔记、代码、conf 文件都齐，集群篇已经完成，对正想把单机版商城往生产级环境迁移的 Java 开发者来说，可以直接对着复现。它实际解决三个问题：服务如何被动态发现、流量如何在网关和中间件层分摊、部署后如何验证集群真的生效。我按拆包的视角，把架构、中间件、部署、验证四条线依次拆开讲。
2. 谷粒商城集群架构：从 gulimall 模块拆分到 Nacos 注册中心
2.1 模块边界与调用链
gulimall 的代码结构是典型的多模块 Maven 工程，业务服务按电商域拆成 product、order、member、coupon、ware 等独立服务。集群化部署前，必须先把每块服务的职责和端口理清楚，否则配置网关和负载均衡时容易把 upstream 地址写错。
| 模块 | 默认端口 | 主要职责 | 集群化关注点 |
|---|---|---|---|
| gulimall-gateway | 88 | 统一入口，路由转发 | 需要多实例，上层用 Nginx 做负载均衡 |
| gulimall-auth-server | 12000 | 认证授权，OAuth2 接入 | 会话和 token 一致性 |
| gulimall-product | 10000 | 商品、分类、品牌管理 | 强依赖 Redis 缓存和搜索 |
| gulimall-order | 9000 | 订单、购物车、状态机 | 异步消息、分布式事务 |
| gulimall-member | 8000 | 会员等级、积分 | 无状态，方便水平扩容 |
| gulimall-coupon | 7000 | 优惠券发放与分摊 | 注意券库存恢复 |
| gulimall-ware | 11000 | 库存、采购 | 数据一致性要求高 |
这些端口在资料包的 SQL 和 YAML 里都能对上。集群化时，除了 gateway，每个服务都可以多实例注册到 Nacos。服务间调用不再写 IP，而是用lb://服务名让负载均衡器去选实例。
2.1.1 端口规划与防火墙注意
部署多节点集群时，防火墙放行不能只开业务端口。Nacos 除了 8848 还有 9848 的 gRPC 端口，Redis Cluster 节点间通信是 16379，Kafka 是 9092，网关是 88。我习惯在安全组里按服务角色分组放行，避免图省事全部放通。
调用链在单机版是浏览器 → 网关 → 业务服务。上了集群之后，动态请求先到 Nginx，由 Nginx 把流量分摊给多个网关实例，网关再通过注册中心找到目标服务；静态资源则由 Nginx 直接返回。
2.2 注册中心为什么选 Nacos：registry.conf 到底改了什么
服务多实例之后，第一件事是服务发现。gulimall 选 Nacos 而不是 Eureka，原因很实际：Nacos 同时提供注册中心和配置中心，一个组件解决两个需求，还支持 namespace 隔离环境。资料包里的 registry.conf 是我在集群篇里重点看的一份文件，我习惯先把它放在 Nacos 服务端 conf 目录下比对，看节点列表和数据库源是否一致。
Nacos 集群部署时，真正的节点列表在conf/cluster.conf，按行写各节点地址。一般我会这样写：
192.168.1.31:8848 192.168.1.32:8848 192.168.1.33:8848然后在application.properties里接上 MySQL，让 Nacos 共享配置和实例数据：
spring.datasource.platform=mysql db.num=1 db.url.0=jdbc:mysql://192.168.1.50:3306/nacos_config?useUnicode=true&characterEncoding=utf8 db.user=root db.password=yourpassword注意 Nacos 集群每个节点的数据库配置必须一致，否则节点间拉不到同一份配置。db.num默认是 1，多数据源时按db.url.0、db.url.1递增。
2.2.1 namespace 与多环境隔离
业务服务侧的注册配置也有几个关键点。每个参与集群的服务都要声明注册地址和命名空间，资料包里的标准写法是这样：
spring: application: name: gulimall-order cloud: nacos: discovery: server-addr: nacos-1:8848,nacos-2:8848,nacos-3:8848 namespace: gulimall-prod config: server-addr: ${spring.cloud.nacos.discovery.server-addr} namespace: gulimall-prod file-extension: yaml server: port: 9000server-addr配置多个节点时，客户端会把所有地址当作已知节点，某个节点挂了不影响注册。namespace必须和服务端一致，否则控制台能看到服务，实际调用却是 503。file-extension: yaml是让配置中心去加载gulimall-order.yaml，这份文件统一放在 Nacos 配置列表里，修改后无需重启服务。
2.3 网关集群与路由规则
网关是流量的第一道关卡。gulimall-gateway 本身也要注册进 Nacos，路由才能用lb://方式转发到目标服务。资料包里的网关配置大致如下：
spring: cloud: gateway: routes: - id: product_route uri: lb://gulimall-product predicates: - Path=/api/product/** filters: - RewritePath=/api/product/(?<segment>.*), /product/$\{segment} - id: order_route uri: lb://gulimall-order predicates: - Path=/api/order/** filters: - RewritePath=/api/order/(?<segment>.*), /order/$\{segment}这里最关键的是uri: lb://gulimall-product中的lb://，它告诉 Spring Cloud Gateway 使用 LoadBalancerClient 从 Nacos 拉取gulimall-product实例列表，而不是走写死的 IP。RewritePath用正则把/api/product/xxx重写为/product/xxx，剥离前缀，内部服务不需要感知外部 URL 规范。网关多实例后，每台实例的路由规则必须一致，最简单的做法是把网关配置也放到 Nacos 配置中心，避免漏改。
3. 中间件集群化：Redis Cluster、Kafka 与 Sentinel 的协同部署
3.1 Redis Cluster：缓存与分布式锁的落点
gulimall 的商品详情、首页轮播、用户验证码都走 Redis 缓存。单机 Redis 只要重启，缓存击穿就能把数据库打挂。集群篇的方案是 Redis Cluster，把 16384 个 slot 分布到多个主从节点上。
我一般用 Docker 起最小拓扑做验证，核心配置是这几个参数：
cluster-enabled yes cluster-config-file nodes.conf cluster-node-timeout 15000 appendonly yes bind 0.0.0.0cluster-enabled开启集群模式；cluster-config-file是节点保存集群状态的文件，每次启动会重写；cluster-node-timeout是节点判断 PONG 超时的时间单位毫秒，设太短容易误判，太长故障转移慢；appendonly yes开启 AOF，避免节点重启丢数据。
节点起好后，用 redis-cli 分配槽位：
redis-cli --cluster create \ 192.168.1.11:6379 192.168.1.12:6379 192.168.1.13:6379 \ 192.168.1.14:6379 192.168.1.15:6379 192.168.1.16:6379 \ --cluster-replicas 1--cluster-replicas 1表示每个主节点配一个从节点，三个主三从组成最小容错集群。某一主节点挂了，从节点会在cluster-node-timeout之后被提升为主节点，这是自动的。
3.1.1 槽位迁移与扩缩容
集群扩容时槽位不会自动迁移，需要手动执行redis-cli --cluster rebalance或reshard。常见做法是先加入新节点，再 reshard，把部分 slot 从老节点搬过去。搬移过程中客户端可能出现MOVED重定向，所以 Spring Boot 配置中的max-redirects要给够：
spring: redis: cluster: nodes: - 192.168.1.11:6379 - 192.168.1.12:6379 - 192.168.1.13:6379 max-redirects: 3max-redirects是客户端跟随 MOVED/ASK 重定向的最大次数。正常情况一次跳转就能找到目标节点，扩容或槽位迁移时需要多次。这里也容易踩坑：Redis Cluster 要求所有节点密码一致，Spring Boot 的spring.redis.password在集群模式下会应用到每个节点，不需要逐个配。
3.2 Kafka 集群：异步消息与故障切换
订单服务创建订单后，要通知库存服务锁定库存，还要给优惠券服务发消息，这些跨服务动作在 gulimall 里走 Kafka。Kafka 集群的配置核心在server.properties，每台 broker 需要有独立且唯一的broker.id，其他配置保持一致：
broker.id=1 listeners=PLAINTEXT://192.168.1.21:9092 log.dirs=/data/kafka-logs num.partitions=8 default.replication.factor=3 offsets.topic.replication.factor=3 min.insync.replicas=2 zookeeper.connect=192.168.1.31:2181,192.168.1.32:2181,192.168.1.33:2181重点解释几个参数：offsets.topic.replication.factor决定消费者 offset 提交主题的副本数，如果小于 broker 数而某个 broker 宕了，部分消费者将无法提交 offset；min.insync.replicas控制写数据时最少几个副本写入成功才算完成，配合 producer 的acks=all，消息基本不丢；log.dirs不要放系统盘，Kafka 对磁盘顺序写依赖很大。
Producer 端用 KafkaTemplate 发送，写法比较简洁：
@Resource private KafkaTemplate<String, String> kafkaTemplate; public void publishOrderPaidEvent(OrderPaidEvent event) { String json = JSON.toJSONString(event); kafkaTemplate.send("order-paid-event", event.getOrderSn(), json); }注意send的第二个参数是 key，拿订单号当 key，同一订单的支付、取消、超时消息会落在同一分区，消费端能按顺序处理。消费端要把 group-id 设置成和项目内一致，否则会重复或漏消费：
@KafkaListener(topics = "order-paid-event", groupId = "order-event-group") public void onMessage(String json) { OrderPaidEvent event = JSON.parseObject(json, OrderPaidEvent.class); // 解锁仓库库存、更新订单状态 }集群环境下，同一 group 的消费实例数不要大于分区数，否则多出来的实例会一直空转。order-paid-event 如果开了 8 个分区，消费实例最多 8 个。
这几个参数光看注释不容易记，我整理了一个对照表，部署时直接对着写：
| 参数 | 单机默认 | 集群建议 | 原因 |
|---|---|---|---|
| offsets.topic.replication.factor | 1 | 3 | 防止 broker 宕机导致 offset 丢失 |
| min.insync.replicas | 1 | 2 | 配合 acks=all 保证不丢消息 |
| default.replication.factor | 1 | 3 | 新建 topic 默认副本数，避免单点 |
3.3 Sentinel 集群限流：保护网关与核心服务
gulimall 学习版常用单机 Sentinel，生产集群则需要打开 cluster 模式。Sentinel 集群限流需要一个 Token Server 做全局流量统计，普通 client 会把请求数据上报给 Token Server，由它统一判定是否放行。
给限流规则加集群开关，通常同时把规则持久化到 Nacos：
[ { "resource": "gulimall-product", "count": 500, "grade": 1, "limitApp": "default", "strategy": 0, "clusterMode": true, "clusterConfig": { "flowId": 1001, "thresholdType": 0 } } ]grade=1表示按 QPS 限流；thresholdType=0表示全局阈值，资源在所有节点共享一个 count，如果每个节点单独计数，用户刷新两次就触发限流了，这是常见误配。Sentinel 客户端还需要配置 Token Server 地址：
spring: cloud: sentinel: transport: port: 8719 dashboard: 192.168.1.40:8858 cluster: server-addr: 192.168.1.41:12000port: 8719是客户端接收控制台心跳的端口。多个服务在同一台机器上时需要改成不同值，否则端口冲突会让控制台显示心跳断开。集群限流适合网关和商品服务这种热点入口，不建议对内部数据库操作开启。
4. 部署实录：从 default.conf 到 nginx.conf 的服务编排
4.1 资料包里的 conf 文件都是干什么的
解开 gulimall 压缩包，会看到 .babelrc、file.conf、registry.conf、default.conf、nginx.conf、gulimall.conf 和一些 CSS 文件。这些不全是后端配置。.babelrc 是前端 vue 工程的编译配置，GL.css、index.css 是静态资源；default.conf 和 nginx.conf 属于 Nginx 层，gulimall.conf 是商城站点的 server 配置。file.conf 和 registry.conf 在集群篇里多用于中间件初始化，比如 Nacos 的数据源初始化或 Sentinel 集群参数。我一般先按部署角色分类，避免拿到包不知道先改哪个。
| 文件 | 归属层 | 部署时的作用 |
|---|---|---|
| .babelrc | 前端编译 | 控制 ES6+ 语法转译规则 |
| file.conf | 数据源/初始化 | 组件启动前的数据源或日志配置 |
| registry.conf | 注册中心 | Nacos 集群节点与库表连接信息 |
| default.conf | Nginx | 默认站点兜底配置 |
| nginx.conf | Nginx | 全局配置，包含 http、event、日志 |
| gulimall.conf | Nginx | 商城反向代理和静态资源规则 |
| GL.css / index.css | 前端静态资源 | 商城页面样式，由 Nginx 静态托管 |
有一点需要提醒：registry.conf 在 Nacos 集群里不是必须的文件名，Nacos 原生用 cluster.conf，这里的 registry.conf 更像资料作者整理后的可复制模板。放进 Nacos conf 目录前，记得先比对 cluster.conf 节点列表。
4.2 gulimall.conf 的动静分离配置
集群部署时，网关前面必须放一层 Nginx，负责 SSL 终端、静态资源缓存和网关负载均衡。资料包里的 gulimall.conf 提供了完整的反向代理模板，我在此基础上调整了上游网关列表，让多个 gateway 实例都能被代理：
upstream gulimall_gateway { server 192.168.1.10:88 max_fails=2 fail_timeout=10s; server 192.168.1.11:88 max_fails=2 fail_timeout=10s; server 192.168.1.12:88 max_fails=2 fail_timeout=10s; } server { listen 80; server_name mall.example.com; root /usr/share/nginx/html; location / { try_files $uri $uri/ @gateway; } location @gateway { proxy_pass http://gulimall_gateway; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_connect_timeout 5s; proxy_read_timeout 30s; } location ~* \.(css|js|png|jpg|jpeg|gif|svg|woff2)$ { expires 7d; add_header Cache-Control "public, immutable"; access_log off; } }这里try_files $uri $uri/ @gateway先检查 Nginx 本地有没有静态文件，有就直接返回，没有就把请求交给 upstream 中的网关。proxy_pass不带 URI 后缀，会把原始请求路径原样转发给网关。location ~*正则匹配静态资源，expires 7d做强缓存。如果前端文件带 hash，缓存可以留更久；不带 hash 的话建议只缓存 1 小时，避免发版后用户看到旧样式。
4.2.1 静态资源缓存策略
gulimall 的前端里，GL.css 和 index.css 这类文件名如果不带 hash，更新后浏览器可能仍使用缓存。常见做法是把 Nginx 缓存时间改短，同时在后端接口响应头里加 ETag。Nginx 默认会对静态文件生成弱 ETag，必要时可以用etag on开启。实际部署时，我一般把 CSS、JS 的expires设为 1 小时，页面 HTML 设为 no-cache，这样既不会每次请求都打到源站，也不会出现发版后样式错乱。
4.3 集群启动顺序与验证
集群部署和单机最大的区别是组件有依赖顺序。我按“基础存储 → 注册中心 → 中间件 → 业务服务 → 网关 → Nginx”的顺序启动：
# 1. Nacos 集群模式启动 /opt/nacos/bin/startup.sh -m cluster # 2. Kafka 每台 broker 依次启动 /opt/kafka/bin/kafka-server-start.sh -daemon /opt/kafka/config/server.properties # 3. 网关和业务服务用同一份 JAR 启动，通过启动参数区分端口 java -jar gulimall-gateway.jar --server.port=88 java -jar gulimall-order.jar --server.port=9000 # 4. 检查 Nginx 配置并热加载 nginx -t && nginx -s reload启动后不要急着打开页面，先用 curl 验证链路：
curl -H "Host: mall.example.com" http://127.0.0.1/api/product/info/23返回 JSON 而不是 503，说明 Nginx → 网关 → product 服务这条链路已通。接着看 Nacos 控制台的服务列表，确认每个服务实例数大于 1、健康状态为 true。再看 Redis Cluster 的状态：
redis-cli --cluster check 192.168.1.11:6379该命令会输出槽位分布、节点状态、主从关系。如果输出里没有 inconsistent 之类的内容，说明缓存层正常。
排错时最常见的有三个问题。第一：服务注册到 Nacos 但网关 503，优先检查 namespace 是否一致，以及服务名是否被写成了下划线。第二：页面能打开但数据加载不出，查看 Redis 连接是否用了集群模式，单机客户端连集群会报 MOVED 错误。第三：Kafka 消费者重复消费，检查 group-id 是否换到了新值，新 group 会从头消费历史消息。
5. 集群压测与验证技巧：用一笔订单走完整条链路
集群起来以后，验证不能只看控制台绿灯。我习惯先用 wrk 对网关和商品接口做一轮压测，确认集群部署没有引入明显的性能损耗：
wrk -t8 -c200 -d60s --latency http://127.0.0.1/api/product/info/23关注输出里的 Requests/sec 和 Latency 分布。如果单实例和集群模式的吞吐差不多，就要检查流量是否被网关或 Nginx 配置限制了，比如 keepalive 没开、线程池太小。
接着验证故障转移。停掉一个网关实例，立刻用 curl 循环请求，观察失败窗口是否过长：
for i in $(seq 1 20); do curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1/api/product/info/23 sleep 0.5 done正常情况下，Nginx 会在 fail_timeout 之后把请求导到健康节点，返回码依然 200。Redis Cluster 的验证方式是杀掉一个主节点，然后执行redis-cli -c set test-key hello，正常情况下从节点自动晋升为主节点，命令仍然成功。Kafka 的验证则是启动控制台消费者，手动向 topic 发一条消息，看能否消费到：
/opt/kafka/bin/kafka-console-consumer.sh --bootstrap-server 192.168.1.21:9092 \ --topic order-event --from-beginning --group verify-cluster压测过程中还要盯着 JVM，用jstat -gcutil <pid> 1000 10观察老年代和 GC 停顿。如果 Full GC 频繁，先调大堆内存，不要急着改限流阈值，集群模式强调水平扩展，单节点堆上限反而可能掩盖问题。Sentinel 规则是否生效，可以用连续快速请求验证，当接口返回Blocked by Sentinel (flow limiting)说明规则已下发生效。如果这轮验证全过，把上面的命令整理成一个verify-cluster.sh，每次发版后跑一遍，比人工盯着多个控制台直观得多。
本文还有配套的精品资源，点击获取
