cc095ed2e9
完全重构项目主 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>
350 lines
11 KiB
Markdown
350 lines
11 KiB
Markdown
# 武术赛事管理系统 - 后端 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+
|
||
|
||
### 本地开发
|
||
|
||
```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（martial-ci.johnsion.club）
|
||
↓ [Runner 执行]
|
||
编译 BladeX 框架 → 编译后端项目 → 构建 Docker 镜像 → 部署容器 → 健康检查
|
||
↓
|
||
生产服务器部署完成（martial-api.johnsion.club）
|
||
```
|
||
|
||
### 部署流程
|
||
|
||
**日常开发（不触发部署）：**
|
||
|
||
```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. **构建 Docker 镜像**（约1分钟）
|
||
- 基于 eclipse-temurin:17-jre-alpine
|
||
- 复制 JAR 文件和配置
|
||
- 构建轻量化镜像
|
||
|
||
3. **部署到生产环境**（约30秒）
|
||
- 停止旧容器
|
||
- 启动新容器
|
||
- 连接数据库和 Redis
|
||
|
||
4. **健康检查**（约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：**
|
||
```yaml
|
||
SPRING_PROFILE: prod
|
||
JAVA_OPTS: "-Xms512m -Xmx1024m"
|
||
```
|
||
|
||
### 故障排查
|
||
|
||
**查看部署日志：**
|
||
```bash
|
||
# Drone 构建日志
|
||
访问: https://martial-ci.johnsion.club
|
||
|
||
# 应用日志
|
||
ssh root@154.30.6.21
|
||
docker logs -f martial-backend
|
||
```
|
||
|
||
**检查服务状态：**
|
||
```bash
|
||
# 查看容器状态
|
||
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)
|
||
|
||
## 📚 开发文档
|
||
|
||
- **[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
|