|
|
# VBase 架构设计文档
|
|
|
|
|
|
## 1. 系统概述
|
|
|
|
|
|
VBase 是一个类似 **Supabase** 的 **Backend-as-a-Service (BaaS)** 平台，为个人开发者（2C）和团队/企业（2B）提供后端资源托管和权限管理服务。采用 Go 语言开发，基于 Vigo 框架构建。
|
|
|
|
|
|
### 1.1 产品定位：可私有化部署的 IAM + BaaS 平台
|
|
|
|
|
|
VBase 是一个**产品化**的解决方案，你可以将 VBase **售卖/部署**给终端客户，客户在自己的环境中独立运行 VBase 实例，完全隔离地管理自己的业务。
|
|
|
|
|
|
#### 三层级架构模型
|
|
|
|
|
|
```
|
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
|
│ Layer 1: VBase 平台运营层 (你的 SaaS 平台) │
|
|
|
│ - 你是 VBase 产品的提供商 │
|
|
|
│ - 功能：实例管理、计费、监控、版本分发 │
|
|
|
│ - 部署模式：托管部署 or 客户自托管 │
|
|
|
└─────────────────────────────────────────────────────────────┘
|
|
|
│
|
|
|
▼ 部署/交付
|
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
|
│ Layer 2: VBase 实例层 (客户的独立部署) │
|
|
|
│ - 每个客户拥有一个完全独立的 VBase 实例 │
|
|
|
│ - 独立数据库、独立用户体系、独立配置 │
|
|
|
│ - 客户可以是：2C 产品 / 2B 产品 / 混合产品 │
|
|
|
│ - 管理员：客户的技术负责人/运维 │
|
|
|
└─────────────────────────────────────────────────────────────┘
|
|
|
│
|
|
|
▼ 使用
|
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
|
│ Layer 3: 客户业务层 (与你无关) │
|
|
|
│ - 客户用 VBase 管理自己的终端用户和业务项目 │
|
|
|
│ ├─ 2C 场景：App 用户注册登录、个人数据管理 │
|
|
|
│ ├─ 2B 场景：企业内部系统、团队协作 │
|
|
|
│ └─ 混合场景：既有终端用户又有内部团队 │
|
|
|
│ - 用户数据完全属于客户，与你无关 │
|
|
|
└─────────────────────────────────────────────────────────────┘
|
|
|
```
|
|
|
|
|
|
#### 目标客户类型
|
|
|
|
|
|
| 客户类型 | 场景说明 | VBase 提供的价值 |
|
|
|
| ---------------- | ------------------------------ | -------------------------------- |
|
|
|
| **2C 产品公司** | 社交 App、电商平台、内容社区等 | 用户认证、个人数据管理、权限控制 |
|
|
|
| **2B 产品公司** | SaaS 软件、企业管理系统 | 多租户隔离、组织架构、RBAC 权限 |
|
|
|
| **混合产品公司** | 既有 C 端用户又有 B 端管理 | 统一身份管理、分级权限控制 |
|
|
|
|
|
|
### 1.2 核心特性
|
|
|
|
|
|
- **项目-资源管理**: 用户可以创建多个项目，每个项目包含独立的后端资源
|
|
|
- **灵活的成员协作**: 支持邀请其他用户加入项目，分配不同角色权限
|
|
|
- **多层级权限控制**: 平台级 → 项目级 → 资源级的三级权限体系
|
|
|
- **RBAC + ABAC 权限模型**: 角色与策略结合的细粒度权限控制
|
|
|
- **OAuth2.0/OIDC 服务端**: 支持作为身份提供商，为应用提供认证服务
|
|
|
- **第三方登录集成**: Google、GitHub、微信等快速登录
|
|
|
- **JWT 认证**: 无状态的 Token 认证机制
|
|
|
|
|
|
### 1.3 技术栈
|
|
|
|
|
|
| 层级 | 技术 |
|
|
|
| -------- | ------------------------------- |
|
|
|
| 框架 | Vigo (Go Web Framework) |
|
|
|
| ORM | GORM |
|
|
|
| 数据库 | MySQL / PostgreSQL / SQLite |
|
|
|
| 缓存 | Redis |
|
|
|
| 认证 | JWT (github.com/golang-jwt/jwt) |
|
|
|
| 密码哈希 | bcrypt |
|
|
|
|
|
|
### 1.4 概念说明
|
|
|
|
|
|
#### 三层级角色体系
|
|
|
|
|
|
| 层级 | 角色 | 说明 | 权限范围 |
|
|
|
| ---------- | ---------- | -------------------------- | ------------------------- |
|
|
|
| **平台层** | 平台管理员 | VBase 产品提供商（你） | 管理所有 VBase 实例 |
|
|
|
| **实例层** | 实例管理员 | 客户的技术负责人 | 管理自己的 VBase 实例配置 |
|
|
|
| **业务层** | 终端用户 | 客户的 C 端用户或 B 端成员 | 使用客户的产品功能 |
|
|
|
|
|
|
#### VBase 实例内部概念
|
|
|
|
|
|
在一个独立的 VBase 实例内部，包含以下核心概念：
|
|
|
|
|
|
**用户 (User)**: VBase 实例中的注册用户
|
|
|
|
|
|
- 可以创建多个项目
|
|
|
- 可以被邀请加入其他项目
|
|
|
- 在不同项目中可以有不同的角色
|
|
|
|
|
|
**项目/组织 (Project/Org)**: 资源管理的基本单元
|
|
|
|
|
|
- 对 2C 场景：对应一个 App 或产品
|
|
|
- 对 2B 场景：对应一个企业或部门
|
|
|
- 企业可以创建多个项目，也可以使用组织层级管理
|
|
|
|
|
|
**资源 (Resource)**: 项目内的后端资源
|
|
|
|
|
|
- 数据库、存储、函数、API 等
|
|
|
- 属于特定项目
|
|
|
- 通过项目权限控制访问
|
|
|
|
|
|
**角色 (Role)**: 项目内的权限集合
|
|
|
|
|
|
- 所有者 (Owner): 项目全部权限
|
|
|
- 管理员 (Admin): 管理项目和成员
|
|
|
- 开发者 (Developer): 读写资源
|
|
|
- 访客 (Viewer): 只读访问
|
|
|
|
|
|
---
|
|
|
|
|
|
## 2. 系统架构
|
|
|
|
|
|
### 2.1 整体架构图
|
|
|
|
|
|
```
|
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
|
│ Client Layer │
|
|
|
│ (Web App / Mobile App / Third-party Services) │
|
|
|
└─────────────────────────────────────────────────────────────┘
|
|
|
│
|
|
|
▼
|
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
|
│ API Gateway │
|
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
|
│ │ Auth Filter │ │ Rate Limiter │ │ Org Context │ │
|
|
|
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
|
|
└─────────────────────────────────────────────────────────────┘
|
|
|
│
|
|
|
▼
|
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
|
│ Application Layer │
|
|
|
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
|
|
│ │ Auth │ │ User │ │ Org │ │ OAuth │ │
|
|
|
│ │ Handler │ │ Handler │ │ Handler │ │ Handler │ │
|
|
|
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
|
|
|
│ │
|
|
|
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
|
|
│ │ Role │ │ Policy │ │Permission│ │
|
|
|
│ │ Handler │ │ Handler │ │ Service │ │
|
|
|
│ └──────────┘ └──────────┘ └──────────┘ │
|
|
|
└─────────────────────────────────────────────────────────────┘
|
|
|
│
|
|
|
▼
|
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
|
│ Service Layer │
|
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
|
│ │ Permission │ │ JWT │ │ Crypto │ │
|
|
|
│ │ Checker │ │ Service │ │ Service │ │
|
|
|
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
|
|
└─────────────────────────────────────────────────────────────┘
|
|
|
│
|
|
|
▼
|
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
|
│ Data Layer │
|
|
|
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
|
|
│ │ User │ │ Org │ │ OAuth │ ... │
|
|
|
│ │ Model │ │ Model │ │ Model │ │
|
|
|
│ └──────────┘ └──────────┘ └──────────┘ │
|
|
|
│ │
|
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
|
|
│ │ MySQL/PostgreSQL │ Redis │ Repository │
|
|
|
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
|
|
└─────────────────────────────────────────────────────────────┘
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 3. 部署模式：VBase 作为产品交付
|
|
|
|
|
|
VBase 设计为可私有化部署的产品，支持两种交付模式：
|
|
|
|
|
|
### 3.1 模式一：托管部署（你帮客户部署运维）
|
|
|
|
|
|
```
|
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
|
│ 你的云基础设施 │
|
|
|
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
|
|
│ │ 客户A实例 │ │ 客户B实例 │ │ 客户C实例 │ │
|
|
|
│ │ (2C产品) │ │ (2B产品) │ │ (混合产品) │ │
|
|
|
│ │ │ │ │ │ │ │
|
|
|
│ │ DB: A_db │ │ DB: B_db │ │ DB: C_db │ │
|
|
|
│ │ Redis: A_1 │ │ Redis: B_1 │ │ Redis: C_1 │ │
|
|
|
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
|
|
└─────────────────────────────────────────────────────────────┘
|
|
|
```
|
|
|
|
|
|
**特点：**
|
|
|
|
|
|
- 你在自己的云基础设施上为客户部署独立的 VBase 实例
|
|
|
- 每个实例完全隔离（独立数据库、独立 Redis）
|
|
|
- 你负责运维，客户只管使用
|
|
|
- 可按照实例数量、资源使用量计费
|
|
|
|
|
|
**适用客户：** 没有运维能力的小团队，希望快速使用
|
|
|
|
|
|
### 3.2 模式二：客户自托管（客户自己部署）
|
|
|
|
|
|
```
|
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
|
│ 客户 A 的基础设施 │
|
|
|
│ ┌─────────────────────────────────────────────────────┐ │
|
|
|
│ │ VBase 实例 │ │
|
|
|
│ │ ┌──────────────┐ ┌──────────────┐ │ │
|
|
|
│ │ │ 用户认证 │ │ 权限管理 │ │ │
|
|
|
│ │ │ (2C用户) │ │ (2B组织) │ │ │
|
|
|
│ │ └──────────────┘ └──────────────┘ │ │
|
|
|
│ │ │ │
|
|
|
│ │ ┌──────────────┐ ┌──────────────┐ │ │
|
|
|
│ │ │ 数据库资源 │ │ 存储资源 │ │ │
|
|
|
│ │ └──────────────┘ └──────────────┘ │ │
|
|
|
│ └─────────────────────────────────────────────────────┘ │
|
|
|
└─────────────────────────────────────────────────────────────┘
|
|
|
```
|
|
|
|
|
|
**特点：**
|
|
|
|
|
|
- 客户在自己的环境中部署 VBase（云服务器、私有云、K8s）
|
|
|
- 数据完全属于客户，与你无关
|
|
|
- 客户自己运维，或者购买你的运维支持服务
|
|
|
- 通常按许可（License）或订阅模式收费
|
|
|
|
|
|
**适用客户：** 有数据合规要求的企业，有自己运维能力的团队
|
|
|
|
|
|
### 3.3 两种模式的对比
|
|
|
|
|
|
| 维度 | 托管部署 | 客户自托管 |
|
|
|
| ------------ | ---------------- | --------------- |
|
|
|
| **部署位置** | 你的云基础设施 | 客户的基础设施 |
|
|
|
| **数据归属** | 客户拥有，你代管 | 客户完全拥有 |
|
|
|
| **运维责任** | 你负责 | 客户负责 |
|
|
|
| **计费模式** | 按用量/实例数 | 按 License/订阅 |
|
|
|
| **定制化** | 受限 | 完全可定制 |
|
|
|
| **网络要求** | 需要公网访问 | 可内网部署 |
|
|
|
|
|
|
这种设计确保：
|
|
|
|
|
|
1. 客户 A 的数据与客户 B 完全隔离
|
|
|
2. 一个实例的故障不影响其他实例
|
|
|
3. 客户可以独立升级、备份、迁移自己的实例
|
|
|
|
|
|
---
|
|
|
|
|
|
## 4. 目录结构（Vigo 规范）
|
|
|
|
|
|
```
|
|
|
vbase/
|
|
|
├── api/ # API 层（按资源模块组织）
|
|
|
│ ├── init.go # API根路由，注册全局中间件
|
|
|
│ ├── auth/ # 认证模块
|
|
|
│ │ ├── init.go # 路由注册
|
|
|
│ │ ├── login.go # 登录/登出/刷新
|
|
|
│ │ ├── register.go # 用户注册
|
|
|
│ │ ├── me.go # 当前用户信息
|
|
|
│ │ └── thirdparty.go# 第三方登录
|
|
|
│ ├── user/ # 用户管理
|
|
|
│ │ ├── init.go
|
|
|
│ │ ├── get.go
|
|
|
│ │ ├── list.go
|
|
|
│ │ ├── create.go
|
|
|
│ │ ├── patch.go
|
|
|
│ │ ├── del.go
|
|
|
│ │ └── status.go
|
|
|
│ ├── org/ # 组织/项目管理
|
|
|
│ │ ├── init.go
|
|
|
│ │ ├── get.go
|
|
|
│ │ ├── list.go
|
|
|
│ │ ├── create.go
|
|
|
│ │ ├── patch.go
|
|
|
│ │ ├── del.go
|
|
|
│ │ ├── tree.go
|
|
|
│ │ └── member.go
|
|
|
│ ├── oauth/ # OAuth2.0/OIDC 服务端
|
|
|
│ │ ├── init.go
|
|
|
│ │ ├── authorize.go # 授权端点
|
|
|
│ │ ├── token.go # 令牌端点
|
|
|
│ │ ├── revoke.go # 撤销令牌
|
|
|
│ │ ├── oidc.go # OIDC 支持
|
|
|
│ │ └── client.go # 客户端管理
|
|
|
│ ├── policy/ # 策略管理（RBAC）
|
|
|
│ │ ├── init.go
|
|
|
│ │ ├── list.go
|
|
|
│ │ ├── get.go
|
|
|
│ │ ├── create.go
|
|
|
│ │ ├── patch.go
|
|
|
│ │ └── del.go
|
|
|
│ ├── role/ # 角色管理（RBAC）
|
|
|
│ │ ├── init.go
|
|
|
│ │ ├── list.go
|
|
|
│ │ ├── get.go
|
|
|
│ │ ├── create.go
|
|
|
│ │ ├── patch.go
|
|
|
│ │ ├── del.go
|
|
|
│ │ └── policy.go # 角色策略关联
|
|
|
│ └── middleware/ # 中间件
|
|
|
│ ├── auth.go # JWT 认证
|
|
|
│ ├── org.go # 组织上下文
|
|
|
│ └── ratelimit.go # 限流
|
|
|
│
|
|
|
├── models/ # 数据模型层（GORM）
|
|
|
│ ├── init.go # 模型注册、迁移
|
|
|
│ ├── base.go # 基础模型
|
|
|
│ ├── user.go # User/Identity/Session
|
|
|
│ ├── org.go # Org/OrgMember
|
|
|
│ ├── policy.go # Policy/Role
|
|
|
│ └── oauth.go # OAuthClient/OAuthToken
|
|
|
│
|
|
|
├── cfg/ # 配置（Vigo 自动解析）
|
|
|
│ ├── cfg.go # Options 结构体
|
|
|
│ ├── db.go # 数据库连接
|
|
|
│ └── sms.go # SMS 配置
|
|
|
│
|
|
|
├── cli/ # 独立运行入口
|
|
|
│ └── main.go # 启动服务器/数据库迁移
|
|
|
│
|
|
|
├── libs/ # 工具库
|
|
|
│ ├── cache/ # Redis 缓存封装
|
|
|
│ ├── jwt/ # JWT 工具
|
|
|
│ ├── crypto/ # 加密工具
|
|
|
│ ├── sms_providers/ # 短信服务商
|
|
|
│ ├── utils/ # 通用工具
|
|
|
│ └── webdav/ # WebDAV 实现
|
|
|
│
|
|
|
├── init.go # 项目根路由（vbase.Router）
|
|
|
├── doc/ # 文档
|
|
|
└── ui/ # 前端
|
|
|
```
|
|
|
|
|
|
### 使用方式
|
|
|
|
|
|
**独立运行：**
|
|
|
|
|
|
```bash
|
|
|
go run cli/main.go
|
|
|
```
|
|
|
|
|
|
**集成到其他项目：**
|
|
|
|
|
|
```go
|
|
|
import "github.com/veypi/vbase"
|
|
|
|
|
|
// 在你的路由中挂载 vbase
|
|
|
router.Extend("vb", vbase.Router) // 所有 vbase API 将通过 /vb/api/... 访问
|
|
|
```
|
|
|
|
|
|
### Vigo 路由规范
|
|
|
|
|
|
**父路由挂载子路由模块** - 使用 `Extend`：
|
|
|
|
|
|
```go
|
|
|
// api/init.go
|
|
|
Router.Extend("/auth", auth.Router) // 将 auth.Router 挂载到 /api/auth
|
|
|
```
|
|
|
|
|
|
**同级创建子路由** - 使用 `SubRouter`：
|
|
|
|
|
|
```go
|
|
|
// api/oauth/init.go
|
|
|
clientRouter := Router.SubRouter("/clients") // 创建 /oauth/clients 子路由
|
|
|
clientRouter.Get("/", "列表", listClients)
|
|
|
```
|
|
|
|
|
|
**跳过中间件** - 使用 `vigo.SkipBefore`：
|
|
|
|
|
|
```go
|
|
|
// 公开端点跳过认证中间件
|
|
|
Router.Post("/login", "登录", vigo.SkipBefore, login)
|
|
|
```
|
|
|
|
|
|
### 上下文键名
|
|
|
|
|
|
中间件设置的上下文键名：
|
|
|
|
|
|
| 键名 | 类型 | 说明 |
|
|
|
| -------------- | -------------- | --------------------------------- |
|
|
|
| `user_id` | string | 当前用户 ID |
|
|
|
| `user_name` | string | 当前用户名 |
|
|
|
| `user_orgs` | []jwt.OrgClaim | 用户所属组织列表 |
|
|
|
| `token_claims` | \*jwt.Claims | 完整的 JWT 声明 |
|
|
|
| `org_id` | string | 当前组织 ID（如果请求指定了组织） |
|
|
|
| `org_roles` | string | 当前组织角色 ID 列表 |
|
|
|
|
|
|
---
|
|
|
|
|
|
## 4. 核心模块设计
|
|
|
|
|
|
### 4.1 认证模块
|
|
|
|
|
|
#### JWT Token 结构
|
|
|
|
|
|
```go
|
|
|
// Claims JWT 声明
|
|
|
type Claims struct {
|
|
|
jwt.RegisteredClaims
|
|
|
UserID string `json:"user_id"`
|
|
|
Username string `json:"username"`
|
|
|
Nickname string `json:"nickname"`
|
|
|
Avatar string `json:"avatar"`
|
|
|
Email string `json:"email"`
|
|
|
Orgs []OrgClaim `json:"orgs"` // 用户所属组织
|
|
|
Type string `json:"type"` // access/refresh
|
|
|
}
|
|
|
```
|
|
|
|
|
|
#### 认证流程
|
|
|
|
|
|
1. **登录**: 验证用户名密码 → 生成 Token 对 → 保存会话
|
|
|
2. **访问**: 验证 Token → 解析用户上下文 → 组织上下文
|
|
|
3. **刷新**: 验证 Refresh Token → 生成新 Token 对 → 失效旧 Token
|
|
|
4. **登出**: Token 加入黑名单 → 标记会话失效
|
|
|
|
|
|
### 4.2 权限模块
|
|
|
|
|
|
#### 权限层级
|
|
|
|
|
|
VBase 采用三级权限体系：
|
|
|
|
|
|
```
|
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
|
│ 1. 平台级权限 (Platform) │
|
|
|
│ - 用户管理自己的账号 │
|
|
|
│ - 创建项目 │
|
|
|
│ - 管理第三方登录绑定 │
|
|
|
└─────────────────────────────────────────────────────────────┘
|
|
|
│
|
|
|
▼
|
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
|
│ 2. 项目级权限 (Project) │
|
|
|
│ - 项目设置管理 │
|
|
|
│ - 成员邀请和管理 │
|
|
|
│ - 资源创建和管理 │
|
|
|
└─────────────────────────────────────────────────────────────┘
|
|
|
│
|
|
|
▼
|
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
|
│ 3. 资源级权限 (Resource) │
|
|
|
│ - 数据库读写 │
|
|
|
│ - 存储操作 │
|
|
|
│ - 函数调用 │
|
|
|
└─────────────────────────────────────────────────────────────┘
|
|
|
```
|
|
|
|
|
|
#### 权限模型: RBAC + ABAC
|
|
|
|
|
|
**策略模型:**
|
|
|
|
|
|
```go
|
|
|
type Policy struct {
|
|
|
Resource string // 资源: user/org/resource/*
|
|
|
Action string // 操作: create/read/update/delete/*
|
|
|
Effect string // 效果: allow/deny
|
|
|
Condition string // 条件: "owner", "org_member", 或复杂表达式
|
|
|
Scope string // 作用域: platform/org/resource
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**权限检查流程:**
|
|
|
|
|
|
```
|
|
|
┌─────────────┐
|
|
|
│ 请求进入 │
|
|
|
└──────┬──────┘
|
|
|
▼
|
|
|
┌─────────────┐ 命中 ┌─────────────┐
|
|
|
│ 检查缓存 │──────────→│ 返回结果 │
|
|
|
└──────┬──────┘ └─────────────┘
|
|
|
│ 未命中
|
|
|
▼
|
|
|
┌─────────────┐
|
|
|
│ 检查组织所有者│──────────→│ 允许(缓存) │
|
|
|
└──────┬──────┘ └─────────────┘
|
|
|
│ 不是所有者
|
|
|
▼
|
|
|
┌─────────────┐
|
|
|
│ 获取用户角色 │
|
|
|
└──────┬──────┘
|
|
|
▼
|
|
|
┌─────────────┐
|
|
|
│ 获取角色策略 │
|
|
|
└──────┬──────┘
|
|
|
▼
|
|
|
┌─────────────┐ Deny ┌─────────────┐
|
|
|
│ 检查Deny策略 │───────────→│ 拒绝(缓存) │
|
|
|
└──────┬──────┘ └─────────────┘
|
|
|
│ 无Deny
|
|
|
▼
|
|
|
┌─────────────┐ Allow ┌─────────────┐
|
|
|
│ 检查Allow策略│───────────→│ 允许(缓存) │
|
|
|
└──────┬──────┘ └─────────────┘
|
|
|
│ 无Allow
|
|
|
▼
|
|
|
┌─────────────┐
|
|
|
│ 默认拒绝 │───────────→│ 拒绝(缓存) │
|
|
|
└─────────────┘ └─────────────┘
|
|
|
```
|
|
|
|
|
|
#### 缓存策略
|
|
|
|
|
|
- **缓存键**: `perm:{user_id}:{org_id}:{resource}:{action}`
|
|
|
- **TTL**: 1 分钟
|
|
|
- **缓存失效**: 角色/策略变更时清除相关缓存
|
|
|
|
|
|
### 4.3 项目/组织模块
|
|
|
|
|
|
VBase 中的 "Org" 概念灵活适配不同场景：
|
|
|
|
|
|
#### 场景 1: 个人项目 (2C)
|
|
|
|
|
|
```
|
|
|
个人开发者
|
|
|
└── 我的项目A (Org: owner=个人)
|
|
|
└── 我的项目B (Org: owner=个人)
|
|
|
```
|
|
|
|
|
|
- 每个项目是一个独立的 Org
|
|
|
- 资源完全隔离
|
|
|
- 可以邀请其他用户协作
|
|
|
|
|
|
#### 场景 2: 团队协作 (2B)
|
|
|
|
|
|
```
|
|
|
创业公司团队
|
|
|
├── Web应用项目 (Org)
|
|
|
│ ├── 所有者: CEO
|
|
|
│ ├── 管理员: CTO
|
|
|
│ └── 开发者: 员工A, 员工B
|
|
|
└── 移动应用项目 (Org)
|
|
|
├── 所有者: CEO
|
|
|
└── ...
|
|
|
```
|
|
|
|
|
|
#### 场景 3: 企业多层级 (2B Enterprise)
|
|
|
|
|
|
```
|
|
|
企业层级 (可选功能)
|
|
|
总公司 (level=0)
|
|
|
├── 技术中台 (level=1, Org)
|
|
|
├── 业务线A (level=1)
|
|
|
│ ├── 项目1 (level=2, Org)
|
|
|
│ └── 项目2 (level=2, Org)
|
|
|
└── 业务线B (level=1)
|
|
|
└── 项目3 (level=2, Org)
|
|
|
```
|
|
|
|
|
|
### 4.4 典型客户场景示例
|
|
|
|
|
|
以下示例展示 VBase 作为产品交付的完整链路：
|
|
|
|
|
|
#### 示例 1: 2C 产品公司（社交 App）
|
|
|
|
|
|
```
|
|
|
你（VBase 提供商）
|
|
|
│
|
|
|
├─ 售卖 VBase 实例给「社交App公司」
|
|
|
│
|
|
|
▼
|
|
|
客户：社交App公司（2C产品）
|
|
|
│
|
|
|
├─ 部署 VBase 实例到自己的服务器（自托管模式）
|
|
|
│
|
|
|
├─ 技术负责人配置 VBase：
|
|
|
│ ├─ 开启 App 用户注册/登录
|
|
|
│ ├─ 配置数据库存储用户资料
|
|
|
│ └─ 设置存储桶保存用户头像
|
|
|
│
|
|
|
▼
|
|
|
终端用户：社交 App 的普通用户
|
|
|
├─ 注册账号（存储在 VBase）
|
|
|
├─ 登录获取 JWT Token
|
|
|
├─ 上传头像到 VBase 存储
|
|
|
└─ 查询好友列表（VBase 数据库）
|
|
|
```
|
|
|
|
|
|
**关键点：**
|
|
|
|
|
|
- 社交 App 公司的用户数据完全在自己的 VBase 实例中
|
|
|
- 你作为 VBase 提供商，接触不到终端用户数据
|
|
|
- 社交 App 公司按需购买 License 或订阅服务
|
|
|
|
|
|
#### 示例 2: 2B 产品公司（SaaS 软件）
|
|
|
|
|
|
```
|
|
|
你（VBase 提供商）
|
|
|
│
|
|
|
├─ 托管部署 VBase 实例给「企业SaaS公司」
|
|
|
│ （部署在你的云服务器上）
|
|
|
│
|
|
|
▼
|
|
|
客户：企业SaaS公司（2B产品）
|
|
|
│
|
|
|
├─ 使用 VBase 管理自己的企业客户
|
|
|
│ ├─ 每个企业客户 = VBase 中的一个 Org
|
|
|
│ ├─ 企业内的部门 = Org 下的子组织
|
|
|
│ └─ 企业员工 = OrgMember
|
|
|
│
|
|
|
▼
|
|
|
终端用户：SaaS 软件的企业用户
|
|
|
├─ 企业 A 的员工使用 VBase 登录 SaaS
|
|
|
├─ 按角色分配权限（管理员/普通员工）
|
|
|
└─ 企业间的数据通过 VBase 完全隔离
|
|
|
```
|
|
|
|
|
|
**关键点：**
|
|
|
|
|
|
- SaaS 公司用 VBase 做租户隔离（多租户架构）
|
|
|
- 你帮 SaaS 公司运维 VBase 实例，按实例数/用户量收费
|
|
|
- SaaS 公司的终端企业用户与你无直接关系
|
|
|
|
|
|
#### 示例 3: 混合产品公司（2C + 2B）
|
|
|
|
|
|
```
|
|
|
你（VBase 提供商）
|
|
|
│
|
|
|
├─ 售卖两个 VBase 实例给「电商平台公司」
|
|
|
│ （一个给 C 端，一个给 B 端管理后台）
|
|
|
│
|
|
|
▼
|
|
|
客户：电商平台公司（混合产品）
|
|
|
│
|
|
|
├─ 实例1：C 端用户系统
|
|
|
│ ├─ 消费者注册/登录
|
|
|
│ ├─ 购物车、订单数据
|
|
|
│ └─ 用户画像存储
|
|
|
│
|
|
|
└─ 实例2：B 端商家管理系统
|
|
|
├─ 商家入驻/审核
|
|
|
├─ 商家员工权限管理
|
|
|
└─ 运营数据分析
|
|
|
```
|
|
|
|
|
|
**关键点：**
|
|
|
|
|
|
- 同一客户的不同业务线可以用独立 VBase 实例
|
|
|
- 完全物理隔离，符合数据合规要求
|
|
|
- 你提供统一的管理控制台给客户技术团队
|
|
|
|
|
|
#### 数据隔离
|
|
|
|
|
|
- **项目隔离**: 每个 Org 是独立的资源边界
|
|
|
- **用户-项目关联**: 通过 `OrgMember` 表维护多对多关系
|
|
|
- **资源归属**: 所有资源通过 `org_id` 归属到具体项目
|
|
|
- **跨项目访问**: 需要显式授权，默认隔离
|
|
|
|
|
|
### 4.5 BaaS 资源管理模块
|
|
|
|
|
|
作为 Supabase-like BaaS 平台，VBase 提供以下后端资源管理能力：
|
|
|
|
|
|
#### 资源类型
|
|
|
|
|
|
| 资源类型 | 说明 | 典型操作 |
|
|
|
| ------------ | --------------- | ------------------------------ |
|
|
|
| **Database** | 数据库表、集合 | 创建表、查询、修改结构、删除表 |
|
|
|
| **Storage** | 文件存储 | 上传、下载、删除、管理存储桶 |
|
|
|
| **Function** | 边缘函数/云函数 | 部署、调用、更新、删除 |
|
|
|
| **API Key** | 访问密钥 | 创建、删除、刷新、权限绑定 |
|
|
|
|
|
|
#### 资源权限模型
|
|
|
|
|
|
```
|
|
|
项目 (Org)
|
|
|
├── 资源组 (Resource Group)
|
|
|
│ ├── 数据库资源
|
|
|
│ │ ├── table_1 (owner: user_a)
|
|
|
│ │ └── table_2 (owner: user_b)
|
|
|
│ ├── 存储资源
|
|
|
│ │ ├── bucket_images (public)
|
|
|
│ │ └── bucket_private (private)
|
|
|
│ └── 函数资源
|
|
|
│ ├── function_api (callable)
|
|
|
│ └── function_cron (internal)
|
|
|
```
|
|
|
|
|
|
#### 资源访问控制
|
|
|
|
|
|
```go
|
|
|
// 资源操作前检查权限
|
|
|
func AccessResource(userID, orgID, resourceType, action string) error {
|
|
|
checker := service.NewPermissionChecker()
|
|
|
result, err := checker.Check(userID, orgID, resourceType, action, nil)
|
|
|
if err != nil || !result.Allowed {
|
|
|
return vigo.ErrForbidden.WithString(result.Reason)
|
|
|
}
|
|
|
|
|
|
// 额外检查资源级别的细粒度权限
|
|
|
// 例如：只能修改自己创建的表
|
|
|
return nil
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### 4.5 OAuth2.0 服务端
|
|
|
|
|
|
#### 支持的授权流程
|
|
|
|
|
|
| 流程 | 说明 | 适用场景 |
|
|
|
| ------------------ | ---------- | -------------------- |
|
|
|
| Authorization Code | 授权码模式 | 服务端应用，最安全 |
|
|
|
| Implicit | 简化模式 | SPA/移动端（不推荐） |
|
|
|
| Client Credentials | 客户端凭证 | 服务间调用 |
|
|
|
| Refresh Token | 刷新令牌 | 延长会话 |
|
|
|
|
|
|
#### 安全特性
|
|
|
|
|
|
- **PKCE**: 防止授权码拦截攻击
|
|
|
- **State**: CSRF 防护
|
|
|
- **Redirect URI 白名单**: 严格匹配
|
|
|
- **Token 过期**: Access Token 1 小时，Refresh Token 30 天
|
|
|
|
|
|
---
|
|
|
|
|
|
## 5. 数据模型
|
|
|
|
|
|
### 5.1 实体关系图 (ER Diagram)
|
|
|
|
|
|
```
|
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
|
│ 平台层 (Platform) │
|
|
|
├─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
|
|
│ User │ │ Identity │ │ Session │ │
|
|
|
│ (平台用户) │ │ (第三方绑定)│ │ (登录会话) │ │
|
|
|
├─────────────┤ ├─────────────┤ ├─────────────┤ │
|
|
|
│ id (PK) │◄──────┤ user_id │ │ id (PK) │ │
|
|
|
│ username │ │ provider │ │ user_id │ │
|
|
|
│ password │ │ provider_uid│ │ token_id │ │
|
|
|
│ email │ │ access_token│ │ type │ │
|
|
|
│ status │ └─────────────┘ │ expires_at │ │
|
|
|
└──────┬──────┘ └─────────────┘ │
|
|
|
│ │
|
|
|
│ 多对多关系（用户-项目） │
|
|
|
│ ┌─────────────┐ ┌─────────────┐ │
|
|
|
│ │ OrgMember │ │ Org │ │
|
|
|
│ │ (项目成员) │ │ (项目) │ │
|
|
|
│ ├─────────────┤ ├─────────────┤ │
|
|
|
└────────►│ user_id │◄──────┤ id (PK) │ │
|
|
|
│ org_id │──────►│ name │ │
|
|
|
│ role_ids │ │ code │ │
|
|
|
│ status │ │ owner_id │ │
|
|
|
└─────────────┘ │ parent_id* │ │
|
|
|
│ path* │ │
|
|
|
└─────────────┘ │
|
|
|
│ │
|
|
|
│ 1:N │
|
|
|
▼ │
|
|
|
┌─────────────┐ │
|
|
|
│ Resource │ │
|
|
|
│ (项目资源) │ │
|
|
|
│ (db/storage)│ │
|
|
|
└─────────────┘ │
|
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
|
|
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
|
│ 权限层 (Permission) │
|
|
|
├─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
|
|
│ Role │ │ RolePolicy │ │ Policy │ │
|
|
|
│ (项目角色) │ │ (角色策略) │ │ (策略) │ │
|
|
|
├─────────────┤ ├─────────────┤ ├─────────────┤ │
|
|
|
│ id (PK) │◄──────┤ role_id │ │ id (PK) │ │
|
|
|
│ org_id │ │ policy_id │──────►│ code │ │
|
|
|
│ name │ └─────────────┘ │ resource │ │
|
|
|
│ policy_ids │ │ action │ │
|
|
|
│ scope │ │ effect │ │
|
|
|
└─────────────┘ │ condition │ │
|
|
|
│ scope │ │
|
|
|
└─────────────┘ │
|
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
|
|
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
|
│ OAuth层 (Identity) │
|
|
|
├─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
|
|
│OAuthClient │ │OAuthAuthz │ │ OAuthToken │ │
|
|
|
│ (OAuth应用) │ │ (授权码) │ │ (访问令牌) │ │
|
|
|
├─────────────┤ ├─────────────┤ ├─────────────┤ │
|
|
|
│ id (PK) │◄──────┤ client_id │ │ id (PK) │ │
|
|
|
│ client_id │ │ user_id │◄──────┤ client_id │ │
|
|
|
│ client_secret│ │ code │ │ user_id │ │
|
|
|
│ redirect_uris│ │ expires_at │ │ access_token│ │
|
|
|
│ owner_id │ └─────────────┘ │ refresh_token│ │
|
|
|
│ org_id │ │ org_id │ │
|
|
|
└─────────────┘ └─────────────┘ │
|
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
|
```
|
|
|
|
|
|
### 5.2 关键模型说明
|
|
|
|
|
|
**User (用户)**
|
|
|
|
|
|
- 平台级唯一用户账号
|
|
|
- 可同时参与多个项目
|
|
|
- 支持第三方账号绑定
|
|
|
|
|
|
**Org (项目/组织)**
|
|
|
|
|
|
- 资源管理的基本单元
|
|
|
- 对 2C 场景: 一个项目 = 一个 Org
|
|
|
- 对 2B 场景: 可以是项目或企业部门
|
|
|
- 支持层级结构（可选）
|
|
|
|
|
|
**OrgMember (项目成员)**
|
|
|
|
|
|
- 维护用户与项目的关联
|
|
|
- 记录角色分配
|
|
|
- 支持多种成员状态（待审核、正常、禁用）
|
|
|
|
|
|
**Role (角色)**
|
|
|
|
|
|
- 项目内定义的权限集合
|
|
|
- 系统预置角色: owner, admin, developer, viewer
|
|
|
- 支持自定义角色
|
|
|
|
|
|
---
|
|
|
|
|
|
## 6. 接口设计原则
|
|
|
|
|
|
### 6.1 RESTful API
|
|
|
|
|
|
- 使用 HTTP 方法表示操作: GET/POST/PATCH/DELETE
|
|
|
- 使用复数名词表示资源: /users, /orgs
|
|
|
- 使用路径参数表示 ID: /users/{user_id}
|
|
|
|
|
|
### 6.2 请求/响应规范
|
|
|
|
|
|
**成功响应:**
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"code": 200,
|
|
|
"message": "success",
|
|
|
"data": { ... }
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**错误响应:**
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"code": 400,
|
|
|
"message": "error description",
|
|
|
"data": null
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### 6.3 分页规范
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"items": [...],
|
|
|
"total": 100,
|
|
|
"page": 1,
|
|
|
"page_size": 10,
|
|
|
"total_pages": 10
|
|
|
}
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
## 7. 安全设计
|
|
|
|
|
|
### 7.1 认证安全
|
|
|
|
|
|
- **密码策略**: bcrypt 哈希，成本因子 12
|
|
|
- **JWT 安全**: HS256 算法，密钥最小 32 字节
|
|
|
- **Token 过期**: 短时效 Access Token + 长时效 Refresh Token
|
|
|
- **Token 撤销**: 黑名单机制
|
|
|
|
|
|
### 7.2 接口安全
|
|
|
|
|
|
- **限流**: 基于 IP 和用户 ID 的滑动窗口限流
|
|
|
- **CSRF 防护**: State 参数、SameSite Cookie
|
|
|
- **SQL 注入**: GORM 参数化查询
|
|
|
- **XSS 防护**: 响应头设置 Content-Type
|
|
|
|
|
|
### 7.3 OAuth 安全
|
|
|
|
|
|
- **PKCE**: 所有移动端/SPA 必须使用
|
|
|
- **Redirect URI 严格匹配**: 包括路径和查询参数
|
|
|
- **Scope 限制**: 每个客户端有允许的范围白名单
|
|
|
|
|
|
---
|
|
|
|
|
|
## 8. 扩展性设计
|
|
|
|
|
|
### 8.1 水平扩展
|
|
|
|
|
|
- **无状态服务**: 不依赖本地存储，可水平扩展
|
|
|
- **共享缓存**: Redis 集群支持
|
|
|
- **数据库读写分离**: GORM 支持读写分离配置
|
|
|
|
|
|
### 8.2 插件化
|
|
|
|
|
|
- **中间件链**: 可插拔的中间件设计
|
|
|
- **策略引擎**: 支持自定义条件表达式
|
|
|
- **第三方登录**: 易于添加新的 OAuth 提供商
|
|
|
|
|
|
---
|
|
|
|
|
|
## 9. 监控与日志
|
|
|
|
|
|
### 9.1 日志规范
|
|
|
|
|
|
- 请求日志: 方法、路径、耗时、状态码
|
|
|
- 错误日志: 堆栈追踪、上下文信息
|
|
|
- 审计日志: 敏感操作记录
|
|
|
|
|
|
### 9.2 指标监控
|
|
|
|
|
|
- QPS、响应时间、错误率
|
|
|
- 缓存命中率
|
|
|
- 数据库连接池状态
|