Files

n72595987@gmail.com 0b908b2f08 docs: 完善文档内容，更新地址和路径信息

更新内容：

前后端架构说明.md：
- 更新项目状态说明，反映 martial-web 已存在
- 添加开发环境和生产环境架构对比图
- 添加详细的请求流程示例
- 更新访问地址为域名（生产环境）
- 更新开发方式说明，包含本地全栈开发
- 完善环境对比表，包含开发和生产地址
- 强调 martial-web 项目而非商业版 Saber

开发指南.md：
- 更新 SQL 脚本路径：doc/sql/ → database/

总体改进：
- 所有生产环境地址使用域名替代 IP:端口
- 反映当前项目的实际状态（前后端都已部署）
- 提供开发和生产两种环境的清晰对比
- 帮助开发者快速理解完整的系统架构

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

2025-11-30 11:36:51 +08:00

19 KiB

Raw Blame History

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（主业务 API）
前端项目：martial-web（Vue 3 管理系统，独立仓库）

两个项目均已部署到生产环境，并配置了自动化 CI/CD 部署流程。

二、前端管理系统

2.1 当前项目前端：martial-web

martial-web 是本项目配套的 Vue 3 管理系统，基于 Element Plus 和 Avue 构建。

项目信息：

仓库位置：/remote_dev/martial/martial-web（独立仓库）
技术栈：Vue 3 + Vite + Element Plus + Avue
生产地址：https://martial.johnsion.club
开发端口：5173

主要功能：

🏠 仪表盘：数据统计、图表展示
👥 用户管理：用户增删改查、角色分配
🔐 权限管理：角色管理、菜单管理、权限分配
🏢 组织架构：部门管理、岗位管理
📋 系统管理：字典管理、参数配置、日志查看
🗂️ 资源管理：文件上传、OSS 配置
⚙️ 开发工具：代码生成器、数据源管理
🥋 业务功能：武术比赛管理（核心业务）

2.2 技术栈

前端框架：Vue 3.4 (Composition API)
UI 组件：Element Plus
表单/表格：Avue
状态管理：Vuex 4
路由：Vue Router 4
构建工具：Vite 5
HTTP 库：Axios
样式：Sass/SCSS

2.3 访问地址

开发环境：

本地开发：http://localhost:5173
API 代理：通过 Vite proxy 转发到后端

生产环境：

前端地址：https://martial.johnsion.club
API 代理：通过 Nginx 转发到后端

2.4 BladeX 官方前端 Saber（可选）

BladeX 框架还提供商业版本的官方前端 Saber（需要购买授权）：

官方仓库：

Gitee: https://gitee.com/smallc/Saber
GitHub: https://github.com/chillzhuang/Saber

与 martial-web 的关系：

martial-web：本项目自主开发的管理系统
Saber：BladeX 官方提供的商业版管理系统
两者都可以对接 martial-master 后端，功能类似

三、前后端交互流程

3.1 开发环境架构

┌─────────────────────────────────────────────────────────────┐
│                    用户浏览器                                  │
└──────────────┬──────────────────────────────────────────────┘
               │
               │ http://localhost:5173
               ▼
┌──────────────────────────────────────────────────────────────┐
│            martial-web 前端 (Vue 3 + Vite)                    │
│  - 登录页面                                                    │
│  - 仪表盘                                                      │
│  - 用户管理                                                    │
│  - 权限管理                                                    │
│  - 武术比赛管理（调用后端 API）                                │
└──────────────┬───────────────────────────────────────────────┘
               │
               │ Vite Dev Proxy
               │ /api → http://localhost:8123/api
               │ /blade-auth → http://localhost:8123/blade-auth
               │ /blade-system → http://localhost:8123/blade-system
               ▼
┌──────────────────────────────────────────────────────────────┐
│         martial-master 后端 (Spring Boot)                     │
│  http://localhost:8123                                        │
│                                                                │
│  ├── /blade-auth/**      → 认证模块                           │
│  ├── /blade-system/**    → 系统管理                           │
│  ├── /blade-desk/**      → 仪表盘                             │
│  ├── /blade-resource/**  → 资源管理                           │
│  ├── /blade-develop/**   → 开发工具                           │
│  └── /api/martial/**     → 武术比赛（核心业务）               │
└──────────────┬───────────────────────────────────────────────┘
               │
               ▼
        ┌──────────────┐
        │ MySQL 33066  │
        │ Redis 63379  │
        └──────────────┘

3.2 生产环境架构

┌─────────────────────────────────────────────────────────────┐
│                    互联网用户                                  │
└──────────────┬──────────────────────────────────────────────┘
               │
               │ HTTPS (Cloudflare CDN)
               ▼
┌──────────────────────────────────────────────────────────────┐
│            Caddy 反向代理（80/443，自动 HTTPS）                │
│  - martial.johnsion.club → localhost:5173                    │
│  - martial-api.johnsion.club → localhost:8123                │
│  - martial-doc.johnsion.club → localhost:8123/doc.html       │
│  - martial-ci.johnsion.club → localhost:8080                 │
└────────┬─────────────────────────────┬───────────────────────┘
         │                             │
         │ 前端请求                     │ API 请求
         ▼                             ▼
┌──────────────────────┐      ┌───────────────────────────────┐
│  martial-frontend    │      │   martial-backend             │
│  (Nginx 容器)         │      │   (Spring Boot)               │
│  端口: 5173:80        │      │   端口: 8123                   │
│                      │      │                               │
│  静态文件服务         │      │   ├── /blade-auth/**          │
│  ├── index.html      │      │   ├── /blade-system/**        │
│  ├── assets/         │      │   ├── /blade-desk/**          │
│  └── ...             │      │   ├── /blade-resource/**      │
│                      │      │   ├── /blade-develop/**       │
│  Nginx 反向代理       │      │   └── /api/martial/**         │
│  └── /blade-auth/**  │──────┘                               │
│      /blade-system/**│      ┌───────────────────────────────┘
│      /api/**         │──────┘
│      → 172.21.0.1:8123                    │
└──────────────────────┘                     │
         │                                   │
         └────────────┬──────────────────────┘
                      │
                      │ Docker Network: martial_martial-network
                      ▼
               ┌──────────────┐
               │ martial-mysql│ (端口: 3306)
               │ martial-redis│ (端口: 6379)
               └──────────────┘

3.3 请求流程示例

用户登录流程：

1. 用户访问 https://martial.johnsion.club
   ↓
2. Caddy 转发到 frontend 容器 (localhost:5173)
   ↓
3. Nginx 返回 Vue 应用 (index.html)
   ↓
4. 前端 JS 发起登录请求: POST /blade-auth/oauth/token
   ↓
5. Nginx 代理到后端: http://172.21.0.1:8123/blade-auth/oauth/token
   ↓
6. Spring Boot 认证模块处理登录
   ↓
7. 返回 Token 给前端
   ↓
8. 前端存储 Token，后续请求携带 Blade-Auth header

业务数据请求流程：

1. 前端请求比赛列表: GET /api/martial/competition/list
   ↓
2. Nginx 代理: http://172.21.0.1:8123/api/martial/competition/list
   ↓
3. Spring Boot martial 模块查询数据库
   ↓
4. 返回 JSON 数据
   ↓
5. 前端展示数据

四、项目访问方式

方式一：生产环境在线访问 ✅

适合场景：

直接使用已部署的完整系统
演示和测试
前端开发（对接生产 API）

访问地址：

前端系统：https://martial.johnsion.club
后端 API：https://martial-api.johnsion.club
API 文档：https://martial-doc.johnsion.club
CI/CD 平台：https://martial-ci.johnsion.club

默认账号：

用户名：admin
密码：admin
租户ID：000000

优点：

✅ 开箱即用，无需本地部署
✅ HTTPS 安全访问
✅ 完整的前后端功能
✅ 生产级别的性能

方式二：本地开发环境 ✅

适合场景：

后端功能开发
API 调试和测试
前端本地开发

启动后端：

cd /remote_dev/martial/martial-master
mvn spring-boot:run

访问地址：
- API Server: http://localhost:8123
- Swagger 文档: http://localhost:8123/doc.html
- Druid 监控: http://localhost:8123/druid

启动前端：

cd /remote_dev/martial/martial-web
npm run dev

访问地址：
- 前端系统: http://localhost:5173

优点：

✅ 可以调试代码
✅ 快速开发迭代
✅ 修改即时生效

方式三：仅使用 API 文档测试

适合场景：

后端 API 测试
接口调试
了解 API 规范

访问方式：

生产环境：

Knife4j API 文档：https://martial-doc.johnsion.club

直接调用 API：
POST https://martial-api.johnsion.club/blade-auth/oauth/token
GET  https://martial-api.johnsion.club/api/martial/competition/list

本地环境：

Knife4j API 文档：http://localhost:8123/doc.html

直接调用 API：
POST http://localhost:8123/blade-auth/token
GET  http://localhost:8123/api/martial/competition/list

优点：

✅ 无需前端，可以直接测试 API
✅ 适合后端开发和调试
✅ Swagger UI 提供可视化测试界面

缺点：

❌ 没有完整的管理界面
❌ 需要手动构造请求参数

方式四：使用第三方 API 工具

适合场景：

复杂 API 测试
批量接口测试
自动化测试

推荐工具：

Postman / Apifox / Insomnia

1. 先调用登录接口获取 Token：
   POST https://martial-api.johnsion.club/blade-auth/oauth/token
   Body: {
     "tenantId": "000000",
     "username": "admin",
     "password": "admin",
     "grant_type": "password",
     "scope": "all"
   }

2. 复制返回的 access_token

3. 在后续请求中添加 Header：
   Blade-Auth: bearer <access_token>

4. 调用业务接口：
   GET https://martial-api.johnsion.club/api/martial/competition/list

VS Code REST Client 扩展

### 1. 登录获取 Token
POST https://martial-api.johnsion.club/blade-auth/oauth/token
Content-Type: application/json

{
  "tenantId": "000000",
  "username": "admin",
  "password": "admin",
  "grant_type": "password",
  "scope": "all"
}

### 2. 调用业务接口
GET https://martial-api.johnsion.club/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 前端源码？

如果您有 BladeX 授权，从官方仓库获取
如果是开源版本，部分功能可能不可用
可以联系 BladeX 官方获取试用版

Q3: 没有 Saber 可以开发吗？

A: 可以！

使用 Knife4j API 文档测试：http://localhost:8123/doc.html
使用 Postman/Apifox 调用 API
自己开发前端（任何技术栈都可以）

Q4: 如何查看系统运行状态？

查看日志：tail -f application.log
健康检查：http://localhost:8123/actuator/health
Druid 监控：http://localhost:8123/druid
Knife4j 文档：http://localhost:8123/doc.html

Q5: 这个项目是微服务吗？

A: 当前是单体应用（Monolithic），但使用了模块化设计。如果需要，可以升级为微服务架构。

七、推荐的开发方式

开发环境配置

本地全栈开发：

# 终端 1: 启动后端
cd /remote_dev/martial/martial-master
mvn spring-boot:run

# 终端 2: 启动前端
cd /remote_dev/martial/martial-web
npm run dev

# 访问
前端：http://localhost:5173
后端：http://localhost:8123
文档：http://localhost:8123/doc.html

仅后端开发：

# 启动后端
cd /remote_dev/martial/martial-master
mvn spring-boot:run

# 使用以下方式测试
1. Knife4j 文档：http://localhost:8123/doc.html
2. Postman/Apifox
3. 对接生产前端：https://martial.johnsion.club（配置 API 代理到 localhost:8123）

仅前端开发：

# 启动前端
cd /remote_dev/martial/martial-web
npm run dev

# 对接生产后端
在 vite.config.js 中配置 proxy 指向：
https://martial-api.johnsion.club

数据库操作

开发环境：

# 使用 Navicat/DBeaver 连接
Host: 127.0.0.1
Port: 33066
Database: martial_db
Username: root
Password: WtcSecure901faf1ac4d32e2bPwd

生产环境（仅运维人员）：

# 通过 Docker 容器访问
ssh root@154.30.6.21
docker exec -it martial-mysql mysql -uroot -pWtcSecure901faf1ac4d32e2bPwd martial_db

八、总结

环境对比表

组件	开发环境	生产环境	说明
后端 API	http://localhost:8123	https://martial-api.johnsion.club	Spring Boot 应用
API 文档	http://localhost:8123/doc.html	https://martial-doc.johnsion.club	Knife4j 文档
Druid 监控	http://localhost:8123/druid	https://martial-api.johnsion.club/druid	数据库监控
前端系统	http://localhost:5173	https://martial.johnsion.club	Vue 3 管理系统
CI/CD 平台	-	https://martial-ci.johnsion.club	Drone CI/CD
MySQL	127.0.0.1:33066	容器内部	数据库
Redis	127.0.0.1:63379	容器内部	缓存

项目特点

架构设计：

✅ 前后端完全分离
✅ 后端提供 RESTful API
✅ 前端独立部署（可替换为任何技术栈）
✅ 单体应用，模块化设计
✅ 支持升级为微服务架构

部署方式：

✅ 生产环境自动化 CI/CD（Drone）
✅ Docker 容器化部署
✅ Caddy 自动 HTTPS
✅ 前后端独立扩展

开发体验：

✅ 本地开发无需依赖生产环境
✅ Vite 热更新，开发效率高
✅ Swagger 文档完整，接口调试方便
✅ 支持调试和日志查看

关键点

前端系统已存在：martial-web 项目（Vue 3），不是 Saber
生产环境可用：https://martial.johnsion.club 直接访问完整系统
本地开发便捷：后端 8123 端口，前端 5173 端口
API 文档齐全：Knife4j 提供完整的 API 测试界面
自动化部署：推送到 main 分支自动触发 CI/CD

开发建议：

使用生产环境了解系统功能
本地启动后端进行业务开发
使用 Knife4j 文档测试接口
前端对接本地或生产 API 均可
开发完成后推送到 dev 分支，测试通过后合并到 main 触发自动部署

19 KiB Raw Blame History Unescape Escape

BladeX 完整架构说明

一、BladeX 完整系统架构

当前项目状态

二、前端管理系统

2.1 当前项目前端：martial-web

2.2 技术栈

2.3 访问地址

2.4 BladeX 官方前端 Saber（可选）

三、前后端交互流程

3.1 开发环境架构

3.2 生产环境架构

3.3 请求流程示例

四、项目访问方式

方式一：生产环境在线访问 ✅

方式二：本地开发环境 ✅

方式三：仅使用 API 文档测试

方式四：使用第三方 API 工具

五、模块启动管理

5.1 单体架构（当前项目）

5.2 微服务架构（可选升级）

六、常见疑问解答

Q1: 为什么没有找到管理界面？

Q2: 如何获取 Saber 前端源码？

Q3: 没有 Saber 可以开发吗？

Q4: 如何查看系统运行状态？

Q5: 这个项目是微服务吗？

七、推荐的开发方式

开发环境配置

数据库操作

八、总结

环境对比表

项目特点

关键点

19 KiB

Raw Blame History