# mars

**Repository Path**: Marsfactory/mars

## Basic Information

- **Project Name**: mars
- **Description**: mars是一套全部开源的快速开发平台，毫无保留给个人及企业免费使用。
前端采用Vue、AntDesign-Vue。
后端采用Spring Boot3、SaToken、Mybatis-Flex、Redis & Jwt。
权限认证使用Jwt，支持多终端认证系统。
支持加载动态权限菜单，多方式轻松权限控制。
高效率开发，使用代码生成器可以一键生成前后端代码。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 32
- **Forks**: 15
- **Created**: 2020-12-15
- **Last Updated**: 2026-08-07

## Categories & Tags

**Categories**: backend

**Tags**: None

## README

# Mars Admin

Mars Admin 是一套前后端分离的企业级后台管理系统，后端基于 **Spring Boot 3 + MyBatis-Flex + Sa-Token**，前端基于 **Vue 3 + Vite + Ant Design Vue**（SoybeanAdmin 模板定制）。系统提供完整的 RBAC 权限、系统配置、文件存储、定时任务、日志审计、接口安全（签名 + SM4 加密）等能力，适合作为中后台管理脚手架或业务系统底座。

---

## 目录

- [功能特性](#功能特性)
- [技术栈](#技术栈)
- [项目结构](#项目结构)
- [环境要求](#环境要求)
- [快速开始](#快速开始)
- [默认账号](#默认账号)
- [配置说明](#配置说明)
- [功能模块](#功能模块)
- [安全机制](#安全机制)
- [接口文档](#接口文档)
- [开发指南](#开发指南)
- [部署说明](#部署说明)
- [数据库说明](#数据库说明)
- [常见问题](#常见问题)

---

## 功能特性

### 系统管理
- **用户管理** — 用户增删改查、角色/部门/岗位分配、密码重置、状态切换、导入导出
- **角色管理** — 菜单权限、按钮权限、数据权限（部门范围）
- **菜单管理** — 动态路由、目录/菜单/按钮三级、内嵌 iframe 外链
- **部门管理** — 树形组织架构
- **岗位管理** — 岗位维护与用户关联
- **字典管理** — 字典类型 + 字典数据，支持树形展示
- **参数设置** — 键值型系统参数（`sys_config`）
- **系统配置** — 14 个 Tab 分组配置（站点、注册、登录、密码、邮件、短信、文件、推送、第三方、支付、安全、小程序、公众号）
- **OSS 配置** — 多存储策略（本地 / MinIO / 阿里云 OSS / 腾讯云 COS）

### 系统运维
- **定时任务** — Quartz 调度，支持 Cron 表达式、常用表达式预设、立即执行、任务日志
- **操作日志** — AOP 记录增删改操作
- **登录日志** — 登录成功/失败审计
- **接口日志** — 全链路 API 请求记录 + ECharts 统计图表
- **系统监控** — CPU、内存、磁盘、JVM 等服务器信息（OSHI）
- **缓存监控** — Redis 键值查看与清理
- **连接池监控** — Druid 内置监控页
- **接口文档** — Knife4j（OpenAPI 3）在线文档

### 业务扩展（预留）
- **内容管理** — 活动、Banner、动态、话题等页面
- **C 端用户** — `tb_user` 及相关关注/收藏/设备表（Service 层已建，REST 待扩展）
- **即时通讯** — WebSocket 聊天（`ws://host/ws/chat`）

### 安全能力
- **Sa-Token** — JWT 风格 Bearer Token，Redis 持久化，支持多端登录策略
- **API 签名** — MD5 防篡改，可配置开关
- **SM4 响应加密** — 国密算法加密接口响应体
- **按钮级权限** — 前端 `v-auth` + 后端 `@SaCheckPermission`
- **生产只读模式** — 生产环境可开启演示只读拦截

---

## 技术栈

### 后端（mars-server）

| 类别 | 技术 | 版本 |
|------|------|------|
| 基础框架 | Spring Boot | 3.0.5 |
| 语言 | Java | 17 |
| ORM | MyBatis-Flex | 1.10.9 |
| 权限认证 | Sa-Token + Redis | 1.38.0 |
| 数据库 | MySQL + Druid 连接池 | 8.x / 1.2.23 |
| 缓存 | Spring Data Redis | — |
| 定时任务 | Spring Quartz | 内存 JobStore |
| 对象存储 | MinIO / Aliyun OSS / Tencent COS | — |
| API 文档 | Knife4j (OpenAPI 3) | 4.4.0 |
| 工具库 | Hutool、Fastjson2、OSHI、POI | — |

### 前端（mars-web）

| 类别 | 技术 | 版本 |
|------|------|------|
| 框架 | Vue | 3.5.13 |
| 构建 | Vite | 6.1.0 |
| 语言 | TypeScript | 5.7.3 |
| UI 组件 | Ant Design Vue | 4.2.6 |
| CSS | UnoCSS + Sass | 65.4.3 |
| 状态管理 | Pinia | 3.0.0 |
| 路由 | Vue Router + Elegant Router | 4.5.0 |
| HTTP | Axios（@sa/axios 封装） | — |
| 图表 | ECharts | 5.6.0 |
| 加密 | sm-crypto（SM4 解密） | — |
| 国际化 | vue-i18n | 11.1.1 |
| 包管理 | pnpm monorepo | ≥ 8.7 |

---

## 项目结构

```
mars/
├── mars-server/                 # 后端 Spring Boot 服务
│   ├── src/main/java/com/mars/admin/
│   │   ├── MarsApplication.java # 启动类
│   │   ├── common/              # 公共 DTO、枚举、VO
│   │   ├── framework/           # 框架层（配置、拦截器、AOP、OSS、Quartz）
│   │   └── modules/             # 业务模块
│   │       ├── auth/            # 认证登录
│   │       ├── base/            # 路由、文件、缓存、SQL 日志
│   │       ├── system/          # 系统管理（RBAC、配置、日志、任务等）
│   │       ├── chat/            # WebSocket 聊天
│   │       └── user/            # C 端用户（预留）
│   ├── src/main/resources/
│   │   ├── application.yml      # 主配置（profile 切换）
│   │   ├── application-dev.yml  # 开发环境
│   │   ├── application-prod.yml # 生产环境
│   │   └── mapper/              # MyBatis XML
│   ├── .env.example             # 环境变量示例
│   └── pom.xml
│
├── mars-web/                    # 前端 Vue 3 管理端
│   ├── src/
│   │   ├── views/               # 页面视图
│   │   │   ├── _builtin/        # 登录、403/404/500、iframe
│   │   │   ├── home/            # 首页
│   │   │   └── manage/          # 管理功能页
│   │   ├── router/              # 路由与守卫
│   │   ├── service/             # API 请求封装
│   │   ├── store/               # Pinia 状态
│   │   ├── utils/               # api-sign、api-encrypt 等
│   │   ├── layouts/             # 布局组件
│   │   └── locales/             # 国际化
│   ├── packages/                # pnpm 子包（axios、hooks、utils…）
│   ├── .env                     # 前端环境变量
│   ├── vite.config.ts
│   └── package.json
│
├── sql/
│   └── mars.sql                 # 完整数据库初始化脚本
│
└── README.md
```

---

## 环境要求

| 依赖 | 版本要求 |
|------|----------|
| JDK | 17+ |
| Maven | 3.6+ |
| Node.js | ≥ 18.12 |
| pnpm | ≥ 8.7 |
| MySQL | 8.0+ |
| Redis | 6.0+ |

---

## 快速开始

### 1. 初始化数据库

```bash
# 创建数据库
mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS mars DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# 导入初始化脚本
mysql -u root -p mars < sql/mars.sql
```

### 2. 启动 Redis

确保 Redis 运行在 `localhost:6379`，默认密码 `123456`（可在配置中修改）。

### 3. 启动后端

```bash
cd mars-server

# 可选：复制环境变量配置
cp .env.example .env

# 开发环境启动（端口 8080，context-path /api）
mvn spring-boot:run

# 或打包后运行
mvn clean package -DskipTests
java -jar target/mars-admin.jar
```

后端地址：`http://localhost:8080/api`

### 4. 启动前端

```bash
cd mars-web

# 必须使用 pnpm
pnpm install
pnpm dev
```

前端地址：`http://localhost:9527`

开发模式下，Vite 会将 `/proxy-default` 代理到 `http://localhost:8080/api`。

### 5. 访问系统

打开浏览器访问 `http://localhost:9527`，使用默认账号登录（见下方）。

---

## 默认账号

| 项目 | 值 |
|------|-----|
| 用户名 | `admin` |
| 密码 | `123456` |
| Druid 监控 | `admin` / `mars666`（dev 默认） |
| SQL 日志页 | `admin` / `mars666` |

---

## 配置说明

### 后端环境变量

参考 `mars-server/.env.example`：

```env
DB_HOST=localhost
DB_PORT=3306
DB_NAME=mars
DB_USERNAME=root
DB_PASSWORD=root

REDIS_PASSWORD=123456

DRUID_USERNAME=admin
DRUID_PASSWORD=mars666

SQL_LOG_USERNAME=admin
SQL_LOG_PASSWORD=mars666

WECHAT_MINI_APPID=
WECHAT_MINI_SECRET=
```

### 后端 Profile

| Profile | 端口 | Context Path | 说明 |
|---------|------|--------------|------|
| dev（默认） | 8080 | `/api` | 开发环境，开启文档与调试日志 |
| prod | 8088 | `/` | 生产环境，关闭文档，可开启只读模式 |

切换方式：修改 `application.yml` 中 `spring.profiles.active`。

### 前端环境变量

主要配置在 `mars-web/.env`：

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `VITE_APP_TITLE` | Mars Admin | 系统标题 |
| `VITE_SERVICE_BASE_URL` | `/proxy-default` | API 基础路径 |
| `VITE_HTTP_PROXY` | `Y` | 开发代理开关 |
| `VITE_AUTH_ROUTE_MODE` | `dynamic` | 动态路由（后端菜单驱动） |
| `VITE_STORAGE_PREFIX` | `mars-admin` | localStorage 前缀 |

生产构建时修改 `mars-web/.env.prod` 中的 `VITE_SERVICE_BASE_URL` 为实际后端地址。

---

## 功能模块

### 系统配置（/manage/sys-setting）

14 个 Tab 分组，统一存储在 `sys_config` 表：

| Tab | 配置组 | 说明 |
|-----|--------|------|
| 系统配置 | site | 站点名称、Logo、版权、ICP、水印 |
| 注册配置 | register | 注册开关、验证码策略 |
| 登录配置 | login | 登录方式、验证码、失败锁定 |
| 密码配置 | password | 密码强度、过期策略 |
| 邮件配置 | email | SMTP 服务器 |
| 邮件模板 | emailTemplate | 邮件模板内容 |
| 短信配置 | sms | 短信服务商 |
| 文件配置 | file | 默认存储、大小限制 |
| 推送配置 | push | 消息推送 |
| 第三方配置 | oauth | OAuth 登录 |
| 支付配置 | pay | 支付渠道 |
| 安全配置 | security | API 签名、SM4 加密 |
| 小程序配置 | mini | 微信小程序 |
| 公众号配置 | mp | 微信公众号 |

API：
- `GET /system/setting` — 获取全部配置
- `PUT /system/setting` — 保存全部配置
- `PUT /system/setting/{group}` — 按组保存
- `GET /system/setting/public` — 公开配置（无需登录）

### 定时任务（/manage/job）

- 基于 Quartz，任务定义存储在 `sys_job` 表，启动时自动加载
- 调用目标格式：`beanName.methodName(参数)`，如 `marsTask.ryNoParams`
- 支持 Cron 表达式校验、常用表达式预设、立即执行、状态开关
- 执行日志记录在 `sys_job_log`

### 文件存储

支持四种存储策略，通过 `sys_oss_config` 配置：

| 类型 | 说明 |
|------|------|
| local | 本地磁盘（`./upload`） |
| minio | MinIO 对象存储（默认） |
| aliyun | 阿里云 OSS |
| cos | 腾讯云 COS |

API 前缀：`/file`（上传、下载、预览、预签名 URL）

### 动态路由

前端采用 **动态路由模式**（`VITE_AUTH_ROUTE_MODE=dynamic`）：
1. 登录后请求 `GET /route/getUserRoutes`
2. 后端根据用户角色返回可访问菜单
3. 前端动态注册路由并渲染侧边栏

---

## 安全机制

### API 签名

开启后，所有非白名单请求需携带签名头：

| Header | 说明 |
|--------|------|
| `X-Timestamp` | 毫秒时间戳 |
| `X-Nonce` | 随机字符串 |
| `X-Sign` | MD5 签名值 |

签名算法：

```
MD5(timestamp + nonce + secret + METHOD + uri + body)
```

- 开关与密钥：系统配置 → 安全配置，或 `sys_config` 中 `sys.security.signEnabled` / `sys.security.signSecret`
- 前端自动签名：`mars-web/src/utils/api-sign.ts`
- 后端校验：`ApiSignInterceptor`
- 白名单：`/auth/**`、`/system/setting/**`、`/file/**`、文档、Druid 等

### SM4 响应加密

开启后，接口响应 `data` 字段使用 SM4（ECB/PKCS5）加密为 hex 字符串：

```json
{
  "code": 200,
  "encrypted": true,
  "data": "a1b2c3..."
}
```

响应头：`X-Encrypted: SM4`

- 前端自动解密：`mars-web/src/utils/api-encrypt.ts`
- 后端加密：`Sm4EncryptResponseAdvice`
- 密钥：16 字节，`sys.security.sm4Key`

### 权限控制

```
用户 → 角色 → 菜单（路由 + 按钮权限码）
              → 部门（数据权限范围）
```

- 后端：`@SaCheckPermission("system:user:list")`
- 前端：`useAuth().hasAuth('system:user:add')` 或 `v-auth` 指令

---

## 接口文档

开发环境启动后端后访问：

| 文档 | 地址 |
|------|------|
| Knife4j | http://localhost:8080/api/doc.html |
| Swagger UI | http://localhost:8080/api/swagger-ui.html |
| Druid 监控 | http://localhost:8080/api/druid/index.html |

---

## 开发指南

### 后端

```bash
cd mars-server

# 开发运行
mvn spring-boot:run

# 指定 profile
mvn spring-boot:run -Dspring-boot.run.profiles=prod

# 打包
mvn clean package -DskipTests
```

**新增模块建议：**
1. 在 `modules/` 下创建 entity → mapper → service → controller
2. Controller 继承 `BaseController` 可自动获得 CRUD + 权限切面
3. 在 `sys_menu` 添加菜单与权限码
4. 前端在 `src/views/manage/` 添加页面，运行 `pnpm gen-route` 生成路由

**新增定时任务：**
1. 在 Spring 容器中注册 Bean（如 `MarsTask`）
2. 管理端添加任务，调用目标填写 `beanName.methodName`
3. Cron 表达式参考常用预设或 [Quartz Cron 生成器](https://www.pppet.net/)

### 前端

```bash
cd mars-web

pnpm dev          # 开发（test 模式，端口 9527）
pnpm dev:prod     # 使用 prod 环境变量开发
pnpm build        # 生产构建 → dist/
pnpm build:test   # 测试环境构建
pnpm preview      # 预览构建结果（端口 9725）
pnpm typecheck    # TypeScript 类型检查
pnpm lint         # ESLint 修复
pnpm gen-route    # 根据 views 目录生成路由
```

**新增页面：**
1. 在 `src/views/manage/` 创建目录和 `index.vue`
2. 运行 `pnpm gen-route` 更新 `router/elegant/routes.ts`
3. 在后端 `sys_menu` 添加对应菜单记录
4. API 定义放在 `src/service/api/`

**前端 monorepo 子包：**

| 包名 | 用途 |
|------|------|
| `@sa/axios` | HTTP 请求封装 |
| `@sa/hooks` | 通用 composables |
| `@sa/utils` | 工具函数（含 MD5） |
| `@sa/materials` | 布局、标签页等 UI 物料 |
| `@sa/color` | 主题色板 |
| `@sa/scripts` | CLI 工具（`sa` 命令） |

---

## 部署说明

### 后端部署

```bash
cd mars-server
mvn clean package -DskipTests -Pprod

# 运行（生产 profile）
java -jar target/mars-admin.jar --spring.profiles.active=prod
```

生产环境建议：
- 配置 `DB_*`、`REDIS_PASSWORD` 等环境变量
- 关闭 API 文档（prod profile 默认关闭）
- 按需开启 `mars.production.read-only.enabled`
- 使用 Nginx 反向代理并配置 HTTPS

### 前端部署

```bash
cd mars-web

# 修改 .env.prod 中的 VITE_SERVICE_BASE_URL 为后端地址
pnpm build

# 将 dist/ 部署到 Nginx
```

Nginx 配置示例：

```nginx
server {
    listen 80;
    server_name your-domain.com;

    # 前端静态资源
    location / {
        root /var/www/mars-web/dist;
        try_files $uri $uri/ /index.html;
    }

    # 后端 API 代理
    location /api/ {
        proxy_pass http://127.0.0.1:8088/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

> 注意：dev 环境后端 context-path 为 `/api`，prod 为 `/`。部署时请根据实际 profile 调整 Nginx 代理路径。

---

## 数据库说明

完整脚本：`sql/mars.sql`

### 系统表（20 张）

| 表名 | 说明 |
|------|------|
| `sys_user` | 系统用户 |
| `sys_role` | 角色 |
| `sys_menu` | 菜单/按钮 |
| `sys_dept` | 部门 |
| `sys_post` | 岗位 |
| `sys_config` | 系统参数/分组配置 |
| `sys_dict_type` / `sys_dict_data` | 字典 |
| `sys_user_role` / `sys_user_dept` / `sys_user_post` | 用户关联 |
| `sys_role_menu` / `sys_role_dept` | 角色关联 |
| `sys_oper_log` | 操作日志 |
| `sys_logininfor` | 登录日志 |
| `sys_api_log` | 接口日志 |
| `sys_oss` / `sys_oss_config` | 文件存储 |
| `sys_job` / `sys_job_log` | 定时任务 |

### 业务表（6 张）

| 表名 | 说明 |
|------|------|
| `tb_user` | C 端用户 |
| `tb_user_follow` | 用户关注 |
| `tb_user_collection` | 用户收藏 |
| `tb_user_device` | 用户设备 |
| `tb_chat_session` | 聊天会话 |
| `tb_chat_message` | 聊天消息 |

---

## 常见问题

### 1. 登录后接口返回 401「签名验证失败」

API 签名默认开启。确保：
- 前端已登录并成功同步签名配置
- 后端 `sys.security.signSecret` 与前端一致
- 如需临时关闭：系统配置 → 安全配置 → 关闭 API 签名

### 2. 接口返回加密数据无法解析

检查系统配置中 SM4 密钥是否为 16 字节，前后端密钥需一致。关闭方式：安全配置 → 关闭 SM4 加密。

### 3. 刷新页面后 404

动态路由模式下，前端路由守卫会在 Token 有效时重新拉取菜单并注册路由。若仍 404，检查 `sys_menu` 中对应菜单的 `route_name` 与前端 `views` 目录是否匹配。

### 4. OSS 菜单不可见或报权限不足

确认 `sys_menu` 中 OSS 相关菜单 `status=1`（启用），且角色已分配 `system:ossConfig:list` 或 `system:sysSetting:list` 权限。

### 5. 定时任务不执行

- 检查任务状态是否为「正常」
- 检查 Cron 表达式是否正确（可在新增时校验）
- 查看 `sys_job_log` 中的执行记录
- 确认调用目标的 Bean 已在 Spring 容器中注册

### 6. 前端代理连接失败

确认后端已启动在 `8080` 端口，且 context-path 为 `/api`。Vite 代理配置见 `mars-web/vite.config.ts`。

---

## 致谢

- 前端基于 [SoybeanAdmin](https://github.com/soybeanjs/soybean-admin-antd) 模板定制
- 后端参考 RuoYi 等开源 admin 框架的 RBAC 设计思路

---

## License

MIT