|
|
# VBase 集成指南
|
|
|
|
|
|
本文档介绍如何将 VBase 作为基础库集成到现有的 Golang 项目中，并使用其权限管理系统。
|
|
|
|
|
|
## 1. 安装
|
|
|
|
|
|
```bash
|
|
|
go get github.com/veypi/vbase
|
|
|
```
|
|
|
|
|
|
## 2. 初始化
|
|
|
|
|
|
在你的应用入口文件（如 `main.go`）中进行初始化。
|
|
|
|
|
|
```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 上：
|
|
|
|
|
|
```go
|
|
|
var Router = vigo.NewRouter()
|
|
|
|
|
|
func init() {
|
|
|
// 将 VBase 挂载到 /vb 前缀
|
|
|
Router.Extend("/vb", vbase.Router)
|
|
|
}
|
|
|
```
|
|
|
|
|
|
## 3. 使用权限系统
|
|
|
|
|
|
VBase 通过 `cfg.Auth` 提供全局权限管理实例。所有中间件方法前缀为 `Require*`。
|
|
|
|
|
|
### 3.1 定义路由权限
|
|
|
|
|
|
```go
|
|
|
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 业务逻辑授权
|
|
|
|
|
|
在创建资源时，授予创建者管理权限：
|
|
|
|
|
|
```go
|
|
|
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 实现权限隔离：
|
|
|
|
|
|
```go
|
|
|
// 为不同应用创建独立的 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`）：
|
|
|
|
|
|
```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_"
|
|
|
```
|
|
|
|
|
|
更多配置详情请参考 [配置文档](./configuration.md)。
|