Matrix Nebula DevOps指令大全

📋 目录

概述
快速开始
任务分组
分支管理
版本管理
发布管理
构建管理
使用场景
常见问题
最佳实践

🎯 概述

Matrix Nebula 构建扩展为项目提供了强大的版本管理、分支管理和构建管理功能，包含10个核心构建指令，采用层次化任务分组结构：

matrix/branch: 分支管理
matrix/version: 语义化版本管理
matrix/release: 预发布版本管理
matrix: 构建管理

🚀 快速开始

前置条件

Java 21+
Gradle 6.0+
Git 2.0+
项目已初始化为 Git 仓库

查看所有可用任务

bash

# 查看分支管理任务
./gradlew tasks --group=matrix/branch

# 查看版本管理任务
./gradlew tasks --group=matrix/version

# 查看发布管理任务
./gradlew tasks --group=matrix/release

# 查看构建管理任务
./gradlew tasks --group=matrix

📂 任务分组

采用层次化分组结构，所有任务都归属于 matrix 父组下的子组：

Matrix/branch 组 - 分支管理

任务名称	描述	参数
`createBranch`	创建新的 Git 分支	`branchName`(必需), `baseBranch`(可选)

Matrix/version 组 - 版本管理

任务名称	描述	版本变化
`tagMajor`	递增主版本号	1.2.3 → 2.0.0
`tagMinor`	递增次版本号	1.2.3 → 1.3.0
`tagPatch`	递增修订版本号	1.2.3 → 1.2.4

Matrix/release 组 - 发布管理

任务名称	描述	版本格式	用途
`tagAlpha`	创建 Alpha 版本	x.y.z-alpha.n	内测版本
`tagBeta`	创建 Beta 版本	x.y.z-beta.n	公测版本
`tagRelease`	创建 Release 版本	x.y.z-release	稳定版本
`tagLts`	创建 LTS 版本	x.y.z-lts	长期支持版本

Matrix 组 - 构建管理

任务名称	描述	输出文件
`buildWar`	构建 WAR 包	build/libs/*.war
`buildExecutableJar`	构建可执行 JAR 包	build/libs/*.jar
`initDB`	初始化数据库架构和基础数据	数据库表结构
`integrateFrontend`	集成前端静态资源到后端项目	src/main/resources/static/*

🌿 分支管理

createBranch - 创建新分支

基本用法:

bash

./gradlew createBranch -PbranchName=feature/user-authentication

从指定分支创建:

bash

./gradlew createBranch -PbranchName=hotfix/critical-bug -PbaseBranch=main

使用场景:

功能开发分支

bash

./gradlew createBranch -PbranchName=feature/payment-integration
./gradlew createBranch -PbranchName=feature/user-dashboard

修复分支

bash

./gradlew createBranch -PbranchName=hotfix/security-patch -PbaseBranch=main
./gradlew createBranch -PbranchName=bugfix/login-issue

发布分支

bash

./gradlew createBranch -PbranchName=release/v2.0.0 -PbaseBranch=develop

分支命名规范:

feature/: 新功能开发
hotfix/: 紧急修复
bugfix/: 一般问题修复
release/: 发布准备
docs/: 文档更新

🏷️ 版本管理

语义化版本控制

遵循 Semantic Versioning 规范：MAJOR.MINOR.PATCH

tagMajor - 主版本递增

用法:

bash

./gradlew tagMajor

示例:

当前版本: 1.2.3
新版本: 2.0.0

适用场景:

不兼容的 API 变更
重大架构调整
破坏性功能更新

tagMinor - 次版本递增

用法:

bash

./gradlew tagMinor

示例:

当前版本: 1.2.3
新版本: 1.3.0

适用场景:

向下兼容的新功能
新增 API 接口
功能增强

tagPatch - 修订版本递增

用法:

bash

./gradlew tagPatch

示例:

当前版本: 1.2.3
新版本: 1.2.4

适用场景:

Bug 修复
安全补丁
性能优化

🚀 发布管理

tagAlpha - Alpha 内测版本

用法:

bash

./gradlew tagAlpha

版本格式: x.y.z-alpha.n

示例:

基础版本: 1.2.0
Alpha 版本: 1.2.0-alpha.1, 1.2.0-alpha.2, ...

tagBeta - Beta 公测版本

用法:

bash

./gradlew tagBeta

版本格式: x.y.z-beta.n

示例:

基础版本: 1.2.0
Beta 版本: 1.2.0-beta.1, 1.2.0-beta.2, ...

tagRelease - Release 稳定版本

用法:

bash

./gradlew tagRelease

版本格式: x.y.z-release

示例:

基础版本: 1.2.0
Release 版本: 1.2.0-release

tagLts - LTS 长期支持版本

用法:

bash

./gradlew tagLts

版本格式: x.y.z-lts

示例:

基础版本: 1.2.0
LTS 版本: 1.2.0-lts

📦 构建管理

buildWar - 构建 WAR 包（含前端集成）

构建用于Web服务器部署的WAR包，支持自动集成前端资源。

基本用法:

bash

# 仅构建后端WAR包
./gradlew buildWar

# 构建包含前端的WAR包
./gradlew buildWar -PfrontendPath=../matrix-vben

输出信息:

🎉 WAR Build Completed Successfully!
✓ Package name: matrix-nebula-1.1.0.war
✓ File location: /path/to/project/build/libs/matrix-nebula-1.1.0.war
✓ Package size: 45.67 MB
✓ Frontend integrated: Yes
✓ Frontend source: ../matrix-vben

📋 Deployment Instructions:
1. Copy matrix-nebula-1.1.0.war to your web server
2. Deploy to Tomcat webapps directory
3. Start/restart Tomcat server

使用场景:

部署到 Tomcat、Jetty 等 Web 容器
传统 Java Web 应用部署
企业级应用服务器部署
前后端一体化部署

部署示例:

bash

# 复制到 Tomcat webapps 目录
cp build/libs/matrix-nebula-1.1.0.war /opt/tomcat/webapps/

# 重命名为 ROOT.war（根路径部署）
cp build/libs/matrix-nebula-1.1.0.war /opt/tomcat/webapps/ROOT.war

buildExecutableJar - 构建可执行 JAR 包（含前端集成）

构建包含所有依赖的可执行JAR包，支持自动集成前端资源。

基本用法:

bash

# 仅构建后端JAR包
./gradlew buildExecutableJar

# 构建包含前端的JAR包
./gradlew buildExecutableJar -PfrontendPath=../matrix-vben

输出信息:

🎉 Executable JAR Build Completed Successfully!
✓ Package name: matrix-nebula-1.1.0.jar
✓ File location: /path/to/project/build/libs/matrix-nebula-1.1.0.jar
✓ Package size: 52.34 MB
✓ Frontend integrated: Yes
✓ Frontend source: ../matrix-vben

📋 Run Instructions:
java -jar matrix-nebula-1.1.0.jar

📋 Optional JVM Arguments:
java -Xmx2g -Dspring.profiles.active=prod -jar matrix-nebula-1.1.0.jar

使用场景:

Spring Boot 应用部署
微服务容器化部署
独立运行的 Java 应用
Docker 镜像构建
前后端一体化部署

运行可执行 JAR:

bash

# 基本运行
java -jar build/libs/matrix-nebula-1.1.0.jar

# 指定配置文件
java -jar build/libs/matrix-nebula-1.1.0.jar --spring.config.location=application-prod.yml

# 指定端口和环境
java -jar build/libs/matrix-nebula-1.1.0.jar --server.port=8080 --spring.profiles.active=prod

# 设置 JVM 参数
java -Xmx2g -Xms1g -jar build/libs/matrix-nebula-1.1.0.jar

Docker 部署示例:

dockerfile

FROM openjdk:21-jre-slim

COPY build/libs/matrix-nebula-1.1.0.jar app.jar

EXPOSE 8080

ENTRYPOINT ["java", "-jar", "/app.jar"]

buildAll - 构建所有包（含前端集成）

同时构建WAR和可执行JAR包，支持自动集成前端资源。

基本用法:

bash

# 构建所有后端包
./gradlew buildAll

# 构建包含前端的所有包
./gradlew buildAll -PfrontendPath=../matrix-vben

输出信息:

🎉 All Build Tasks Completed Successfully!
✓ WAR package: Ready for web server deployment
✓ JAR package: Ready for standalone execution
✓ Frontend integration: Completed

执行过程:

如果指定了 frontendPath，自动执行前端集成
构建WAR包
构建可执行JAR包
显示构建完成摘要

使用场景:

一次性构建多种部署格式
CI/CD 流程中的批量构建
发布前的完整构建验证
多环境部署准备

部署建议:

WAR包部署:

适用于Tomcat、Jetty等Web服务器
将WAR包复制到webapps目录
启动/重启Web服务器

JAR包部署:

适用于独立运行环境
直接使用java -jar命令运行
支持JVM参数调优

生产环境运行示例:

bash

# 基本运行
java -jar matrix-nebula-1.0.0.jar

# 生产环境运行（推荐）
java -Xmx2g -Dspring.profiles.active=prod -jar matrix-nebula-1.0.0.jar

initDB - 数据库初始化

基本用法:

bash

./gradlew initDB

功能说明:

自动连接到 MariaDB 数据库
执行 ddl/matrix.sql 文件中的 SQL 脚本
创建数据库表结构和基础数据
支持事务回滚，确保数据一致性

输出信息:

✓ Executing SQL file: matrix.sql
✓ Database initialization completed successfully

使用场景:

项目首次部署时初始化数据库
开发环境重置数据库结构
测试环境准备基础数据
CI/CD 流程中的数据库准备

配置说明:

数据库连接: localhost:2025
用户名: root
密码: Matrix.Develop.2025
字符集: utf8mb4

注意事项:

确保 MariaDB 服务已启动
确保 ddl/matrix.sql 文件存在
执行前请备份重要数据

integrateFrontend - 前端静态资源集成

基本用法:

bash

./gradlew integrateFrontend -PfrontendPath=matrix-vben

使用绝对路径:

bash

./gradlew integrateFrontend -PfrontendPath=D:\Projects\matrix-vben

功能说明:

自动清理之前集成的静态资源
从指定前端项目的 apps/web-antd/dist 目录复制构建产物
复制到后端项目的 src/main/resources/static 目录
支持绝对路径和相对路径（相对于后端项目的父目录）
显示详细的集成统计信息和目录结构

输出信息:

🧹 Cleaning previous frontend integration...
📦 Integrating frontend resources...
✅ Frontend integration completed successfully!
📁 Frontend source: D:\Matrix\1_nebula\matrix-vben\apps\web-antd\dist
📁 Backend target: D:\Matrix\1_nebula\matrix-nebula\src\main
esources\static
📊 Files copied: 127
📊 Total size: 2.45 MB

📋 Integration Summary:
├── Static Resources Structure:
│   ├── 📁 assets/
│   │   ├── 📄 index-BwvkvsJ-.js (1.23 MB)
│   │   ├── 📄 index-DiwrgTda.css (245.67 KB)
│   │   └── 📁 images/
│   ├── 📄 index.html (2.34 KB)
│   └── 📄 favicon.ico (4.18 KB)
└── Integration completed at 2024-12-14 15:30:45

使用场景:

前后端分离项目的静态资源托管
单体应用部署时集成前端资源
开发环境快速集成测试
CI/CD 流程中的自动化集成

前置条件:

前端项目已构建完成（存在 apps/web-antd/dist 目录）
前端项目路径正确且可访问
后端项目具有写入权限

路径解析规则:

绝对路径: 直接使用指定的完整路径

相对路径: 相对于后端项目的父目录解析

后端项目: D:\Matrix\1_nebula\matrix-nebula
相对路径: matrix-vben
解析结果: D:\Matrix\1_nebula\matrix-vben

集成示例:

bash

# 1. 构建前端项目
cd ../matrix-vben
npm run build

# 2. 返回后端项目并集成
cd ../matrix-nebula
./gradlew integrateFrontend -PfrontendPath=matrix-vben

# 3. 启动后端服务验证
./gradlew bootRun

错误处理:

如果前端目录不存在，会显示详细错误信息
如果 dist 目录不存在，会提示先构建前端项目
集成过程中的任何错误都会中断操作并回滚

🎯 使用场景

场景1: 新功能开发流程

bash

# 1. 创建功能分支
./gradlew createBranch -PbranchName=feature/user-management

# 2. 开发完成后，创建 Alpha 版本进行内测
./gradlew tagAlpha

# 3. 内测通过后，创建 Beta 版本进行公测
./gradlew tagBeta

# 4. 公测通过后，递增次版本号发布正式版本
./gradlew tagMinor

# 5. 构建部署包
./gradlew buildExecutableJar

场景2: 紧急修复流程

bash

# 1. 从主分支创建修复分支
./gradlew createBranch -PbranchName=hotfix/security-fix -PbaseBranch=main

# 2. 修复完成后，递增修订版本号
./gradlew tagPatch

# 3. 构建部署包
./gradlew buildWar

场景3: 长期支持版本发布

bash

# 1. 创建 LTS 版本
./gradlew tagLts

# 2. 构建多种格式的部署包
./gradlew buildWar
./gradlew buildExecutableJar

场景4: 持续集成/持续部署 (CI/CD)

bash

# Jenkins/GitLab CI 脚本示例
./gradlew clean
./gradlew test
./gradlew tagMinor
./gradlew buildExecutableJar

# 部署到生产环境
docker build -t myapp:$(git describe --tags --abbrev=0) .
docker push myapp:$(git describe --tags --abbrev=0)

场景5: 前端集成开发流程

bash

# 1. 开发前端功能
cd ../matrix-vben
npm run dev

# 2. 前端开发完成后构建
npm run build

# 3. 集成到后端项目
cd ../matrix-nebula
./gradlew integrateFrontend -PfrontendPath=matrix-vben

# 4. 构建完整应用
./gradlew buildExecutableJar

# 5. 启动验证
java -jar build/libs/matrix-nebula-*.jar

场景6: 生产环境部署准备

bash

# 1. 确保前端是生产构建
cd ../matrix-vben
npm run build:prod

# 2. 集成前端资源
cd ../matrix-nebula
./gradlew integrateFrontend -PfrontendPath=matrix-vben

# 3. 创建发布版本
./gradlew tagRelease

# 4. 构建生产包
./gradlew buildWar buildExecutableJar

# 5. 验证集成结果
ls -la src/main/resources/static/

❓ 常见问题

Q1: 如何查看当前项目的版本？

bash

git tag --sort=-version:refname | head -1

Q2: 标签创建失败怎么办？

可能原因:

标签已存在
不是 Git 仓库
没有提交记录

解决方案:

bash

# 检查是否为 Git 仓库
git status

# 查看现有标签
git tag

# 删除错误的标签（如果需要）
git tag -d <tag-name>
git push origin --delete <tag-name>

Q3: 如何自定义版本号？

当前版本是自动基于最新标签递增的。如需自定义版本号，可以手动创建标签：

bash

git tag -a 2.0.0 -m "Custom version 2.0.0"
git push origin 2.0.0

Q4: 构建失败怎么办？

WAR 构建失败:

确保项目应用了 war 插件
检查 build.gradle 中的 WAR 配置

JAR 构建失败:

确保项目应用了 org.springframework.boot 插件
检查 Spring Boot 配置

Q5: 标签推送到远程仓库失败？

常见推送失败原因:

没有配置 Git 认证信息
没有推送权限
网络连接问题
远程仓库不存在

解决方案:

bash

# 1. 检查远程仓库配置
git remote -v

# 2. 配置认证信息（如果需要）
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# 3. 手动推送标签
git push origin --tags

Q6: 如何查看特定任务组的帮助？

bash

# 查看特定任务的帮助信息
./gradlew help --task createBranch
./gradlew help --task tagMajor
./gradlew help --task buildWar

# 查看任务组的所有任务
./gradlew tasks --group=matrix/branch
./gradlew tasks --group=matrix/version
./gradlew tasks --group=matrix/release
./gradlew tasks --group=matrix

Q7: 前端集成失败怎么办？

常见集成失败原因:

前端项目未构建或 dist 目录不存在
路径配置错误
权限不足无法写入 static 目录
前端项目路径包含特殊字符

解决方案:

bash

# 1. 检查前端项目是否已构建
ls ../matrix-vben/apps/web-antd/dist

# 2. 手动构建前端项目
cd ../matrix-vben && npm run build

# 3. 检查路径是否正确
./gradlew integrateFrontend -PfrontendPath=../matrix-vben

# 4. 使用绝对路径
./gradlew integrateFrontend -PfrontendPath=D:\Matrix\1_nebula\matrix-vben

Q8: 如何验证前端集成是否成功？

bash

# 1. 检查静态资源目录
ls -la src/main/resources/static/

# 2. 启动应用验证
./gradlew bootRun

# 3. 访问前端页面
# 浏览器访问: http://localhost:8080

Q9: 集成后如何清理静态资源？

bash

# 删除静态资源目录
rm -rf src/main/resources/static/*

# 或者重新集成（会自动清理）
./gradlew integrateFrontend -PfrontendPath=matrix-vben

Q10: 支持哪些前端框架？

支持所有生成静态文件的前端框架:

Vue.js (Vite/Webpack)
React (Create React App/Vite)
Angular
Svelte
纯静态 HTML/CSS/JS

要求:

构建产物位于 apps/web-antd/dist 目录
包含 index.html 作为入口文件

💡 最佳实践

1. 版本号管理

主版本 (Major): 用于不兼容的重大变更
次版本 (Minor): 用于向下兼容的新功能
修订版本 (Patch): 用于向下兼容的问题修正

2. 分支管理

bash

# 功能分支
feature/feature-name

# 修复分支
hotfix/issue-description
bugfix/bug-description

# 发布分支
release/version-number

3. 发布流程

开发阶段: 使用 Alpha 版本进行内部测试
测试阶段: 使用 Beta 版本进行公开测试
发布阶段: 使用正式版本号发布
长期支持: 对重要版本创建 LTS 标签

4. 构建策略

开发环境: 使用 buildExecutableJar 快速部署
生产环境: 根据部署方式选择 WAR 或 JAR
容器化部署: 优先使用 buildExecutableJar
传统部署: 使用 buildWar 部署到应用服务器

5. 自动化建议

bash

# 在 CI/CD 管道中使用
./gradlew clean test tagMinor buildExecutableJar

# 定期创建 LTS 版本
./gradlew tagLts

# 构建多格式包用于不同部署场景
./gradlew buildWar buildExecutableJar

6. 前端集成最佳实践

开发环境: 使用相对路径便于团队协作

bash

./gradlew integrateFrontend -PfrontendPath=matrix-vben

生产环境: 使用绝对路径确保路径准确

bash

./gradlew integrateFrontend -PfrontendPath=/opt/frontend/matrix-vben

版本同步: 前后端版本保持一致

bash

# 前端构建
cd ../matrix-vben && npm run build:prod
# 后端集成和版本标记
cd ../matrix-nebula && ./gradlew integrateFrontend -PfrontendPath=matrix-vben tagMinor

自动化集成: 在构建脚本中组合使用

bash

# 完整的构建和集成流程
./gradlew clean integrateFrontend -PfrontendPath=matrix-vben buildExecutableJar

7. 部署策略建议

单体部署: 集成前端后构建 JAR 包
容器化部署: 在 Dockerfile 中集成前端资源
微服务架构: 考虑使用独立的静态资源服务
CDN 部署: 生产环境可考虑将静态资源部署到 CDN

📞 技术支持

如有问题或建议，请联系开发团队或提交 Issue。

版本: v1.2.0
更新日期: 2025年9月
维护团队: Matrix Nebula Development Team

Matrix Nebula DevOps指令大全 ​

📋 目录 ​

🎯 概述 ​

🚀 快速开始 ​

前置条件 ​

查看所有可用任务 ​

📂 任务分组 ​

Matrix/branch 组 - 分支管理 ​

Matrix/version 组 - 版本管理 ​

Matrix/release 组 - 发布管理 ​

Matrix 组 - 构建管理 ​

🌿 分支管理 ​

createBranch - 创建新分支 ​

🏷️ 版本管理 ​

语义化版本控制 ​

tagMajor - 主版本递增 ​

tagMinor - 次版本递增 ​

tagPatch - 修订版本递增 ​

🚀 发布管理 ​

tagAlpha - Alpha 内测版本 ​

tagBeta - Beta 公测版本 ​

tagRelease - Release 稳定版本 ​

tagLts - LTS 长期支持版本 ​

📦 构建管理 ​

buildWar - 构建 WAR 包（含前端集成） ​

buildExecutableJar - 构建可执行 JAR 包（含前端集成） ​

buildAll - 构建所有包（含前端集成） ​

initDB - 数据库初始化 ​

integrateFrontend - 前端静态资源集成 ​

🎯 使用场景 ​

场景1: 新功能开发流程 ​

场景2: 紧急修复流程 ​

场景3: 长期支持版本发布 ​

场景4: 持续集成/持续部署 (CI/CD) ​

场景5: 前端集成开发流程 ​

场景6: 生产环境部署准备 ​

❓ 常见问题 ​

Q1: 如何查看当前项目的版本？ ​

Q2: 标签创建失败怎么办？ ​

Q3: 如何自定义版本号？ ​

Q4: 构建失败怎么办？ ​

Q5: 标签推送到远程仓库失败？ ​

Q6: 如何查看特定任务组的帮助？ ​

Q7: 前端集成失败怎么办？ ​

Q8: 如何验证前端集成是否成功？ ​

Q9: 集成后如何清理静态资源？ ​

Q10: 支持哪些前端框架？ ​

💡 最佳实践 ​

1. 版本号管理 ​

2. 分支管理 ​

3. 发布流程 ​

4. 构建策略 ​

5. 自动化建议 ​

6. 前端集成最佳实践 ​

7. 部署策略建议 ​

📞 技术支持 ​

Matrix Nebula DevOps指令大全

📋 目录

🎯 概述

🚀 快速开始

前置条件

查看所有可用任务

📂 任务分组

Matrix/branch 组 - 分支管理

Matrix/version 组 - 版本管理

Matrix/release 组 - 发布管理

Matrix 组 - 构建管理

🌿 分支管理

createBranch - 创建新分支

🏷️ 版本管理

语义化版本控制

tagMajor - 主版本递增

tagMinor - 次版本递增

tagPatch - 修订版本递增

🚀 发布管理

tagAlpha - Alpha 内测版本

tagBeta - Beta 公测版本

tagRelease - Release 稳定版本

tagLts - LTS 长期支持版本

📦 构建管理

buildWar - 构建 WAR 包（含前端集成）

buildExecutableJar - 构建可执行 JAR 包（含前端集成）

buildAll - 构建所有包（含前端集成）

initDB - 数据库初始化

integrateFrontend - 前端静态资源集成

🎯 使用场景

场景1: 新功能开发流程

场景2: 紧急修复流程

场景3: 长期支持版本发布

场景4: 持续集成/持续部署 (CI/CD)

场景5: 前端集成开发流程

场景6: 生产环境部署准备

❓ 常见问题

Q1: 如何查看当前项目的版本？

Q2: 标签创建失败怎么办？

Q3: 如何自定义版本号？

Q4: 构建失败怎么办？

Q5: 标签推送到远程仓库失败？

Q6: 如何查看特定任务组的帮助？

Q7: 前端集成失败怎么办？

Q8: 如何验证前端集成是否成功？

Q9: 集成后如何清理静态资源？

Q10: 支持哪些前端框架？

💡 最佳实践

1. 版本号管理

2. 分支管理

3. 发布流程

4. 构建策略

5. 自动化建议

6. 前端集成最佳实践

7. 部署策略建议

📞 技术支持