|
|
# VBase
|
|
|
|
|
|
<p align="center">
|
|
|
<img src="https://img.shields.io/badge/Go-1.24+-00ADD8?style=flat-square&logo=go" alt="Go Version">
|
|
|
<img src="https://img.shields.io/badge/License-Apache%202.0-blue?style=flat-square" alt="License">
|
|
|
<img src="https://img.shields.io/badge/Framework-Vigo-orange?style=flat-square" alt="Framework">
|
|
|
</p>
|
|
|
|
|
|
<p align="center">
|
|
|
<b>基于 Golang 的高性能身份认证与权限管理基础框架</b>
|
|
|
</p>
|
|
|
|
|
|
<p align="center">
|
|
|
<a href="#快速开始">快速开始</a> •
|
|
|
<a href="#核心特性">核心特性</a> •
|
|
|
<a href="#集成指南">集成指南</a> •
|
|
|
<a href="#api文档">API 文档</a> •
|
|
|
<a href="#架构设计">架构设计</a>
|
|
|
</p>
|
|
|
|
|
|
---
|
|
|
|
|
|
## 简介
|
|
|
|
|
|
**VBase** 是一个基于 [Vigo](https://github.com/veypi/vigo) 框架开发的高性能后端基础框架，提供一套标准化的用户管理、作用域权限控制（Scoped RBAC）和 OAuth2 认证服务。可作为独立服务部署，也可作为基础库集成到你的 Go 项目中。
|
|
|
|
|
|
## 核心特性
|
|
|
|
|
|
- 🔐 **完整认证体系** - JWT Token 认证（Access + Refresh）、多因素认证（短信验证码）
|
|
|
- 🛡️ **Scoped RBAC 权限控制** - 基于作用域（Scope）的角色访问控制，支持资源级权限和通配符权限
|
|
|
- <20> **层级权限管理** - 支持资源类型（奇数层）和实例（偶数层）的精细化权限控制
|
|
|
- 🔑 **OAuth2 Provider** - 完整的 OAuth2 服务端实现，支持第三方应用接入
|
|
|
- 🗄️ **多数据库支持** - MySQL、PostgreSQL、SQLite 自动适配
|
|
|
- 📱 **内置管理界面** - 基于 vhtml 的嵌入式管理后台
|
|
|
- 🚀 **高性能** - 基于洋葱模型中间件架构，低延迟高并发
|
|
|
- 🧪 **完整测试** - 集成测试脚本覆盖核心业务流程
|
|
|
|
|
|
## 快速开始
|
|
|
|
|
|
### 安装
|
|
|
|
|
|
```bash
|
|
|
go get github.com/veypi/vbase
|
|
|
```
|
|
|
|
|
|
### 作为独立服务运行
|
|
|
|
|
|
```bash
|
|
|
# 克隆项目
|
|
|
git clone https://github.com/veypi/vbase.git
|
|
|
cd vbase
|
|
|
|
|
|
# 配置数据库（编辑 dev.yaml 或使用环境变量）
|
|
|
export DSN="root:password@tcp(127.0.0.1:3306)/vbase?charset=utf8&parseTime=True"
|
|
|
export DB="mysql"
|
|
|
|
|
|
# 启动服务
|
|
|
go run ./cli/main.go
|
|
|
|
|
|
# 或使用 Makefile（默认端口 4001）
|
|
|
make run
|
|
|
```
|
|
|
|
|
|
服务默认在 `http://localhost:4000` 启动，管理界面访问 `/vb/` 路径。
|
|
|
|
|
|
### 作为库集成
|
|
|
|
|
|
```go
|
|
|
package main
|
|
|
|
|
|
import (
|
|
|
"github.com/veypi/vbase"
|
|
|
"github.com/veypi/vigo"
|
|
|
)
|
|
|
|
|
|
var Router = vigo.NewRouter()
|
|
|
|
|
|
func init() {
|
|
|
// 挂载 VBase 路由到 /vb 前缀
|
|
|
Router.Extend("/vb", vbase.Router)
|
|
|
}
|
|
|
```
|
|
|
|
|
|
更多集成方式请参考 [集成指南](./docs/integration.md)。
|
|
|
|
|
|
## 项目结构
|
|
|
|
|
|
```
|
|
|
vbase/
|
|
|
├── api/ # REST API 接口层
|
|
|
│ ├── auth/ # 认证接口（登录、注册、Token 刷新）
|
|
|
│ ├── oauth/ # OAuth2 Provider 接口
|
|
|
│ ├── role/ # 角色管理
|
|
|
│ └── user/ # 用户管理
|
|
|
├── auth/ # 核心权限控制模块（Scoped RBAC 实现）
|
|
|
├── cfg/ # 配置管理
|
|
|
├── cli/ # 命令行入口
|
|
|
├── models/ # 数据模型（GORM）
|
|
|
├── ui/ # 前端管理界面（vhtml）
|
|
|
└── docs/ # 文档
|
|
|
```
|