OneAuth/docs/integration.md

VBase 集成指南

本文档介绍如何将 VBase 作为基础库集成到现有的 Golang 项目中，并使用其权限管理系统。

1. 安装

go get github.com/veypi/vbase

2. 初始化

在你的应用入口文件（如 main.go）中进行初始化。

package main

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

func main() {
	// cfg.Global 已包含默认配置（SQLite 内存数据库）
	// 可通过环境变量或 YAML 文件覆盖
	app := vigo.New("myapp", vbase.Router, cfg.Global, vigo.WithInit(vbase.Init))
	panic(app.Run())
}

VBase 自带嵌入式管理界面，启动后访问 /vb/ 即可使用。

2.1 挂载路由

VBase Router 已内置所有 API 路由（/api/auth、/api/users、/api/roles、/api/oauth、/api/settings 等）和 UI 路由（/vb/、/v/、/vhtml/）。

如果你的应用需要自定义路由，将 VBase Router 挂载到你的 Router 上：

var Router = vigo.NewRouter()

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

3. 使用权限系统

VBase 通过 cfg.Auth 提供全局权限管理实例。所有中间件方法前缀为 Require*。

3.1 定义路由权限

func init() {
	// 所有路由需要登录
	Router.Use(cfg.Auth.Login())

	// 资源操作示例
	// 创建文章 (需要 "article" 的创建权限 Level 1)
	Router.Post("/articles", cfg.Auth.RequireCreate("article"), CreateArticle)

	// 读取文章 (需要对特定实例的读取权限 Level 2)
	Router.Get("/articles/{id}", cfg.Auth.RequireRead("article:{id}"), GetArticle)

	// 更新文章 (需要对特定实例的写入权限 Level 4)
	Router.Put("/articles/{id}", cfg.Auth.RequireWrite("article:{id}"), UpdateArticle)

	// 删除文章 (需要对特定实例的管理员权限 Level 7)
	Router.Delete("/articles/{id}", cfg.Auth.RequireAdmin("article:{id}"), DeleteArticle)
}

3.2 权限码动态解析

权限码支持动态占位符，从不同来源获取值：

语法	来源	示例
{key} 或 {key@ctx}	Context	{appID}
{key@path}	路径参数	{appID@path}
{key@query}	Query 参数	{appID@query}
{key@header}	Header	{Authorization@header}

3.3 业务逻辑授权

在创建资源时，授予创建者管理权限：

func CreateArticle(x *vigo.X, req *ArticleReq) (*Article, error) {
	userID := cfg.Auth.UserID(x)

	article := &Article{Title: req.Title, AuthorID: userID}
	cfg.DB().Create(article)

	// 授予用户对该文章的管理员权限 (Level 7)
	permID := "article:" + article.ID
	cfg.Auth.Grant(x.Context(), userID, permID, auth.LevelAdmin)

	return article, nil
}

3.4 多 Scope 权限隔离

不同业务模块通过 Scope 实现权限隔离：

// 为不同应用创建独立的 Provider
var AppA_Auth = auth.Factory.New("app_a")
var AppB_Auth = auth.Factory.New("app_b")

// AppA 的用户权限不会影响 AppB

4. Session 管理

VBase 使用 Session + JWT 双 Token 机制：

• Access Token：短期有效（默认 15 分钟），用于 API 认证
• Refresh Token：长期有效（默认 30 天），用于刷新 Access Token
• Session：记录登录设备信息和 IP，支持版本号轮换防止并发刷新互踢

Token 默认通过 HttpOnly Cookie 传送。Session 可通过 auth.RevokeSession、auth.RevokeOtherSessions、auth.RevokeAllSessions 管理。

5. 配置说明

VBase 默认使用 SQLite 内存数据库（/tmp/vbase.db），无需任何外部依赖即可运行。

配置文件示例（config.yaml）：

db:
  type: "sqlite"
  dsn: "/tmp/vbase.db"

redis:
  addr: "memory"

key: "your-secret-key-min-32-characters"

jwt:
  access_expiry: 900
  refresh_expiry: 2592000
  issuer: "vbase"
  cookie_prefix: "vb_"

更多配置详情请参考 配置文档。