docs: 更新README,简化内容并更新域名配置
This commit is contained in:
405
README.md
405
README.md
@@ -2,349 +2,130 @@
|
|||||||
|
|
||||||
基于 BladeX 4.0.1 企业级框架构建的武术比赛管理系统后端服务。
|
基于 BladeX 4.0.1 企业级框架构建的武术比赛管理系统后端服务。
|
||||||
|
|
||||||
## 🌐 在线访问
|
## 在线访问
|
||||||
|
|
||||||
- **生产环境 API**: https://martial-api.johnsion.club
|
| 服务 | 地址 | 说明 |
|
||||||
- **API 文档**: https://martial-doc.johnsion.club
|
|------|------|------|
|
||||||
- **前端系统**: https://martial.johnsion.club
|
| 后端 API | https://martial-api.aitisai.com | Spring Boot 服务 |
|
||||||
- **CI/CD 管理**: https://martial-ci.johnsion.club
|
| 管理后台 | https://martial-admin.aitisai.com | Web 管理端 |
|
||||||
|
| 用户端 | https://martial.aitisai.com | 报名小程序 H5 |
|
||||||
|
| 裁判端 | https://martial-mini.aitisai.com | 裁判评分小程序 |
|
||||||
|
| OSS 存储 | https://martial-oss.aitisai.com | MinIO 对象存储 |
|
||||||
|
| MinIO 控制台 | https://martial-minio.aitisai.com | MinIO 管理界面 |
|
||||||
|
|
||||||
## 📦 技术栈
|
## 技术栈
|
||||||
|
|
||||||
- **框架**: Spring Boot 3.2.4
|
- **框架**: Spring Boot 3.2.4 + BladeX 4.0.1
|
||||||
- **语言**: Java 17
|
- **语言**: Java 17
|
||||||
|
- **数据库**: MySQL 8.0 + Redis 7
|
||||||
- **ORM**: MyBatis-Plus
|
- **ORM**: MyBatis-Plus
|
||||||
- **数据库**: MySQL 8.0
|
- **数据库迁移**: Flyway
|
||||||
- **缓存**: Redis 7
|
- **对象存储**: MinIO
|
||||||
- **API 文档**: Knife4j (Swagger)
|
- **反向代理**: Caddy
|
||||||
- **企业框架**: BladeX 4.0.1 RELEASE
|
- **容器化**: Docker Compose
|
||||||
|
|
||||||
## 📁 项目结构
|
## 快速开始
|
||||||
|
|
||||||
```
|
|
||||||
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+
|
- JDK 17+
|
||||||
- **Maven**: 3.8+
|
- Maven 3.8+
|
||||||
- **MySQL**: 8.0+
|
- Docker & Docker Compose
|
||||||
- **Redis**: 6.0+
|
|
||||||
|
### Docker Compose 部署(推荐)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 克隆项目
|
||||||
|
git clone https://git.waypeak.work/martial/martial-master.git
|
||||||
|
cd martial-master
|
||||||
|
|
||||||
|
# 启动所有服务
|
||||||
|
docker compose up -d
|
||||||
|
|
||||||
|
# 查看服务状态
|
||||||
|
docker compose ps
|
||||||
|
```
|
||||||
|
|
||||||
|
服务启动后:
|
||||||
|
- API 服务: http://localhost:8123
|
||||||
|
- API 文档: http://localhost:8123/doc.html
|
||||||
|
|
||||||
### 本地开发
|
### 本地开发
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 1. 克隆项目
|
# 编译项目
|
||||||
git clone https://git.waypeak.work/martial/martial-master.git
|
mvn clean package -DskipTests
|
||||||
cd martial-master
|
|
||||||
|
|
||||||
# 2. 编译 BladeX 框架(首次必须)
|
# 运行(需要先启动 MySQL 和 Redis)
|
||||||
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 配置和运维
|
|
||||||
- **[docs/DATABASE_MIGRATION.md](./docs/DATABASE_MIGRATION.md)** - 数据库迁移指南 (Flyway)
|
|
||||||
|
|
||||||
## 🗄️ 数据库
|
|
||||||
|
|
||||||
**连接信息(生产环境):**
|
|
||||||
- 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
|
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: 新功能
|
martial-master/
|
||||||
fix: 修复 Bug
|
├── src/main/java/org/springblade/
|
||||||
docs: 文档更新
|
│ ├── modules/martial/ # 武术比赛核心业务
|
||||||
style: 代码格式调整
|
│ │ ├── controller/ # 接口控制器
|
||||||
refactor: 重构
|
│ │ ├── service/ # 业务逻辑
|
||||||
perf: 性能优化
|
│ │ ├── mapper/ # 数据访问
|
||||||
test: 测试相关
|
│ │ └── pojo/ # 实体类
|
||||||
chore: 构建/工具配置
|
│ └── ... # BladeX 框架模块
|
||||||
|
├── src/main/resources/
|
||||||
|
│ ├── application.yml # 主配置
|
||||||
|
│ ├── application-dev.yml # 开发环境
|
||||||
|
│ ├── application-prod.yml # 生产环境
|
||||||
|
│ └── db/migration/ # Flyway 迁移脚本
|
||||||
|
├── database/ # 数据库初始化脚本
|
||||||
|
├── docs/ # 项目文档
|
||||||
|
├── docker-compose.yml # Docker 编排配置
|
||||||
|
└── Dockerfile # 镜像构建文件
|
||||||
```
|
```
|
||||||
|
|
||||||
## 👥 开发团队
|
## Docker Compose 服务
|
||||||
|
|
||||||
- **开发者**: JohnSion
|
| 服务 | 端口 | 说明 |
|
||||||
- **AI 助手**: Claude Code
|
|------|------|------|
|
||||||
- **基础框架**: BladeX 4.0.1 (上海布雷德科技有限公司)
|
| martial-api | 8123 | 后端 API 服务 |
|
||||||
|
| martial-mysql | 3306 | MySQL 数据库 |
|
||||||
|
| martial-redis | 6379 | Redis 缓存 |
|
||||||
|
| minio | 9000/9001 | 对象存储 |
|
||||||
|
|
||||||
## 📄 许可协议
|
## 数据库迁移
|
||||||
|
|
||||||
### BladeX 商业授权
|
项目使用 Flyway 管理数据库版本,应用启动时自动执行迁移。
|
||||||
|
|
||||||
本项目基于 **BladeX 商业框架** 构建,需遵守以下协议:
|
**添加新迁移:**
|
||||||
|
```bash
|
||||||
|
# 在 src/main/resources/db/migration/ 创建脚本
|
||||||
|
# 命名规范: V{版本号}__{描述}.sql
|
||||||
|
# 示例: V3__add_new_table.sql
|
||||||
|
```
|
||||||
|
|
||||||
#### 版权声明
|
详细说明:[docs/DATABASE_MIGRATION.md](./docs/DATABASE_MIGRATION.md)
|
||||||
- BladeX 是一个商业化软件,系列产品知识产权归**上海布雷德科技有限公司**独立所有
|
|
||||||
- 您一旦开始复制、下载、安装或者使用本产品,即被视为完全理解并接受本协议的各项条款
|
|
||||||
- 更多详情请看:[BladeX商业授权许可协议](https://license.bladex.cn)
|
|
||||||
|
|
||||||
#### 授权范围
|
## 开发文档
|
||||||
- **专业版**:只可用于**个人学习**及**个人私活**项目,不可用于公司或团队,不可泄露给任何第三方
|
|
||||||
- **企业版**:可用于**企业名下**的任何项目,企业版员工在**未购买**专业版授权前,只授权开发**所在授权企业名下**的项目,**不得将BladeX用于个人私活**
|
|
||||||
- **共同遵守**:若甲方需要您提供项目源码,则需代为甲方购买BladeX企业授权,甲方购买后续的所有项目都无需再次购买授权
|
|
||||||
|
|
||||||
#### 商用权益
|
| 文档 | 说明 |
|
||||||
- ✔️ 遵守[商业协议](https://license.bladex.cn)的前提下,将BladeX系列产品用于授权范围内的商用项目,并上线运营
|
|------|------|
|
||||||
- ✔️ 遵守[商业协议](https://license.bladex.cn)的前提下,不限制项目数,不限制服务器数
|
| [CLAUDE.md](./CLAUDE.md) | 项目完整说明 |
|
||||||
- ✔️ 遵守[商业协议](https://license.bladex.cn)的前提下,将自行编写的业务代码申请软件著作权
|
| [docs/开发指南.md](./docs/开发指南.md) | 开发规范 |
|
||||||
|
| [docs/架构说明.md](./docs/架构说明.md) | 架构设计 |
|
||||||
|
| [docs/DATABASE_MIGRATION.md](./docs/DATABASE_MIGRATION.md) | 数据库迁移指南 |
|
||||||
|
|
||||||
#### 何为侵权
|
## 相关仓库
|
||||||
- ❌ 不遵守商业协议,私自销售商业源码
|
|
||||||
- ❌ 以任何理由将BladeX源码用于申请软件著作权
|
|
||||||
- ❌ 将商业源码以任何途径任何理由泄露给未授权的单位或个人
|
|
||||||
- ❌ 开发完毕项目,没有为甲方购买企业授权,向甲方提供了BladeX代码
|
|
||||||
- ❌ 基于BladeX拓展研发与BladeX有竞争关系的衍生框架,并将其开源或销售
|
|
||||||
|
|
||||||
#### 侵权后果
|
| 仓库 | 说明 |
|
||||||
- 情节较轻:第一次发现警告处理
|
|------|------|
|
||||||
- 情节较重:封禁账号,踢出商业群,并保留追究法律责任的权利
|
| [martial-master](https://git.waypeak.work/martial/martial-master) | 后端 API |
|
||||||
- 情节严重:与本地律师事务所合作,以公司名义起诉侵犯计算机软件著作权
|
| [martial-web](https://git.waypeak.work/martial/martial-web) | 管理后台前端 |
|
||||||
|
| [martial-mini](https://git.waypeak.work/martial/martial-mini) | 用户端小程序 |
|
||||||
|
| [martial-admin-mini](https://git.waypeak.work/martial/martial-admin-mini) | 裁判端小程序 |
|
||||||
|
|
||||||
#### 技术支持
|
## 许可协议
|
||||||
- **答疑时间**: 工作日 9:00 ~ 17:00,周末、节假日休息
|
|
||||||
- **技术社区**: https://sns.bladex.cn
|
本项目基于 **BladeX 商业框架** 构建,需遵守 [BladeX 商业授权许可协议](https://license.bladex.cn)。
|
||||||
- **官方QQ**: 1272154962
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
**最后更新**: 2025-11-30
|
**最后更新**: 2024-12-29
|
||||||
**项目版本**: 4.0.1 RELEASE
|
|
||||||
**部署环境**: Docker + Drone CI/CD
|
|
||||||
|
|||||||
Reference in New Issue
Block a user