flipped-aurora/gin-vue-admin · 上手攻略

  • 仓库：flipped-aurora/gin-vue-admin
  • 链接：https://github.com/flipped-aurora/gin-vue-admin
  • 分类：全栈开发框架 / 后台管理脚手架（Go + Vue）
  • 作者：spark
  • 更新：2026-07-13

1. 是什么

Gin-Vue-Admin（社区常简称 GVA）是一套前后端分离的全栈开发基础平台： - 后端：Gin（Go Web 框架）+ GORM + Casbin 权限模型 - 前端：Vue 3 + Element Plus + Vite - 数据库：MySQL / MariaDB 5.7+（InnoDB） - 缓存：Redis（JWT 多端登录限制） - 辅助：Swagger 自动文档、fsnotify + viper 热更新 YAML 配置、zap 日志、表单生成器、代码生成器

它不是简单的"脚手架模板"，更像一套带运营 8 年沉淀的中后台最佳实践集，在 GitHub 拥有约 2.4 万 ⭐（截至 2026 年 7 月），被广泛用于中小型企业后台、CMS、ERP、IoT 平台等场景。

当前主流发行版本：v2.9.2（2026-05-26 在 madewithvuejs.com 索引中显示；具体标签请以仓库 Releases 页为准）。

2. 解决什么问题

写业务后台是体力活——用户/角色/菜单/权限/上传/分页/字典/配置/接口文档 90% 都是重复劳动。GVA 把这些统统内置：

  • 不要写一遍 JWT/Casbin：开箱内置；角色 → API、角色 → 菜单 双维度授权。
  • 不要手写 CRUD：可视化"代码生成器"按表结构直接产出后端 handler/service/model + 前端 list/form 页面。
  • 不要为每个项目从零搭建项目：内置用户/角色/菜单/API 管理、条件搜索、分片上传、多点登录限制、表单生成器等"开箱即用"模块。
  • 配套完整文档/视频：官方文档站 + B 站教程 + 知识库 Yuque + 插件市场，覆盖环境到部署全流程。

3. 快速安装

3.1 前置环境

组件 版本要求 说明
Go ≥ 1.22（README 标注，徽章为 1.20） 后端编译运行
Node.js > v18.16.0 前端构建（Node 20 LTS 也可）
MySQL / MariaDB 5.7+ InnoDB 引擎
Redis 5+ JWT 多端登录限制、JWT 黑名单
IDE 推荐 GoLand；VSCode 也提供 gin-vue-admin.code-workspace

若使用 Windows，已自带 WSL2 即可，无需特别配置。

3.2 启动步骤

# 1) 克隆
git clone https://github.com/flipped-aurora/gin-vue-admin.git
cd gin-vue-admin

# 2) 启动后端
cd server
go generate      # 通过 go:generate 生成 swagger 等代码
go run .         # 默认监听 :8888

# 3) 另起一个终端启动前端
cd ../web
npm install
npm run serve    # 默认 :8080，会代理 /api 到 8888

启动后浏览器访问： - 前端 dev：http://localhost:8080 - 后端 Swagger API 文档：http://localhost:8888/swagger/index.html

3.3 生成 Swagger 文档（可选）

go install github.com/swaggo/swag/cmd/swag@latest
cd server
swag init        # 输出 docs/docs.go / swagger.json / swagger.yaml

3.4 演示账号

官方在线 demo：http://demo.gin-vue-admin.com 用户名 admin / 密码 123456

4. 核心用法

4.1 典型目录约定

gin-vue-admin/
├── server/                 ← 后端（用 IDE 单独打开此目录）
│   ├── api/v1/             ← HTTP handler
│   ├── service/            ← 业务逻辑
│   ├── model/              ← GORM 模型
│   ├── router/             ← 路由 + Casbin 中间件
│   ├── config/             ← viper 配置
│   ├── source/             ← MySQL & Redis 客户端
│   └── docs/               ← swag init 生成
├── web/                    ← 前端（Vue 3 + Element Plus）
│   ├── src/api/            ← axios 封装
│   ├── src/view/           ← 业务页面
│   └── src/router/         ← 动态路由
└── gin-vue-admin.code-workspace

4.2 代码生成器（最常用）

通过 Web 端"代码生成器"导入 MySQL 表 → 一键生成： - 后端：api/{table}.go、service/{table}.go、model/{table}.go、router/{table}.go - 前端：src/view/{module}/{table}/{list,form}.vue、src/api/{table}.js

产生基础 CRUD 后，只需在该 service 写业务逻辑即可。model 层可直接 db.AutoMigrate 推表。

4.3 权限模型

权限分两类，用 Casbin 表达： 1. 角色 → API：谁能调哪些路由（中间件 JWTAuth() + CasbinHandler()） 2. 角色 → 菜单：登录后从 user.GetMenuTree() 拉取该用户菜单树，前端动态渲染

新增接口只需在 server/router/{module}/{table}_router.go 写：

authorityRouter.POST("createAuthority", authorityApi.CreateAuthority) // 需 Casbin 匹配

并在 Casbin 策略库(casbin_rule 表)给对应角色写入 p, role_id, /path, METHOD 即生效。

4.4 Swagger 注释式 API 文档

在 handler 上方按 swagger 规范写注释：

// @Tags ExaCustomer
// @Summary 创建客户
// @Security ApiKeyAuth
// @accept json
// @Produce json
// @Param data body request.ExaCustomerReq true "客户信息"
// @Success 200 {object} response.Response{...}
// @Router /exa/customer [post]
func (a *CustomerApi) CreateCustomer(c *gin.Context) { ... }

运行 swag init 后即可在 swagger UI 看到接口描述、参数 schema、鉴权方式。

4.5 配置热更新

server/config.yaml 由 viper.WatchConfig() + fsnotify 监听，修改后无需重启服务。

4.6 分片上传

前端使用 vue-simple-uploader 风格封装；后端在 fileUploadAndDownload 模块支持七牛云 / 阿里云 OSS / 腾讯云 COS 三种 driver，配置切换即可。

5. 典型适用场景

  • 企业内部后台（订单、库存、CRM、ERP）
  • IoT / 监控平台（设备管理 + Grafana 看板嵌入）
  • CMS / 内容平台
  • 教学 / 毕设：作为"完整可见的中后台范例"给学生拆解
  • 快速搭建 MVP：B 站视频教程从环境到部署完整

6. 坑与注意

  1. 许可证 = BSL 1.1（Business Source License） - 学习、评估、个人/非商用：免费使用，注意保留版权声明。 - 商用、生产部署或去除版权：必须 购买授权。误用可能产生法律责任，开公司项目前务必看清。
  2. 必须 cd server 后再 go run：不要在仓库根目录 go run，会报 import 路径混乱。
  3. MySQL 必须 InnoDB，且 sql_mode 不要过严，否则 GORM 默认建表会因日期默认值报错（NO_ZERO_DATE）。
  4. Redis 必连：否则登录会因为 JWT 黑名单/Ping 失败报错。最小配置 config.yaml 里给个 dev redis：127.0.0.1:6379，无密码。
  5. 前端 Node 版本：< v18 会触发 crypto.hash 等 polyfill 报错；v20 LTS 完全可用。
  6. 代码生成器 ≠ 全自动：生成的只是"模板"，复杂业务（如树结构、审批流、租户隔离）仍要二次开发。
  7. 国内访问 GitHub 慢：clone / go mod download 可能需配 GOPROXY=https://goproxy.cn,direct。
  8. 不再提供免费技术支持：作者明确告知，付费支持才走一对一。

7. 与同类对比

项目 后端 前端 特点 适合
Gin-Vue-Admin Go / Gin Vue 3 / Element Plus 中文活跃社区，代码生成器+表单生成器+BSL 商业许可 国内中小团队、想"开箱即用"的
go-admin Go / Gin Vue / React 双前端 插件式框架，更轻量 偏好 framework 自己拼装的
RuoYi-Vue Java / Spring Boot Vue 2/3 国产经典、文档细致、人气高 Java 技术栈、稳妥选择
vue-vben-admin 任意（前端为主） Vue 3 / TS / Naive/Antdv 现代化 TS 优先的前端模板 前端为主、要换后端的
soybeanjs/soybean-admin 任意 Vue 3 / Naive UI / TS 极致清爽现代 偏前端的中小项目

如果团队栈是 Go + Vue，且希望"装好就跑业务"，GVA 仍是国内最顺手的选择之一。如果你的下游代码不会被对外发行、或不在意 BSL，可直接用；反之建议评估 go-admin / vben admin / 自建。

8. 一句话推荐结论

国内中小团队用 Go + Vue 做业务后台，GVA 仍是"最快让你下班"的脚手架——功能全、教程全，但商用前务必看清 BSL 1.1 的边界。

参考来源

  • 仓库 README：https://github.com/flipped-aurora/gin-vue-admin
  • 官方文档：https://www.gin-vue-admin.com
  • 在线演示：http://demo.gin-vue-admin.com（账号 admin / 123456）
  • 插件市场：https://plugin.gin-vue-admin.com/
  • 视频教程合集（B 站）：https://www.bilibili.com/video/BV1Rg411u7xH/
  • madewithvuejs 索引（最新版本 v2.9.2，2026-05-26 提及）：https://madewithvuejs.com/gin-vue-admin
  • 版本号信息以仓库 Releases 页面 为准

不确定处：徽章所示 Go 版本（1.20）与文档要求（>=1.22）有出入，以仓库根目录 go.mod 为准；本篇未联网核对 go.mod，建议读者本地实测。