Mall4cloud 开源版（Spring Cloud B2B2C 微服务商城）项目介绍

一句话定位：Mall4cloud 是 Mall4j 体系下的微服务版商城，用 JDK 17 + Spring Boot 4 + Spring Cloud 2025 拆出 12 个 Spring Boot 应用、10 个独立数据库，覆盖平台端、商家端、买家端和下单到发货的主链路。它不是能直接交付的成品，而是「微服务电商架构的完整参考实现」——配置全在 Nacos、支付只有演示闭环、营销模块一张表都没有。

1. 项目是什么

它是「一套后端 12 个进程 + 三套前端」的 B2B2C 商城，按业务垂直拆服务、按服务水平拆库。

后端是一棵 Maven 多模块树：父 POM 下 14 个一级模块，其中 mall4cloud-api（10 个子模块）和 mall4cloud-common（6 个子模块）是契约与公共库，其余 12 个模块各含一个 @SpringBootApplication 启动类：

三件需要先认清的事：

• 仓库里没有「能直接跑」的配置。application.yml、bootstrap.yml 只写了 Nacos 地址，数据源、Redis、网关路由全在 Nacos 配置中心。doc/8-部署运维/2-中间件-docker-compose/mysql/initdb/mall4cloud_nacos.sql 才是那份「真正的配置」——不导它，服务起得来但网关没有路由、连不上库。
• 它是「架构样板」，不是「成品商城」。支付只有演示闭环，优惠券、拼团、秒杀、分销、退款、结算对账连表都没有。README 里「包含平台端、商家端、用户端和完整订单流程」是准确描述；但「完整」仅指下单到发货这一段。
• AGPL-3.0 是硬约束。它不是 Apache/MIT：把改过的版本部署成对外服务，也要向使用者提供源码。想闭源商用只能走官网商业授权。

2. 核心特性

没有的东西同样要写清楚：在 521 个 Java 文件和 39 张业务表里搜不到优惠券、拼团、秒杀、砍价、分销、直播、退款单、结算单、物流轨迹。搜索 coupon 只命中搜索常量与缓存名，没有对应实体、控制器和表。所以拿它当「营销型商城」会失望，它的价值在交易主链路的工程结构。

3. 技术架构

结构上的五个特点：

• 配置即架构：网关路由（/mall4cloud_product/** 转发到 lb://mall4cloud-product）、数据源、Redis、OSS、Seata 地址全写在 Nacos 的 application.yml 与 mall4cloud-gateway.yml 里。仓库里的 YAML 只负责「找到 Nacos」，这解释了为什么很多人克隆后启动一脸茫然。
• 一服务一库，跨库靠 Seata：10 个库各自 undo_log，下单要同时写订单库、扣商品库库存、写支付单，靠 @GlobalTransactional 兜底；seata 配置在 Nacos 里用 default_tx_group 指向 192.168.1.46:8091。
• 接口契约独立成模块：19 个 @FeignClient 全部声明在 mall4cloud-api 下，服务间只依赖契约模块而不依赖实现，改实现不影响调用方编译。
• 鉴权下沉到业务服务：网关不做 Token 校验，mall4cloud-common-security 的 AuthFilter 在每个业务服务里拦请求，再通过 TokenFeignClient 回 auth 校验、通过 PermissionFeignClient 回 rbac 校验 URI + Method。好处是服务可单独访问，代价是每个服务都得带着 Feign 依赖。
• 异步链路用延迟消息：下单后发 order-cancel-topic（延迟等级 +N）实现超时取消，取消后再发 stock-unlock-topic 解锁库存；支付成功发 order-notify-topic。5 个 @RocketMQMessageListener 构成整条异步闭环。

4. 目录结构

值得单独提一句：这个仓库自带「AI 副驾驶」文档。.agents/skills/mall4cloud/SKILL.md 和 .claude/skills/mall4cloud/ 是同一份内容（各 36 KB），把「哪个功能看哪几篇文档、哪个服务哪张表哪个端口」做成了路由表。这是 2026 年开源项目里少见的做法，对二次开发上手确实省时间——但它是文档，不是运行时能力。

5. 快速上手

环境要求

JDK 17、Maven 3.9+、Docker 与 Compose、Node.js 20.19+ 或 22.12+、pnpm 8~10。内存是隐形成本：一次起 6 个服务，按文档建议每个服务给 -Xms512m -Xmx512m，再加 MySQL、Redis、Nacos、RocketMQ、ES，8 GB 机器会很紧。

第一步：拉代码

git clone --depth 1 https://gitee.com/gz-yami_admin/mall4cloud.git
cd mall4cloud
ls db doc front-end

第二步：起中间件（先改 IP 再启动）

cd doc/8-部署运维/2-中间件-docker-compose
sed -i 's/192.168.1.46/你的服务器IP/g' docker-compose.yaml
chmod -R 777 ./rocketmq
chmod -R 666 ./minio/data
docker compose -f docker-compose.yaml up -d

compose 会把 mysql/initdb 下的三份 SQL 自动导入，写入 Nacos 配置、Seata、Canal 的库表。启动后到 MinIO 控制台 9001 建桶 mall4cloud，否则上传图片会 500。

第三步：构建并启动最小链路

网关、auth、rbac、platform、biz 五个服务足够跑通「登录进后台」：

mvn -DskipTests clean package
export NACOS_HOST=你的服务器IP
java -jar mall4cloud-gateway/target/mall4cloud-gateway.jar
java -jar mall4cloud-auth/target/mall4cloud-auth.jar
java -jar mall4cloud-rbac/target/mall4cloud-rbac.jar
java -jar mall4cloud-platform/target/mall4cloud-platform.jar
java -jar mall4cloud-biz/target/mall4cloud-biz.jar

jar 名取自各模块 artifactId，以 target/ 下实际产物为准。平台端默认账号 admin / 123456（auth_account 里两条 admin 记录分别是平台端与商家端，我核对过 BCrypt 哈希确实对应 123456）。

第四步：起前端

cd front-end/mall4cloud-platform
corepack enable
pnpm install
pnpm dev

用 npm 或 yarn 会被 preinstall: npx only-allow pnpm 直接拦掉。VITE_APP_BASE_API 只填网关地址（示例 http://192.168.1.80:8000），不要指向 9101、9104 这些业务端口。

验证

curl -i http://127.0.0.1:8000/mall4cloud_rbac/menu/route

返回 401 或未授权而不是 404，说明网关路由与 Nacos 配置都通了；能登录后台则 auth、rbac、platform 三个库也对了。

6. 功能模块清单

49 张表按库分布，比逐张罗列更有用：

（每库各含 1 张 undo_log，合计 10 张，所以表数相加为 49。）

三个判断：

• 交易链路是完整的：商品 → 购物车 → 下单 → 支付单 → 发货 → 收货，每步都有表和状态字段，order 表还有 version 做乐观锁。
• 平台端是空壳的：platform 库只有平台用户和系统配置，平台对店铺的接口（分页、新建、修改、重置密码）其实写在 mall4cloud-multishop 的 controller/platform 包里。方法名叫 getShopAuditingPage，但只是普通分页——新建店铺直接 shopStatus = OPEN，没有审核流程、没有保证金、没有结算。
• 营销与售后是缺的：没有优惠券、没有退款单、没有售后工单。要做「平台型商城」，运营侧基本要自建。

7. 版本与授权

AGPL-3.0 到底意味着什么，这条必须说清：AGPL 与 GPL 的关键差别在网络分发条款——如果你修改后以服务形式提供给外部用户使用，也要向这些用户提供完整对应源码（含你的修改）。所以「自己公司内部后台用」通常没问题，「做成 SaaS 卖给商家」就必须开源或买商业授权。商业版的「100% 源码交付、源码无加密、永久授权」是官网宣传口径，不能当成开源版的承诺。

版本号上有个小坑：标签叫 v4.0，POM 里还是 1.0-SNAPSHOT，代码里也没有 version.json 之类的版本文件。判断你手上的代码是哪一版，只能靠 git describe 或看提交时间。

8. 商业模式说明

典型「开源版聚流量、商业版收钱、交付服务变现」结构：

官网宣传企业版覆盖 B2C、B2B2C、S2B2C、B2B2B、SaaS、多租户、跨境，这部分我无法从代码核实，只能标注为「官方宣传」。可核实的事实是：开源版把「营销、结算、售后」这几块最容易被商家付费的部分留在了商业版，开源部分保留了交易内核与微服务骨架——产品分层意图很明显。

9. 生态与周边

要注意两点：本文链接是 gz-yami_admin 这个仓库，README 与文档里的地址指向 gz-yami，两者内容一致（同一提交 6750d36），拉代码时别以为是两个项目。另外社区活跃度不均衡——约 7K Star 却 0 个开放 Issue、9 个 PR，说明问题主要在 QQ 群消化，公开检索价值有限。

10. 选型建议

适合你，如果：

• 你要学「Spring Cloud 微服务电商」的完整落地：服务拆分、Feign 契约、Nacos 配置、Seata 事务、RocketMQ 延迟消息、Canal 同步 ES，这套组合是现成教材；
• 团队是 Java 栈且已上 JDK 17，能接受 Spring Boot 4 / Spring Cloud 2025 这套新版本；
• 你要的是 B2B2C 交易内核，营销、结算、售后准备自研；
• 用于自用或学习——AGPL 对内部使用基本无感。

不适合你，如果：

• 你想要开箱即用的商城：缺营销、缺售后、缺结算，装完只是「能下单」；
• 你只有 2~4 GB 内存的小机器：12 个服务 + 8 个中间件是硬成本；
• 你要闭源 SaaS：AGPL 会要求你开源修改，除非买商业授权；
• 你团队没有微服务运维经验：Nacos 配置错一处，网关 404、服务连不上库，排查门槛比单体高一个量级。

和同类怎么比：和 ZKMall、ShopWind、YoShop 这些「单体/多商户后台」比，Mall4cloud 的差异是工程结构而非功能数量——它的服务边界、契约模块、异步链路更接近真实生产架构，但业务功能反而更少；和 Mall4j 单体版比，它是同一套产品思路的分布式版本，选哪个取决于你是否真的需要拆服务，而不是哪个「更高级」。

11. 风险与坑

• 配置不在仓库里：网关路由、数据源、Redis、OSS 全在 Nacos。只 git clone 不导 mysql/initdb/mall4cloud_nacos.sql，网关起来也是 404，服务连不上库。这是新手第一大坑。
• 中间件密码全是同一个明文：80jpnH4.r5g 同时是 MySQL root、Redis、MinIO、Elasticsearch、Nacos 的密码，写在 docker-compose.yaml 和 Nacos 初始化 SQL 里。上线前必须逐项更换，且别用 sed 全局替换后忘了 Nacos 里那条。
• Nacos 账号两处不一致：各服务 bootstrap.yml 默认 nacos / nacos，而初始化 SQL 写入的是 nacos / 80jpnH4.r5g，compose 还开了 NACOS_AUTH_ENABLE=true。不改就是启动即 403。
• 示例 IP 有三套且互不相同：compose 与 Nacos 配置用 192.168.1.46，前端 .env 用 192.168.1.80，PayController 的回调地址写死 http://192.168.1.17:8126/mall4cloud_payment。最后这个如果忘了改，支付回调永远打不通。
• 支付是演示闭环，不是真支付：PayController.pay() 生成支付单后立刻调用 payNoticeController.submit(payId)，没有微信/支付宝 SDK、没有签名验签。接真实支付要自己重写这一段，别以为「配个密钥就行」。
• 网关 CORS 放开到任意来源：Nacos 里 mall4cloud-gateway.yml 配了 allowedOriginPatterns: "*" 且 allow-credentials: true。生产环境应改成白名单，否则配合 Cookie 场景有 CSRF 风险。
• Token 的「加密」名不副实：TokenStore.encryptToken() 只是 Base64(随机串 + 时间戳 + sysType)，decryptToken() 反向 Base64。安全性实际靠 Redis 里的随机 UUID，别指望它防篡改。
• Token 有效期注释与实现矛盾：注释写「普通用户 1 小时、系统管理员 2 小时」，代码三个分支都乘 24 * 30，实际全是 30 天。做安全审计时按 30 天算。
• 平台端没有审核流：createShop() 直接置 shopStatus = OPEN，平台对店铺只有分页/新建/改资料/重置密码。想做「入驻审核 + 保证金」得自己加表加状态机。
• 没有单元测试：521 个 Java 文件里找不到 src/test 目录。升级 Spring Boot 4 或改公共模块，只能靠手点回归，这在微服务里成本很高。
• Seata 依赖 undo_log：10 个库每库一张，漏建或表结构不匹配，全局事务回滚会失败并留下脏数据。手工建库时最容易漏。
• 文档里有不能照搬的 SQL：doc/8-部署运维/3-已知风险与待核对项.md 自己承认「update mall4cloud_product set update_time = now() 不匹配当前表名」——库名是 mall4cloud_product，表名不是。
• RocketMQ 控制台无鉴权：8180 端口没配登录保护，ES 健康检查也被 management.health.elasticsearch.enabled=false 关掉了（出错不报警）。这两个只能靠网络层隔离。
• 技术栈太新，生态要自测：Spring Boot 4.0.3 + Spring Cloud 2025.1.1 + springdoc 3.0.2 + knife4j 4.5.0 是 2026 年的组合，第三方 starter 兼容性没有经过大规模验证，遇到怪问题先怀疑版本而不是代码。
• AGPL 不是摆设：对外提供服务也要提供源码。把它当「免费商用」会踩法律坑，商业用途先读协议或买授权。

12. 参考链接