# go-admin

**Repository Path**: kordar/goadmin

## Basic Information

- **Project Name**: go-admin
- **Description**: golang 后台管理通用类库
- **Primary Language**: Go
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2021-12-16
- **Last Updated**: 2026-04-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# goadmin

基于 Gin 的后台管理模块，提供登录（图形验证码 + JWT）、RBAC 鉴权、通用资源 CRUD（resource API）、以及一组内置资源（管理员、字典、路由、系统设置等）。

本仓库是一个 Go Module（库），不包含 `main` 启动入口；你可以在你的服务中引入后，通过 [starter.Server](file:///d:/Projects/GolangProjects/goadmin/starter/server.go#L28-L76) 一键挂载相关模块与路由。

## 功能

- 登录与鉴权：验证码获取、登录换取 JWT，后续请求通过 `Token` Header 鉴权
- RBAC：非超级管理员按路由/场景校验权限
- 资源化 CRUD：通过 `/resource/:apiName/*` 统一对资源进行增删改查
- 内置资源：`admin`、`dict`、`dict-item`、`jumpway`、`router`、`setting`、`setting-icon`、`yaml`

## 依赖与环境

- Go：`go.mod` 标记为 Go 1.25.0（建议 Go 1.25+）
- 运行期依赖：MySQL、Redis
- Web 框架：Gin（由 `ginsys-starter` 统一启动与装配）

## 集成与启动

1. 引入依赖：

```bash
go get gitee.com/kordar/goadmin@latest
```

2. 在你的服务中创建启动入口（示例）：

```go
package main

import "gitee.com/kordar/goadmin/starter"

func main() {
	starter.Server(nil, nil)
}
```

3. 配置 MySQL / Redis / RBAC，并确保存在名为 `sys` 的实例（见下文“配置要点”）。

## 配置要点

本项目通过依赖注入获取数据库与 Redis 客户端，默认使用以下具名实例：

- MySQL：`mysql.sys`（见 [GoAdminDB](file:///d:/Projects/GolangProjects/goadmin/admin/inject/in.go#L20-L24)）
- Redis：`goredis.sys`（见 [GoAdminDB](file:///d:/Projects/GolangProjects/goadmin/admin/inject/in.go#L20-L24)）

同时，`goadmin` 模块本身会读取以下配置键：

- `goadmin.db`：默认数据库实例 id（例如 `sys`），用于校验 MySQL 实例存在（见 [GoAdminModule.Load](file:///d:/Projects/GolangProjects/goadmin/admin/module.go#L31-L45)）
- `goadmin.hmac-sample-secret`：JWT 签名秘钥（长度需 > 6 才会覆盖默认值，见 [GoAdminModule.Load](file:///d:/Projects/GolangProjects/goadmin/admin/module.go#L41-L46)）
- `goadmin.login`：登录页配置（接口直接透传，见 [AuthController.Config](file:///d:/Projects/GolangProjects/goadmin/admin/controller/auth_ctrl.go#L72-L76)）
- `upload.domain`：图片域名/前缀（用于头像等字段拼接，见 [DomainImage](file:///d:/Projects/GolangProjects/goadmin/admin/util/upload_util.go#L10-L14)）
- `gorm_log_level`：GORM 日志级别（见 [starter.Server](file:///d:/Projects/GolangProjects/goadmin/starter/server.go#L28-L51)）

MySQL / Redis / RBAC 的具体连接参数由对应 starter 模块读取：

- MySQL：`github.com/kordar/mysql-starter`
- Redis：`github.com/kordar/goredis-starter`
- RBAC：`github.com/kordar/gorbac-starter`（依赖 MySQL 与 Redis）

只要确保上述 starter 能初始化出 `mysql.sys` 与 `goredis.sys`，并将 `goadmin.db` 设置为 `sys`，即可满足本模块的最小运行前置条件。

## HTTP API

### 登录相关（无需鉴权）

- `GET /login/captcha`：获取图形验证码
- `POST /login/captcha`：同上
- `POST /login/submit`：登录（body 见 [LoginForm](file:///d:/Projects/GolangProjects/goadmin/admin/form/admin_form.go#L7-L12)）
- `POST /login/config`：获取登录配置（返回 `goadmin.login` 配置段）

登录成功后会返回 `token`（JWT），后续请求通过 Header 传入：

- `Token: <jwt>`

### 受保护接口（需要 Token）

资源通用接口：

- `POST /resource/:apiName/info`
- `POST /resource/:apiName/list`
- `POST /resource/:apiName/add`
- `POST /resource/:apiName/update`
- `POST /resource/:apiName/delete`
- `POST /resource/:apiName/edit`
- `POST /resource/:apiName/configs`
- `POST /resource/:apiName/upload`
- `POST /resource/:apiName/download`

内置 `apiName`（对应各服务的 `ResourceName()`）：

- `admin`、`dict`、`dict-item`、`jumpway`、`router`、`setting`、`setting-icon`、`yaml`

后台功能接口：

- `POST /menus`
- `POST /admin/user-info`
- `POST /admin/register`
- `POST /admin/reset-password`
- `POST /admin/upload-avatar`

RBAC 接口：

- `POST /rbac/assign`
- `POST /rbac/roles`
- `POST /rbac/add-role`
- `GET /rbac/get-roles-by-user`
- `POST /rbac/update-role`
- `POST /rbac/delete-role`
- `POST /rbac/batch-delete-role`
- `POST /rbac/permissions`
- `GET /rbac/get-children`
- `POST /rbac/add-permission-children`
- `GET /rbac/get-permissions-by-user`
- `POST /rbac/add-permission`
- `POST /rbac/update-permission`
- `POST /rbac/delete-permission`
- `POST /rbac/batch-delete-permission`
- `POST /rbac/fast-add-permission`
- `POST /rbac/rules`
- `POST /rbac/add-rule`
- `POST /rbac/update-rule`
- `POST /rbac/delete-rule`

完整路由定义见 [admin/router.go](file:///d:/Projects/GolangProjects/goadmin/admin/router.go#L21-L75)。

## 目录结构

- [admin](file:///d:/Projects/GolangProjects/goadmin/admin)：核心模块（路由、控制器、服务、RBAC、资源 CRUD）
- [starter](file:///d:/Projects/GolangProjects/goadmin/starter)：一键装配并启动服务
- [reader](file:///d:/Projects/GolangProjects/goadmin/reader)：查询/格式化读取辅助
- [cli](file:///d:/Projects/GolangProjects/goadmin/cli)：命令行相关（当前多为预留）

## 开发与测试

```bash
go test ./...
```