From 47d0b70a9c8166ba40f4d45e796ca9323e08b147 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=AE=85=E6=88=BF?= Date: Mon, 29 Dec 2025 14:17:09 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0README=EF=BC=8C?= =?UTF-8?q?=E7=AE=80=E5=8C=96=E5=86=85=E5=AE=B9=E5=B9=B6=E6=9B=B4=E6=96=B0?= =?UTF-8?q?=E5=9F=9F=E5=90=8D=E9=85=8D=E7=BD=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 405 +++++++++++++----------------------------------------- 1 file changed, 93 insertions(+), 312 deletions(-) diff --git a/README.md b/README.md index a2e9b98..20c9a4f 100644 --- a/README.md +++ b/README.md @@ -2,349 +2,130 @@ 基于 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 +| 服务 | 地址 | 说明 | +|------|------|------| +| 后端 API | https://martial-api.aitisai.com | Spring Boot 服务 | +| 管理后台 | 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 +- **数据库**: MySQL 8.0 + Redis 7 - **ORM**: MyBatis-Plus -- **数据库**: MySQL 8.0 -- **缓存**: Redis 7 -- **API 文档**: Knife4j (Swagger) -- **企业框架**: BladeX 4.0.1 RELEASE +- **数据库迁移**: Flyway +- **对象存储**: MinIO +- **反向代理**: Caddy +- **容器化**: 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+ -- **Maven**: 3.8+ -- **MySQL**: 8.0+ -- **Redis**: 6.0+ +- JDK 17+ +- Maven 3.8+ +- Docker & Docker Compose + +### 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 -# 1. 克隆项目 -git clone https://git.waypeak.work/martial/martial-master.git -cd martial-master +# 编译项目 +mvn clean package -DskipTests -# 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 配置和运维 -- **[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 -# 开发环境 +# 运行（需要先启动 MySQL 和 Redis） 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: 构建/工具配置 +martial-master/ +├── src/main/java/org/springblade/ +│ ├── modules/martial/ # 武术比赛核心业务 +│ │ ├── controller/ # 接口控制器 +│ │ ├── service/ # 业务逻辑 +│ │ ├── mapper/ # 数据访问 +│ │ └── pojo/ # 实体类 +│ └── ... # 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 +``` -#### 版权声明 -- BladeX 是一个商业化软件，系列产品知识产权归**上海布雷德科技有限公司**独立所有 -- 您一旦开始复制、下载、安装或者使用本产品，即被视为完全理解并接受本协议的各项条款 -- 更多详情请看：[BladeX商业授权许可协议](https://license.bladex.cn) +详细说明：[docs/DATABASE_MIGRATION.md](./docs/DATABASE_MIGRATION.md) -#### 授权范围 -- **专业版**：只可用于**个人学习**及**个人私活**项目，不可用于公司或团队，不可泄露给任何第三方 -- **企业版**：可用于**企业名下**的任何项目，企业版员工在**未购买**专业版授权前，只授权开发**所在授权企业名下**的项目，**不得将BladeX用于个人私活** -- **共同遵守**：若甲方需要您提供项目源码，则需代为甲方购买BladeX企业授权，甲方购买后续的所有项目都无需再次购买授权 +## 开发文档 -#### 商用权益 -- ✔️ 遵守[商业协议](https://license.bladex.cn)的前提下，将BladeX系列产品用于授权范围内的商用项目，并上线运营 -- ✔️ 遵守[商业协议](https://license.bladex.cn)的前提下，不限制项目数，不限制服务器数 -- ✔️ 遵守[商业协议](https://license.bladex.cn)的前提下，将自行编写的业务代码申请软件著作权 +| 文档 | 说明 | +|------|------| +| [CLAUDE.md](./CLAUDE.md) | 项目完整说明 | +| [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 -- **官方QQ**: 1272154962 +## 许可协议 + +本项目基于 **BladeX 商业框架** 构建，需遵守 [BladeX 商业授权许可协议](https://license.bladex.cn)。 --- -**最后更新**: 2025-11-30 -**项目版本**: 4.0.1 RELEASE -**部署环境**: Docker + Drone CI/CD +**最后更新**: 2024-12-29