martial/martial-master
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: martial:a7c7da109bd1a7f744325bd84914c1647c3242cc
Branches Tags
martial:main martial:dev
...
compare: martial:4d13f9e38c1a880328d9c548ec3239f476a971c0
Branches Tags
martial:main martial:dev

3 Commits
a7c7da109b ... 4d13f9e38c

Author SHA1 Message Date
n72595987@gmail.com
4d13f9e38c docs: 完善文档内容，更新地址和路径信息
Some checks failed
continuous-integration/drone/push Build is failing
Details 
更新内容：

前后端架构说明.md：
- 更新项目状态说明，反映 martial-web 已存在
- 添加开发环境和生产环境架构对比图
- 添加详细的请求流程示例
- 更新访问地址为域名（生产环境）
- 更新开发方式说明，包含本地全栈开发
- 完善环境对比表，包含开发和生产地址
- 强调 martial-web 项目而非商业版 Saber

开发指南.md：
- 更新 SQL 脚本路径：doc/sql/ → database/

总体改进：
- 所有生产环境地址使用域名替代 IP:端口
- 反映当前项目的实际状态（前后端都已部署）
- 提供开发和生产两种环境的清晰对比
- 帮助开发者快速理解完整的系统架构

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-11-30 12:59:18 +08:00
n72595987@gmail.com
cc095ed2e9 docs: 重写项目根目录 README 
完全重构项目主 README 文件，提供更清晰的项目说明：

新增内容：
- 🌐 在线访问：所有域名地址集中展示
- 📦 技术栈：清晰列出所有技术组件
- 📁 项目结构：完整的目录树形结构说明
- 🚀 快速开始：本地开发环境搭建指南
- 🔄 自动化部署：详细的 CI/CD 流程说明
- 📚 开发文档：文档导航链接
- 🗄️ 数据库：连接信息和脚本位置
- 🔧 配置说明：环境配置和切换方法
- 🔐 安全配置：认证、授权、监控说明
- 📊 监控管理：所有管理界面地址
- 🤝 贡献指南：Git 提交规范
- 👥 开发团队：团队信息
- 📄 许可协议：完整的 BladeX 商业授权说明

地址更新：
- 所有 IP:端口 → 域名（https://martial-*.johnsion.club）
- 明确区分开发分支（dev）和生产分支（main）
- 补充 dev 分支工作流程说明

其他改进：
- 保留完整的 BladeX 商业授权条款
- 优化文档结构和排版
- 增加更多实用的运维命令

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-11-30 12:59:11 +08:00
n72595987@gmail.com
ef1d4d1942 docs: 更新文档中的访问地址为域名 
将 IP:端口形式的地址替换为域名：
- http://154.30.6.21:8123 → https://martial-api.johnsion.club
- http://154.30.6.21:8080 → https://martial-ci.johnsion.club
- http://154.30.6.21 → https://martial.johnsion.club
- http://localhost:8123/doc.html → https://martial-doc.johnsion.club

更新的文件：
- docs/README.md: 新人入门路径增加域名说明
- docs/CI-CD部署总结.md: 所有访问地址替换为域名，标记域名配置已完成

本地开发相关的 localhost 配置保持不变。

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-11-30 12:59:02 +08:00
5 changed files with 631 additions and 336 deletions
Expand all files Collapse all files

453
README.md
View File

@@ -1,220 +1,349 @@
## 版权声明
* BladeX是一个商业化软件，系列产品知识产权归**上海布雷德科技有限公司**独立所有
* 您一旦开始复制、下载、安装或者使用本产品，即被视为完全理解并接受本协议的各项条款
* 更多详情请看：[BladeX商业授权许可协议](https://license.bladex.cn)
# 武术赛事管理系统 - 后端 API
## 答疑流程
>1. 遇到问题或Bug
>2. 业务型问题打断点调试尝试找出问题所在
>3. 系统型问题通过百度、谷歌、社区查找解决方案
>4. 未解决问题则进入技术社区进行发帖提问：[https://sns.bladex.cn](https://sns.bladex.cn)
>5. 将帖子地址发至商业群，特别简单三言两语就能描述清楚的也可在答疑时间内发至商业群提问
>6. 发帖的时候一定要描述清楚，详细描述遇到问题的**重现步骤**、**报错详细信息**、**相关代码与逻辑**、**使用软件版本**以及**操作系统版本**，否则随意发帖提问将会提高我们的答疑难度。
基于 BladeX 4.0.1 企业级框架构建的武术比赛管理系统后端服务。
## 答疑时间
* 工作日：9:00 ~ 17:00 提供答疑，周末、节假日休息，暂停答疑
* 请勿**私聊提问**，以免被其他用户的消息覆盖从而无法获得答疑
* 答疑时间外遇到问题可以将问题发帖至[技术社区](https://sns.bladex.cn)，我们后续会逐个回复
## 🌐 在线访问
## 授权范围
* 专业版：只可用于**个人学习**及**个人私活**项目，不可用于公司或团队，不可泄露给任何第三方
* 企业版：可用于**企业名下**的任何项目，企业版员工在**未购买**专业版授权前，只授权开发**所在授权企业名下**的项目，**不得将BladeX用于个人私活**
* 共同遵守：若甲方需要您提供项目源码，则需代为甲方购买BladeX企业授权，甲方购买后续的所有项目都无需再次购买授权
- **生产环境 API**: https://martial-api.johnsion.club
- **API 文档**: https://martial-doc.johnsion.club
- **前端系统**: https://martial.johnsion.club
- **CI/CD 管理**: https://martial-ci.johnsion.club
## 商用权益
* ✔️ 遵守[商业协议](https://license.bladex.cn)的前提下，将BladeX系列产品用于授权范围内的商用项目，并上线运营
* ✔️ 遵守[商业协议](https://license.bladex.cn)的前提下，不限制项目数，不限制服务器数
* ✔️ 遵守[商业协议](https://license.bladex.cn)的前提下，将自行编写的业务代码申请软件著作权
## 📦 技术栈
## 何为侵权
* ❌ 不遵守商业协议，私自销售商业源码
* ❌ 以任何理由将BladeX源码用于申请软件著作权
* ❌ 将商业源码以任何途径任何理由泄露给未授权的单位或个人
* ❌ 开发完毕项目，没有为甲方购买企业授权，向甲方提供了BladeX代码
* ❌ 基于BladeX拓展研发与BladeX有竞争关系的衍生框架，并将其开源或销售
- **框架**: Spring Boot 3.2.4
- **语言**: Java 17
- **ORM**: MyBatis-Plus
- **数据库**: MySQL 8.0
- **缓存**: Redis 7
- **API 文档**: Knife4j (Swagger)
- **企业框架**: BladeX 4.0.1 RELEASE
## 侵权后果
* 情节较轻：第一次发现警告处理
* 情节较重：封禁账号，踢出商业群，并保留追究法律责任的权利
* 情节严重：与本地律师事务所合作，以公司名义起诉侵犯计算机软件著作权
## 📁 项目结构
## 举报有奖
* 向官方提供有用线索并成功捣毁盗版个人或窝点，将会看成果给予 500～10000 不等的现金奖励
* 官方唯一指定QQ：1272154962
```
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 # 项目完整说明
---
```
## 🚀 自动化部署
## 🚀 快速开始
### Drone CI/CD 自动部署配置
### 环境要求
- **JDK**: 17+
- **Maven**: 3.8+
- **MySQL**: 8.0+
- **Redis**: 6.0+
### 本地开发
```bash
# 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](./CLAUDE.md)
## 🔄 自动化部署
### CI/CD 架构
本项目已配置 Drone CI/CD 实现代码推送后的全自动编译、部署流程。
#### 📋 部署架构
```
开发者 Push 代码
↓
Gitea 仓库（git.waypeak.work）
↓ [Webhook 触发]
Drone CI Server（154.30.6.21:8080）
Drone CI Server（martial-ci.johnsion.club）
↓ [Runner 执行]
编译 BladeX 框架 → 编译后端项目 → SCP 传输 JAR → systemctl 重启服务 → 健康检查
编译 BladeX 框架 → 编译后端项目 → 构建 Docker 镜像 → 部署容器 → 健康检查
↓
生产服务器部署完成（154.30.6.21:8123）
生产服务器部署完成（martial-api.johnsion.club）
```
#### ⚙️ 部署配置
### 部署流程
**服务器信息：**
- Drone Server: http://154.30.6.21:8080
- 生产环境: 154.30.6.21:8123
- 部署方式: systemd 服务管理
**日常开发（不触发部署）：**
```bash
# 1. 切换到开发分支
git checkout dev
# 2. 修改代码并提交
git add .
git commit -m "feat: 添加新功能"
git push origin dev
# ✅ 推送到 dev 分支不会触发自动部署
```
**发布到生产环境：**
```bash
# 1. 合并开发分支到 main
git checkout main
git merge dev
# 2. 推送到 main 分支（自动触发部署）
git push origin main
# 3. 查看部署进度
# 访问 Drone UI: https://martial-ci.johnsion.club
# 或等待约 5-6 分钟后直接访问生产环境
```
### 部署步骤（全自动）
**部署步骤（全自动）：**
1. **编译完整项目**（约4-5分钟）
- 克隆 BladeX 框架代码（martial-tool）
- 编译框架并安装到 Maven 本地仓库
- 编译后端项目（martial-master）
- 生成 blade-api.jar（约236MB）
2. **传输构建产物**（约10-20秒）
- 使用 SCP 传输 JAR 文件到生产服务器
- 目标路径: `/app/martial-backend/bin/blade-api.jar`
2. **构建 Docker 镜像**（约1分钟）
- 基于 eclipse-temurin:17-jre-alpine
- 复制 JAR 文件和配置
- 构建轻量化镜像
3. **部署到生产环境**（约3秒）
- 执行 `systemctl restart martial-backend`
- systemd 自动管理进程生命周期
- 自动重启、日志管理、故障恢复
3. **部署到生产环境**（约30秒）
- 停止旧容器
- 启动新容器
- 连接数据库和 Redis
4. **健康检查**（约45秒）
- 等待 Spring Boot 应用完全启动
- 检查健康端点: `/actuator/health`
- 验证部署成功
**总耗时：** 约 5-6 分钟
**总耗时：** 约 6-7 分钟
#### 🔧 使用方法
**日常开发流程：**
```bash
# 1. 修改代码
vim src/main/java/...
# 2. 提交代码
git add .
git commit -m "你的提交信息"
# 3. 推送到 main 分支（自动触发部署）
git push origin main
# 4. 查看部署进度
# 访问 Drone UI: http://154.30.6.21:8080
# 或等待约 5-6 分钟后直接访问生产环境
```
### 访问地址
**部署完成后：**
- 访问后端 API: http://154.30.6.21:8123
- 查看 API 文档: http://154.30.6.21:8123/doc.html
- 健康检查: http://154.30.6.21:8123/actuator/health
- 后端 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
`.drone.yml` - Drone CI/CD 配置文件
```yaml
steps:
- name: 编译完整项目
image: maven:3.9-eclipse-temurin-17
commands:
- git clone https://git.waypeak.work/martial/martial-tool.git
- cd martial-tool && mvn clean install -DskipTests -q
- cd /drone/src && mvn clean package -DskipTests
- name: 传输构建产物
image: appleboy/drone-scp
settings:
host: 154.30.6.21
target: /app/martial-backend/bin/
- name: 部署到生产环境
image: appleboy/drone-ssh
settings:
script:
- systemctl restart martial-backend
- name: 健康检查
image: curlimages/curl:latest
commands:
- sleep 45
- curl -f http://154.30.6.21:8123/actuator/health
```
#### 🔐 Systemd 服务配置
服务名称: `martial-backend.service`
```bash
# 查看服务状态
systemctl status martial-backend
# 查看日志
journalctl -u martial-backend -f
# 手动重启
systemctl restart martial-backend
# 日志文件位置
/app/martial-backend/logs/application.log
/app/martial-backend/logs/error.log
```
#### 🛠️ 环境要求
### 部署配置
**生产服务器：**
- JDK 17 (通过 sdkman 管理)
- MySQL 8.0 (端口: 33066)
- Redis 7 (端口: 63379)
- systemd 服务管理
- MySQL 8.0 (Docker 容器)
- Redis 7 (Docker 容器)
- Docker Network: martial_martial-network
**CI/CD 服务器：**
- Drone Server + Drone Runner (Docker 部署)
- Maven 3.9 + Eclipse Temurin JDK 17 (CI 容器镜像)
**环境变量配置在 docker-compose.yml：**
```yaml
SPRING_PROFILE: prod
JAVA_OPTS: "-Xms512m -Xmx1024m"
```
#### ⚠️ 注意事项
### 故障排查
1. **仅 main 分支触发自动部署**
- 其他分支不会触发部署流程
- 开发分支请使用 feature/* 或 dev 分支
2. **部署失败排查**
**查看部署日志：**
```bash
# 查看 Drone 构建日志
访问: http://154.30.6.21:8080
# Drone 构建日志
访问: https://martial-ci.johnsion.club
# 查看应用日志
# 应用日志
ssh root@154.30.6.21
tail -f /app/martial-backend/logs/application.log
# 检查服务状态
systemctl status martial-backend
docker logs -f martial-backend
```
3. **手动回滚**
**检查服务状态：**
```bash
# 如需回滚到之前的版本
# 1. 找到之前成功的 JAR 文件备份
# 2. 替换当前 JAR
# 3. 重启服务
systemctl restart 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](./docs/CI-CD部署总结.md)
可通过 Drone UI 查看所有部署历史记录：
- 访问: http://154.30.6.21:8080
- 查看每次构建的详细日志
- 查看每个步骤的执行时间和状态
## 📚 开发文档
- **[CLAUDE.md](./CLAUDE.md)** - 项目完整说明、构建命令、技术栈
- **[docs/README.md](./docs/README.md)** - 文档索引和快速导航
- **[docs/架构说明.md](./docs/架构说明.md)** - BladeX 架构设计说明
- **[docs/前后端架构说明.md](./docs/前后端架构说明.md)** - 前后端分离架构
- **[docs/开发指南.md](./docs/开发指南.md)** - 开发规范和最佳实践
- **[docs/CI-CD部署总结.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 容器配置)
```
**环境切换：**
```bash
# 开发环境
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
## 🤝 贡献指南
1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'feat: Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 提交 Pull Request
**提交规范：**
```
feat: 新功能
fix: 修复 Bug
docs: 文档更新
style: 代码格式调整
refactor: 重构
perf: 性能优化
test: 测试相关
chore: 构建/工具配置
```
## 👥 开发团队
- **开发者**: JohnSion
- **AI 助手**: Claude Code
- **基础框架**: BladeX 4.0.1 (上海布雷德科技有限公司)
## 📄 许可协议
### BladeX 商业授权
本项目基于 **BladeX 商业框架** 构建，需遵守以下协议：
#### 版权声明
- BladeX 是一个商业化软件，系列产品知识产权归**上海布雷德科技有限公司**独立所有
- 您一旦开始复制、下载、安装或者使用本产品，即被视为完全理解并接受本协议的各项条款
- 更多详情请看：[BladeX商业授权许可协议](https://license.bladex.cn)
#### 授权范围
- **专业版**：只可用于**个人学习**及**个人私活**项目，不可用于公司或团队，不可泄露给任何第三方
- **企业版**：可用于**企业名下**的任何项目，企业版员工在**未购买**专业版授权前，只授权开发**所在授权企业名下**的项目，**不得将BladeX用于个人私活**
- **共同遵守**：若甲方需要您提供项目源码，则需代为甲方购买BladeX企业授权，甲方购买后续的所有项目都无需再次购买授权
#### 商用权益
- ✔️ 遵守[商业协议](https://license.bladex.cn)的前提下，将BladeX系列产品用于授权范围内的商用项目，并上线运营
- ✔️ 遵守[商业协议](https://license.bladex.cn)的前提下，不限制项目数，不限制服务器数
- ✔️ 遵守[商业协议](https://license.bladex.cn)的前提下，将自行编写的业务代码申请软件著作权
#### 何为侵权
- ❌ 不遵守商业协议，私自销售商业源码
- ❌ 以任何理由将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

34
docs/CI-CD部署总结.md
View File

@@ -4,8 +4,8 @@
### ✅ 已完成的工作
#### 1. Drone CI/CD 服务器部署（154.30.6.21）
- **Drone Server**: http://154.30.6.21:8080 ✅ 运行中
#### 1. Drone CI/CD 服务器部署
- **Drone Server**: https://martial-ci.johnsion.club ✅ 运行中
- **Drone Runner**: ✅ 已连接并轮询任务
- **管理员账号**: JohnSion ✅ 已创建
- **RPC Secret**: 55db397727eb7def59f3f588c0b503e0 ✅ 已配置
@@ -71,7 +71,7 @@ git push origin main
### 步骤2：在 Drone UI 中激活仓库 ⚠️ 需要你操作
1. 访问 http://154.30.6.21:8080
1. 访问 https://martial-ci.johnsion.club
2. 使用 Gitea 账号登录（JohnSion）
3. 授权 Drone 访问你的仓库
4. 在仓库列表中点击 **ACTIVATE**：
@@ -113,7 +113,7 @@ Drone CI 检测到代码变更
↓
5. 拉取最新镜像并重启容器
↓
6. 健康检查 (http://154.30.6.21:8123/actuator/health)
6. 健康检查 (https://martial-api.johnsion.club/actuator/health)
↓
✅ 部署成功
```
@@ -134,7 +134,7 @@ Drone CI 检测到代码变更
↓
5. 拉取最新镜像并重启容器
↓
6. 健康检查 (http://154.30.6.21/)
6. 健康检查 (https://martial.johnsion.club)
↓
✅ 部署成功
```
@@ -144,12 +144,12 @@ Drone CI 检测到代码变更
## 🌐 访问地址
### 部署后的应用
- **前端**: http://154.30.6.21
- **后端 API**: http://154.30.6.21:8123
- **API 文档**: http://154.30.6.21:8123/doc.html
- **前端**: https://martial.johnsion.club
- **后端 API**: https://martial-api.johnsion.club
- **API 文档**: https://martial-doc.johnsion.club
### CI/CD 管理
- **Drone UI**: http://154.30.6.21:8080
- **Drone UI**: https://martial-ci.johnsion.club
---
@@ -257,16 +257,13 @@ JAVA_OPTS: "-Xms512m -Xmx1024m"
1. ✅ **完成代码推送**（见上方步骤1）
2. ✅ **激活 Drone 仓库**（见上方步骤2）
3. ⭐ **配置域名**（可选）
- 前端: martial.waypeak.work → 154.30.6.21:80
- 后端: api.martial.waypeak.work → 154.30.6.21:8123
- CI/CD: drone.waypeak.work → 154.30.6.21:8080
3. ✅ **配置域名**（已完成）
- 前端: https://martial.johnsion.club
- 后端: https://martial-api.johnsion.club
- API 文档: https://martial-doc.johnsion.club
- CI/CD: https://martial-ci.johnsion.club
4. ⭐ **配置 HTTPS**（可选）
- 使用 Let's Encrypt 免费证书
- 在 Nginx 中配置 SSL
5. ⭐ **配置构建通知**（可选）
4. ⭐ **配置构建通知**（可选）
- 邮件通知
- 钉钉/企业微信通知
- Telegram 通知
@@ -275,4 +272,5 @@ JAVA_OPTS: "-Xms512m -Xmx1024m"
生成时间：2025-11-29
部署服务器：154.30.6.21
域名：*.johnsion.club
管理员：JohnSion

2
docs/README.md
View File

@@ -95,7 +95,7 @@
### 第一天：环境准备
1. 阅读 [CLAUDE.md](../CLAUDE.md) 了解项目概况
2. 配置开发环境（JDK、Maven、MySQL、Redis）
3. 启动项目，访问 http://localhost:8123/doc.html
3. 启动项目，访问 https://martial-doc.johnsion.club（生产环境）或 http://localhost:8123/doc.html（本地开发）
### 第二天：理解架构
1. 阅读 [前后端架构说明.md](./前后端架构说明.md) 了解完整系统

476
docs/前后端架构说明.md
View File

@@ -27,15 +27,25 @@ BladeX 完整架构
"The frontend is a separate Vue.js project (not in this repository)"
```
**当前您手上只有后端项目** `martial-master`，前端管理系统是独立的项目。
**当前您手上的项目包含**：
- 后端项目：`martial-master`（主业务 API）
- 前端项目：`martial-web`（Vue 3 管理系统，独立仓库）
两个项目均已部署到生产环境，并配置了自动化 CI/CD 部署流程。
---
## 二、前端管理系统 - Saber
## 二、前端管理系统
### 2.1 Saber 是什么？
### 2.1 当前项目前端：martial-web
**Saber** 是 BladeX 官方的 Vue 3 管理后台系统，提供可视化的管理界面。
**martial-web** 是本项目配套的 Vue 3 管理系统，基于 Element Plus 和 Avue 构建。
**项目信息**：
- 仓库位置：`/remote_dev/martial/martial-web`（独立仓库）
- 技术栈：Vue 3 + Vite + Element Plus + Avue
- 生产地址：https://martial.johnsion.club
- 开发端口：5173
**主要功能**：
- 🏠 **仪表盘**：数据统计、图表展示
@@ -45,54 +55,61 @@ BladeX 完整架构
- 📋 **系统管理**：字典管理、参数配置、日志查看
- 🗂️ **资源管理**：文件上传、OSS 配置
- ⚙️ **开发工具**：代码生成器、数据源管理
- 🥋 **业务功能**：武术比赛管理（根据菜单配置）
- 🥋 **业务功能**：武术比赛管理（核心业务）
### 2.2 Saber 技术栈
### 2.2 技术栈
```
前端框架：Vue 3
前端框架：Vue 3.4 (Composition API)
UI 组件：Element Plus
状态管理：Pinia
表单/表格：Avue
状态管理：Vuex 4
路由：Vue Router 4
构建工具：Vite
构建工具：Vite 5
HTTP 库：Axios
样式：Sass/SCSS
```
### 2.3 Saber 项目地址
### 2.3 访问地址
**官方仓库**（需要授权访问）：
**开发环境**：
- 本地开发：http://localhost:5173
- API 代理：通过 Vite proxy 转发到后端
**生产环境**：
- 前端地址：https://martial.johnsion.club
- API 代理：通过 Nginx 转发到后端
### 2.4 BladeX 官方前端 Saber（可选）
BladeX 框架还提供商业版本的官方前端 **Saber**（需要购买授权）：
**官方仓库**：
```
Gitee: https://gitee.com/smallc/Saber
GitHub: https://github.com/chillzhuang/Saber
```
**注意**：BladeX 是商业框架，完整源码需要购买授权。
### 2.4 Saber 运行端口
根据配置文件中的线索：
```yaml
# application-dev.yml
blade:
token:
domain: http://127.0.0.1:1888 # 前端地址
```
**默认端口**：`1888`（开发环境）
**与 martial-web 的关系**：
- martial-web：本项目自主开发的管理系统
- Saber：BladeX 官方提供的商业版管理系统
- 两者都可以对接 martial-master 后端，功能类似
---
## 三、前后端交互流程
### 3.1 开发环境架构
```
┌─────────────────────────────────────────────────────────────┐
│ 用户浏览器 │
└──────────────┬──────────────────────────────────────────────┘
│
│ http://localhost:1888
│ http://localhost:5173
▼
┌──────────────────────────────────────────────────────────────┐
│ Saber 前端 (Vue 3) │
│ martial-web 前端 (Vue 3 + Vite) │
│ - 登录页面 │
│ - 仪表盘 │
│ - 用户管理 │
@@ -100,10 +117,10 @@ blade:
│ - 武术比赛管理（调用后端 API） │
└──────────────┬───────────────────────────────────────────────┘
│
│ HTTP 请求（JSON）
│ POST /blade-auth/token
│ GET /blade-system/user/list
│ GET /api/martial/competition/list
│ Vite Dev Proxy
│ /api → http://localhost:8123/api
│ /blade-auth → http://localhost:8123/blade-auth
│ /blade-system → http://localhost:8123/blade-system
▼
┌──────────────────────────────────────────────────────────────┐
│ martial-master 后端 (Spring Boot) │
@@ -114,28 +131,183 @@ blade:
│ ├── /blade-desk/** → 仪表盘 │
│ ├── /blade-resource/** → 资源管理 │
│ ├── /blade-develop/** → 开发工具 │
│ └── /api/martial/** → 武术比赛（您的业务） │
│ └── /api/martial/** → 武术比赛（核心业务） │
└──────────────┬───────────────────────────────────────────────┘
│
▼
┌──────────────┐
│ MySQL │
│ Redis │
│ MySQL 33066 │
│ Redis 63379 │
└──────────────┘
```
### 3.2 生产环境架构
```
┌─────────────────────────────────────────────────────────────┐
│ 互联网用户 │
└──────────────┬──────────────────────────────────────────────┘
│
│ HTTPS (Cloudflare CDN)
▼
┌──────────────────────────────────────────────────────────────┐
│ Caddy 反向代理（80/443，自动 HTTPS） │
│ - martial.johnsion.club → localhost:5173 │
│ - martial-api.johnsion.club → localhost:8123 │
│ - martial-doc.johnsion.club → localhost:8123/doc.html │
│ - martial-ci.johnsion.club → localhost:8080 │
└────────┬─────────────────────────────┬───────────────────────┘
│ │
│ 前端请求 │ API 请求
▼ ▼
┌──────────────────────┐ ┌───────────────────────────────┐
│ martial-frontend │ │ martial-backend │
│ (Nginx 容器) │ │ (Spring Boot) │
│ 端口: 5173:80 │ │ 端口: 8123 │
│ │ │ │
│ 静态文件服务 │ │ ├── /blade-auth/** │
│ ├── index.html │ │ ├── /blade-system/** │
│ ├── assets/ │ │ ├── /blade-desk/** │
│ └── ... │ │ ├── /blade-resource/** │
│ │ │ ├── /blade-develop/** │
│ Nginx 反向代理 │ │ └── /api/martial/** │
│ └── /blade-auth/** │──────┘ │
│ /blade-system/**│ ┌───────────────────────────────┘
│ /api/** │──────┘
│ → 172.21.0.1:8123 │
└──────────────────────┘ │
│ │
└────────────┬──────────────────────┘
│
│ Docker Network: martial_martial-network
▼
┌──────────────┐
│ martial-mysql│ (端口: 3306)
│ martial-redis│ (端口: 6379)
└──────────────┘
```
### 3.3 请求流程示例
**用户登录流程**：
```
1. 用户访问 https://martial.johnsion.club
↓
2. Caddy 转发到 frontend 容器 (localhost:5173)
↓
3. Nginx 返回 Vue 应用 (index.html)
↓
4. 前端 JS 发起登录请求: POST /blade-auth/oauth/token
↓
5. Nginx 代理到后端: http://172.21.0.1:8123/blade-auth/oauth/token
↓
6. Spring Boot 认证模块处理登录
↓
7. 返回 Token 给前端
↓
8. 前端存储 Token，后续请求携带 Blade-Auth header
```
**业务数据请求流程**：
```
1. 前端请求比赛列表: GET /api/martial/competition/list
↓
2. Nginx 代理: http://172.21.0.1:8123/api/martial/competition/list
↓
3. Spring Boot martial 模块查询数据库
↓
4. 返回 JSON 数据
↓
5. 前端展示数据
```
---
## 四、当前项目的使用方式
## 四、项目访问方式
### 方式一：仅使用 API（当前可用）✅
### 方式一：生产环境在线访问 ✅
**适合场景**：
- 前端单独开发
- 移动端开发
- API 集成测试
- 直接使用已部署的完整系统
- 演示和测试
- 前端开发（对接生产 API）
**访问地址**：
```
前端系统：https://martial.johnsion.club
后端 API：https://martial-api.johnsion.club
API 文档：https://martial-doc.johnsion.club
CI/CD 平台：https://martial-ci.johnsion.club
```
**默认账号**：
```
用户名：admin
密码：admin
租户ID：000000
```
**优点**：
- ✅ 开箱即用，无需本地部署
- ✅ HTTPS 安全访问
- ✅ 完整的前后端功能
- ✅ 生产级别的性能
---
### 方式二：本地开发环境 ✅
**适合场景**：
- 后端功能开发
- API 调试和测试
- 前端本地开发
**启动后端**：
```bash
cd /remote_dev/martial/martial-master
mvn spring-boot:run
访问地址：
- API Server: http://localhost:8123
- Swagger 文档: http://localhost:8123/doc.html
- Druid 监控: http://localhost:8123/druid
```
**启动前端**：
```bash
cd /remote_dev/martial/martial-web
npm run dev
访问地址：
- 前端系统: http://localhost:5173
```
**优点**：
- ✅ 可以调试代码
- ✅ 快速开发迭代
- ✅ 修改即时生效
---
### 方式三：仅使用 API 文档测试
**适合场景**：
- 后端 API 测试
- 接口调试
- 了解 API 规范
**访问方式**：
**生产环境**：
```
Knife4j API 文档：https://martial-doc.johnsion.club
直接调用 API：
POST https://martial-api.johnsion.club/blade-auth/oauth/token
GET https://martial-api.johnsion.club/api/martial/competition/list
```
**本地环境**：
```
Knife4j API 文档：http://localhost:8123/doc.html
@@ -147,90 +319,32 @@ GET http://localhost:8123/api/martial/competition/list
**优点**：
- ✅ 无需前端，可以直接测试 API
- ✅ 适合后端开发和调试
- ✅ Swagger UI 提供可视化测试界面
**缺点**：
- ❌ 没有可视化界面
- ❌ 需要手动构造 HTTP 请求
- ❌ 没有完整的管理界面
- ❌ 需要手动构造请求参数
---
### 方式二：搭配 Saber 前端（需要获取源码）
### 方式四：使用第三方 API 工具
**步骤 1：获取 Saber 源码**
**适合场景**：
- 复杂 API 测试
- 批量接口测试
- 自动化测试
如果您有 BladeX 授权，可以从官方获取 Saber 源码：
```bash
# Gitee
git clone https://gitee.com/smallc/Saber.git
# GitHub
git clone https://github.com/chillzhuang/Saber.git
```
**步骤 2：配置后端地址**
```javascript
// Saber/src/config/website.js
export default {
// 后端 API 地址
apiUrl: 'http://localhost:8123',
// Token 存储键
tokenHeader: 'Blade-Auth',
// 其他配置...
}
```
**步骤 3：安装依赖并启动**
```bash
cd Saber
# 安装依赖
npm install
# 或
yarn install
# 启动开发服务器
npm run dev
# 或
yarn dev
```
**步骤 4：访问**
```
浏览器访问：http://localhost:1888
默认账号：
用户名：admin
密码：admin
```
**步骤 5：使用管理后台**
登录后，您可以在 Saber 管理后台中：
- 📊 查看仪表盘数据
- 👥 管理用户和角色
- 📋 配置菜单权限
- 🥋 使用武术比赛管理功能（需要先配置菜单）
---
### 方式三：使用第三方 API 工具（临时方案）
如果暂时没有 Saber 源码，可以使用：
**推荐工具**：
**Postman / Apifox / Insomnia**
```
1. 先调用登录接口获取 Token：
POST http://localhost:8123/blade-auth/token
POST https://martial-api.johnsion.club/blade-auth/oauth/token
Body: {
"tenantId": "000000",
"username": "admin",
"password": "admin",
"grant_type": "captcha",
"grant_type": "password",
"scope": "all"
}
@@ -240,25 +354,25 @@ yarn dev
Blade-Auth: bearer <access_token>
4. 调用业务接口：
GET http://localhost:8123/api/martial/competition/list
GET https://martial-api.johnsion.club/api/martial/competition/list
```
**VS Code REST Client 扩展**
```http
### 1. 登录获取 Token
POST http://localhost:8123/blade-auth/token
POST https://martial-api.johnsion.club/blade-auth/oauth/token
Content-Type: application/json
{
"tenantId": "000000",
"username": "admin",
"password": "admin",
"grant_type": "captcha",
"grant_type": "password",
"scope": "all"
}
### 2. 调用业务接口
GET http://localhost:8123/api/martial/competition/list
GET https://martial-api.johnsion.club/api/martial/competition/list
Blade-Auth: bearer {{token}}
```
@@ -371,62 +485,116 @@ BladeX 微服务架构
## 七、推荐的开发方式
### 当前阶段（无 Saber）
### 开发环境配置
```
1. 后端开发：
- 在 VS Code 中开发业务逻辑
- 使用 F5 调试运行
2. 接口测试：
- 使用 Knife4j：http://localhost:8123/doc.html
- 使用 Postman/Apifox
3. 数据库操作：
- 使用 Navicat/DBeaver 连接 MySQL
- 执行 SQL 查看数据
```
### 有 Saber 前端时
```
1. 启动后端：
cd martial-master
**本地全栈开发**：
```bash
# 终端 1: 启动后端
cd /remote_dev/martial/martial-master
mvn spring-boot:run
2. 启动前端：
cd Saber
# 终端 2: 启动前端
cd /remote_dev/martial/martial-web
npm run dev
3. 访问管理后台：
http://localhost:1888
# 访问
前端：http://localhost:5173
后端：http://localhost:8123
文档：http://localhost:8123/doc.html
```
4. 全栈开发：
- 后端改代码 → 前端调用 API
- 前端页面 → 调用后端接口
**仅后端开发**：
```bash
# 启动后端
cd /remote_dev/martial/martial-master
mvn spring-boot:run
# 使用以下方式测试
1. Knife4j 文档：http://localhost:8123/doc.html
2. Postman/Apifox
3. 对接生产前端：https://martial.johnsion.club（配置 API 代理到 localhost:8123）
```
**仅前端开发**：
```bash
# 启动前端
cd /remote_dev/martial/martial-web
npm run dev
# 对接生产后端
在 vite.config.js 中配置 proxy 指向：
https://martial-api.johnsion.club
```
### 数据库操作
**开发环境**：
```bash
# 使用 Navicat/DBeaver 连接
Host: 127.0.0.1
Port: 33066
Database: martial_db
Username: root
Password: WtcSecure901faf1ac4d32e2bPwd
```
**生产环境**（仅运维人员）：
```bash
# 通过 Docker 容器访问
ssh root@154.30.6.21
docker exec -it martial-mysql mysql -uroot -pWtcSecure901faf1ac4d32e2bPwd martial_db
```
---
## 八、总结
| 组件 | 状态 | 地址 | 说明 |
|------|------|------|------|
| **后端 API** | ✅ 有 | http://localhost:8123 | 当前项目 |
| **API 文档** | ✅ 有 | http://localhost:8123/doc.html | Knife4j |
| **Druid 监控** | ✅ 有 | http://localhost:8123/druid | 数据库监控 |
| **前端管理系统** | ❌ 无 | http://localhost:1888 | Saber（需单独获取） |
| **模块管理界面** | ❌ 无 | - | 单体应用，无需管理 |
### 环境对比表
**关键点**：
- ✅ 后端可以独立运行和开发
- ✅ 使用 Knife4j 可以完成所有测试
- ❌ 如需可视化管理界面，需要部署 Saber 前端
- ❌ 单体架构下没有"模块启动管理"的概念
| 组件 | 开发环境 | 生产环境 | 说明 |
|------|---------|----------|------|
| **后端 API** | http://localhost:8123 | https://martial-api.johnsion.club | Spring Boot 应用 |
| **API 文档** | http://localhost:8123/doc.html | https://martial-doc.johnsion.club | Knife4j 文档 |
| **Druid 监控** | http://localhost:8123/druid | https://martial-api.johnsion.club/druid | 数据库监控 |
| **前端系统** | http://localhost:5173 | https://martial.johnsion.club | Vue 3 管理系统 |
| **CI/CD 平台** | - | https://martial-ci.johnsion.club | Drone CI/CD |
| **MySQL** | 127.0.0.1:33066 | 容器内部 | 数据库 |
| **Redis** | 127.0.0.1:63379 | 容器内部 | 缓存 |
### 项目特点
**架构设计**：
- ✅ 前后端完全分离
- ✅ 后端提供 RESTful API
- ✅ 前端独立部署（可替换为任何技术栈）
- ✅ 单体应用，模块化设计
- ✅ 支持升级为微服务架构
**部署方式**：
- ✅ 生产环境自动化 CI/CD（Drone）
- ✅ Docker 容器化部署
- ✅ Caddy 自动 HTTPS
- ✅ 前后端独立扩展
**开发体验**：
- ✅ 本地开发无需依赖生产环境
- ✅ Vite 热更新，开发效率高
- ✅ Swagger 文档完整，接口调试方便
- ✅ 支持调试和日志查看
### 关键点
1. **前端系统已存在**：martial-web 项目（Vue 3），不是 Saber
2. **生产环境可用**：https://martial.johnsion.club 直接访问完整系统
3. **本地开发便捷**：后端 8123 端口，前端 5173 端口
4. **API 文档齐全**：Knife4j 提供完整的 API 测试界面
5. **自动化部署**：推送到 main 分支自动触发 CI/CD
---
**建议**：
1. 现阶段专注后端 API 开发
2. 使用 Knife4j 测试接口
3. 如需前端，可以自己用 Vue/React 开发，或等待获取 Saber 源码
**开发建议**：
1. 使用生产环境了解系统功能
2. 本地启动后端进行业务开发
3. 使用 Knife4j 文档测试接口
4. 前端对接本地或生产 API 均可
5. 开发完成后推送到 dev 分支，测试通过后合并到 main 触发自动部署

2
docs/开发指南.md
View File

@@ -60,7 +60,7 @@ src/main/java/org/springblade/modules/martial/
#### 步骤 1：创建数据库表
```sql
-- doc/sql/mysql/martial-competition-tables.sql
-- database/martial-db/新增表.sql
CREATE TABLE mt_judge_level (
id BIGINT PRIMARY KEY,
level_name VARCHAR(50) NOT NULL COMMENT '等级名称',