OneAuth/README.md

VBase

基于 Golang 的高性能身份认证与权限管理基础框架

快速开始 • 核心特性 • 集成指南 • API 文档 • 架构设计

---

简介

VBase 是一个基于 Vigo 框架开发的高性能后端基础框架，提供一套标准化的用户管理、作用域权限控制（Scoped RBAC）和 OAuth2 认证服务。支持 Session + JWT 双 Token 认证、Cookie 令牌传送和短信/邮箱验证码注册。可作为独立服务部署，也可作为基础库集成到你的 Go 项目中。

核心特性

• 完整认证体系 — Session + JWT（Access + Refresh Token），HttpOnly Cookie / Header / Query 多通道传送
• Scoped RBAC 权限控制 — 基于作用域（Scope）的角色访问控制，支持多应用权限隔离
• 层级权限管理 — 支持资源类型（奇数层）和实例（偶数层）的精细化权限控制
• OAuth2 Provider — 完整的 OAuth2 服务端实现，支持第三方应用接入
• 多因素认证 — 短信/邮箱验证码注册和验证
• 多数据库支持 — SQLite（默认）、MySQL、PostgreSQL 自动适配
• 嵌入式管理界面 — 基于 vhtml 的管理后台，开箱即用
• API 文档 — 内置 /_api.json 接口文档端点
• 高性能 — 基于洋葱模型中间件架构，Redis 缓存 Session 验证

快速开始

安装

go get github.com/veypi/vbase

作为独立服务运行

# 克隆项目
git clone https://github.com/veypi/vbase.git
cd vbase

# 直接启动（默认 SQLite + 端口 4000）
go run ./cli/*.go -p 4000

# 或使用 Makefile
make run

服务默认在 http://localhost:4000 启动，管理界面访问 /vb/ 路径，API 文档访问 /_api.json。

作为库集成

package main

import (
	"github.com/veypi/vbase"
	"github.com/veypi/vbase/cfg"
	"github.com/veypi/vigo"
)

func main() {
	app := vigo.New("myapp", vbase.Router, cfg.Global, vigo.WithInit(vbase.Init))
	panic(app.Run())
}

更多集成方式请参考 集成指南。

项目结构

vbase/
├── api/           # REST API 接口层
│   ├── auth/      # 认证接口（登录、注册、Token 刷新）
│   ├── oauth/     # OAuth2 Provider 接口
│   ├── role/      # 角色管理
│   ├── user/      # 用户管理
│   ├── settings/  # 系统设置接口
│   └── verification/ # 验证码接口
├── auth/          # 核心权限控制模块（Scoped RBAC + Session 管理）
├── cfg/           # 配置管理
├── cli/           # 命令行入口
├── models/        # 数据模型（GORM）
├── ui/            # 前端管理界面（vhtml）
└── docs/          # 文档