- MateCloud 是 AI 原生 · 云原生的 DDD 微服务脚手架，基于 Spring Boot 4 + Spring Cloud 2025 + Dubbo 3 + Spring AI 2.0，单体（
mate-monolith）与微服务双形态一键切换。 - 开源版含 网关 / 认证 / 系统管理 / 通知 四个核心服务 + 27 个即插即用 Starter（18 核心 + 9 高级），完整展示 DDD 四层 + CQRS 读写分离。
- AI 原生：Spring AI 2.0 +
@Tool自动发现 + 会话记忆 + 流式对话，支持 6 个 LLM 提供商（Anthropic / OpenAI / 智谱 / Minimax / DeepSeek / Ollama）。 - MCP 原生工程闭环（Loop Engineering）：
mate --mcp把mate-cli与业务@Tool暴露为 MCP 工具，让 AI Agent 在「观察 → 推理 → 执行 → 反馈」闭环中操作集群——查服务、调 RPC、生成代码、迁移数据库。 - 认证基于 Sa-Token（密码 / 短信 / 验证码登录）；Docker Compose 一键编排，
mate-cli提供脚手架、Nacos 配置、服务发现、健康检查与代码生成。
设计理念： 最小公共、各司其职、Starter = 即插即用能力。
接入层 → 网关（:9010）→ 业务服务（auth / system / notice，Dubbo RPC + DDD 四层）→ 能力层 Starter → 基础设施（MySQL / Redis / RabbitMQ / Nacos / MinIO），可观测性（Actuator / Prometheus / Tracing）横切。详见 总体架构文档。
真实运行截图（前端 admin
:3000+ 后端网关:9010），基于 mate-ui 设计系统。
 工作台 · 概览 / 服务健康 |
 菜单管理 · RBAC 菜单树 |
 角色管理 · 菜单 / 数据权限 |
 管理员 · 分配角色 |
 数据字典 · 类型 / 数据 |
 参数配置 · 系统键值 |
 身份接入 · 企微/钉钉/飞书/LDAP |
 微服务 · 灰度发布 / 路由测试 |
 登录审计 · 日志 / UA / 状态 |
MateCloud 提供了完整的部署与开发文档，涵盖架构设计、Starter 使用、CLI 命令、前端开发和生产部署等内容。
cd mate-ui && pnpm dev:docs # → http://localhost:5174- JDK 21+
- Maven 3.9+
- Docker & Docker Compose
- Node.js 20+（运行
mate-ui前端时需要）
在项目根目录执行完整编译，再构建并启动本地服务栈：
# 1. 编译
mvn clean install -DskipTests
# 2. 启动基础设施（MySQL + Redis + RabbitMQ + Nacos + MinIO）
make infra-up
# 3. 初始化 Nacos 配置
java -jar mate-cli/target/mate-cli.jar config init
# 4. 启动所有服务
make up服务启动后，通过网关端口 9010 访问后端接口，Nacos 控制台端口为 8848。
数据库自动初始化：无需手动建表。
mate-system首次启动时，Flyway 自动执行db/migration/下的迁移（V1.0.0建表 →V1.0.1种子数据 → ……），完成建表、 内置账号admin/admin123、角色、菜单与字典的初始化。每个服务有独立的版本历史表flyway_history_<module>。详见 数据库迁移 与 菜单配置。
cd mate-ui
pnpm install
pnpm dev # → http://localhost:3000默认开发账号：admin / admin123
| 依赖 | 版本 |
|---|---|
| Java | 21 |
| Spring Boot | 4.0.7 |
| Spring Cloud | 2025.1.2 |
| Spring Cloud Alibaba | 2025.1.0.0 |
| Spring AI | 2.0.0 |
| Dubbo | 3.3.6 |
| MyBatis Plus | 3.5.16 |
| Sa-Token | 1.45.0 |
| Redisson | 4.5.0 |
| Vue | 3.5 |
| Element Plus | latest |
| Vite | latest |
| 功能 | 说明 |
|---|---|
| DDD 四层架构 | trigger / application / domain / infrastructure，领域层零框架依赖 |
| CQRS 读写分离 | CommandService 写 + QueryService 读，职责清晰 |
| 微服务 · 单体双形态 | Spring Cloud + Dubbo 3 RPC + Nacos；mate-monolith 单体一键切换；灰度 · 限流 · Seata |
| 27 个 Starter | 18 核心 + 9 高级：持久化、缓存、锁、MQ、任务、分片、租户、安全、可观测、AI、测试…… |
| 多租户 SaaS | 行级隔离 / Schema 隔离 / 独立数据源三种模式 |
| AI 原生集成 | Spring AI 2.0 + @Tool 自动发现 + 会话记忆 + 流式对话 + 6 个 LLM 提供商 |
| MCP 原生工程闭环 | mate --mcp + 业务 @Tool 暴露为 MCP 工具，AI Agent 闭环操作集群（Loop Engineering） |
| 分布式锁 | @DistributedLock 注解，Redisson 实现 |
| 接口签名 | @ApiSign 防篡改，HMAC-SHA256 签名验证 |
| 限流降级 | @RateLimit 注解限流 + Sentinel 动态规则 |
| 审计日志 | @AuditLog 自动记录操作日志 |
| 数据权限 | @DataPermission 注解式行级数据过滤 |
| 幂等控制 | @Idempotent 防重复提交 |
| 灰度发布 | Dubbo + Gateway 双链路灰度路由 |
| 代码生成 | CLI 一键生成 DDD 四层代码 + Flyway 迁移 |
| MCP Server | mate-cli --mcp，Claude Code / Claude Desktop 直接调用业务工具 |
mate-ui -- Vue 3 前端 (pnpm monorepo)
├── apps/admin -- 管理后台 SPA [3000]
├── apps/docs -- VitePress 文档站 [5174]
└── packages/ -- 共享包 (core, hooks, ui, utils)
matecloud
├── mate-common -- 纯类型库（零自动配置）
│ ├── mate-base -- BaseEntity, Result, BizException, ErrorCode
│ └── mate-api -- RPC 接口、命令、响应、枚举
├── mate-starters -- 13 个即插即用 Starter（7 核心 + 6 业务）
│ ├── mate-ds-starter -- MyBatis Plus + Druid + Flyway
│ ├── mate-web-starter -- 全局异常 + Jackson + DevTools
│ ├── mate-cache-starter -- Caffeine L1 + Redis L2 + @DistributedLock
│ ├── mate-nacos-starter -- Nacos 注册发现 + 配置中心
│ ├── mate-rpc-starter -- Dubbo RPC
│ ├── mate-sa-token-starter -- Sa-Token（Servlet + Reactor）
│ ├── mate-monitor-starter -- Actuator + Prometheus + Tracing
│ ├── mate-mq-starter -- RabbitMQ + 延迟队列
│ ├── mate-job-starter -- XXL-Job 执行器
│ ├── mate-security-starter -- @ApiSign @RateLimit @AuditLog @Idempotent
│ ├── mate-file-starter -- MinIO 上传/下载/预签名
│ ├── mate-excel-starter -- EasyExcel 导入导出
│ └── mate-tenant-starter -- 多租户（行级/Schema/独立数据源）
├── mate-starters-contrib -- 8 个高级 Starter（按需引入）
│ ├── mate-seata-starter -- 分布式事务
│ ├── mate-sharding-starter -- ShardingSphere 分库分表
│ ├── mate-sentinel-starter -- Sentinel 限流降级
│ ├── mate-gray-starter -- 灰度发布
│ ├── mate-flow-starter -- 轻量工作流引擎
│ ├── mate-rule-starter -- Aviator 规则引擎
│ ├── mate-ai-starter -- Spring AI 2.0 + @Tool + MCP
│ └── mate-test-starter -- Testcontainers + @MateTest
├── mate-gateway -- API 网关 [9010]
├── mate-auth -- 认证服务 [9020]
├── mate-cli -- CLI 工具 + MCP Server
└── mate-biz
├── mate-system -- 系统管理（DDD 示范 + RBAC + 字典 + AI）[9030]
└── mate-notice -- 通知服务（短信/邮件适配器）[9050]- MateCloud 使用 5 层配置策略，服务的
application.yml只需约 15 行。 - 环境变量 → Nacos 服务级配置 → Nacos 共享配置 → classpath 默认值 → 服务入口文件，优先级从高到低。
- 默认数据库脚本通过 Flyway 自动迁移，业务表前缀
mate_；每服务独立版本线（flyway_history_<module>），详见 数据库迁移文档。 - 包名统一为
vip.mate.*，Starter 包名vip.mate.starter.*。 - 详细配置策略参见
docs/conventions/config-strategy.md。
mate-ai-starter 封装 Spring AI 2.0，提供三大能力：
@Tool自动发现 — 任何 Spring Bean 方法标注@Tool即可被 LLM 调用- 多提供商支持 — 一个环境变量切换 Anthropic / OpenAI / 智谱 / Minimax / DeepSeek / Ollama
- MCP Server 桥接 — Claude Code / Claude Desktop 可以直接调用集群中的
@Tool方法
@Component
@RequiredArgsConstructor
public class DictAiTools {
private final IDictQueryService dictQueryService;
@Tool(description = "List all dict entries for a given dictType.")
public List<DictData> listDictByType(
@ToolParam(description = "Dict type code, e.g. 'user_status'")
String dictType) {
return dictQueryService.findByType(dictType);
}
}# CLI 直接对话
java -jar mate-cli/target/mate-cli.jar ai chat "列出所有用户状态字典"
# 启动 MCP Server（集成 Claude Code）
java -jar mate-cli/target/mate-cli.jar --mcpmate new module mate-order --port 9060 # 新建业务模块（DDD 四层骨架）
mate new aggregate Order --module mate-order # 新建聚合
mate service list # Nacos 注册的服务
mate service health # 健康检查
mate config init # 初始化 Nacos 共享配置
mate gen code --table mate_order # 代码生成
mate ai chat "..." # AI 对话
mate --mcp # 启动 MCP ServerMateCloud 开源软件遵循 Apache 2.0 协议，允许商业使用，但务必保留类作者、Copyright 信息。
- 欢迎提交 PR，请基于
dev分支提交，详见 贡献指南。 - 欢迎提交 Issue，请写清楚问题现象、开发环境和复现步骤。
- 本项目遵循 Contributor Covenant 行为准则。
- 安全漏洞请参阅 安全策略 — 不要创建公开 Issue。