goadmin是基于gin构建的独立项目框架，非gin插件，需克隆完整项目并执行migrate初始化数据库、严格按模块机制注册路由、启用backend权限模式才能正常运行。
GoAdmin不是Gin插件，而是独立项目框架
别被“Gin整合GoAdmin”这种说法误导——GoAdmin本身基于Gin构建，但不是通过gin.Engine.Use()就能接入的中间件。它是一套完整封装的项目结构，包含预设路由、RBAC权限模型、数据库迁移脚本和CLI工具。直接在已有Gin项目里go get github.com/go-admin-team/go-admin然后调用某个函数，大概率会报错：panic: runtime error: invalid memory address or nil pointer dereference，因为GoAdmin依赖其自己的初始化流程（如app.Initialize()、配置加载顺序、Casbin策略加载时机）。
正确做法是：从GoAdmin官方仓库克隆完整项目，再按需修改业务模块。强行“整合”只会陷入配置冲突、中间件注册顺序错乱、JWT密钥不一致等连锁问题。
启动前必须跑通 migrate 和 config/settings.yml
GoAdmin启动失败最常见的原因是数据库未初始化或配置文件路径不对。它不会像Laravel那样自动提示“请先运行php artisan migrate”，而是静默失败或卡在server命令后无响应。
-
./go-admin migrate -c config/settings.yml必须成功执行，否则sys_user表不存在，登录接口直接返回500 internal server error -
config/settings.yml中的database.dsn必须是标准MySQL格式：root:password@tcp(127.0.0.1:3306)/go_admin?charset=utf8mb4&parseTime=True&loc=Local，漏掉&或写成&会导致连接失败 - Redis配置项
redis.addr如果没配，部分功能（如登录日志、缓存菜单）会降级但不报错；但如果启用了cache.enabled: true而Redis不可达，服务会panic退出
新增业务路由必须遵循 GoAdmin 的模块注册机制
想加一个“城市管理”接口，不能像普通Gin那样直接写r.POST("/city", handler)。GoAdmin强制要求路由注册走routerCheckRole或routerNoCheck切片，且需绑定到指定Group（如v1.Group("/admin")），否则中间件（JWT校验、角色权限检查）不会生效。
典型错误写法：
func registerCityRouter(r *gin.RouterGroup) {
r.GET("/city", apis.City{}.GetList) // ❌ 缺少authMiddleware.MiddlewareFunc()，接口裸奔
}
正确写法（参考app/admin/router/province.go）：
func registerCityRouter(v1 *gin.RouterGroup, authMiddleware *jwt.GinJWTMiddleware) {
api := apis.City{}
r := v1.Group("/city").Use(authMiddleware.MiddlewareFunc()).Use(middleware.AuthCheckRole())
r.GET("", api.GetList)
r.POST("", api.Create)
}
注意：AuthCheckRole()依赖Casbin策略表已存在，如果migrate没跑完就注册该路由，访问时会返回403 forbidden而非明确错误提示。
前端路由权限模式选 backend 才真正安全
GoAdmin支持两种权限控制模式：frontend（前端过滤路由）和backend（后端动态返回可访问菜单）。很多人图省事设成VITE_ROUTER_ACCESS_MODE=frontend，结果发现只要改前端authority字段就能绕过所有权限——因为后端根本没做校验。
真正起作用的是backend模式，它要求：
- 用户登录后，前端调用
/api/v1/menu获取带authority字段的菜单树 - 每个API请求仍需携带
Authorization: Bearer xxx，由AuthCheckRole()中间件调用Casbin执行e.Enforce(role, path, method) -
casbin_model.conf必须与数据库中的sys_casbin_rule表保持同步，手动增删规则后要重启服务或调用casbin.LoadPolicy()
这个环节最容易被忽略：改了菜单权限，忘了更新Casbin策略表，或者没重启服务导致策略未重载，结果权限看似开了实则无效。
