用 Go 搭一套带权限的中后台（go-admin）

企业内部的中后台系统，用户、角色、菜单、部门、字典、操作日志、登录日志这几张表和对应的增删改查页面，几乎每换一个项目就要重写一遍。权限模型更难处理，菜单能不能看见、接口能不能调用、数据能看到哪个部门，三件事分属不同的控制层，做到第三个项目才大致摸清该怎么组织。

go-admin 是基于 Gin 与 Vue 的开源中后台脚手架，内置 RBAC 权限、JWT 鉴权和代码生成器，改一下数据库连接就能启动带权限的管理后台。

它拆成两个仓库：后端是 go-admin，前端是 go-admin-ui，两者必须放在同一个文件夹下才能联调。后端技术栈为 Gin + GORM + Casbin + JWT，前端可在 Element UI、Arco Design、Ant Design 三套方案中选择。仓库地址是 https://github.com/go-admin-team/go-admin，采用 MIT License，主要语言为 Go，占比 99.1%，当前 Star 12798、Fork 2598、开放 Issue 23。

它解决的是什么问题

没有这类脚手架时，一个中后台项目启动阶段要自己完成：建库建表并写好初始化数据的迁移脚本，搭一套登录鉴权与请求中间件，实现角色与菜单、按钮、接口之间的授权关系，再补上日志记录和接口文档。这些代码与业务无关，却占据了项目前期相当一部分时间。

go-admin 把这些部分做成可复用的底座。按 README 的说法，初始化系统只需要修改配置文件里的数据库连接，然后用迁移指令建好库表，用服务指令启动 API。功能层面还有代码生成器和表单构建，把「按数据表结构生成增删改查业务」这一步也做成了可视化操作。

典型使用场景

• 承接内部管理系统交付的团队，已经有明确的表和字段，希望在一套成型底座上补业务页面，而不是从登录页开始写。
• 后端选型为 Go 的开发者，需要 RBAC、JWT、Swagger 文档、操作日志这些常规能力，同时希望前端也能一起拿到。
• 租户或组织架构复杂的系统，需要按机构划分数据范围。仓库定位里写了多租户支持，角色管理中也有按组织划分的数据范围权限。
• 只是先评估形态的人，可以直接打开在线 Demo 看效果，Element Plus vue3 版在 https://vue.go-admin.pro ，antd 版在 https://antd.go-admin.pro ，两处的账号密码都是 admin / 123456。

几个常见疑问

给角色配了菜单权限，用户登录后为什么还提示没有接口访问权限？

Issue 里有多条反馈指向同一处：接口权限和菜单权限是两套分开配置的东西，只配菜单权限不够。有的用户升级到 v2.0.7 后，角色管理的菜单树里只看到系统管理、开发工具、定时任务、系统工具、文章管理这几项，找不到「接口权限」及子项。这类问题在仓库里标记为已解决，处理时先确认版本与迁移是否执行完整，再检查角色上是否同时分配了接口权限。

MySQL 上执行 migrate 为什么会中断？

v2.4.0 的发布说明里记录了这个已知问题：在 MySQL 上跑 migrate 会报 Error 1264 (22003): Out of range value for column 'sort'，原因是种子菜单的 sort 值超出了 MySQL 的 tinyint 范围。迁移框架不是事务性的，跑到出错那条就停下，排在它之后的清理迁移不会执行，因此该版本要求的「清理库中残留权限数据」实际没做。使用 MySQL 时不要停留在这一版。

从旧版本升级要注意什么？

v2.5.0 有两处破坏性变更，其中核心导入路径发生变化，所有 github.com/go-admin-team/go-admin-core 都要改为带 /v2 的形式。v2.6.0 改了限流行为，被限流的请求现在返回 HTTP 429，之前返回的是 HTTP 200 加 body 里的 code: 500，会影响负载均衡和可用性监控的判断。v2.7.0 要求 Go 1.27.1 或更高版本，并且升级前需要跑一次 migrate，代码生成器从这一版开始输出 Vue 3 页面。

主要功能

• RBAC 权限控制：基于 Casbin 实现，覆盖菜单权限、按钮权限标识与接口权限，角色可按组织划分数据范围。
• JWT 鉴权与中间件：提供用户认证、跨域、访问日志、跟踪 ID 等中间件，接口遵循 RESTful 设计规范。
• 代码生成器：根据数据表结构生成对应的增删改查业务代码，整个过程在界面上可视化操作。v2.7.0 起生成 Vue 3 页面。
• 表单构建：拖拽方式自定义页面样式与布局。
• 系统管理模块：包含用户管理、部门管理、岗位管理、菜单管理、角色管理、字典管理、参数管理。
• 日志模块：操作日志记录系统正常操作与异常信息，登录日志记录登录情况并包含登录异常。
• 接口文档：基于 swaggo，根据业务代码自动生成 API 接口文档。
• 多命令模式：migrate 负责初始化数据库资源，server 负责启动服务。

安装与最短示例

本地环境要求 Go 1.27.1、Node.js v22 以上（推荐 v24 LTS）、包管理器 pnpm v9 以上。前端项目使用 pnpm。先把两个仓库取到同一个目录里：

mkdir goadmin
cd goadmin
git clone https://github.com/go-admin-team/go-admin.git
git clone https://github.com/go-admin-team/go-admin-ui.git

想最快看到运行效果，用 SQLite 路线。它需要 C 编译器（cgo）和 sqlite3 构建标签，普通的 go build 不带这个标签：

cd ./go-admin
go build -tags sqlite3
./go-admin migrate -c config/settings.sqlite.yml
./go-admin server -c config/settings.sqlite.yml

Windows 下把命令里的 ./go-admin 换成 go-admin.exe。API 随后运行在 http://localhost:8000 。打开界面需要在 go-admin-ui 目录里执行 pnpm install 与 pnpm dev，用 admin / 123456 登录。

换成 MySQL、PostgreSQL 或 SQL Server 时走另一条路径，编译前不再带 sqlite3 标签，数据库信息写在 config/settings.yml 的 settings.database 下：

cd ./go-admin
go mod tidy
go build
vi ./config/settings.yml
./go-admin migrate -c config/settings.yml
./go-admin server -c config/settings.yml

仓库里还有 Dockerfile 与 docker-compose.yml。README 给出的镜像构建命令是 docker build -t go-admin .，容器启动的完整参数在节选中被截断，compose 的用法仓库里没有说明。

关键参数

• -c：指定配置文件路径，常见取值是 config/settings.yml 与 config/settings.sqlite.yml。
• -tags sqlite3：构建时启用 SQLite 支持，缺了它会走 cgo 报错。Windows 10 以上如果没装 CGO，会看到 cgo: exec gcc: exec: "gcc": executable file not found in %PATH% 这类提示。
• migrate 与 server：前者初始化数据库，后者启动服务，首次部署必须先跑 migrate。
• -a=true：Issue 里出现过 go-admin server -c=config/settings.dev.yml -a=true 的启动写法，README 节选没有解释这个参数的作用。
• 配置文件里的 settings.database：数据库连接信息写在这一段，同时需要确认日志路径。

结果在哪里看

• 后端服务启动后，API 监听 http://localhost:8000 。
• 前端在 go-admin-ui 目录执行 pnpm dev 后进入登录页，README 没有说明开发服务器占用哪个端口。
• migrate 执行完成后，库表与种子数据写入配置里指定的数据库；仓库根目录带了一个 go-admin-db.db 文件。
• 接口文档由 swaggo 生成，可在 Swagger 页面查看与调试接口。

实际使用中的坑

• 权限配置走错层。有用户按教程给新角色配好菜单显示和文档权限后，用该账号登录仍提示文档无访问权限，这条 Issue 评论 12 条，状态为待解决。接口权限与菜单权限分开配置是这个项目的设计，配置时两部分都要覆盖。
• role_key 值会越权。有反馈指出按 role_key 拉取权限时，如果一个普通角色的该字段被误设成 admin，它会拉到超级管理员的菜单。这条已标记为已解决。
• 角色权限改动影响面过大。修改某个用户的角色权限并提交后，sys_casbin_rule 表被整表更新，评论 8 条，状态为已解决。
• 改头像连带改密码。有反馈称修改头像并提交后密码也被一起改了，评论 7 条，已解决。

和同类的差别在哪

可核验的同功能对照项目只有一个，下面把两者的定位摆在一起，方便判断选哪个方向。

• go-admin-team/go-admin（本项目）：适合团队用 Go 做后端、需要一套同时具备 RBAC、代码生成与多租户的中后台底座的开发者。部署方式为后端编译成二进制加独立的前端仓库，官方提供 Dockerfile 与 docker-compose.yml，最短路径是构建 SQLite 版本后依次跑 migrate 与 server。主要限制在于工具链要求较高，需要 Go 1.27.1，首次部署必须执行 migrate，v2.4.0 在 MySQL 上的迁移存在中断问题，Issue 里与权限配置相关的困惑较多。要后端、权限模型和代码生成一起到位时选它更合适。项目地址：https://github.com/go-admin-team/go-admin
• Sarkararnob754/pro-design-admin（同功能档位，Star 2）：从仓库描述看，它提供的是管理界面方向的模板。适合只需要一套现成管理后台界面、自己掌握后端的前端开发者。部署方式仓库没有说明，主要限制未逐一核实。手上已有后端、只想拿一份界面起步时，选它更合适。项目地址：https://github.com/Sarkararnob754/pro-design-admin

如果只是想快速搭一批管理页面，不打算引入 Go 工具链，也不需要数据库迁移和 RBAC 这一整套后端能力，go-admin 的启动成本反而更高，它要求先装 Go 1.27.1、再跑一次 migrate 才能看到界面。这种情况下先从前端模板类的项目入手更省事。反过来，需要用户、角色、菜单、数据范围和接口权限连成一套时，纯界面模板补不上这块。

适合谁，不适合谁

适合用 Go 做后端、需要在短时间内交付一套带权限体系的内部管理系统的团队；也适合已经有一批现成数据表，想用代码生成器把增删改查页面批量做出来的开发者。不适合只想要一份静态管理界面、不想引入后端服务和数据库迁移链路的场景；对权限模型有大量定制需求、需要频繁改写授权逻辑的项目，也要评估改造量是否划算。

焚评：这个项目的量化评分

本项目的选题来自 焚.com（一个按公开公式给 GitHub 项目打分的站）。焚评当前总分 9.8 分（满分 10）。下表是各维度的得分：

评分口径、权重与计算方式见焚.com 的评分方法页；数据随 GitHub 指标刷新，具体数值以焚.com 当前页面为准。本文正文为诀.com 独立撰写，评分数据由焚.com 授权引用。