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.
39 KiB
39 KiB
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/订阅 |
| 定制化 | 受限 | 完全可定制 |
| 网络要求 | 需要公网访问 | 可内网部署 |
3.4 关键设计：完全隔离
无论哪种模式，每个 VBase 实例都是完全独立的：
// 实例级别的完全隔离
// - 独立的数据库连接
// - 独立的 Redis 命名空间
// - 独立的 JWT 密钥
// - 独立的配置
type VBaseInstance struct {
InstanceID string // 实例唯一标识
DatabaseDSN string // 独立数据库
RedisPrefix string // Redis 前缀隔离
JWTSecret string // 独立 JWT 密钥
Config InstanceConfig
}
这种设计确保：
- 客户 A 的数据与客户 B 完全隔离
- 一个实例的故障不影响其他实例
- 客户可以独立升级、备份、迁移自己的实例
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 # 客户端管理
│ └── 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/ # 前端
使用方式
独立运行：
go run cli/main.go
集成到其他项目：
import "github.com/veypi/vbase"
// 在你的路由中挂载 vbase
router.Extend("vb", vbase.Router) // 所有 vbase API 将通过 /vb/api/... 访问
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)
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)
资源访问控制
// 资源操作前检查权限
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 请求/响应规范
成功响应:
{
"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、响应时间、错误率
- 缓存命中率
- 数据库连接池状态