███╗ ███╗ ██████╗ ██████╗ ████████╗ ██╗ ███████╗ ███████╗ ████╗ ████║ ██╔═══██╗ ██╔══██╗ ╚══██╔══╝ ██║ ██╔════╝ ██╔════╝ ██╔████╔██║ ██║ ██║ ██████╔╝ ██║ ██║ ███████╗ █████╗ ██║╚██╔╝██║ ██║ ██║ ██╔══██╗ ██║ ██║ ╚════██║ ██╔══╝ ██║ ╚═╝ ██║ ╚██████╔╝ ██║ ██║ ██║ ██║ ███████║ ███████╗ ╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚══════╝ ╚══════╝
现代化企业级后台管理脚手架
Mortise 是一款现代化、模块化的企业级后台管理脚手架项目，基于 Spring Boot 3.5.6 构建。采用多模块单体架构设计，集成了完整的认证授权、监控、缓存等企业级功能，开箱即用。
- 🏗️ 模块化设计 - 清晰的模块划分，低耦合高内聚
- 🚀 开箱即用 - Docker Compose 一键启动完整环境
- 🔒 安全可靠 - Spring Security 6 + JWT 双重保障
- 📊 可观测性 - 集成 Prometheus + Grafana 监控体系
- ⚡ 高性能 - MyBatis-Flex + Redis 缓存优化
- 🛡️ 生产就绪 - 限流、熔断、配置加密等企业级特性
💡 提示: 截图即将上线，敬请期待...
| 指标 | 数值 | 说明 |
|---|---|---|
| 🚀 启动时间 | < 10s | 应用冷启动到就绪 |
| 📦 内存占用 | ~300MB | 空闲状态 JVM 内存 |
| 🔥 QPS | 1000+ | 单机并发处理能力 |
| ⚡ 响应时间 | < 50ms | 平均 API 响应时间 |
| 💾 数据库连接池 | 10-20 | HikariCP 默认配置 |
| 🔴 Redis 命中率 | > 90% | 缓存命中率 |
📝 注: 以上数据基于 4C8G 服务器，实际性能因环境而异。
后端核心
- Spring Boot 3.5.6 - 主框架
- Spring Security 6 - 安全认证框架
- JWT (JJWT 0.12.5) - 无状态 Token 认证
- MyBatis-Flex 1.11.0 - 轻量级 ORM 框架
- Redis 6.0+ - 缓存与会话存储
- PostgreSQL 17 - 主数据库（推荐）/ MySQL 8.0+
监控与运维
- Spring Boot Actuator - 应用健康监控
- Prometheus - 时序数据库与指标收集
- Grafana - 可视化监控面板
- HikariCP - 高性能数据库连接池
安全与限流
- Resilience4j 2.2.0 - 限流、熔断、重试
- Jasypt 3.0.5 - 配置文件加密
- Apache Commons - 工具库集合（Lang3, IO, Codec, Collections4）
开发工具
- SpringDoc OpenAPI - API 文档自动生成
- Lombok - 简化 Java 代码
- ULID Creator - 分布式唯一 ID 生成器
核心业务模块
- 用户管理 - 用户注册、登录、个人信息管理、密码修改
- 角色管理 - 角色定义、权限分配、角色层级
- 菜单管理 - 动态菜单加载、多级菜单支持、权限控制
- 权限管理 - 基于角色的访问控制（RBAC）、细粒度权限控制
- 字典管理 - 系统字典配置、字典缓存优化
安全与认证
- JWT 认证 - 无状态 Token 认证、自动续期、Token 刷新
- Spring Security 集成 - 统一认证授权、方法级权限控制
- 配置加密 - Jasypt 敏感配置加密存储
缓存与性能
- 多级缓存 - 统一缓存抽象、Redis 实现、缓存过期策略
- SPI 架构 - 缓存接口可扩展、支持自定义实现
- 缓存预热 - 应用启动时自动加载热点数据
监控与运维
- Actuator 集成 - 健康检查、应用指标、端点管理
- Prometheus 集成 - 指标导出、自定义指标
- Grafana 可视化 - 实时监控面板、告警配置
- 数据库监控 - HikariCP 连接池监控、慢查询分析
限流与保护
- Resilience4j 限流 - 基于令牌桶的限流
- 熔断降级 - 自动故障恢复、服务保护
开发体验
- 模块化架构 - 清晰的模块划分（10+ 模块）
- 详细文档 - 50+ 技术文档、最佳实践指南
- Docker 支持 - 一键启动开发环境
- 操作日志 - 完整的审计日志、操作追踪
- 文件管理 - 对象存储集成、文件上传下载
- API 文档 - SpringDoc OpenAPI 3 集成
- 通知系统 - 站内信、邮件、短信通知
- 工作流引擎 - Flowable 集成
- 多租户支持 - 租户隔离、数据隔离
- 分布式事务 - Seata 集成
- 消息队列 - RocketMQ/Kafka 集成
- 全文搜索 - Elasticsearch 集成
- 定时任务 - XXL-Job 集成
- 微服务化 - Spring Cloud 改造方案
| 组件 | 版本要求 | 推荐版本 |
|---|---|---|
| Java | 21+ | Eclipse Temurin 21 |
| Maven | 3.6.0+ | 3.9.x |
| 数据库 | PostgreSQL 12+ / MySQL 8.0+ | PostgreSQL 17 |
| Redis | 6.0+ | 7.x |
| IDE | - | IntelliJ IDEA 2023+ |
| Git | 2.0+ | 最新版本 |
| 组件 | 版本要求 |
|---|---|
| Docker | 20.10+ |
| Docker Compose | 2.0+ |
最低配置
- CPU: 2 核心
- 内存: 4 GB
- 磁盘: 10 GB 可用空间
推荐配置
- CPU: 4 核心以上
- 内存: 8 GB 以上
- 磁盘: 20 GB 可用空间（包含 Docker 镜像）
- ✅ Windows 10/11
- ✅ macOS 11+
- ✅ Linux (Ubuntu 20.04+, CentOS 7+, Debian 10+)
适合快速体验和开发环境，一键启动包含数据库、Redis、Nginx 等完整服务。
# HTTPS
git clone https://github.com/rymcu/mortise.git
cd mortise
# SSH
git clone [email protected]:rymcu/mortise.git
cd mortise# Windows (以管理员身份运行 PowerShell)
.\update_hosts.bat
# macOS/Linux
sudo ./update_hosts.sh添加的域名映射：
127.0.0.1 rymcu.local
127.0.0.1 npm.rymcu.local
127.0.0.1 auth.rymcu.local
127.0.0.1 logto.rymcu.local
# 启动服务（首次启动会下载镜像，需要几分钟）
docker-compose up -d
# 查看启动日志
docker-compose logs -f
# 检查服务状态
docker-compose ps| 服务 | 地址 | 说明 |
|---|---|---|
| 🌐 应用主页 | http://localhost:9999 | 主应用服务 |
| 📊 Actuator | http://localhost:9999/mortise/actuator | 监控端点 |
| 🗄️ PostgreSQL | localhost:5432 | 数据库（用户: mortise, 密码: mortise） |
| 🔴 Redis | localhost:6379 | 缓存服务 |
| 🌐 Nginx | http://localhost:80 | 反向代理 |
# 停止服务
docker-compose stop
# 停止并删除容器
docker-compose down
# 停止并删除容器、网络、卷
docker-compose down -v适合日常开发调试，需要手动配置环境。
# 检查 Java 版本（需要 21+）
java -version
# 检查 Maven 版本（需要 3.6+）
mvn -version
# 检查 PostgreSQL（需要安装并启动）
psql --version
# 检查 Redis（需要安装并启动）
redis-cli --version-- 连接 PostgreSQL
psql -U postgres
-- 创建数据库
CREATE DATABASE mortise;
-- 创建用户
CREATE USER mortise WITH PASSWORD 'your_password';
-- 授权
GRANT ALL PRIVILEGES ON DATABASE mortise TO mortise;
-- 退出
\q# Windows (需要先安装 Redis)
redis-server
# macOS
brew services start redis
# Linux
sudo systemctl start redis
# 或
redis-server编辑配置文件 mortise-app/src/main/resources/application-dev.yml：
spring:
datasource:
url: jdbc:postgresql://localhost:5432/mortise
username: mortise
password: your_password
data:
redis:
host: localhost
port: 6379
# password: your_redis_password # 如有密码# 清理并编译
mvn clean install -DskipTests
# 或只编译
mvn clean package -DskipTests# 方式 1: 使用 Maven 启动
cd mortise-app
mvn spring-boot:run
# 方式 2: 使用 jar 包启动
java -jar mortise-app/target/mortise-app-0.0.1.jar
# 方式 3: 指定配置文件启动
java -jar mortise-app/target/mortise-app-0.0.1.jar --spring.profiles.active=dev# 健康检查（需要先登录获取 Token）
curl http://localhost:9999/mortise/actuator/health
# 或在浏览器访问
http://localhost:9999/mortise/actuator在 IDE 中启动：
- 导入项目到 IntelliJ IDEA
- 找到
MortiseApplication.java - 右键 → Run 'MortiseApplication'
- 开启 IDEA 的 Build Project Automatically 实现热重载
适合生产环境部署。
# 生产环境打包
mvn clean package -Pprod -DskipTests
# 生成的 jar 包位置
ls -lh mortise-app/target/mortise-app-0.0.1.jar# 构建镜像
docker build -t mortise:latest .
# 运行容器
docker run -d \
--name mortise-app \
-p 9999:9999 \
-e SPRING_PROFILES_ACTIVE=prod \
-e SPRING_DATASOURCE_URL=jdbc:postgresql://db-host:5432/mortise \
-e SPRING_DATASOURCE_USERNAME=mortise \
-e SPRING_DATASOURCE_PASSWORD=your_password \
-e SPRING_DATA_REDIS_HOST=redis-host \
mortise:latest
# 查看日志
docker logs -f mortise-app创建服务文件 /etc/systemd/system/mortise.service：
[Unit]
Description=Mortise Application
After=network.target
[Service]
Type=simple
User=mortise
WorkingDirectory=/opt/mortise
ExecStart=/usr/bin/java -jar /opt/mortise/mortise-app.jar
Restart=on-failure
RestartSec=10
[Install]
WantedBy=multi-user.target启动服务：
# 重载配置
sudo systemctl daemon-reload
# 启动服务
sudo systemctl start mortise
# 开机自启
sudo systemctl enable mortise
# 查看状态
sudo systemctl status mortise启动失败：数据库连接错误
问题: Connection refused 或 Authentication failed
解决:
- 检查数据库是否启动：
psql -U postgres - 检查用户名密码是否正确
- 检查数据库是否已创建：
\l查看数据库列表 - 检查防火墙是否开放 5432 端口
启动失败：Redis 连接错误
问题: Could not connect to Redis
解决:
- 检查 Redis 是否启动：
redis-cli ping（应返回 PONG） - 检查配置文件中的 Redis 地址和端口
- 如果有密码，确保配置了正确的密码
Docker 启动慢
问题: docker-compose up 长时间无响应
解决:
- 首次启动需要下载镜像，耐心等待
- 使用国内镜像加速器
- 查看具体日志：
docker-compose logs -f
端口被占用
问题: Port 9999 is already in use
解决:
- 修改
application.yml中的端口号 - 或停止占用端口的进程：
- Windows:
netstat -ano | findstr 9999 - Linux/Mac:
lsof -i :9999
- Windows:
应用启动后，可通过以下方式访问监控端点：
# PowerShell
$response = Invoke-RestMethod -Uri "http://localhost:9999/mortise/api/v1/auth/login" `
-Method Post `
-ContentType "application/json" `
-Body '{"account":"your_account","password":"your_password"}'
$token = $response.data.token
# Bash/cURL
curl -X POST http://localhost:9999/mortise/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"account":"your_account","password":"your_password"}'# PowerShell
Invoke-RestMethod -Uri "http://localhost:9999/mortise/actuator/health" `
-Headers @{ Authorization = "Bearer $token" }
# Bash/cURL
curl -H "Authorization: Bearer <token>" \
http://localhost:9999/mortise/actuator/health| 端点 | 描述 | URL | 认证 |
|---|---|---|---|
| 🏥 健康检查 | 应用整体健康状态、组件状态 | /mortise/actuator/health |
✅ |
| ℹ️ 应用信息 | 版本、环境、构建信息 | /mortise/actuator/info |
✅ |
| 📈 性能指标 | JVM、系统、应用指标 | /mortise/actuator/metrics |
✅ |
| 📊 Prometheus | Prometheus 格式指标导出 | /mortise/actuator/prometheus |
✅ |
| 📝 端点列表 | 所有可用 Actuator 端点 | /mortise/actuator |
✅ |
| 🗃️ 数据库 | 数据库连接池状态 | /mortise/actuator/metrics/hikaricp.* |
✅ |
| 🔧 配置属性 | 应用配置信息 | /mortise/actuator/configprops |
✅ |
| 🌿 环境变量 | 系统环境和配置 | /mortise/actuator/env |
✅ |
💡 提示: 所有端点都需要 JWT Token 认证
# prometheus.yml
global:
scrape_interval: 15s
evaluation_interval: 15s
scrape_configs:
- job_name: 'mortise-application'
metrics_path: '/mortise/actuator/prometheus'
static_configs:
- targets: ['localhost:9999']
# JWT 认证配置
bearer_token: 'your_jwt_token'
# 或使用文件
# bearer_token_file: '/path/to/token.txt'JVM 指标
jvm_memory_used_bytes{area="heap"} # 堆内存使用量
jvm_memory_max_bytes{area="heap"} # 堆内存最大值
jvm_gc_pause_seconds_sum # GC 总耗时
jvm_threads_live_threads # 活跃线程数
数据库连接池
hikaricp_connections_active # 活跃连接数
hikaricp_connections_idle # 空闲连接数
hikaricp_connections_pending # 等待连接数
hikaricp_connections_timeout_total # 连接超时次数
HTTP 请求
http_server_requests_seconds_count # 请求总数
http_server_requests_seconds_sum # 请求总耗时
http_server_requests_seconds_max # 最大响应时间
系统指标
system_cpu_usage # 系统 CPU 使用率
process_cpu_usage # 进程 CPU 使用率
system_load_average_1m # 系统负载
- Spring Boot 2.1 Statistics (Dashboard ID: 6756)
- JVM (Micrometer) (Dashboard ID: 4701)
- Spring Boot APM Dashboard (Dashboard ID: 12900)
导入方式：Grafana → Dashboards → Import → 输入 Dashboard ID
# 清理编译
mvn clean install
# 跳过测试编译
mvn clean install -DskipTests
# 运行测试
mvn test
# 打包应用
mvn package
# 运行应用
mvn spring-boot:run
# 查看依赖树
mvn dependency:tree
# 更新依赖
mvn versions:display-dependency-updates# 启动所有服务
docker-compose up -d
# 查看日志
docker-compose logs -f [service_name]
# 停止服务
docker-compose stop
# 重启服务
docker-compose restart [service_name]
# 删除容器和网络
docker-compose down
# 删除容器、网络和卷
docker-compose down -v
# 重新构建镜像
docker-compose build --no-cache
# 查看服务状态
docker-compose ps# 克隆项目
git clone https://github.com/rymcu/mortise.git
# 创建功能分支
git checkout -b feature/your-feature
# 提交更改
git add .
git commit -m "feat: your feature description"
# 推送到远程
git push origin feature/your-feature
# 同步上游
git fetch upstream
git rebase upstream/master# 连接 Redis
redis-cli
# 查看所有键
KEYS *
# 查看键值
GET key_name
# 删除键
DEL key_name
# 清空数据库
FLUSHDB
# 查看内存使用
INFO memory# 连接数据库
psql -U mortise -d mortise
# 查看所有表
\dt
# 查看表结构
\d table_name
# 执行 SQL 文件
\i path/to/file.sql
# 导出数据库
pg_dump -U mortise mortise > backup.sql
# 导入数据库
psql -U mortise mortise < backup.sql项目包含 50+ 份详细技术文档，位于 docs/ 目录。
- 项目架构优化 - 整体架构设计
- 模块依赖与 SPI 架构 - 模块化设计原则
- 架构重构计划 - 重构路线图
查看完整文档列表：docs/MIGRATION_INDEX.md
mortise/
├── mortise-common/ # 公共模块 - 通用工具类、异常定义
├── mortise-core/ # 核心模块 - 基础配置、结果封装
├── mortise-cache/ # 缓存模块 - 缓存抽象与 Redis 实现
├── mortise-auth/ # 认证模块 - JWT、Spring Security 集成
├── mortise-web/ # Web 模块 - 全局异常、拦截器
├── mortise-system/ # 系统模块 - 用户、角色、菜单管理
├── mortise-log/ # 日志模块 - 操作日志、审计日志
├── mortise-monitor/ # 监控模块 - Actuator、指标自定义
├── mortise-notification/ # 通知模块 - 消息通知服务
└── mortise-app/ # 应用模块 - 启动类、配置整合
🎯 SPI 架构设计
- 缓存接口抽象，支持多种实现（Redis、本地缓存）
- Jackson 序列化器可扩展
- 监控指标自定义接口
🔄 缓存过期策略
- 统一过期时间管理
- Redis 键空间通知监听
- 自动缓存刷新机制
📊 可观测性
- 自定义 Actuator 端点
- Prometheus 指标导出
- HikariCP 连接池监控
- 应用性能指标收集
🛡️ 安全保障
- JWT Token 认证
- Spring Security 方法级权限
- Jasypt 配置加密
- Resilience4j 限流保护
我们欢迎并感谢任何形式的贡献！
- 在 GitHub Issues 创建 Issue
- 清晰描述问题、重现步骤、期望行为
- 提供错误日志、截图等相关信息
- 在 GitHub Discussions 发起讨论
- 说明功能的使用场景和价值
- 提供参考实现或设计思路
-
Fork 项目
# Fork 后克隆到本地 git clone https://github.com/YOUR_USERNAME/mortise.git cd mortise
-
创建功能分支
git checkout -b feature/amazing-feature # 或修复分支 git checkout -b fix/bug-description -
编写代码
- 遵循项目代码规范
- 添加必要的注释和文档
- 编写单元测试
-
提交变更
git add . git commit -m 'feat: add amazing feature' # 使用 Conventional Commits 规范
-
同步上游代码
git remote add upstream https://github.com/rymcu/mortise.git git fetch upstream git rebase upstream/master
-
推送到 GitHub
git push origin feature/amazing-feature
-
创建 Pull Request
- 访问 GitHub 仓库页面
- 点击 "New Pull Request"
- 填写 PR 描述、关联 Issue
- 等待代码审查
代码风格
- 遵循 阿里巴巴 Java 开发手册
- 使用 IDE 格式化工具（提供配置文件）
- 类、方法添加 Javadoc 注释
提交信息规范
使用 Conventional Commits 格式：
<type>(<scope>): <subject>
<body>
<footer>
Type 类型：
feat: 新功能fix: Bug 修复docs: 文档变更style: 代码格式（不影响功能）refactor: 重构（不增加功能不修复 Bug）perf: 性能优化test: 测试相关chore: 构建工具、依赖管理
示例：
feat(auth): add password encryption support
- Implement BCrypt password encoder
- Add password strength validation
- Update user registration flow
Closes #123测试要求
- 新功能必须包含单元测试
- 测试覆盖率不低于 70%
- 确保所有测试通过
文档要求
- 新功能需要更新相关文档
- API 变更需要更新接口文档
- 重要变更需要在 CHANGELOG.md 记录
所有 Pull Request 都需要经过代码审查：
- 至少 1 位维护者审批
- 通过所有 CI 检查
- 解决所有审查意见
- 保持提交历史清晰
| 渠道 | 用途 | 响应时间 |
|---|---|---|
| 📖 技术文档 | 查阅详细文档 | 即时 |
| 🐛 GitHub Issues | Bug 报告、问题追踪 | 1-3 天 |
| 💡 GitHub Discussions | 功能建议、技术讨论 | 3-7 天 |
| 商务合作、私密问题 | 7 天内 |
- 官方网站: https://rymcu.com
- 在线演示: 即将上线
- API 文档: 开发中
- 视频教程: 计划中
Q: 支持哪些数据库？
A: 目前支持 PostgreSQL（推荐）和 MySQL。推荐使用 PostgreSQL 17，性能和功能更完善。
Q: 可以用于商业项目吗？
A: 可以。本项目基于 MIT 协议，可免费用于商业项目。
Q: 如何升级 Spring Boot 版本？
A: 修改 pom.xml 中的 spring-boot-starter-parent 版本，然后执行 mvn clean install 测试兼容性。
Q: 监控端点需要认证吗？
A: 是的。所有 Actuator 端点都需要 JWT Token 认证，确保生产环境安全。
Q: 如何自定义缓存实现？
A: 实现 CacheService 接口，通过 SPI 机制注册自定义实现。参考 缓存过期 SPI 指南。
| 版本 | 发布日期 | 主要更新 |
|---|---|---|
| v0.0.1 | 2024-09-24 | 🎉 首次发布：核心功能、基础架构 |
v0.0.1 (✅ 已完成)
├─ 用户、角色、菜单管理
├─ JWT 认证授权
├─ Redis 缓存集成
├─ Actuator 监控
└─ 基础文档
v0.2.0 (🚧 开发中 - 预计 Q1 2025)
├─ 操作日志完善
├─ 文件上传管理
├─ API 文档集成
├─ 监控告警优化
└─ 性能优化
v0.3.0 (📋 计划中 - 预计 Q2 2025)
├─ 通知系统
├─ 工作流引擎
├─ 多租户支持
├─ 前端管理界面
└─ 单元测试覆盖
v1.0.0 (🎯 目标 - 预计 Q3 2025)
├─ 生产就绪认证
├─ 完整测试覆盖
├─ 性能基准测试
├─ 安全加固
└─ 详尽使用手册
v2.0.0 (💡 展望)
├─ 微服务架构
├─ 消息队列集成
├─ 分布式事务
├─ 全文搜索
└─ 大数据分析
本项目基于 MIT License 开源协议。
MIT License
Copyright (c) 2024 RYMCU
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction...
✅ 商业使用
✅ 修改
✅ 分发
✅ 私人使用
感谢所有为本项目做出贡献的开发者：
本项目基于以下优秀的开源项目构建：
- Spring Boot - 应用框架
- Spring Security - 安全框架
- MyBatis-Flex - ORM 框架
- Redis - 缓存数据库
- PostgreSQL - 关系型数据库
- Resilience4j - 容错库
- Prometheus - 监控系统
- Grafana - 可视化平台
- 感谢 JetBrains 提供的开源许可证
- 感谢所有提供反馈和建议的用户
| 资源 | 链接 | 描述 |
|---|---|---|
| 🏠 项目主页 | GitHub | 源代码仓库 |
| 📖 文档中心 | Docs | 完整技术文档 |
| 🐛 问题追踪 | Issues | Bug 报告与功能请求 |
| 💬 讨论区 | Discussions | 技术讨论与交流 |
| 📝 变更日志 | Releases | 版本发布记录 |
| 👥 贡献者 | Contributors | 项目贡献者列表 |
| 📊 代码统计 | Insights | 项目活跃度统计 |