chore: 整理docs目录结构，添加Flyway插件
- 新增 docs/guides/ 目录存放有用文档 - 新增 docker-deployment.md Docker部署指南 - 删除20+临时报告和过时文档 - 添加 flyway-maven-plugin 用于数据库迁移管理 - docker-compose 改用 Dockerfile.quick 快速构建 Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
This commit is contained in:
Z-WICK
co-authored by
factory-droid[bot]
factory-droid[bot]
parent
dcb6210725
commit
db6f85eef3
@@ -0,0 +1,276 @@
|
||||
# 武术管理系统 CI/CD 自动化部署 - 完成总结
|
||||
|
||||
## 🎉 部署状态
|
||||
|
||||
### ✅ 已完成的工作
|
||||
|
||||
#### 1. Drone CI/CD 服务器部署
|
||||
- **Drone Server**: https://martial-ci.johnsion.club ✅ 运行中
|
||||
- **Drone Runner**: ✅ 已连接并轮询任务
|
||||
- **管理员账号**: JohnSion ✅ 已创建
|
||||
- **RPC Secret**: 55db397727eb7def59f3f588c0b503e0 ✅ 已配置
|
||||
|
||||
#### 2. 部署服务器基础设施
|
||||
- **MySQL 8.0**: ✅ 运行中（端口 3306）
|
||||
- 数据库: martial_db
|
||||
- 表数量: 53 张
|
||||
- 测试数据: 2场比赛、10名运动员、9个项目
|
||||
- 密码: WtcSecure901faf1ac4d32e2bPwd
|
||||
|
||||
- **Redis 7-alpine**: ✅ 运行中（端口 6379）
|
||||
- 密码: RedisSecure2024MartialXyZ789ABC
|
||||
- 持久化: AOF 模式
|
||||
|
||||
- **Docker Compose**: ✅ 配置完成
|
||||
- 位置: /app/martial/docker-compose.yml
|
||||
- 网络: martial-network
|
||||
|
||||
#### 3. CI/CD 配置文件
|
||||
- **后端仓库** (martial-master):
|
||||
- `.drone.yml` ✅ 已创建并提交
|
||||
- `Dockerfile` ✅ 已创建并提交
|
||||
- SSH Secret ✅ 你已配置
|
||||
|
||||
- **前端仓库** (martial-web):
|
||||
- `.drone.yml` ✅ 已创建并提交
|
||||
- `Dockerfile` ✅ 已创建并提交
|
||||
- `nginx.conf` ✅ 已创建并提交
|
||||
- SSH Secret ✅ 你已配置
|
||||
|
||||
---
|
||||
|
||||
## 📋 待完成的步骤
|
||||
|
||||
### 步骤1：推送代码到 Gitea ⚠️ 需要你操作
|
||||
|
||||
**方法A：添加 SSH 公钥到 Gitea（推荐）**
|
||||
|
||||
1. 复制以下公钥：
|
||||
```
|
||||
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQCzXo91kuSXHfsuqvgm1hdquE+JuaEn2qJB35+BxxFRKFXhwGoMLAAP6kEnawvRPpugfZ7C0bG/6zgQ4E32UwtihaDAEgweyLWKPDW4GEcDofQdgrprBPAoODZc4soAIH3kQ/LePNMsWnwDtc7BANCCmtEk0hnXvMbbFVD6U5MOwfvofzkbCE7OPxOLz+dTNMs8nxOuo9T00rK5julPeCJapJWUbEXXG4X+G2yY7Otx7X1qv7BHE31deRHIUonWT8Wh4EUiyOxUCmXC04l35yOF1rt2dBVa2AHwbpNiKjWVupSoiq+32PTQKoqc85hDRSEueXXjy/GPSCG/MFaLl4LwGMj0Ok/oirlB5RlhjvQpKrvpmYfUg+rS5rhsmKd5dmvzOtyadFoNamZF1g9nNFSmrXh1yhejIkAbUBTJvtuH66fSkH3WDIEp2/TnGr/XVsbAh717meNHMl92Yv/CAQT3JhSMoMA+D1xZWVrRCpMyU05WAepTv+AQOrxm0rvb7MOHVTgBdzmQHVLFFKImYtKDQjhtZnx6cuk/+Y7MmUT/rmdxvjaPpJe/JYmm+dOLnuMU0vtBksTlP7J+xymT5n69P7sh0AtFxRTh4SZaoZu4zDeh98GsbTFSoVgXe4nc7vyBmrKL9pu0OCo5wrrdqa6wzVoyZzUAeC888dFa1XBQQw== katana-import@test.johnsion.club
|
||||
```
|
||||
|
||||
2. 登录 https://git.waypeak.work
|
||||
3. 进入 设置 → SSH / GPG 密钥
|
||||
4. 添加上面的公钥
|
||||
|
||||
**方法B：在本地推送代码**
|
||||
|
||||
在你本地机器上：
|
||||
```bash
|
||||
# 后端
|
||||
cd martial-master
|
||||
git pull
|
||||
git push origin main
|
||||
|
||||
# 前端
|
||||
cd martial-web
|
||||
git pull
|
||||
git push origin main
|
||||
```
|
||||
|
||||
### 步骤2：在 Drone UI 中激活仓库 ⚠️ 需要你操作
|
||||
|
||||
1. 访问 https://martial-ci.johnsion.club
|
||||
2. 使用 Gitea 账号登录（JohnSion）
|
||||
3. 授权 Drone 访问你的仓库
|
||||
4. 在仓库列表中点击 **ACTIVATE**：
|
||||
- `martial/martial-master`
|
||||
- `martial/martial-web`
|
||||
|
||||
### 步骤3：触发首次构建（推送代码后自动触发）
|
||||
|
||||
代码推送后，Drone 会自动：
|
||||
1. 拉取代码
|
||||
2. 编译项目
|
||||
3. 构建 Docker 镜像
|
||||
4. 部署到生产服务器
|
||||
5. 执行健康检查
|
||||
|
||||
**或者手动触发：**
|
||||
1. 进入 Drone UI 中的仓库页面
|
||||
2. 点击右上角 "NEW BUILD"
|
||||
3. 选择 `main` 分支
|
||||
4. 点击 "CREATE"
|
||||
|
||||
---
|
||||
|
||||
## 🚀 自动化部署流程
|
||||
|
||||
### 后端部署流程
|
||||
```
|
||||
推送代码到 main 分支
|
||||
↓
|
||||
Drone CI 检测到代码变更
|
||||
↓
|
||||
1. 编译 BladeX 框架（缓存 Maven 依赖）
|
||||
↓
|
||||
2. 编译后端项目并打包 JAR
|
||||
↓
|
||||
3. 构建 Docker 镜像
|
||||
↓
|
||||
4. SSH 到部署服务器（154.30.6.21）
|
||||
↓
|
||||
5. 拉取最新镜像并重启容器
|
||||
↓
|
||||
6. 健康检查 (https://martial-api.johnsion.club/actuator/health)
|
||||
↓
|
||||
✅ 部署成功
|
||||
```
|
||||
|
||||
### 前端部署流程
|
||||
```
|
||||
推送代码到 main 分支
|
||||
↓
|
||||
Drone CI 检测到代码变更
|
||||
↓
|
||||
1. 安装 npm 依赖（使用国内镜像加速）
|
||||
↓
|
||||
2. 构建生产版本（npm run build）
|
||||
↓
|
||||
3. 构建 Docker 镜像（Nginx + 静态文件）
|
||||
↓
|
||||
4. SSH 到部署服务器
|
||||
↓
|
||||
5. 拉取最新镜像并重启容器
|
||||
↓
|
||||
6. 健康检查 (https://martial.johnsion.club)
|
||||
↓
|
||||
✅ 部署成功
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🌐 访问地址
|
||||
|
||||
### 部署后的应用
|
||||
- **前端**: https://martial.johnsion.club
|
||||
- **后端 API**: https://martial-api.johnsion.club
|
||||
- **API 文档**: https://martial-doc.johnsion.club
|
||||
|
||||
### CI/CD 管理
|
||||
- **Drone UI**: https://martial-ci.johnsion.club
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ 常用运维命令
|
||||
|
||||
### Drone 相关
|
||||
```bash
|
||||
# 查看 Drone Server 日志
|
||||
ssh root@154.30.6.21 "docker logs -f drone"
|
||||
|
||||
# 查看 Runner 日志
|
||||
ssh root@154.30.6.21 "docker logs -f drone-runner"
|
||||
|
||||
# 重启 Drone 服务
|
||||
ssh root@154.30.6.21 "docker restart drone drone-runner"
|
||||
```
|
||||
|
||||
### 应用相关
|
||||
```bash
|
||||
# 查看所有容器状态
|
||||
ssh root@154.30.6.21 "docker ps"
|
||||
|
||||
# 查看应用日志
|
||||
ssh root@154.30.6.21 "docker logs -f martial-backend"
|
||||
ssh root@154.30.6.21 "docker logs -f martial-frontend"
|
||||
|
||||
# 重启应用
|
||||
ssh root@154.30.6.21 "cd /app/martial && docker compose restart backend"
|
||||
ssh root@154.30.6.21 "cd /app/martial && docker compose restart frontend"
|
||||
|
||||
# 查看数据库
|
||||
ssh root@154.30.6.21 "docker exec -it martial-mysql mysql -uroot -pWtcSecure901faf1ac4d32e2bPwd martial_db"
|
||||
```
|
||||
|
||||
### Docker Compose 管理
|
||||
```bash
|
||||
# 查看服务状态
|
||||
ssh root@154.30.6.21 "cd /app/martial && docker compose ps"
|
||||
|
||||
# 查看日志
|
||||
ssh root@154.30.6.21 "cd /app/martial && docker compose logs -f backend"
|
||||
|
||||
# 停止所有服务
|
||||
ssh root@154.30.6.21 "cd /app/martial && docker compose down"
|
||||
|
||||
# 启动所有服务
|
||||
ssh root@154.30.6.21 "cd /app/martial && docker compose up -d"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 配置详情
|
||||
|
||||
### 数据库连接
|
||||
- Host: 154.30.6.21 (容器内使用 martial-mysql)
|
||||
- Port: 3306
|
||||
- Database: martial_db
|
||||
- Username: root
|
||||
- Password: WtcSecure901faf1ac4d32e2bPwd
|
||||
|
||||
### Redis 配置
|
||||
- Host: 154.30.6.21 (容器内使用 martial-redis)
|
||||
- Port: 6379
|
||||
- Password: RedisSecure2024MartialXyZ789ABC
|
||||
- Database: 8
|
||||
|
||||
### 环境变量
|
||||
后端容器环境变量在 docker-compose.yml 中配置：
|
||||
```yaml
|
||||
SPRING_PROFILE: dev
|
||||
JAVA_OPTS: "-Xms512m -Xmx1024m"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 故障排查
|
||||
|
||||
### 构建失败
|
||||
1. 检查 Drone UI 中的构建日志
|
||||
2. 确认 SSH Secret 配置正确
|
||||
3. 确认部署服务器可以被 SSH 访问
|
||||
|
||||
### 部署失败
|
||||
1. SSH 到部署服务器检查容器状态：`docker ps -a`
|
||||
2. 查看容器日志：`docker logs martial-backend`
|
||||
3. 检查数据库连接：`docker exec martial-mysql mysql -uroot -p...`
|
||||
|
||||
### 应用无法访问
|
||||
1. 检查容器是否运行：`docker ps | grep martial`
|
||||
2. 检查端口是否监听：`ss -tlnp | grep 8123`
|
||||
3. 查看应用日志：`docker logs martial-backend`
|
||||
|
||||
---
|
||||
|
||||
## 📚 文档位置
|
||||
|
||||
- **后端文档**: /remote_dev/martial/martial-master/CLAUDE.md
|
||||
- **CI/CD 配置**: /remote_dev/martial/martial-master/.drone.yml
|
||||
- **部署配置**: /app/martial/docker-compose.yml (部署服务器上)
|
||||
- **数据库脚本**: /remote_dev/martial/martial-master/doc/sql/martial-db/
|
||||
|
||||
---
|
||||
|
||||
## 🎯 下一步建议
|
||||
|
||||
1. ✅ **完成代码推送**（见上方步骤1）
|
||||
2. ✅ **激活 Drone 仓库**（见上方步骤2）
|
||||
3. ✅ **配置域名**（已完成）
|
||||
- 前端: https://martial.johnsion.club
|
||||
- 后端: https://martial-api.johnsion.club
|
||||
- API 文档: https://martial-doc.johnsion.club
|
||||
- CI/CD: https://martial-ci.johnsion.club
|
||||
|
||||
4. ⭐ **配置构建通知**（可选）
|
||||
- 邮件通知
|
||||
- 钉钉/企业微信通知
|
||||
- Telegram 通知
|
||||
|
||||
---
|
||||
|
||||
生成时间：2025-11-29
|
||||
部署服务器：154.30.6.21
|
||||
域名：*.johnsion.club
|
||||
管理员：JohnSion
|
||||
@@ -0,0 +1,224 @@
|
||||
# 数据库迁移指南
|
||||
|
||||
本项目使用 **Flyway** 进行数据库版本管理和自动迁移。
|
||||
|
||||
## 概述
|
||||
|
||||
Flyway 是一个数据库迁移工具，它能够：
|
||||
- 自动追踪数据库版本
|
||||
- 按顺序执行迁移脚本
|
||||
- 确保团队成员的数据库结构一致
|
||||
- 支持回滚和修复
|
||||
|
||||
## 工作原理
|
||||
|
||||
1. 应用启动时，Flyway 自动扫描 `src/main/resources/db/migration` 目录
|
||||
2. 检查 `flyway_schema_history` 表，确定已执行的版本
|
||||
3. 按版本号顺序执行未运行的迁移脚本
|
||||
4. 记录执行结果到历史表
|
||||
|
||||
## 迁移脚本命名规范
|
||||
|
||||
```
|
||||
V{版本号}__{描述}.sql
|
||||
```
|
||||
|
||||
### 命名规则
|
||||
|
||||
| 规则 | 说明 | 示例 |
|
||||
|------|------|------|
|
||||
| 前缀 | 必须以 `V` 开头（大写） | V1, V2, V10 |
|
||||
| 版本号 | 数字，支持小数点 | 1, 2, 2.1, 10 |
|
||||
| 分隔符 | **两个下划线** | `__` |
|
||||
| 描述 | 用下划线连接单词 | add_user_table |
|
||||
| 后缀 | 必须是 `.sql` | .sql |
|
||||
|
||||
### 正确示例
|
||||
|
||||
```
|
||||
V1__baseline.sql # 基线版本
|
||||
V2__add_project_fields.sql # 添加项目字段
|
||||
V3__create_order_table.sql # 创建订单表
|
||||
V4__add_index_to_user.sql # 添加用户索引
|
||||
V4.1__fix_user_column_type.sql # 修复用户列类型（小版本）
|
||||
V10__major_refactor.sql # 大版本重构
|
||||
```
|
||||
|
||||
### 错误示例
|
||||
|
||||
```
|
||||
v1__init.sql # 错误：v 应该大写
|
||||
V1_init.sql # 错误：只有一个下划线
|
||||
V1-init.sql # 错误：使用了连字符
|
||||
V1__init.SQL # 错误：后缀应该小写
|
||||
init.sql # 错误：缺少版本前缀
|
||||
```
|
||||
|
||||
## 如何添加新的迁移
|
||||
|
||||
### 步骤 1：确定版本号
|
||||
|
||||
查看当前最新版本：
|
||||
```bash
|
||||
ls src/main/resources/db/migration/
|
||||
```
|
||||
|
||||
新版本号 = 最新版本号 + 1
|
||||
|
||||
### 步骤 2：创建迁移脚本
|
||||
|
||||
在 `src/main/resources/db/migration/` 目录创建新文件：
|
||||
|
||||
```sql
|
||||
-- =====================================================
|
||||
-- 迁移脚本: [描述]
|
||||
-- 版本: V{版本号}
|
||||
-- 描述: [详细说明]
|
||||
-- 日期: YYYY-MM-DD
|
||||
-- =====================================================
|
||||
|
||||
-- 你的 SQL 语句
|
||||
ALTER TABLE xxx ADD COLUMN yyy VARCHAR(100);
|
||||
```
|
||||
|
||||
### 步骤 3：测试迁移
|
||||
|
||||
本地启动应用，观察日志：
|
||||
```
|
||||
Flyway Community Edition 9.x.x
|
||||
Successfully validated 3 migrations
|
||||
Current version of schema: 2
|
||||
Migrating schema to version 3 - create_order_table
|
||||
Successfully applied 1 migration
|
||||
```
|
||||
|
||||
### 步骤 4：提交代码
|
||||
|
||||
```bash
|
||||
git add src/main/resources/db/migration/V3__xxx.sql
|
||||
git commit -m "db: 添加xxx迁移脚本"
|
||||
git push
|
||||
```
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 1. 幂等性脚本
|
||||
|
||||
编写可重复执行的脚本，避免重复执行报错：
|
||||
|
||||
```sql
|
||||
-- 添加列（如果不存在）
|
||||
SET @exist := (SELECT COUNT(*) FROM information_schema.columns
|
||||
WHERE table_schema = DATABASE()
|
||||
AND table_name = 'your_table'
|
||||
AND column_name = 'new_column');
|
||||
SET @sql := IF(@exist = 0,
|
||||
'ALTER TABLE your_table ADD COLUMN new_column VARCHAR(100)',
|
||||
'SELECT 1');
|
||||
PREPARE stmt FROM @sql;
|
||||
EXECUTE stmt;
|
||||
DEALLOCATE PREPARE stmt;
|
||||
```
|
||||
|
||||
### 2. 不要修改已执行的脚本
|
||||
|
||||
一旦迁移脚本被执行（已提交到版本库），**永远不要修改它**。
|
||||
|
||||
如果需要修复，创建新的迁移脚本：
|
||||
```
|
||||
V3__create_table.sql # 已执行，有错误
|
||||
V4__fix_v3_error.sql # 新建脚本修复错误
|
||||
```
|
||||
|
||||
### 3. 小步迁移
|
||||
|
||||
每个迁移脚本只做一件事：
|
||||
- V2__add_user_email.sql
|
||||
- V3__add_user_phone.sql
|
||||
- 不要: V2__add_user_email_and_phone_and_address.sql
|
||||
|
||||
### 4. 添加注释
|
||||
|
||||
```sql
|
||||
-- =====================================================
|
||||
-- 迁移脚本: 添加用户邮箱字段
|
||||
-- 版本: V5
|
||||
-- 描述: 为用户表添加邮箱字段，用于接收通知
|
||||
-- 作者: 张三
|
||||
-- 日期: 2024-12-29
|
||||
-- 关联需求: JIRA-123
|
||||
-- =====================================================
|
||||
```
|
||||
|
||||
### 5. 备份数据
|
||||
|
||||
生产环境执行迁移前，务必备份数据库：
|
||||
```bash
|
||||
mysqldump -u root -p martial_db > backup_$(date +%Y%m%d).sql
|
||||
```
|
||||
|
||||
## 常见问题
|
||||
|
||||
### Q1: 迁移失败怎么办？
|
||||
|
||||
1. 查看错误日志，定位问题
|
||||
2. 修复数据库中的问题（手动）
|
||||
3. 修复迁移脚本
|
||||
4. 执行 Flyway repair（如需要）
|
||||
|
||||
### Q2: 如何跳过某个版本？
|
||||
|
||||
不建议跳过版本。如果必须跳过，可以创建空脚本：
|
||||
```sql
|
||||
-- V3__placeholder.sql
|
||||
-- 此版本跳过
|
||||
SELECT 1;
|
||||
```
|
||||
|
||||
### Q3: 多人开发版本冲突怎么办？
|
||||
|
||||
使用日期时间作为版本号前缀：
|
||||
```
|
||||
V20241229001__add_field.sql
|
||||
V20241229002__fix_bug.sql
|
||||
```
|
||||
|
||||
### Q4: 如何查看迁移历史？
|
||||
|
||||
```sql
|
||||
SELECT * FROM flyway_schema_history ORDER BY installed_rank;
|
||||
```
|
||||
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
src/main/resources/
|
||||
└── db/
|
||||
└── migration/
|
||||
├── V1__baseline.sql # 基线版本
|
||||
├── V2__add_project_fields.sql # 添加项目字段
|
||||
└── V3__xxx.sql # 后续迁移...
|
||||
```
|
||||
|
||||
## 配置说明
|
||||
|
||||
application.yml 中的 Flyway 配置：
|
||||
|
||||
```yaml
|
||||
spring:
|
||||
flyway:
|
||||
enabled: true # 启用 Flyway
|
||||
locations: classpath:db/migration # 迁移脚本位置
|
||||
table: flyway_schema_history # 版本历史表名
|
||||
baseline-version: 0 # 基线版本号
|
||||
baseline-on-migrate: true # 自动执行基线
|
||||
validate-on-migrate: true # 校验迁移脚本
|
||||
encoding: UTF-8 # 脚本编码
|
||||
out-of-order: false # 禁止乱序执行
|
||||
clean-disabled: true # 禁用清理（生产安全）
|
||||
```
|
||||
|
||||
## 参考资料
|
||||
|
||||
- [Flyway 官方文档](https://flywaydb.org/documentation/)
|
||||
- [Spring Boot Flyway 集成](https://docs.spring.io/spring-boot/docs/current/reference/html/howto.html#howto.data-initialization.migration-tool.flyway)
|
||||
@@ -0,0 +1,160 @@
|
||||
# Docker 部署指南
|
||||
|
||||
本项目提供三种 Docker 构建方式，适用于不同场景。
|
||||
|
||||
## 构建方式对比
|
||||
|
||||
| 方式 | Dockerfile | 适用场景 | 构建速度 | 依赖条件 |
|
||||
|------|------------|----------|----------|----------|
|
||||
| 快速构建 | `Dockerfile.quick` | 本地开发迭代 | 最快 | 本地已编译 JAR |
|
||||
| 离线构建 | `Dockerfile` | CI/CD 离线环境 | 中等 | 需要 `.m2-repo` 目录 |
|
||||
| 完整构建 | `Dockerfile.fullbuild` | 全新环境 | 最慢 | 需要 martial-tool 源码 |
|
||||
|
||||
---
|
||||
|
||||
## 方式一：快速构建（推荐日常开发）
|
||||
|
||||
适用于本地开发，需要先在本地编译项目。
|
||||
|
||||
```bash
|
||||
# 1. 本地编译
|
||||
mvn clean package -DskipTests
|
||||
|
||||
# 2. 构建镜像并启动
|
||||
docker-compose up --build
|
||||
```
|
||||
|
||||
或一条命令：
|
||||
|
||||
```bash
|
||||
mvn clean package -DskipTests && docker-compose up --build
|
||||
```
|
||||
|
||||
**前提条件**：
|
||||
- 本地已安装 JDK 17+ 和 Maven 3.9+
|
||||
- martial-tool 依赖已安装到本地 Maven 仓库
|
||||
|
||||
**docker-compose.yml 配置**：
|
||||
```yaml
|
||||
martial-api:
|
||||
build:
|
||||
context: .
|
||||
dockerfile: Dockerfile.quick
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 方式二：离线构建
|
||||
|
||||
适用于 CI/CD 环境或无法访问 Maven 仓库的场景。
|
||||
|
||||
```bash
|
||||
# 1. 准备离线依赖（首次或依赖变更时执行）
|
||||
cp -r ~/.m2/repository .m2-repo
|
||||
|
||||
# 2. 构建镜像并启动
|
||||
docker-compose up --build
|
||||
```
|
||||
|
||||
**前提条件**：
|
||||
- 本地 `~/.m2/repository` 包含所有项目依赖
|
||||
- `.m2-repo` 目录已复制到项目根目录
|
||||
|
||||
**docker-compose.yml 配置**：
|
||||
```yaml
|
||||
martial-api:
|
||||
build:
|
||||
context: .
|
||||
dockerfile: Dockerfile
|
||||
```
|
||||
|
||||
**注意**：`.m2-repo` 目录较大（通常几百MB），建议添加到 `.gitignore`。
|
||||
|
||||
---
|
||||
|
||||
## 方式三：完整构建
|
||||
|
||||
适用于全新环境，从零开始构建整个项目（包括 BladeX 框架）。
|
||||
|
||||
```bash
|
||||
# 需要在包含 martial-tool 和 martial-master 的父目录执行
|
||||
cd /path/to/parent-directory
|
||||
docker build -f martial-master/Dockerfile.fullbuild -t martial-api:latest .
|
||||
```
|
||||
|
||||
**目录结构要求**：
|
||||
```
|
||||
parent-directory/
|
||||
├── martial-tool/ # BladeX 框架源码
|
||||
└── martial-master/ # 本项目
|
||||
```
|
||||
|
||||
**特点**：
|
||||
- 完全自包含，不依赖本地环境
|
||||
- 构建时间最长（需编译两个项目）
|
||||
- 适合首次部署或 CI/CD 完整构建
|
||||
|
||||
---
|
||||
|
||||
## 常用命令
|
||||
|
||||
```bash
|
||||
# 启动所有服务
|
||||
docker-compose up -d
|
||||
|
||||
# 重新构建并启动
|
||||
docker-compose up -d --build
|
||||
|
||||
# 强制重新创建容器
|
||||
docker-compose up -d --force-recreate
|
||||
|
||||
# 查看日志
|
||||
docker logs -f martial-api
|
||||
|
||||
# 停止所有服务
|
||||
docker-compose down
|
||||
|
||||
# 停止并删除数据卷（慎用，会清除数据库数据）
|
||||
docker-compose down -v
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 环境变量
|
||||
|
||||
可在 `docker-compose.yml` 中配置以下环境变量：
|
||||
|
||||
| 变量 | 说明 | 默认值 |
|
||||
|------|------|--------|
|
||||
| `SPRING_PROFILE` | Spring 配置文件 | `docker` |
|
||||
| `JAVA_OPTS` | JVM 参数 | `-Xms512m -Xmx1024m -XX:+UseG1GC` |
|
||||
| `SPRING_DATASOURCE_URL` | 数据库连接 | 见 docker-compose.yml |
|
||||
| `SPRING_DATA_REDIS_HOST` | Redis 地址 | `redis` |
|
||||
|
||||
---
|
||||
|
||||
## 故障排查
|
||||
|
||||
### 1. JAR 文件不存在
|
||||
```
|
||||
COPY target/blade-api.jar: not found
|
||||
```
|
||||
**解决**：先执行 `mvn clean package -DskipTests`
|
||||
|
||||
### 2. .m2-repo 目录不存在
|
||||
```
|
||||
COPY .m2-repo: not found
|
||||
```
|
||||
**解决**：执行 `cp -r ~/.m2/repository .m2-repo` 或改用 `Dockerfile.quick`
|
||||
|
||||
### 3. martial-tool 目录不存在
|
||||
```
|
||||
COPY martial-tool: not found
|
||||
```
|
||||
**解决**：确保在正确的父目录执行，或改用其他构建方式
|
||||
|
||||
### 4. Flyway 迁移失败
|
||||
```
|
||||
Migration checksum mismatch
|
||||
```
|
||||
**解决**：执行 `mvn flyway:repair` 修复迁移记录
|
||||
+1171
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,410 @@
|
||||
# BladeX 框架架构说明
|
||||
|
||||
## 一、架构概览
|
||||
|
||||
本项目基于 **BladeX 4.0.1 企业级框架**，采用混合式架构设计，包含：
|
||||
- 分层架构（common 通用层）
|
||||
- 模块化架构（modules 业务模块）
|
||||
- DDD 思想（pojo/entity/dto/vo 分离）
|
||||
|
||||
## 二、目录结构对比
|
||||
|
||||
### 传统 Spring Boot 项目（清晰简单）
|
||||
|
||||
```
|
||||
src/main/java/com/company/project/
|
||||
├── controller/ # 所有控制器
|
||||
├── service/ # 所有服务
|
||||
│ └── impl/
|
||||
├── mapper/dao/ # 所有数据访问
|
||||
├── entity/model/ # 所有实体
|
||||
├── dto/ # 所有DTO
|
||||
├── vo/ # 所有VO
|
||||
├── config/ # 配置类
|
||||
├── util/ # 工具类
|
||||
└── constant/ # 常量
|
||||
```
|
||||
|
||||
**特点**：按技术层级分包，结构扁平，一目了然
|
||||
|
||||
---
|
||||
|
||||
### BladeX 项目（复杂混合）
|
||||
|
||||
```
|
||||
src/main/java/org/springblade/
|
||||
├── Application.java # 主启动类
|
||||
│
|
||||
├── common/ # 通用层（横向关注点）
|
||||
│ ├── cache/ # 缓存工具（UserCache、DictCache等）
|
||||
│ ├── config/ # 全局配置（Swagger、Blade核心配置等）
|
||||
│ ├── constant/ # 全局常量（CommonConstant、DictConstant等）
|
||||
│ ├── enums/ # 通用枚举
|
||||
│ ├── event/ # 事件监听器（日志监听等）
|
||||
│ ├── filter/ # 全局过滤器
|
||||
│ ├── handler/ # 全局处理器
|
||||
│ ├── launch/ # 启动相关
|
||||
│ └── utils/ # 通用工具类
|
||||
│
|
||||
├── job/ # 定时任务模块（独立）
|
||||
│ ├── controller/ # 任务管理API
|
||||
│ ├── mapper/ # 任务数据访问
|
||||
│ ├── pojo/ # 任务数据对象
|
||||
│ │ ├── entity/ # JobInfo, JobServer
|
||||
│ │ ├── dto/
|
||||
│ │ └── vo/
|
||||
│ ├── processor/ # 任务处理器（实际执行逻辑）
|
||||
│ └── service/ # 任务业务逻辑
|
||||
│
|
||||
└── modules/ # 业务模块（核心业务）
|
||||
├── auth/ # 认证授权模块
|
||||
│ ├── config/ # 认证配置
|
||||
│ ├── constant/ # 认证常量
|
||||
│ ├── granter/ # Token授权器（多种登录方式）
|
||||
│ ├── handler/ # 认证处理器
|
||||
│ ├── provider/ # 认证提供者
|
||||
│ ├── service/ # 认证服务
|
||||
│ └── utils/ # 认证工具
|
||||
│
|
||||
├── system/ # 系统管理模块
|
||||
│ ├── controller/ # 用户、角色、菜单、部门等API
|
||||
│ ├── mapper/ # 数据访问层
|
||||
│ ├── pojo/
|
||||
│ │ ├── entity/ # 系统实体（User、Role、Menu等）
|
||||
│ │ ├── dto/ # 数据传输对象
|
||||
│ │ └── vo/ # 视图对象
|
||||
│ ├── service/ # 系统业务逻辑
|
||||
│ ├── excel/ # Excel导入导出
|
||||
│ ├── rule/ # 业务规则
|
||||
│ └── wrapper/ # 数据包装器
|
||||
│
|
||||
├── resource/ # 资源管理模块
|
||||
│ ├── controller/ # 附件、OSS、SMS API
|
||||
│ ├── mapper/
|
||||
│ ├── pojo/
|
||||
│ ├── service/
|
||||
│ ├── builder/ # OSS构建器（支持多云存储）
|
||||
│ ├── config/ # 资源配置
|
||||
│ ├── endpoint/ # 端点
|
||||
│ ├── rule/ # 规则
|
||||
│ └── utils/ # 资源工具
|
||||
│
|
||||
├── desk/ # 工作台模块
|
||||
│ ├── controller/ # 仪表盘、通知API
|
||||
│ ├── mapper/
|
||||
│ ├── pojo/
|
||||
│ ├── service/
|
||||
│ └── wrapper/
|
||||
│
|
||||
├── develop/ # 开发工具模块
|
||||
│ ├── controller/ # 代码生成、数据源管理API
|
||||
│ ├── mapper/
|
||||
│ ├── pojo/
|
||||
│ └── service/
|
||||
│
|
||||
└── martial/ # 武术比赛模块（主业务）⭐
|
||||
├── controller/ # 比赛业务API
|
||||
├── mapper/ # 数据访问层
|
||||
├── pojo/
|
||||
│ ├── entity/ # 9个核心实体
|
||||
│ │ ├── Competition.java # 赛事
|
||||
│ │ ├── Athlete.java # 运动员
|
||||
│ │ ├── Judge.java # 裁判
|
||||
│ │ ├── Project.java # 项目
|
||||
│ │ ├── Schedule.java # 赛程
|
||||
│ │ ├── Venue.java # 场馆
|
||||
│ │ ├── Score.java # 评分
|
||||
│ │ ├── Result.java # 成绩
|
||||
│ │ └── RegistrationOrder.java # 报名订单
|
||||
│ ├── dto/
|
||||
│ └── vo/
|
||||
└── service/
|
||||
```
|
||||
|
||||
## 三、架构特点分析
|
||||
|
||||
### ✅ 优点
|
||||
|
||||
1. **功能全面**
|
||||
- 内置认证授权、权限管理、多租户、OSS、SMS等
|
||||
- 开箱即用，快速开发
|
||||
|
||||
2. **模块独立**
|
||||
- 每个 module 相对独立，可单独开发
|
||||
- 便于团队分工协作
|
||||
|
||||
3. **高度封装**
|
||||
- 框架提供大量基础功能
|
||||
- 减少重复代码
|
||||
|
||||
### ⚠️ 缺点（为什么感觉"乱"）
|
||||
|
||||
#### 1. **职责边界模糊**
|
||||
|
||||
```
|
||||
❓ common 和 modules 的边界不清
|
||||
- common/config vs modules/auth/config
|
||||
- common/utils vs modules/resource/utils
|
||||
|
||||
什么应该放 common？
|
||||
✅ 真正通用的、跨模块的（如：DateUtil、StringUtil）
|
||||
❌ 某个模块专用的（应该放模块内部）
|
||||
```
|
||||
|
||||
#### 2. **结构不统一**
|
||||
|
||||
```
|
||||
❓ modules 下各模块结构不一致
|
||||
|
||||
auth 模块： system 模块：
|
||||
├── config/ ├── controller/
|
||||
├── granter/ ├── mapper/
|
||||
├── service/ ├── pojo/
|
||||
└── utils/ │ ├── entity/
|
||||
│ ├── dto/
|
||||
martial 模块： │ └── vo/
|
||||
├── controller/ ├── service/
|
||||
├── mapper/ ├── excel/
|
||||
├── pojo/ └── wrapper/
|
||||
│ ├── entity/
|
||||
│ ├── dto/
|
||||
│ └── vo/
|
||||
└── service/
|
||||
|
||||
为什么不统一？
|
||||
- auth 没有 pojo 目录（因为它不直接操作数据库表）
|
||||
- system 有 excel/wrapper（因为需要导入导出）
|
||||
- martial 结构最标准（因为是典型CRUD业务）
|
||||
```
|
||||
|
||||
#### 3. **多余层级**
|
||||
|
||||
```
|
||||
❓ 为什么要多一层 pojo？
|
||||
|
||||
传统做法：
|
||||
modules/martial/entity/Competition.java
|
||||
modules/martial/dto/CompetitionDTO.java
|
||||
|
||||
BladeX 做法：
|
||||
modules/martial/pojo/entity/Competition.java
|
||||
modules/martial/pojo/dto/CompetitionDTO.java
|
||||
|
||||
原因：DDD 思想中，pojo 代表"领域对象"的总称
|
||||
但实际上增加了复杂度，没有明显好处
|
||||
```
|
||||
|
||||
#### 4. **job 模块孤立**
|
||||
|
||||
```
|
||||
❓ 为什么 job 不在 modules 里？
|
||||
|
||||
既然有 modules，job 应该是：
|
||||
modules/job/
|
||||
├── controller/
|
||||
└── ...
|
||||
|
||||
而不是单独拿出来，破坏了统一性
|
||||
```
|
||||
|
||||
## 四、架构设计理念分析
|
||||
|
||||
BladeX 混合了多种架构理念：
|
||||
|
||||
### 1. 分层架构（Layered Architecture）
|
||||
|
||||
```
|
||||
common 层 → 为所有模块提供通用功能
|
||||
```
|
||||
|
||||
**目的**：代码复用
|
||||
**问题**：边界不清，什么都往 common 塞
|
||||
|
||||
### 2. 模块化架构（Modular Architecture）
|
||||
|
||||
```
|
||||
modules/ → 按业务领域划分模块
|
||||
```
|
||||
|
||||
**目的**：业务隔离，独立演进
|
||||
**问题**：模块结构不统一
|
||||
|
||||
### 3. DDD 思想（Domain-Driven Design）
|
||||
|
||||
```
|
||||
pojo/entity/ → 实体
|
||||
pojo/dto/ → 数据传输对象
|
||||
pojo/vo/ → 视图对象
|
||||
```
|
||||
|
||||
**目的**：分离关注点，清晰职责
|
||||
**问题**：层级过多，不够彻底（缺少聚合根、值对象等核心概念）
|
||||
|
||||
### 4. 微服务思想（部分）
|
||||
|
||||
```
|
||||
每个 module 独立：controller + service + mapper + pojo
|
||||
```
|
||||
|
||||
**目的**：为将来拆分成微服务做准备
|
||||
**问题**：单体架构下过度设计
|
||||
|
||||
## 五、为什么会这样设计？
|
||||
|
||||
### 商业框架的通病
|
||||
|
||||
BladeX 是一个**商业企业级框架**，它的设计目标是：
|
||||
|
||||
1. **功能全面** → 覆盖各种场景
|
||||
2. **快速开发** → 内置大量模板代码
|
||||
3. **灵活扩展** → 支持多种架构演进
|
||||
|
||||
但这导致：
|
||||
- ✅ 功能多 → ❌ 结构复杂
|
||||
- ✅ 封装好 → ❌ 理解成本高
|
||||
- ✅ 可扩展 → ❌ 过度设计
|
||||
|
||||
### 类比：豪华汽车 vs 普通汽车
|
||||
|
||||
```
|
||||
传统 Spring Boot 项目 = 普通家用车
|
||||
- 结构简单，容易理解
|
||||
- 功能够用，性价比高
|
||||
- 维护方便
|
||||
|
||||
BladeX 框架 = 豪华商务车
|
||||
- 功能丰富，配置复杂
|
||||
- 适合企业场景
|
||||
- 需要专业维护
|
||||
```
|
||||
|
||||
## 六、如何理解这个架构？
|
||||
|
||||
### 思维模型：三层金字塔
|
||||
|
||||
```
|
||||
┌──────────────┐
|
||||
│ modules │ 业务层（核心）
|
||||
│ 业务模块 │ - 专注业务逻辑
|
||||
└──────────────┘ - 模块独立
|
||||
▲
|
||||
│
|
||||
┌──────────────┐
|
||||
│ job │ 功能层（辅助）
|
||||
│ 定时任务 │ - 定时调度
|
||||
└──────────────┘ - 后台任务
|
||||
▲
|
||||
│
|
||||
┌──────────────┐
|
||||
│ common │ 基础层（通用）
|
||||
│ 通用工具 │ - 工具类
|
||||
└──────────────┘ - 配置
|
||||
- 常量
|
||||
```
|
||||
|
||||
### 核心原则
|
||||
|
||||
1. **common** = 真正通用的、跨模块的
|
||||
2. **modules** = 业务核心，模块独立
|
||||
3. **job** = 定时任务的特殊模块
|
||||
|
||||
## 七、与标准架构的映射
|
||||
|
||||
如果你熟悉传统架构，可以这样理解：
|
||||
|
||||
| BladeX 架构 | 传统架构 | 说明 |
|
||||
|------------|---------|------|
|
||||
| `common/utils/` | `util/` | 工具类 |
|
||||
| `common/constant/` | `constant/` | 常量 |
|
||||
| `common/config/` | `config/` | 配置 |
|
||||
| `modules/martial/controller/` | `controller/` | 控制器 |
|
||||
| `modules/martial/service/` | `service/` | 服务 |
|
||||
| `modules/martial/mapper/` | `mapper/` | 数据访问 |
|
||||
| `modules/martial/pojo/entity/` | `entity/` | 实体（多了pojo层） |
|
||||
| `modules/martial/pojo/dto/` | `dto/` | DTO（多了pojo层） |
|
||||
| `modules/martial/pojo/vo/` | `vo/` | VO（多了pojo层） |
|
||||
|
||||
**关键差异**：
|
||||
- ✅ 传统：一个 `entity/` 目录
|
||||
- ❌ BladeX：`modules/martial/pojo/entity/`（多两层）
|
||||
|
||||
## 八、实际开发时如何思考？
|
||||
|
||||
### 场景1：我要加个工具类
|
||||
|
||||
```java
|
||||
❓ 放哪里？
|
||||
|
||||
问：这个工具类是给多个模块用的吗？
|
||||
✅ 是 → common/utils/XxxUtil.java
|
||||
❌ 否 → modules/martial/utils/XxxUtil.java（在模块内部创建utils目录）
|
||||
```
|
||||
|
||||
### 场景2：我要加个实体类
|
||||
|
||||
```java
|
||||
❓ 放哪里？
|
||||
|
||||
固定位置：
|
||||
modules/martial/pojo/entity/Xxx.java
|
||||
|
||||
（虽然多了pojo层，但保持一致）
|
||||
```
|
||||
|
||||
### 场景3：我要加个配置类
|
||||
|
||||
```java
|
||||
❓ 放哪里？
|
||||
|
||||
问：这个配置是全局的吗？
|
||||
✅ 是（如：Redis配置） → common/config/RedisConfig.java
|
||||
❌ 否（如：武术评分规则） → modules/martial/config/ScoringConfig.java
|
||||
```
|
||||
|
||||
### 场景4：我要加个Controller
|
||||
|
||||
```java
|
||||
❓ 放哪里？
|
||||
|
||||
固定位置：
|
||||
modules/martial/controller/XxxController.java
|
||||
|
||||
（不需要思考，统一放这里）
|
||||
```
|
||||
|
||||
## 九、总结
|
||||
|
||||
### 现状
|
||||
|
||||
这是一个**混合式架构**的商业框架项目：
|
||||
- ✅ 功能全面，开箱即用
|
||||
- ⚠️ 结构复杂，理解成本高
|
||||
- ❌ 设计不够统一，有些"乱"
|
||||
|
||||
### 建议
|
||||
|
||||
1. **不要试图改造整体架构**
|
||||
- 成本太高
|
||||
- 可能破坏框架功能
|
||||
|
||||
2. **理解规则，遵循规则**
|
||||
- 虽然不完美，但有规律可循
|
||||
- 保持代码风格一致
|
||||
|
||||
3. **专注业务**
|
||||
- 核心工作在 `modules/martial/`
|
||||
- 不需要关心其他模块细节
|
||||
|
||||
4. **参考现有代码**
|
||||
- 看 `modules/system/` 的实现
|
||||
- 模仿其结构和写法
|
||||
|
||||
### 核心理念
|
||||
|
||||
**把它当作"带框架的项目"而不是"纯净的项目"**
|
||||
- 框架部分：auth, system, resource, desk, develop, common, job
|
||||
- 业务部分：modules/martial/ （这是你要关注的）
|
||||
|
||||
---
|
||||
|
||||
**下一步**：查看《开发指南.md》，学习如何在这个架构下高效开发。
|
||||
Reference in New Issue
Block a user