# xmcx

**Repository Path**: freedomflow/xmcx

## Basic Information

- **Project Name**: xmcx
- **Description**: No description available
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-02
- **Last Updated**: 2026-05-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# XMCX 微服务平台

基于 Spring Cloud Alibaba + Vue 3 的企业级微服务架构平台

## 项目简介

XMCX (XMCX Microservice Platform) 是一个基于 Spring Cloud Alibaba 技术栈构建的企业级微服务平台，采用前后端分离架构，提供统一的认证授权、网关路由、服务治理等功能。

## 技术栈

### 后端技术

| 技术 | 版本 | 说明 |
|------|------|------|
| Java | 17 | 编程语言 |
| Spring Boot | 3.2.4 | 基础框架 |
| Spring Cloud | 2023.0.1 | 微服务框架 |
| Spring Cloud Alibaba | 2023.0.1.0 | 阿里微服务生态 |
| MyBatis Plus | 3.5.5 | ORM 框架 |
| Nacos | 2.3.0 | 服务注册与配置中心 |
| Knife4j | 4.4.0 | API 文档 |
| MySQL | 8.0.33 | 关系型数据库 |
| Redis | 7 | 缓存 |
| JWT | 0.12.3 | 认证授权 |
| Elasticsearch | 7.17.16 | 搜索引擎 |
| RocketMQ | - | 消息队列 |
| XXL-Job | - | 分布式任务调度 |

### 前端技术

| 技术 | 版本 | 说明 |
|------|------|------|
| Vue | 3.4.21 | 前端框架 |
| Vue Router | 4.3.0 | 路由管理 |
| Pinia | 2.1.7 | 状态管理 |
| Vite | 5.2.8 | 构建工具 |
| Element Plus | 2.6.3 | UI 组件库 |
| Ant Design Vue | 4.2.0 | UI 组件库 |
| Axios | 1.6.8 | HTTP 客户端 |
| JSEncrypt | 3.3.2 | 加密库 |

## 项目结构

```
xmcx/
├── backend/                # 后端项目
│   ├── xmcx-framework/    # 框架层
│   │   ├── xmcx-gateway/  # 网关服务
│   │   ├── xmcx-common/   # 公共模块
│   │   ├── xmcx-api/      # API 接口定义
│   │   ├── xmcx-redis/    # Redis 封装
│   │   ├── xmcx-nacos/    # Nacos 封装
│   │   ├── xmcx-oauth/    # OAuth 认证
│   │   ├── xmcx-log/      # 日志模块
│   │   ├── xmcx-knife4j/  # Knife4j 配置
│   │   ├── xmcx-rocketmq/ # RocketMQ 封装
│   │   ├── xmcx-elasticsearch/ # ES 封装
│   │   ├── xmcx-mail/     # 邮件服务
│   │   └── xmcx-xxljob/   # XXL-Job 封装
│   └── xmcx-biz/          # 业务层
│       ├── xmcx-admin/    # 后台管理服务
│       └── xmcx-auth/     # 认证授权服务
├── frontend/              # 前端项目
│   ├── src/               # 源代码
│   ├── public/            # 静态资源
│   └── package.json       # 依赖配置
├── database/              # 数据库脚本
│   └── xmcx-complete.sql # 完整完整初始化脚本
├── docker-compose.yml     # Docker 编排
├── pom.xml                # Maven 父工程
└── README.md              # 项目说明
```

## 快速开始

### 环境要求

- JDK 17+
- Maven 3.8+
- Node.js 18+
- MySQL 8.0+
- Redis 7+
- Docker & Docker Compose (可选)

### 使用 Docker Compose 启动（推荐）

```bash
# 1. 克隆项目
git clone <repository-url>
cd xmcx

# 2. 启动所有服务
docker-compose up -d

# 3. 查看服务状态
docker-compose ps

# 4. 查看日志
docker-compose logs -f

# 5. 停止服务
docker-compose down
```

### 本地开发

#### 后端启动

```bash
# 1. 启动基础设施
docker-compose up -d mysql redis nacos

# 2. 编译项目
cd backend
mvn clean package -DskipTests

# 3. 启动服务
# Gateway
java -jar xmcx-framework/xmcx-gateway/target/xmcx-gateway-1.0.0-SNAPSHOT.jar

# Auth
java -jar xmcx-biz/xmcx-auth/target/xmcx-auth-1.0.0-SNAPSHOT.jar

# Admin
java -jar xmcx-biz/xmcx-admin/target/xmcx-admin-1.0.0-SNAPSHOT.jar
```

#### 前端启动

```bash
# 1. 安装依赖
cd frontend
npm install

# 2. 启动开发服务器
npm run dev

# 3. 构建生产版本
npm run build
```

## 服务访问

| 服务 | 地址 | 说明 |
|------|------|------|
| Gateway | http://localhost:8081 | API 网关 |
| Gateway API 文档聚合 | http://localhost:8081/doc.html | 所有微服务 API 文档聚合 |
| Admin API 文档 | http://localhost:9002/doc.html | Knife4j 文档 |
| Auth API 文档 | http://localhost:9001/doc.html | Knife4j 文档 |
| MySQL | localhost:3306 | 数据库 |
| Redis | localhost:6379 | 缓存 |
| Nacos | http://localhost:8848/nacos | 服务注册中心 (nacos/nacos) |

**默认账号**: admin / admin123

### API 文档聚合

平台通过网关统一聚合所有微服务的 API 文档：

1. **访问聚合文档**: `http://localhost:8081/doc.html`
2. **切换服务**: 在文档页面顶部的下拉菜单中选择不同的微服务
3. **查看接口**: 选择服务后可查看该服务的所有 API 接口
4. **在线测试**: 支持在文档页面直接测试 API 接口

**文档分组**:
- **xmcx-auth**: 认证授权服务
- **xmcx-admin**: 后台管理服务

各微服务独立配置，通过网关统一访问，方便开发和调试。

## 核心功能

### 后台管理 (Admin)

- 用户管理
- 角色管理
- 菜单管理
- 应用管理
- 审计日志

### 认证授权 (Auth)

- JWT 令牌生成与验证
- 用户登录/登出
- 权限验证
- 刷新令牌

### 网关服务 (Gateway)

- 统一路由
- 负载均衡
- 熔断降级
- 限流保护

## 数据库

数据库初始化脚本位于 `database/xmcx-complete.sql`，包含：

- 表结构定义
- 初始数据
- 默认管理员账号

使用 Docker Compose 启动时会自动初始化。

手动初始化：

```bash
docker exec -i xmcx-mysql mysql -uroot -proot xmcx < database/xmcx-complete.sql
```

## 配置说明

### 环境变量

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| SPRING_PROFILES_ACTIVE | 运行环境 | prod |
| SPRING_CLOUD_NACOS_DISCOVERY_SERVER_ADDR | Nacos 地址 | localhost:8848 |
| SPRING_DATASOURCE_URL | 数据库连接 | jdbc:mysql://localhost:3306/xmcx |
| SPRING_DATASOURCE_USERNAME | 数据库用户名 | root |
| SPRING_DATASOURCE_PASSWORD | 数据库密码 | root |
| XMCX_REDIS_HOST | Redis 主机 | localhost |
| XMCX_REDIS_PORT | Redis 端口 | 6379 |
| XMCX_JWT_SECRET | JWT 密钥 | (需修改) |

### 修改配置

根据实际环境修改 `docker-compose.yml` 或各服务的 `application.yml` 配置文件。

## 开发指南

### 添加新服务

1. 在 `backend/xmcx-biz` 下创建新模块
2. 在 `pom.xml` 中添加模块声明
3. 引入 `xmcx-knife4j` 依赖
4. 在配置文件中设置服务标题和描述
5. 在 Gateway 的 `application.yml` 中添加路由配置
6. 在 Gateway 的配置中添加服务名称映射（可选）
7. 创建对应的 Dockerfile
8. 在 `docker-compose.yml` 中添加服务配置

**注意**：Knife4j 聚合会自动从 Gateway 路由定义中识别所有以 `xmcx-` 开头的微服务并自动聚合，无需手动配置。

### API 文档配置

#### 微服务配置

在微服务的 `application.yml` 中配置 Knife4j：

```yaml
xmcx:
  knife4j:
    enabled: true
    service-title: 认证授权服务
    service-desc: 提供用户登录、Token 管理、权限验证等功能
```

#### Gateway 服务名称映射配置

在 Gateway 的 `application.yml` 中配置服务名称映射（可选）：

```yaml
xmcx:
  knife4j:
    # 服务名称映射配置（不含 xmcx- 前缀）
    service-names:
      auth: 认证授权服务
      admin: 后台管理服务
      user: 用户服务
```

**说明**：
- 如果配置了映射，则使用配置的显示名称
- 如果未配置，则自动生成：首字母大写 + "服务"（如 Auth 服务）
- 新增服务时，只需在配置文件中添加一行映射即可，无需修改代码

#### Gateway 路由配置

在 Gateway 的 `application.yml` 中配置路由：

```yaml
spring:
  cloud:
    gateway:
      routes:
        - id: xmcx-auth-doc
          uri: lb://xmcx-auth
          predicates:
            - Path=/v3/api-docs/auth/**
          filters:
            - RewritePath=/v3/api-docs/auth/(?<segment>.*), /v3/api-docs/$\{segment}
```

**注意**：Knife4j 聚合会自动识别所有以 `xmcx-` 开头的微服务路由（排除网关自身），无需额外配置。

#### 在 Controller 中使用 Swagger 注解

```java
@RestController
@RequestMapping("/api/user")
@Tag(name = "用户管理", description = "用户管理相关接口")
public class UserController {
    
    @GetMapping("/{id}")
    @Operation(summary = "根据ID查询用户", description = "通过用户ID获取用户详细信息")
    @Parameter(name = "id", description = "用户ID", required = true)
    public User getById(@PathVariable Long id) {
        // ...
    }
}
```

### 访问 API 文档

1. **网关聚合文档**: `http://localhost:8081/doc.html`
   - 在页面顶部切换不同的服务分组
   - 查看所有微服务的接口文档

2. **单服务文档**: `http://localhost:{service-port}/doc.html`
   - 访问单个服务的独立文档

### 常用命令

```bash
# Maven 打包
mvn clean package -DskipTests

# Docker 查看日志
docker-compose logs -f [service-name]

# Docker 重启服务
docker-compose restart [service-name]

# 进入容器
docker exec -it [container-name] sh

# 数据库备份
docker exec xmcx-mysql mysqldump -uroot -proot xmcx > backup.sql
```

## 故障排查

### 端口冲突

确保以下端口未被占用：3306, 6379, 8848, 8081, 9001, 9002

### 服务启动失败

```bash
# 查看详细日志
docker-compose logs [service-name]

# 检查依赖服务
docker-compose ps

# 重启服务
docker-compose restart [service-name]
```

### 数据库连接问题

```bash
# 检查 MySQL 容器
docker ps | grep mysql

# 测试连接
docker exec -it xmcx-admin ping mysql
```

## 相关文档

- [Docker 部署文档](DOCKER.md)
- [数据库配置总结](DATABASE_DOCKER_SUMMARY.md)

## 贡献指南

欢迎提交 Issue 和 Pull Request。

## 许可证

MIT License