gin-vue-admin Documentation

Vite+Vue3+Gin拥有AI辅助的基础开发平台，企业级业务AI+开发解决方案，内置mcp辅助服务，内置skills管理，支持TS和JS混用。它集成了JWT鉴权、权限管理、动态路由、显隐可控组件、分页封装、多点登录拦截、资源权限、上传下载、代码生成器、表单生成器和可配置的导入导出等开发必备功能。

24,924 stars Go Go 1 file · ~5,054 tokens #admin#ai#casbin#claw#element-ui#gin#gin-admin#gin-vue-admin
RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy gin-vue-admin on any server, homelab, or cloud container platform.

1-Click Terminal Command
bash (docker run) 
docker run -d --name gin-vue-admin -p 8080:8080 --restart always mysql:8.0.21
Configured Services & Ports
⚙️ web
image: build locally
🔌 Ports: 8080:8080
⚙️ server
image: build locally
🔌 Ports: 8888:8888
⚙️ mysql
image: mysql:8.0.21
🔌 Ports: 13306:3306
⚙️ redis
image: redis:6.0.6
🔌 Ports: 16379:6379
docker-compose.yml
yaml (docker-compose.yml) 
version: "3"

# 声明一个名为network的networks,subnet为network的子网地址,默认网关是177.7.0.1
networks:
  network:
    ipam:
      driver: default
      config:
        - subnet: '177.7.0.0/16'
        
# 设置mysql，redis持久化保存
volumes:
  mysql:
  redis:
  
services:
  web:
    build:
      context: ../../web
      dockerfile: ./Dockerfile
    container_name: gva-web
    restart: always
    ports:
      - '8080:8080'
    depends_on:
      - server
    command: [ 'nginx-debug', '-g', 'daemon off;' ]
    networks:
      network:
        ipv4_address: 177.7.0.11

  server:
    build:
      context: ../../server
      dockerfile: ./Dockerfile
    container_name: gva-server
    restart: always
    ports:
      - '8888:8888'
    depends_on:
      mysql:
        condition: service_healthy
      redis:
        condition: service_healthy
    links:
      - mysql
      - redis
    networks:
      network:
        ipv4_address: 177.7.0.12

  mysql:
    image: mysql:8.0.21       # 如果您是 arm64 架构：如 MacOS 的 M1，请修改镜像为 image: mysql/mysql-server:8.0.21
    container_name: gva-mysql
    command: mysqld --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci #设置utf8字符集
    restart: always
    ports:
      - "13306:3306"  # host物理直接映射端口为13306
    environment:
      #MYSQL_ROOT_PASSWORD: 'Aa@6447985' # root管理员用户密码
      MYSQL_DATABASE: 'qmPlus' # 初始化启动时要创建的数据库的名称
      MYSQL_USER: 'gva'
      MYSQL_PASSWORD: 'Aa@6447985'
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "gva", "-pAa@6447985"]
      interval: 10s
      timeout: 5s
      retries: 3
    volumes:
      - mysql:/var/lib/mysql
    networks:
      network:
        ipv4_address: 177.7.0.13

  redis:
    image: redis:6.0.6
    container_name: gva-redis # 容器名
    restart: always
    ports:
      - '16379:6379'
    healthcheck:
      test: ["CMD-SHELL", "redis-cli ping | grep PONG || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 3
    volumes:
      - redis:/data
    networks:
      network:
        ipv4_address: 177.7.0.14

File: README.md

一分钟生成前后端基础代码

| ⭐️ 高度适配AI编辑器的MCP
📄 创建基础模板
🤖 AI生成结构
⏰ 生成代码
🏷️ 分配权限
🎉 基础CURD生成完成 | |

| --- | --- |

项目文档

重要提示

  1. 本项目从起步到开发到部署均有文档和详细视频教程。
  2. 本项目需要您有一定的 golang 和 vue 基础。
  3. 您完全可以通过我们的教程和文档完成一切操作，因此我们不再提供免费的技术服务，如需服务请进行付费支持。
  4. 本项目采用 BSL 1.1 授权。非商用、学习、评估等用途请遵循仓库许可证；如将此项目用于商用或生产环境，或需要移除版权与署名信息，请购买授权。您需保留仓库、日志和代码中的版权声明信息。

1. 基本介绍

1.1 项目介绍

Gin-vue-admin是一个基于 vue 和 gin 开发的全栈前后端分离的开发基础平台，集成jwt鉴权，动态路由，动态菜单，casbin鉴权，表单生成器，代码生成器等功能，提供多种示例文件，让您把更多时间专注在业务开发上。

1.2 贡献指南

Hi! 首先感谢你使用 gin-vue-admin。

Gin-vue-admin 是一套为快速研发准备的一整套前后端分离架构式的开源框架，旨在快速搭建中小型项目。

Gin-vue-admin 的成长离不开大家的支持，如果你愿意为 gin-vue-admin 贡献代码或提供建议，请阅读以下内容。

1.2.1 Issue 规范

  • issue 仅用于提交 Bug 或 Feature 以及设计相关的内容，其它内容可能会被直接关闭。
  • 在提交 issue 之前，请搜索相关内容是否已被提出。

1.2.2 Pull Request 规范

  • 请先 fork 一份到自己的项目下，不要直接在仓库下建分支。
  • commit 信息要以 [文件名]: 描述信息 的形式填写，例如 README.md: fix xxx bug。
  • 如果是修复 bug，请在 PR 中给出描述信息。
  • 合并代码需要两名维护人员参与：一人进行 review 后 approve，另一人再次 review，通过后即可合并。

2. 使用说明

  • node版本 > v18.16.0
  • golang版本 >= v1.22
  • IDE推荐：Goland

2.1 server项目

使用 Goland 等编辑工具，打开server目录，不可以打开 gin-vue-admin 根目录

bash
# 克隆项目
git clone https://github.com/flipped-aurora/gin-vue-admin.git
# 进入server文件夹
cd server

# 使用 go mod 并安装go依赖包
go generate

# 运行
go run .

2.2 web项目

bash
# 进入web文件夹
cd web

# 安装依赖
npm install

# 启动web项目
npm run serve

2.3 swagger自动化API文档

2.3.1 安装 swagger

bash
go install github.com/swaggo/swag/cmd/swag@latest

2.3.2 生成API文档

bash
cd server
swag init

执行上面的命令后，server目录下会出现docs文件夹里的 docs.go, swagger.json, swagger.yaml 三个文件更新，启动go服务之后, 在浏览器输入 http://localhost:8888/swagger/index.html 即可查看swagger文档

2.4 VSCode工作区

2.4.1 开发

使用 VSCode 打开根目录下的工作区文件 gin-vue-admin.code-workspace，在边栏可以看到三个虚拟目录：backend、frontend、root。

2.4.2 运行/调试

在运行和调试中也可以看到三个 task：Backend、Frontend、Both (Backend & Frontend)。运行 Both (Backend & Frontend) 可以同时启动前后端项目。

2.4.3 settings

在工作区配置文件中有 go.toolsEnvVars 字段，是用于 VSCode 自身的 go 工具环境变量。此外在多 go 版本的系统中，可以通过 gopath、go.goroot 指定运行版本。

json
"go.gopath": null,
    "go.goroot": null,

3. 技术选型

  • 前端：用基于 Vue 的 Element 构建基础页面。
  • 后端：用 Gin 快速搭建基础restful风格API，Gin 是一个go语言编写的Web框架。
  • 数据库：采用 MySQL 或 MariaDB（5.7+），数据库引擎 InnoDB，使用 gorm 实现对数据库的基本操作。
  • 缓存：使用 Redis 实现记录当前活跃用户的 jwt 令牌并实现多点登录限制。
  • API文档：使用 Swagger 构建自动化文档。
  • 配置文件：使用 fsnotify 和 viper 实现 yaml 格式的配置文件。
  • 日志：使用 zap 实现日志记录。

4. 项目架构

4.1 系统架构图

4.2 详细设计图 （提供者:[baobeisuper](https://github.com/baobeisuper)）

4.3 目录结构

(详细目录结构请见源码...)

5. 主要功能

  • 权限管理：基于 jwt 和 casbin 实现的权限管理。
  • 文件上传下载：实现基于 七牛云, 阿里云, 腾讯云 的文件上传操作。
  • 分页封装：前端使用 mixins 封装分页，分页方法调用即可。
  • 用户管理：系统管理员分配用户角色和角色权限。
  • 角色管理：创建权限控制的主要对象，可以给角色分配不同 api 权限和菜单权限。
  • 菜单管理：实现用户动态菜单配置，实现不同角色不同菜单。
  • api管理：不同用户可调用的 api 接口的权限不同。
  • 配置管理：配置文件可前台修改(在线体验站点不开放此功能)。
  • 条件搜索：增加条件搜索示例。
  • restful示例：可以参考用户管理模块中的示例 API。
  • 多点登录限制：借助 Redis 配合对应配置限制多端登录状态。
  • 分片上传：提供文件分片上传和大文件分片上传功能示例。
  • 表单生成器：表单生成器借助 @Variant Form。
  • 代码生成器：后台基础逻辑以及简单 curd 的代码生成器。

6. 知识库

6.1 团队博客

https://www.yuque.com/flipped-aurora
内有前端框架教学视频。如果觉得项目对您有所帮助可以添加我的个人微信: shouzi_1994。

6.2 教学视频

  1. 手把手教学视频: https://www.bilibili.com/video/BV1Rg411u7xH/
  2. 后端目录结构调整介绍以及使用方法: https://www.bilibili.com/video/BV1x44y117TT/
  3. golang基础教学视频: bilibili
  4. gin框架基础教学: bilibili
  5. gin-vue-admin 版本更新介绍视频: bilibili

7. 联系方式

微信交流群

防止广告进群，添加微信，输入以下代码执行结果（请勿转码为string）：

go
str := "5Yqg5YWlR1ZB5Lqk5rWB576k"
decodeBytes, err := base64.StdEncoding.DecodeString(str)
fmt.Println(decodeBytes, err)

8. 贡献者

感谢您对gin-vue-admin的贡献!

9. 捐赠

如果你觉得这个项目对你有帮助，你可以请作者喝饮料 :tropical_drink: 点我

10. 注意事项

请遵守 BSL 1.1 许可证要求并保留作品声明；商用、生产使用或去除版权信息请务必获取授权
未授权超出许可范围使用将依法追究法律责任。

File: server/plugin/email/README.MD

GVA 邮件发送功能插件

开发者：GIN-VUE-ADMIN 官方

使用步骤

1. 前往GVA主程序下的initialize/router.go 在Routers 方法最末尾按照你需要的及安全模式添加本插件

text
例：
本插件可以采用gva的配置文件 也可以直接写死内容作为配置 建议为gva添加配置文件结构 然后将配置传入
PluginInit(PrivateGroup, email.CreateEmailPlug(
	global.GVA_CONFIG.Email.To,
	global.GVA_CONFIG.Email.From,
	global.GVA_CONFIG.Email.Host,
	global.GVA_CONFIG.Email.Secret,
	global.GVA_CONFIG.Email.Nickname,
	global.GVA_CONFIG.Email.Port,
	global.GVA_CONFIG.Email.IsSSL,
	global.GVA_CONFIG.Email.IsLoginAuth,
	))

同样也可以再传入时写死

PluginInit(PrivateGroup, email.CreateEmailPlug(
"[email protected]",
"[email protected]",
"smtp.qq.com",
"global.GVA_CONFIG.Email.Secret",
"登录密钥",
465,
true,
true,
))

2. 配置说明

2-1 全局配置结构体说明

text
//其中 Form 和 Secret 通常来说就是用户名和密码

type Email struct {
    To          string  // 收件人:多个以英文逗号分隔 例：[email protected] [email protected] 正式开发中请把此项目作为参数使用 此处配置主要用于发送错误监控邮件
    From        string  // 发件人  你自己要发邮件的邮箱
    Host        string  // 服务器地址 例如 smtp.qq.com  请前往QQ或者你要发邮件的邮箱查看其smtp协议
    Secret      string  // 密钥    用于登录的密钥 最好不要用邮箱密码 去邮箱smtp申请一个用于登录的密钥
    Nickname    string  // 昵称    发件人昵称 自定义即可 可以不填
    Port        int     // 端口     请前往QQ或者你要发邮件的邮箱查看其smtp协议 大多为 465
    IsSSL       bool    // 是否SSL   是否开启SSL
    IsLoginAuth bool    // 是否LoginAuth   是否使用LoginAuth认证方式（适用于IBM、微软邮箱服务器等）
}

2-2 入参结构说明

text
//其中 Form 和 Secret 通常来说就是用户名和密码

type Email struct {
    To      string `json:"to"`      // 邮件发送给谁
    Subject string `json:"subject"` // 邮件标题
    Body    string `json:"body"`    // 邮件内容
}

3. 方法API

text
utils.EmailTest(邮件标题，邮件主体) 发送测试邮件
例:utils.EmailTest("测试邮件"，"测试邮件")
utils.ErrorToEmail(邮件标题,邮件主体) 错误监控
例:utils.ErrorToEmail("测试邮件"，"测试邮件")
utils.Email(目标邮箱多个的话用逗号分隔，邮件标题，邮件主体) 发送测试邮件
例:utils.Email(”a.qq.com,b.qq.com“,"测试邮件"，"测试邮件")

4. 可直接调用的接口

text
测试接口： /email/emailTest [post] 已配置swagger

发送邮件接口接口： /email/emailSend [post] 已配置swagger
入参：
type Email struct {
    To      string `json:"to"`      // 邮件发送给谁
    Subject string `json:"subject"` // 邮件标题
    Body    string `json:"body"`    // 邮件内容
}

File: server/README.md

server项目结构

shell
├── api
│   └── v1
├── config
├── core
├── docs
├── global
├── initialize
│   └── internal
├── middleware
├── model
│   ├── request
│   └── response
├── packfile
├── resource
│   ├── excel
│   ├── page
│   └── template
├── router
├── service
├── source
└── utils
    ├── timer
    └── upload
文件夹 说明 描述
api api层 api层
--v1 v1版本接口 v1版本接口
config 配置包 config.yaml对应的配置结构体
core 核心文件 核心组件(zap, viper, server)的初始化
docs swagger文档目录 swagger文档目录
global 全局对象 全局对象
initialize 初始化 router,redis,gorm,validator, timer的初始化
--internal 初始化内部函数 gorm 的 longger 自定义,在此文件夹的函数只能由 initialize 层进行调用
middleware 中间件层 用于存放 gin 中间件代码
model 模型层 模型对应数据表
--request 入参结构体 接收前端发送到后端的数据。
--response 出参结构体 返回给前端的数据结构体
packfile 静态文件打包 静态文件打包
resource 静态资源文件夹 负责存放静态文件
--excel excel导入导出默认路径 excel导入导出默认路径
--page 表单生成器 表单生成器 打包后的dist
--template 模板 模板文件夹,存放的是代码生成器的模板
router 路由层 路由层
service service层 存放业务逻辑问题
source source层 存放初始化数据的函数
utils 工具包 工具函数封装
--timer timer 定时器接口封装
--upload oss oss接口封装

File: web/README.md

gin-vue-admin web

Project setup

text
npm install

Compiles and hot-reloads for development

text
npm run serve

Compiles and minifies for production

text
npm run build

Run your tests

text
npm run test

Lints and fixes files

text
npm run lint

整理代码结构

text
/* Detailed source-code truncated for AI context efficiency. */

File: README-en.md

English | 简体中文

gitee: https://gitee.com/pixelmax/gin-vue-admin

github: https://github.com/flipped-aurora/gin-vue-admin

Project Guidelines

Online Documentation : https://www.gin-vue-admin.com/

From the environment to the deployment of teaching videos

Development Steps (Contributor: LLemonGreen And Fann)

1. Basic Introduction

1.1 Project Introduction

Gin-vue-admin is a backstage management system based on vue and gin, which separates the front and rear of the full stack. It integrates jwt authentication, dynamic routing, dynamic menu, casbin authentication, form generator, code generator and other functions. It provides a variety of sample files, allowing you to focus more time on business development.

Online Demo: http://demo.gin-vue-admin.com

username：admin

password：123456

1.2 Contributing Guide

Hi! Thank you for choosing gin-vue-admin.

Gin-vue-admin is a full-stack (frontend and backend separation) framework for developers, designers and product managers.

We are excited that you are interested in contributing to gin-vue-admin. Before submitting your contribution though, please make sure to take a moment and read through the following guidelines.

1.2.1 Issue Guidelines

  • Issues are exclusively for bug reports, feature requests and design-related topics. Other questions may be closed directly. If any questions come up when you are using Element, please hit Gitter for help.

  • Before submitting an issue, please check if similar problems have already been issued.

1.2.2 Pull Request Guidelines

  • Fork this repository to your own account. Do not create branches here.

  • Commit info should be formatted as [File Name]: Info about commit. (e.g. README.md: Fix xxx bug)

  • Make sure PRs are created to develop branch instead of master branch.

  • If your PR fixes a bug, please provide a description about the related bug.

  • Merging a PR takes two maintainers: one approves the changes after reviewing, and then the other reviews and merges.

1.3 Version list

2. Getting started

text
- node version > v8.6.0
- golang version >= v1.14
- IDE recommendation: Goland
- initialization project: different versions of the database are not initialized. See synonyms at initialization https://www.gin-vue-admin.com/docs/first
- Replace the Qiniuyun public key, private key, warehouse name and default url address in the project to avoid data confusion in the test file.

2.1 server project

use Goland And other editing tools，open server catalogue，You can't open it. gin-vue-admin root directory

bash
# clone the project
git clone https://github.com/flipped-aurora/gin-vue-admin.git

# open server catalogue
cd server

# use go mod And install the go dependency package
go generate

# Compile 
go build -o server main.go (windows the compile command is go build -o server.exe main.go )

# Run binary
./server (windows The run command is server.exe)

2.1 web project

bash
# enter the project directory
cd web

# install dependency
npm install

# develop
npm run serve

2.2 Server

bash
# using go.mod

# install go modules
go list (go mod tidy)

# build the server
go build

2.3 API docs auto-generation using swagger

2.3.1 install swagger

(1) Using VPN or outside mainland China

text
go get -u github.com/swaggo/swag/cmd/swag

(2) In mainland China

In mainland China, access to go.org/x is prohibited，we recommend goproxy.io or goproxy.cn

bash
# If you are using a version of Go 1.13 - 1.15 Need to set up manually GO111MODULE=on, The opening mode is as follows, If your Go version is 1.16 ~ Latest edition You can ignore the following step one
# Step one、Enable Go Modules Function
go env -w GO111MODULE=on 
# Step two、Configuration GOPROXY Environment variable
go env -w GOPROXY=https://goproxy.cn,https://goproxy.io,direct

# If you dislike trouble,You can use the go generate Automatically execute code before compilation, But this can't be used command line terminal of `Goland` or `Vscode` 
cd server
go generate -run "go env -w .*?"

# Use the following command to download swag
go get -u github.com/swaggo/swag/cmd/swag

2.3.2 API docs generation

text
cd server
swag init

After executing the above command，server directory will appear in the docs folder docs.go, swagger.json, swagger.yaml Three file updates，After starting the go service, type in the browser http://localhost:8888/swagger/index.html You can view swagger document

3. Technical selection

  • Frontend: using Element based on Vue，to code the page.
  • Backend: using Gin to quickly build basic RESTful API. Ginis a web framework written in Go (Golang).
  • DB: MySql(5.6.44)，using gorm` to implement data manipulation, added support for SQLite databases.
  • Cache: using Redis to implement the recording of the JWT token of the currently active user and implement the multi-login restriction.
  • API: using Swagger to auto generate APIs docs。
  • Config: using fsnotify and viper to implement yaml config file。
  • Log: using zap record logs。

4. Project Architecture

4.1 Architecture Diagram

4.2 Front-end Detailed Design Diagram (Contributor: [baobeisuper](https://github.com/baobeisuper))

4.3 Project Layout

text
/* Detailed source-code truncated for AI context efficiency. */

5. Features

  • Authority management: Authority management based on jwt and casbin.
  • File upload and download: implement file upload operations based on Qiniuyun', Aliyun 'and Tencent Cloud (please develop your own application for each platform corresponding to token or key ).
  • Pagination Encapsulation：The frontend uses mixins to encapsulate paging, and the paging method can call mixins .
  • User management: The system administrator assigns user roles and role permissions.
  • Role management: Create the main object of permission control, and then assign different API permissions and menu permissions to the role.
  • Menu management: User dynamic menu configuration implementation, assigning different menus to different roles.
  • API management: Different users can call different API permissions.
  • Configuration management: the configuration file can be modified in the foreground (this feature is not available in the online experience site).
  • Conditional search: Add an example of conditional search.
  • Restful example: You can see sample APIs in user management module.
  • Multi-login restriction: Change user-multipoint to true in system in config.yaml (You need to configure redis and redis parameters yourself. During the test period, please report in time if there is a bug).
  • Upload file by chunk：Provides examples of file upload and large file upload by chunk.
  • Form Builder：With the help of @form-generator.
  • Code generator: Providing backend with basic logic and simple curd code generator.

6. Knowledge base

6.1 Team blog

https://www.yuque.com/flipped-aurora

There are video courses about frontend framework in our blo. If you think the project is helpful to you, you can add my personal WeChat:shouzi_1994，your comments is welcomed。

6.2 Video courses

(1) Development environment course

Bilibili：https://www.bilibili.com/video/BV1Fg4y187Bw/

(2) Template course

Bilibili：https://www.bilibili.com/video/BV16K4y1r7BD/

(3) 2.0 version introduction and development experience

Bilibili：https://www.bilibili.com/video/BV1aV411d7Gm#reply2831798461

(4) Golang basic course

https://space.bilibili.com/322210472/channel/detail?cid=108884

(5) gin frame basic teaching

bilibili：https://space.bilibili.com/322210472/channel/detail?cid=126418&ctype=0

(6) gin-vue-admin version update introduction video

bilibili：https://space.bilibili.com/322210472/channel/detail?cid=126418&ctype=0

7.Contacts

7.1 Groups

QQ group: 622360840

| QQ group |d
| :---: |
| |

Wechat group: comment "加入gin-vue-admin交流群"

Wechat

[About Us](https://www.gin-vue-admin.com/about/join.html)

8. Contributors

Thank you for considering your contribution to gin-vue-admin!

9. Donate

If you find this project useful, you can buy author a glass of juice :tropical_drink: here

10. Commercial considerations

If you use this project for commercial purposes, please comply with the Apache2.0 agreement and retain the author's technical support statement.

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#admin Browse admin catalog → #ai Browse ai catalog → #casbin Browse casbin catalog → #claw Browse claw catalog → #element-ui Browse element-ui catalog → #gin Browse gin catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →