mirror of https://github.com/veypi/OneAuth.git
You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
26 KiB
26 KiB
VBase 架构设计文档
1. 系统概述
VBase 是一个类似 Supabase 的 Backend-as-a-Service (BaaS) 平台，为个人开发者（2C）和团队/企业（2B）提供后端资源托管和权限管理服务。采用 Go 语言开发，基于 Vigo 框架构建。
1.1 产品定位
| 用户类型 | 使用场景 | 功能需求 |
|---|---|---|
| 个人开发者 (2C) | 创建个人项目，管理应用后端资源 | 项目管理、资源隔离、API 访问 |
| 团队/初创 (2B) | 团队协作开发，共享项目资源 | 成员管理、角色权限、组织隔离 |
| 企业客户 (2B) | 多项目/多团队管理，合规要求 | 组织架构、细粒度权限、审计日志 |
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 概念说明
项目 (Project/Org): 资源管理的基本单元
- 个人开发者创建的项目 = 个人项目
- 团队创建的项目 = 团队项目
- 企业可以创建多个项目，也可以使用组织层级管理
用户 (User): 平台注册用户
- 可以创建多个项目
- 可以被邀请加入其他项目
- 在不同项目中可以有不同的角色
资源 (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/
├── cmd/
│ └── server/ # 应用入口
│ └── main.go
├── internal/
│ ├── api/ # API 层
│ │ ├── auth/ # 认证相关
│ │ │ ├── handler.go # 登录/注册/刷新
│ │ │ └── thirdparty.go # 第三方登录
│ │ ├── user/ # 用户管理
│ │ ├── org/ # 组织管理
│ │ ├── oauth/ # OAuth2.0 服务端
│ │ │ ├── client.go # 客户端管理
│ │ │ ├── oauth.go # 授权流程
│ │ │ └── oidc.go # OIDC 支持
│ │ └── middleware/ # 中间件
│ │ ├── auth.go # JWT 认证
│ │ ├── org.go # 组织上下文
│ │ └── ratelimit.go # 限流
│ ├── service/ # 业务逻辑层
│ │ └── permission.go # 权限检查服务
│ ├── model/ # 数据模型层
│ │ ├── base.go # 基础模型
│ │ ├── user.go # 用户/身份/会话
│ │ ├── org.go # 组织/成员
│ │ ├── policy.go # 策略/角色
│ │ ├── oauth.go # OAuth 相关
│ │ └── migrate.go # 数据库迁移
│ ├── cache/ # 缓存层
│ │ └── redis.go # Redis 封装
│ ├── pkg/ # 工具包
│ │ ├── jwt/ # JWT 工具
│ │ └── crypto/ # 加密工具
│ └── config/ # 配置管理
│ └── config.go
├── doc/ # 文档
└── ui/ # 前端 (忽略)
4. 核心模块设计
4.1 认证模块
JWT Token 结构
// 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
}
认证流程
- 登录: 验证用户名密码 → 生成 Token 对 → 保存会话
- 访问: 验证 Token → 解析用户上下文 → 组织上下文
- 刷新: 验证 Refresh Token → 生成新 Token 对 → 失效旧 Token
- 登出: Token 加入黑名单 → 标记会话失效
4.2 权限模块
权限层级
VBase 采用三级权限体系：
┌─────────────────────────────────────────────────────────────┐
│ 1. 平台级权限 (Platform) │
│ - 用户管理自己的账号 │
│ - 创建项目 │
│ - 管理第三方登录绑定 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 2. 项目级权限 (Project) │
│ - 项目设置管理 │
│ - 成员邀请和管理 │
│ - 资源创建和管理 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 3. 资源级权限 (Resource) │
│ - 数据库读写 │
│ - 存储操作 │
│ - 函数调用 │
└─────────────────────────────────────────────────────────────┘
权限模型: RBAC + ABAC
策略模型:
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)
数据隔离
- 项目隔离: 每个 Org 是独立的资源边界
- 用户-项目关联: 通过
OrgMember表维护多对多关系 - 资源归属: 所有资源通过
org_id归属到具体项目 - 跨项目访问: 需要显式授权，默认隔离
4.4 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 请求/响应规范
成功响应:
{
"code": 200,
"message": "success",
"data": { ... }
}
错误响应:
{
"code": 400,
"message": "error description",
"data": null
}
6.3 分页规范
{
"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、响应时间、错误率
- 缓存命中率
- 数据库连接池状态