# SevenAdmin

**Repository Path**: lorock/seven-admin

## Basic Information

- **Project Name**: SevenAdmin
- **Description**: SevenAdmin 是一个基于 Go + Vue3 的多租户管理后台系统，SaaS 应用设计。它提供了完整的基础功能和强大的代码生成工具，让你专注于业务开发而不是重复的基础代码。
- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: v2
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 18
- **Created**: 2026-04-01
- **Last Updated**: 2026-04-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SevenAdmin

<div align="center">
  <img src="doc/image/favicon.png" alt="SevenAdmin Logo" width="200"/>
</div>


[![Go Version](https://img.shields.io/badge/Go-1.24+-00ADD8?style=flat&logo=go)](https://golang.org)
[![Vue Version](https://img.shields.io/badge/Vue-3.x-4FC08D?style=flat&logo=vue.js)](https://vuejs.org)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

[简体中文](README.md) | [English](README_en.md)

---

## 📖 项目简介

SevenAdmin 是一个基于 **Go + Vue3** 的多租户管理后台系统，采用 SaaS 应用设计。提供完整的基础功能和强大的代码生成工具，让你专注于业务开发。

### ✨ 核心特性

- **🏢 多租户架构** - 基于 Context 的透明租户隔离，全链路自动过滤
- **🛠️ 强大的 CLI** - 一键生成前后端完整代码（Model、Repository、DTO、Service、Controller、Vue、API）
- **🗄️ 多数据库支持** - 支持 SQL (PostgreSQL/MySQL/SQLite/SQLServer) 和 MongoDB，统一 API
- **🎯 完整基础功能** - 用户、角色、权限、菜单、租户、日志、文件管理等开箱即用
- **⚡ 技术栈** - Go + Fiber v2 + GORM/MongoDB + Vue3 + TypeScript + Element Plus
- **🔐 安全加固** - JWT 黑名单、CORS 白名单、安装 Token 保护、文件上传安全、路径穿越防护
- **📦 Web 安装向导** - 浏览器图形化安装，支持数据库配置自动检测

### 📜 维护说明

本项目最初由 [乐清 (illusoryNone)](https://gitee.com/illusoryNone) 创建并开发，自 **2026年4月** 起由 [lorock](https://gitee.com/lorock) 接手维护。感谢原作者的辛勤贡献！

---

## 📸 系统截图

### 菜单管理
![菜单管理](doc/image/menu.png)

### 文件管理
![文件管理](doc/image/storage.png)

### 租户管理
![租户管理](doc/image/tenant.png)

---

## 📋 功能列表

| 功能模块 | 功能说明 |
|---------|---------|
| **用户管理** | 用户 CRUD、角色分配、多部门、禁用/启用、重置密码、一键登录 |
| **租户管理** | 租户 CRUD、自动初始化、套餐配置、域名绑定、禁用/启用 |
| **角色管理** | 角色 CRUD、权限配置、角色分组、批量操作 |
| **菜单管理** | 动态菜单、权限绑定、树形管理 |
| **权限管理** | 基于 Casbin 的 RBAC、菜单权限、按钮权限、数据权限 |
| **组织架构** | 部门管理、岗位管理、组织树形结构 |
| **字典管理** | 数据字典大类/小类、多列排序、导入/导出 |
| **操作日志** | 记录所有操作、请求追踪、审计功能、自动清理过期日志 |
| **文件管理** | 多存储支持（本地/OSS/MinIO/COS/S3/Cloudinary）、存储分类、上传/下载/预览/删除 |
| **消息系统** | SSE 实时消息推送、多租户消息管理、已读未读状态、消息中心 |
| **定时任务** | 基于 Cron 的任务调度、系统任务、自定义任务、执行日志、立即执行 |
| **系统配置** | 在线配置管理、参数分组、键值对管理 |
| **安装向导** | Web 图形化安装、环境检测、数据库连接测试、一键初始化 |

---

## 🚀 快速开始

### 环境要求

| 组件 | 版本要求 |
|------|---------|
| Go | 1.24+ |
| Node.js | >=20.19.0 |
| pnpm | >=8.8.0 |
| PostgreSQL | 13+ (推荐) / MySQL 8+ / SQLite 3 / SQLServer 2019+ / MongoDB 6+ |

### 1. 克隆项目

```bash
git clone https://gitee.com/lorock/seven-admin.git
cd seven-admin

# 安装依赖
make install
```

### 2. 启动开发服务

> **提示：** 首次启动会自动进入 Web 安装向导，通过浏览器完成数据库配置和系统初始化。

**方式一：Makefile 一键启动（推荐）**

```bash
# 同时启动前后端（后端 Air 热重载 + 前端 Vite HMR）
make dev

# 或使用 go run 方式
make dev-go

# 指定配置文件
make dev ENV=dev    # 使用 config-dev.yaml
make dev ENV=prod   # 使用 config-prod.yaml
```

**方式二：手动启动**

```bash
# 终端 1 - 启动后端
cd backend
go run cmd/main.go
# 或使用 Air 热重载（需安装: go install github.com/cosmtrek/air@latest）
air -c .air.toml

# 终端 2 - 启动前端
cd frontend
pnpm dev
```

后端服务：`http://localhost:8080` | 前端服务：`http://localhost:5173`

> **配置文件：** 编辑 `config/config.yaml` 可手动配置（支持 `config-dev.yaml` 开发环境、`config-prod.yaml` 生产环境）。

---

## 🔧 核心功能详解

### 1. CLI 代码生成工具

一键生成标准化的前后端业务代码。

#### 编译工具

```bash
cd backend
go build -o generate cmd/generate/main.go
```

#### 生成 Model + Repository

```bash
# SQL 数据库（默认）
./generate model Product sys_product --comment=商品

# MongoDB 数据库
./generate model Product --db=mongo --comment=商品

# 非多租户模型
./generate model Tenant sys_tenant --comment=租户 --tenant=false
```

#### 生成完整应用层（后端）

```bash
# 为已有模型生成 DTO + Service + Controller
./generate app Product --module=Product --comment=商品
```

#### 生成前端代码

```bash
# 生成前端页面（TypeScript + Vue + API）
./generate frontend Product --module=product --comment=商品

# 简写形式
./generate fe Product --comment=商品

# 支持多种列表模式
./generate fe Menu --mode=tree --comment=菜单           # 树形列表
./generate fe Product --mode=card --comment=商品        # 卡片列表
./generate fe Banner --mode=draggable --comment=轮播图  # 可拖拽列表
```

**详细文档：** [CLI 工具使用指南](doc/cli.md)

---

### 2. 多租户系统

基于 Context 的透明租户隔离，开箱即用。

#### 请求链路

```
HTTP Request (Header: X-Tenant-ID)
    ↓
Middleware (注入 TenantID 到 Context)
    ↓
Controller (传递 c.Context())
    ↓
Service (使用 ctx)
    ↓
Repository (自动应用租户过滤)
    ↓
Database (WHERE tenant_id = ?)
```

#### 使用示例

```go
// Controller 层
func (c *productController) List(ctx *fiber.Ctx) error {
    var req dto.ProductListReq
    if err := ctx.BodyParser(&req); err != nil {
        return response.FailWithMsg(ctx, response.ParamsValidError, "参数错误")
    }

    // 使用 ctx.Context() 传递租户信息
    data, err := c.srv.List(ctx.Context(), &req)
    return response.CheckAndRespWithData(ctx, data, err)
}

// Service 层
func (s *productService) Create(ctx context.Context, req *dto.ProductCreateReq, operatorID uint) (*dto.ProductRes, error) {
    entity := &models.Product{
        TenantBaseModel: types.TenantBaseModel{
            TenantID:  0, // 将由中间件自动设置
            CreatedBy: operatorID,
        },
        Name:   &req.Name,
        Price:  &req.Price,
    }

    // 从上下文获取租户ID
    if tenantID, ok := database.GetTenantID(ctx); ok && tenantID > 0 {
        entity.TenantID = tenantID
    }

    // Repository 会自动应用租户过滤
    if err := s.repo.Create(ctx, entity); err != nil {
        return nil, err
    }

    return s.toDTO(entity), nil
}
```

**详细文档：** [多租户使用指南](doc/multi-tenant-context.md)

---

### 3. Repository 数据访问层

现代化的数据访问层，SQL 和 MongoDB 使用统一 API。

#### 基础 CRUD

```go
// 创建
product := &models.Product{Name: "iPhone 15", Price: 5999}
err := productRepo.Create(ctx, product)

// 查询
product, err := productRepo.GetById(ctx, id)

// 更新
product.Price = 6999
err := productRepo.Update(ctx, product)

// 删除（软删除）
err := productRepo.Delete(ctx, id)
```

#### 高级查询

```go
// Filter 查询构建器（SQL 和 MongoDB 通用）
filter := types.NewFilter().
    Set("status", 1).              // WHERE status = 1
    Set("price >=", 100).           // AND price >= 100
    Set("name LIKE", "%手机%").     // AND name LIKE '%手机%'
    Preload("Category").            // 预加载分类
    OrderBy("created_at DESC")      // ORDER BY created_at DESC

// SQL 和 MongoDB 使用完全相同的 API
products, total, err := productRepo.GetPage(ctx, filter, page, pageSize)

// 统计
count, err := productRepo.Count(ctx, filter)

// 存在性检查
exists, err := productRepo.Exists(ctx, filter)

// 聚合查询
sum, err := orderRepo.Sum(ctx, "amount", filter)
avg, err := productRepo.Avg(ctx, "price", filter)
```

#### 事务支持

```go
// 事务自动提交/回滚
err := orderRepo.Transaction(ctx, func(txCtx context.Context) error {
    // 创建订单
    if err := orderRepo.Create(txCtx, order); err != nil {
        return err
    }

    // 扣减库存
    if err := productRepo.Update(txCtx, product); err != nil {
        return err
    }

    // 返回 nil 自动提交，返回 error 自动回滚
    return nil
})
```

**详细文档：** [Repository 使用指南](doc/repo.md)

---

### 4. 安全特性

系统内置多层安全防护机制：

- **JWT 安全** - 自动密钥生成、签名算法验证、Token 黑名单（登出即时失效）、密码修改后 Token 强制失效
- **CORS 白名单** - 支持环境变量配置允许的源，开发模式仅允许本地访问
- **安装保护** - 安装接口需要 Token 认证，安装完成后自动关闭入口
- **文件上传安全** - 危险扩展名黑名单、MIME 类型验证、Magic Bytes 检测、可疑内容扫描
- **路径穿越防护** - 文件系统操作严格校验路径边界
- **安全响应头** - CSP、HSTS、X-Frame-Options、Referrer-Policy 等完整安全头
- **SQL 注入防护** - 标识符清理与参数化查询
- **错误信息脱敏** - 生产环境隐藏数据库连接细节等敏感信息

---

## 🐳 Docker 部署（生产环境）

### 一键部署

```bash
# 1. 克隆项目
git clone https://gitee.com/lorock/seven-admin.git
cd seven-admin

# 2. 配置环境变量
cp .env.example .env
# 编辑 .env，修改数据库密码和 JWT 密钥（重要！）

# 3. 启动服务
make docker-up
```

启动后访问 `http://localhost:8080` 完成安装向导。

### Docker 常用命令

```bash
make docker-up         # 启动服务（后台运行）
make docker-down       # 停止服务
make docker-logs       # 查看日志
make docker-rebuild    # 重新构建并启动
make docker-build      # 仅构建镜像
make docker-clean      # 清理镜像和数据卷（危险）
```

### 配置说明

| 环境变量 | 默认值 | 说明 |
|---------|--------|------|
| `APP_PORT` | `8080` | 应用对外端口 |
| `DB_DRIVER` | `postgres` | 数据库驱动 (postgres/mysql/sqlite) |
| `DB_HOST` | `postgres` | 数据库主机 |
| `DB_PORT` | `5432` | 数据库端口 |
| `DB_NAME` | `seven_admin` | 数据库名称 |
| `DB_USER` | `postgres` | 数据库用户 |
| `DB_PASSWORD` | `postgres` | 数据库密码（请修改！） |
| `JWT_SECRET` | - | JWT 签名密钥（请修改！） |

### 启用 Redis 缓存

1. 编辑 `docker-compose.yml`，取消 `redis` 服务的注释
2. 修改应用服务的 `depends_on` 添加 redis
3. 在 `.env` 中配置 `REDIS_PASSWORD`
4. 在后端配置中将 `cache.driver` 改为 `redis`

---

## 🛠️ 技术栈

### 后端
| 技术 | 说明 |
|------|------|
| [Go](https://golang.org) | 后端开发语言 (1.24+) |
| [Fiber v2](https://gofiber.io) | 高性能 Web 框架（基于 fasthttp） |
| [GORM](https://gorm.io) | ORM 框架，支持多数据库 |
| [Casbin](https://casbin.org) | 权限控制引擎 |
| [JWT](https://github.com/golang-jwt/jwt) | 身份认证 |
| [Swagger](https://swagger.io) | API 文档自动生成 |
| [Zap/Logrus](https://github.com/sirupsen/logrus) | 结构化日志 |
| [Viper](https://github.com/spf13/viper) | 配置管理 |
| [DIG](https://go.uber.org/dig) | 依赖注入 |

### 前端
| 技术 | 说明 |
|------|------|
| [Vue 3](https://vuejs.org) | 前端框架 |
| [TypeScript](https://www.typescriptlang.org) | 类型安全 |
| [Element Plus](https://element-plus.org) | UI 组件库 |
| [Vite](https://vitejs.dev) | 构建工具 |
| [Pinia](https://pinia.vuejs.org) | 状态管理 |
| [Vue Router](https://router.vuejs.org) | 路由管理 |
| [TailwindCSS](https://tailwindcss.com) | 原子化 CSS |
| [Axios](https://axios-http.com) | HTTP 客户端 |
| [Vue I18n](https://vue-i18n.intlify.dev) | 国际化 |

### 数据库
| 数据库 | 说明 |
|------|------|
| PostgreSQL | 推荐，功能最完善 |
| MySQL / MariaDB | 广泛使用的关系型数据库 |
| SQLite | 轻量级，适合开发和小型部署 |
| SQLServer | 企业级数据库支持 |
| MongoDB | NoSQL 文档数据库 |

---

## 📚 相关文档

| 文档 | 说明 |
|------|------|
| [CLI 工具使用指南](doc/cli.md) | 代码生成工具详细文档 |
| [多租户使用指南](doc/multi-tenant-context.md) | 多租户实现原理和使用方法 |
| [Repository 使用指南](doc/repo.md) | 数据访问层完整使用文档 |
| [定时任务调度系统](doc/schedule-system.md) | 定时任务开发和使用指南 |
| [路由和菜单指南](doc/route-and-menu-guide.md) | 路由和菜单配置说明 |
| [消息系统](doc/message-system.md) | SSE 实时消息推送系统 |
| [权限系统](doc/permission.md) | Casbin 权限配置与使用 |
| [开发规范](doc/rules.md) | 代码规范与开发约定 |
| [参数校验示例](doc/validation-examples.md) | 请求参数校验使用示例 |

---

## 📄 开源协议

本项目采用 [MIT License](LICENSE) 开源协议。

---

## 📞 联系方式

- **Gitee**: [https://gitee.com/lorock/seven-admin](https://gitee.com/lorock/seven-admin)
- **Issues**: [提交问题](https://gitee.com/lorock/seven-admin/issues)

---

<div align="center">

**如果这个项目对你有帮助，请给一个 ⭐️ Star ⭐️**

Made with ❤️ by [lorock](https://gitee.com/lorock)

</div>