OneAuth/README.md

VBase

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

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

---

简介

VBase 是一个基于 Vigo 框架开发的高性能后端基础框架，提供一套标准化的用户管理、组织架构（多租户）、权限控制（RBAC）和 OAuth2 认证服务。可作为独立服务部署，也可作为基础库集成到你的 Go 项目中。

核心特性

• 🔐 完整认证体系 - JWT Token 认证（Access + Refresh）、多因素认证（短信验证码）
• 🛡️ RBAC 权限控制 - 基于角色的访问控制，支持资源级权限和通配符权限
• 🏢 多租户架构 - 组织级别的数据隔离，灵活适配 B2C/B2B/平台型业务
• 🔑 OAuth2 Provider - 完整的 OAuth2 服务端实现，支持第三方应用接入
• 🗄️ 多数据库支持 - MySQL、PostgreSQL、SQLite 自动适配
• 📱 内置管理界面 - 基于 vhtml 的嵌入式管理后台
• 🚀 高性能 - 基于洋葱模型中间件架构，低延迟高并发
• 🧪 完整测试 - 集成测试脚本覆盖核心业务流程

快速开始

安装

go get github.com/veypi/vbase

作为独立服务运行

# 克隆项目
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/ 路径。

作为库集成

package main

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

var Router = vigo.NewRouter()

func init() {
    // 挂载 VBase 路由到 /vb 前缀
    Router.Extend("/vb", vbase.Router)
}

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

项目结构

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

配置说明

VBase 支持通过配置文件或环境变量进行配置：

# 数据库配置
dsn: "root:password@tcp(127.0.0.1:3306)/vbase?charset=utf8&parseTime=True"
db: "mysql"  # 可选: mysql, postgres, sqlite

# JWT 配置
jwt:
  secret: "your-secret-key-min-32-characters"
  access_expiry: "1h"
  refresh_expiry: "720h"

# 应用配置
app:
  id: "myapp"
  name: "My Application"
  init_admin:
    username: "admin"
    password: "admin123"
    email: "admin@example.com"

# OAuth2 提供商配置
providers:
  github:
    enabled: true
    client_id: "your-github-client-id"
    client_secret: "your-github-client-secret"

环境变量命名规则：直接使用配置项的大写下划线形式，例如 JWT_SECRET、PROVIDERS_GITHUB_CLIENT_ID。

权限系统

基础用法

// 创建应用专属的权限实例
var AppAuth = vbase.Auth.New("myapp")

func init() {
    // 定义角色
    AppAuth.AddRole("admin", "管理员", "*:*")
    AppAuth.AddRole("editor", "编辑", "article:create", "article:update")
}

// 使用权限中间件保护路由
Router.Post("/articles", "创建文章", AppAuth.Perm("article:create"), createArticle)
Router.Patch("/articles/{id}", "更新文章", AppAuth.PermWithOwner("article:update", "id"), updateArticle)

权限格式

• resource:action - 基础格式，如 user:read, org:create
• app:resource:action - 带应用前缀，如 myapp:article:delete
• resource:* - 通配符权限，匹配资源的所有操作

更多权限用法请参考 集成文档。

API 概览

认证接口

方法	路径	描述
POST	/vb/api/auth/login	用户登录
POST	/vb/api/auth/register	用户注册
POST	/vb/api/auth/refresh	刷新 Token
POST	/vb/api/auth/logout	退出登录
POST	/vb/api/auth/sms/send	发送短信验证码
POST	/vb/api/auth/sms/login	短信验证码登录

用户管理

方法	路径	描述
GET	/vb/api/user/info	获取当前用户信息
PATCH	/vb/api/user/info	更新用户信息
GET	/vb/api/users	获取用户列表（管理员）

组织管理

方法	路径	描述
POST	/vb/api/orgs	创建组织
GET	/vb/api/orgs	获取组织列表
GET	/vb/api/orgs/{id}	获取组织详情
POST	/vb/api/orgs/{id}/members	添加组织成员
GET	/vb/api/orgs/{id}/members	获取组织成员列表

OAuth2 接口

方法	路径	描述
GET	/vb/api/oauth/authorize	授权端点
POST	/vb/api/oauth/token	Token 端点
GET	/vb/api/userinfo	用户信息端点

完整 API 文档请参考 API 文档。

多租户场景支持

VBase 的组织（Org）设计灵活，支持多种业务模式：

场景	特点	Org 使用方式
B2C 应用	单租户，所有用户直接面对平台	可选，权限绑定到全局
B2B SaaS	多租户，数据严格隔离	强制使用，请求需携带 X-Org-ID
平台型	平台 + 商家 + 消费者	商家端使用 Org，消费者端可选

架构设计

VBase 采用洋葱模型和分层架构：

Request -> [Global Middlewares] -> [Router] -> [Group Middlewares]
                                              -> [Handler]
                                              -> [Service/Logic]
                                              -> [Model/DAO] -> Database
                                                    |
Response <- [Global After Middleware] <-------------+

详细架构说明请参考 架构设计文档。

开发

运行测试

# 运行集成测试
./scripts/tests/run_all.sh

# 或单独运行测试
./scripts/tests/01_basic_auth.sh

构建

go build -o vbase cli/main.go

命令行子命令

# 生成配置文件
go run ./cli/main.go gen_cfg

# 数据库操作
go run ./cli/main.go db [migrate|seed|...]

技术栈

• 语言: Go 1.24+
• Web 框架: Vigo (洋葱模型)
• ORM: GORM
• 认证: JWT + OAuth2
• 前端: vhtml/vhtml-ui
• 数据库: MySQL / PostgreSQL / SQLite

贡献

欢迎提交 Issue 和 Pull Request！

许可证

Apache License 2.0

---

Made with ❤️ by veypi