From cc095ed2e900c2c6fa25d4c7c159685c5c80fcf3 Mon Sep 17 00:00:00 2001 From: "n72595987@gmail.com" Date: Sun, 30 Nov 2025 11:11:59 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E5=86=99=E9=A1=B9=E7=9B=AE?= =?UTF-8?q?=E6=A0=B9=E7=9B=AE=E5=BD=95=20README?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 完全重构项目主 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 --- README.md | 461 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 295 insertions(+), 166 deletions(-) diff --git a/README.md b/README.md index 06b67bd..150ca75 100644 --- a/README.md +++ b/README.md @@ -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 分支 +**查看部署日志：** +```bash +# Drone 构建日志 +访问: https://martial-ci.johnsion.club -2. **部署失败排查** - ```bash - # 查看 Drone 构建日志 - 访问: http://154.30.6.21:8080 +# 应用日志 +ssh root@154.30.6.21 +docker logs -f martial-backend +``` - # 查看应用日志 - ssh root@154.30.6.21 - tail -f /app/martial-backend/logs/application.log +**检查服务状态：** +```bash +# 查看容器状态 +docker ps | grep martial - # 检查服务状态 - systemctl status martial-backend - ``` +# 查看健康状态 +curl https://martial-api.johnsion.club/actuator/health -3. **手动回滚** - ```bash - # 如需回滚到之前的版本 - # 1. 找到之前成功的 JAR 文件备份 - # 2. 替换当前 JAR - # 3. 重启服务 - systemctl restart martial-backend - ``` +# 重启服务 +cd /app/martial && docker-compose restart backend +``` -#### 📊 部署历史 +详细部署文档请参考：[docs/CI-CD部署总结.md](./docs/CI-CD部署总结.md) -可通过 Drone UI 查看所有部署历史记录： -- 访问: http://154.30.6.21:8080 -- 查看每次构建的详细日志 -- 查看每个步骤的执行时间和状态 +## 📚 开发文档 ---- \ No newline at end of file +- **[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