# BladeX 完整架构说明 ## 一、BladeX 完整系统架构 BladeX 是一个**前后端分离**的企业级微服务架构，完整的系统包含多个项目： ``` BladeX 完整架构 ├── 后端项目（当前） │ ├── martial-master # Spring Boot 后端 API（当前项目） │ └── martial-tool # BladeX 框架核心（依赖库） │ ├── 前端项目（独立仓库） │ ├── Saber (推荐) # Vue 3 + Element Plus 管理后台 ⭐ │ └── Sword (旧版) # Vue 2 + Avue 管理后台（已不推荐） │ └── 可选组件 ├── BladeX-Auth # 独立认证中心（微服务版） ├── BladeX-Gateway # 网关服务（微服务版） └── BladeX-Register # 注册中心（Nacos） ``` ### 当前项目状态 根据 `CLAUDE.md` 的说明： ``` "The frontend is a separate Vue.js project (not in this repository)" ``` **当前您手上只有后端项目** `martial-master`，前端管理系统是独立的项目。 --- ## 二、前端管理系统 - Saber ### 2.1 Saber 是什么？ **Saber** 是 BladeX 官方的 Vue 3 管理后台系统，提供可视化的管理界面。 **主要功能**： - 🏠 **仪表盘**：数据统计、图表展示 - 👥 **用户管理**：用户增删改查、角色分配 - 🔐 **权限管理**：角色管理、菜单管理、权限分配 - 🏢 **组织架构**：部门管理、岗位管理 - 📋 **系统管理**：字典管理、参数配置、日志查看 - 🗂️ **资源管理**：文件上传、OSS 配置 - ⚙️ **开发工具**：代码生成器、数据源管理 - 🥋 **业务功能**：武术比赛管理（根据菜单配置） ### 2.2 Saber 技术栈 ``` 前端框架：Vue 3 UI 组件：Element Plus 状态管理：Pinia 路由：Vue Router 4 构建工具：Vite HTTP 库：Axios ``` ### 2.3 Saber 项目地址 **官方仓库**（需要授权访问）： ``` Gitee: https://gitee.com/smallc/Saber GitHub: https://github.com/chillzhuang/Saber ``` **注意**：BladeX 是商业框架，完整源码需要购买授权。 ### 2.4 Saber 运行端口 根据配置文件中的线索： ```yaml # application-dev.yml blade: token: domain: http://127.0.0.1:1888 # 前端地址 ``` **默认端口**：`1888`（开发环境） --- ## 三、前后端交互流程 ``` ┌─────────────────────────────────────────────────────────────┐ │ 用户浏览器 │ └──────────────┬──────────────────────────────────────────────┘ │ │ http://localhost:1888 ▼ ┌──────────────────────────────────────────────────────────────┐ │ Saber 前端 (Vue 3) │ │ - 登录页面 │ │ - 仪表盘 │ │ - 用户管理 │ │ - 权限管理 │ │ - 武术比赛管理（调用后端 API） │ └──────────────┬───────────────────────────────────────────────┘ │ │ HTTP 请求（JSON） │ POST /blade-auth/token │ GET /blade-system/user/list │ GET /api/martial/competition/list ▼ ┌──────────────────────────────────────────────────────────────┐ │ martial-master 后端 (Spring Boot) │ │ http://localhost:8123 │ │ │ │ ├── /blade-auth/** → 认证模块 │ │ ├── /blade-system/** → 系统管理 │ │ ├── /blade-desk/** → 仪表盘 │ │ ├── /blade-resource/** → 资源管理 │ │ ├── /blade-develop/** → 开发工具 │ │ └── /api/martial/** → 武术比赛（您的业务） │ └──────────────┬───────────────────────────────────────────────┘ │ ▼ ┌──────────────┐ │ MySQL │ │ Redis │ └──────────────┘ ``` --- ## 四、当前项目的使用方式 ### 方式一：仅使用 API（当前可用）✅ **适合场景**： - 前端单独开发 - 移动端开发 - API 集成测试 **访问方式**： ``` Knife4j API 文档：http://localhost:8123/doc.html 直接调用 API： POST http://localhost:8123/blade-auth/token GET http://localhost:8123/api/martial/competition/list ``` **优点**： - ✅ 无需前端，可以直接测试 API - ✅ 适合后端开发和调试 **缺点**： - ❌ 没有可视化界面 - ❌ 需要手动构造 HTTP 请求 --- ### 方式二：搭配 Saber 前端（需要获取源码） **步骤 1：获取 Saber 源码** 如果您有 BladeX 授权，可以从官方获取 Saber 源码： ```bash # Gitee git clone https://gitee.com/smallc/Saber.git # GitHub git clone https://github.com/chillzhuang/Saber.git ``` **步骤 2：配置后端地址** ```javascript // Saber/src/config/website.js export default { // 后端 API 地址 apiUrl: 'http://localhost:8123', // Token 存储键 tokenHeader: 'Blade-Auth', // 其他配置... } ``` **步骤 3：安装依赖并启动** ```bash cd Saber # 安装依赖 npm install # 或 yarn install # 启动开发服务器 npm run dev # 或 yarn dev ``` **步骤 4：访问** ``` 浏览器访问：http://localhost:1888 默认账号： 用户名：admin 密码：admin ``` **步骤 5：使用管理后台** 登录后，您可以在 Saber 管理后台中： - 📊 查看仪表盘数据 - 👥 管理用户和角色 - 📋 配置菜单权限 - 🥋 使用武术比赛管理功能（需要先配置菜单） --- ### 方式三：使用第三方 API 工具（临时方案） 如果暂时没有 Saber 源码，可以使用： **Postman / Apifox / Insomnia** ``` 1. 先调用登录接口获取 Token： POST http://localhost:8123/blade-auth/token Body: { "tenantId": "000000", "username": "admin", "password": "admin", "grant_type": "captcha", "scope": "all" } 2. 复制返回的 access_token 3. 在后续请求中添加 Header： Blade-Auth: bearer 4. 调用业务接口： GET http://localhost:8123/api/martial/competition/list ``` **VS Code REST Client 扩展** ```http ### 1. 登录获取 Token POST http://localhost:8123/blade-auth/token Content-Type: application/json { "tenantId": "000000", "username": "admin", "password": "admin", "grant_type": "captcha", "scope": "all" } ### 2. 调用业务接口 GET http://localhost:8123/api/martial/competition/list Blade-Auth: bearer {{token}} ``` --- ## 五、模块启动管理 ### 5.1 单体架构（当前项目） **当前项目是单体应用**，所有模块在一个进程中运行： ``` java -jar blade-api.jar 启动后，所有模块同时可用： ✅ auth 模块 ✅ system 模块 ✅ resource 模块 ✅ desk 模块 ✅ develop 模块 ✅ martial 模块 ✅ job 模块 ``` **没有独立的模块启动管理**，因为不是微服务架构。 --- ### 5.2 微服务架构（可选升级） 如果升级到微服务版本，架构会变成： ``` BladeX 微服务架构 ├── BladeX-Register (Nacos) # 注册中心，管理所有服务 ├── BladeX-Gateway # 网关服务 ├── BladeX-Auth # 认证服务 ├── BladeX-System # 系统服务 ├── BladeX-Resource # 资源服务 ├── BladeX-Desk # 工作台服务 └── Martial-Service # 武术比赛服务（您的业务） ``` **此时会有管理界面**： **Nacos 控制台**： ``` 地址：http://localhost:8848/nacos 功能： - 查看所有注册的服务 - 服务健康检查 - 配置管理 - 服务上下线 ``` **Sentinel 控制台**（可选）： ``` 地址：http://localhost:8858 功能： - 流量控制 - 熔断降级 - 系统负载保护 ``` **Spring Boot Admin**（可选）： ``` 地址：http://localhost:7002 功能： - 监控所有 Spring Boot 应用 - 查看日志 - 查看 JVM 信息 - 健康检查 ``` --- ## 六、常见疑问解答 ### Q1: 为什么没有找到管理界面？ **A**: 当前项目是**纯后端 API 项目**，前端管理系统（Saber）是独立的项目，需要单独获取和部署。 ### Q2: 如何获取 Saber 前端源码？ **A**: - 如果您有 BladeX 授权，从官方仓库获取 - 如果是开源版本，部分功能可能不可用 - 可以联系 BladeX 官方获取试用版 ### Q3: 没有 Saber 可以开发吗？ **A**: 可以！ - 使用 Knife4j API 文档测试：http://localhost:8123/doc.html - 使用 Postman/Apifox 调用 API - 自己开发前端（任何技术栈都可以） ### Q4: 如何查看系统运行状态？ **A**: - 查看日志：`tail -f application.log` - 健康检查：http://localhost:8123/actuator/health - Druid 监控：http://localhost:8123/druid - Knife4j 文档：http://localhost:8123/doc.html ### Q5: 这个项目是微服务吗？ **A**: 当前是**单体应用**（Monolithic），但使用了模块化设计。如果需要，可以升级为微服务架构。 --- ## 七、推荐的开发方式 ### 当前阶段（无 Saber） ``` 1. 后端开发： - 在 VS Code 中开发业务逻辑 - 使用 F5 调试运行 2. 接口测试： - 使用 Knife4j：http://localhost:8123/doc.html - 使用 Postman/Apifox 3. 数据库操作： - 使用 Navicat/DBeaver 连接 MySQL - 执行 SQL 查看数据 ``` ### 有 Saber 前端时 ``` 1. 启动后端： cd martial-master mvn spring-boot:run 2. 启动前端： cd Saber npm run dev 3. 访问管理后台： http://localhost:1888 4. 全栈开发： - 后端改代码 → 前端调用 API - 前端页面 → 调用后端接口 ``` --- ## 八、总结 | 组件 | 状态 | 地址 | 说明 | |------|------|------|------| | **后端 API** | ✅ 有 | http://localhost:8123 | 当前项目 | | **API 文档** | ✅ 有 | http://localhost:8123/doc.html | Knife4j | | **Druid 监控** | ✅ 有 | http://localhost:8123/druid | 数据库监控 | | **前端管理系统** | ❌ 无 | http://localhost:1888 | Saber（需单独获取） | | **模块管理界面** | ❌ 无 | - | 单体应用，无需管理 | **关键点**： - ✅ 后端可以独立运行和开发 - ✅ 使用 Knife4j 可以完成所有测试 - ❌ 如需可视化管理界面，需要部署 Saber 前端 - ❌ 单体架构下没有"模块启动管理"的概念 --- **建议**： 1. 现阶段专注后端 API 开发 2. 使用 Knife4j 测试接口 3. 如需前端，可以自己用 Vue/React 开发，或等待获取 Saber 源码