宅房
fdd346b27f
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
武术赛事管理系统 - 后端 API
基于 BladeX 4.0.1 企业级框架构建的武术比赛管理系统后端服务。
🌐 在线访问
- 生产环境 API: https://martial-api.johnsion.club
- API 文档: https://martial-doc.johnsion.club
- 前端系统: https://martial.johnsion.club
- CI/CD 管理: https://martial-ci.johnsion.club
📦 技术栈
- 框架: Spring Boot 3.2.4
- 语言: Java 17
- ORM: MyBatis-Plus
- 数据库: MySQL 8.0
- 缓存: Redis 7
- API 文档: Knife4j (Swagger)
- 企业框架: BladeX 4.0.1 RELEASE
📁 项目结构
martial-master/
├── src/main/java/org/springblade/
│ ├── Application.java # 主启动类
│ ├── common/ # 公共工具和配置
│ ├── modules/ # 业务模块
│ │ ├── auth/ # 认证授权
│ │ ├── system/ # 系统管理
│ │ ├── resource/ # 资源管理
│ │ ├── desk/ # 工作台
│ │ ├── develop/ # 代码生成
│ │ └── martial/ # ⭐ 武术比赛业务（核心）
│ └── job/ # 定时任务
├── src/main/resources/
│ ├── application.yml # 主配置
│ ├── application-dev.yml # 开发环境
│ ├── application-test.yml # 测试环境
│ └── application-prod.yml # 生产环境
├── database/ # 数据库脚本
│ ├── bladex/ # BladeX 框架表
│ ├── flowable/ # 工作流表
│ ├── martial-db/ # 武术业务表
│ └── upgrade/ # 升级脚本
├── docs/ # 项目文档
│ ├── README.md # 文档索引
│ ├── 架构说明.md # 架构设计
│ ├── 前后端架构说明.md # 前后端交互
│ ├── 开发指南.md # 开发规范
│ └── CI-CD部署总结.md # 部署文档
├── scripts/ # 运维脚本
│ ├── docker/ # Docker 部署
│ └── fatjar/ # JAR 启动脚本
├── .drone.yml # CI/CD 配置
├── Dockerfile # Docker 镜像构建
└── CLAUDE.md # 项目完整说明
🚀 快速开始
环境要求
- JDK: 17+
- Maven: 3.8+
- MySQL: 8.0+
- Redis: 6.0+
本地开发
# 1. 克隆项目
git clone https://git.waypeak.work/martial/martial-master.git
cd martial-master
# 2. 编译 BladeX 框架（首次必须）
cd /path/to/martial-tool
mvn clean install -DskipTests
# 3. 编译并运行
cd /path/to/martial-master
mvn clean package -DskipTests -Dmaven.test.skip=true
mvn spring-boot:run
# 4. 访问应用
# API: http://localhost:8123
# 文档: http://localhost:8123/doc.html
详细说明请参考：CLAUDE.md
🔄 自动化部署
CI/CD 架构
本项目已配置 Drone CI/CD 实现代码推送后的全自动编译、部署流程。
开发者 Push 代码
↓
Gitea 仓库（git.waypeak.work）
↓ [Webhook 触发]
Drone CI Server（martial-ci.johnsion.club）
↓ [Runner 执行]
编译 BladeX 框架 → 编译后端项目 → 构建 Docker 镜像 → 部署容器 → 健康检查
↓
生产服务器部署完成（martial-api.johnsion.club）
部署流程
日常开发（不触发部署）：
# 1. 切换到开发分支
git checkout dev
# 2. 修改代码并提交
git add .
git commit -m "feat: 添加新功能"
git push origin dev
# ✅ 推送到 dev 分支不会触发自动部署
发布到生产环境：
# 1. 合并开发分支到 main
git checkout main
git merge dev
# 2. 推送到 main 分支（自动触发部署）
git push origin main
# 3. 查看部署进度
# 访问 Drone UI: https://martial-ci.johnsion.club
# 或等待约 5-6 分钟后直接访问生产环境
部署步骤（全自动）
-
编译完整项目（约4-5分钟）
- 克隆 BladeX 框架代码（martial-tool）
- 编译框架并安装到 Maven 本地仓库
- 编译后端项目（martial-master）
- 生成 blade-api.jar（约236MB）
-
构建 Docker 镜像（约1分钟）
- 基于 eclipse-temurin:17-jre-alpine
- 复制 JAR 文件和配置
- 构建轻量化镜像
-
部署到生产环境（约30秒）
- 停止旧容器
- 启动新容器
- 连接数据库和 Redis
-
健康检查（约45秒）
- 等待 Spring Boot 应用完全启动
- 检查健康端点:
/actuator/health - 验证部署成功
总耗时： 约 6-7 分钟
访问地址
部署完成后：
- 后端 API: https://martial-api.johnsion.club
- API 文档: https://martial-doc.johnsion.club
- 健康检查: https://martial-api.johnsion.club/actuator/health
- 前端系统: https://martial.johnsion.club
CI/CD 管理：
- Drone UI: https://martial-ci.johnsion.club
部署配置
生产服务器：
- MySQL 8.0 (Docker 容器)
- Redis 7 (Docker 容器)
- Docker Network: martial_martial-network
环境变量配置在 docker-compose.yml：
SPRING_PROFILE: prod
JAVA_OPTS: "-Xms512m -Xmx1024m"
故障排查
查看部署日志：
# Drone 构建日志
访问: https://martial-ci.johnsion.club
# 应用日志
ssh root@154.30.6.21
docker logs -f martial-backend
检查服务状态：
# 查看容器状态
docker ps | grep martial
# 查看健康状态
curl https://martial-api.johnsion.club/actuator/health
# 重启服务
cd /app/martial && docker-compose restart backend
详细部署文档请参考：docs/CI-CD部署总结.md
📚 开发文档
- CLAUDE.md - 项目完整说明、构建命令、技术栈
- docs/README.md - 文档索引和快速导航
- docs/架构说明.md - BladeX 架构设计说明
- docs/前后端架构说明.md - 前后端分离架构
- docs/开发指南.md - 开发规范和最佳实践
- docs/CI-CD部署总结.md - CI/CD 配置和运维
🗄️ 数据库
连接信息（生产环境）：
- Host: 容器内使用
martial-mysql - Port: 3306
- Database: martial_db
- Username: root
- Password: WtcSecure901faf1ac4d32e2bPwd
数据库脚本：
- BladeX 框架表:
database/bladex/bladex.mysql.all.create.sql - Flowable 工作流表:
database/flowable/flowable.mysql.all.create.sql - 武术业务表:
database/martial-db/martial_db.sql
🔧 配置说明
配置文件优先级：
application.yml (基础配置)
↓
application-{profile}.yml (环境配置)
↓
环境变量 (Docker 容器配置)
环境切换：
# 开发环境
mvn spring-boot:run -Dspring-boot.run.profiles=dev
# 测试环境
java -jar blade-api.jar --spring.profiles.active=test
# 生产环境（Docker）
SPRING_PROFILE=prod
🔐 安全配置
- Token 认证: 无状态 Token 机制
- 多租户隔离: 基于 tenant_id 的数据隔离
- 权限控制: RBAC 角色权限体系
- SQL 监控: Druid 数据库连接池监控
- API 文档: 生产环境可配置访问控制
📊 监控和管理
- API 文档: https://martial-doc.johnsion.club
- Druid 监控: https://martial-api.johnsion.club/druid
- 用户名: blade
- 密码: 1qaz@WSX
- 健康检查: https://martial-api.johnsion.club/actuator/health
- CI/CD 管理: https://martial-ci.johnsion.club
🤝 贡献指南
- Fork 本仓库
- 创建特性分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'feat: Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 提交 Pull Request
提交规范：
feat: 新功能
fix: 修复 Bug
docs: 文档更新
style: 代码格式调整
refactor: 重构
perf: 性能优化
test: 测试相关
chore: 构建/工具配置
👥 开发团队
- 开发者: JohnSion
- AI 助手: Claude Code
- 基础框架: BladeX 4.0.1 (上海布雷德科技有限公司)
📄 许可协议
BladeX 商业授权
本项目基于 BladeX 商业框架 构建，需遵守以下协议：
版权声明
- BladeX 是一个商业化软件，系列产品知识产权归上海布雷德科技有限公司独立所有
- 您一旦开始复制、下载、安装或者使用本产品，即被视为完全理解并接受本协议的各项条款
- 更多详情请看：BladeX商业授权许可协议
授权范围
- 专业版：只可用于个人学习及个人私活项目，不可用于公司或团队，不可泄露给任何第三方
- 企业版：可用于企业名下的任何项目，企业版员工在未购买专业版授权前，只授权开发所在授权企业名下的项目，不得将BladeX用于个人私活
- 共同遵守：若甲方需要您提供项目源码，则需代为甲方购买BladeX企业授权，甲方购买后续的所有项目都无需再次购买授权
商用权益
- ✔️ 遵守商业协议的前提下，将BladeX系列产品用于授权范围内的商用项目，并上线运营
- ✔️ 遵守商业协议的前提下，不限制项目数，不限制服务器数
- ✔️ 遵守商业协议的前提下，将自行编写的业务代码申请软件著作权
何为侵权
- ❌ 不遵守商业协议，私自销售商业源码
- ❌ 以任何理由将BladeX源码用于申请软件著作权
- ❌ 将商业源码以任何途径任何理由泄露给未授权的单位或个人
- ❌ 开发完毕项目，没有为甲方购买企业授权，向甲方提供了BladeX代码
- ❌ 基于BladeX拓展研发与BladeX有竞争关系的衍生框架，并将其开源或销售
侵权后果
- 情节较轻：第一次发现警告处理
- 情节较重：封禁账号，踢出商业群，并保留追究法律责任的权利
- 情节严重：与本地律师事务所合作，以公司名义起诉侵犯计算机软件著作权
技术支持
- 答疑时间: 工作日 9:00 ~ 17:00，周末、节假日休息
- 技术社区: https://sns.bladex.cn
- 官方QQ: 1272154962
最后更新: 2025-11-30 项目版本: 4.0.1 RELEASE 部署环境: Docker + Drone CI/CD