From f846c27a519804ae7f2166cb34ad2de2aa24d51e Mon Sep 17 00:00:00 2001 From: veypi Date: Sun, 15 Feb 2026 20:32:28 +0800 Subject: [PATCH] =?UTF-8?q?docs(readme):=20=E5=AE=8C=E5=96=84=E9=A1=B9?= =?UTF-8?q?=E7=9B=AE=20README.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 添加项目介绍、核心特性、快速开始指南 - 添加项目结构说明和配置文档 - 添加权限系统使用示例和 API 概览 - 添加多租户场景支持和架构设计说明 --- README.md | 279 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 278 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 326dbdd..f083fdc 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,280 @@ # VBase -基于 vhtml/vigo 框架实现，提供用户认证、数据库存储、文件存储等功能。 +

+ Go Version + License + Framework +

+ +

+ 基于 Golang 的高性能身份认证与权限管理基础框架 +

+ +

+ 快速开始 • + 核心特性 • + 集成指南 • + API 文档 • + 架构设计 +

+ +--- + +## 简介 + +**VBase** 是一个基于 [Vigo](https://github.com/veypi/vigo) 框架开发的高性能后端基础框架，提供一套标准化的用户管理、组织架构（多租户）、权限控制（RBAC）和 OAuth2 认证服务。可作为独立服务部署，也可作为基础库集成到你的 Go 项目中。 + +## 核心特性 + +- 🔐 **完整认证体系** - JWT Token 认证（Access + Refresh）、多因素认证（短信验证码） +- 🛡️ **RBAC 权限控制** - 基于角色的访问控制，支持资源级权限和通配符权限 +- 🏢 **多租户架构** - 组织级别的数据隔离，灵活适配 B2C/B2B/平台型业务 +- 🔑 **OAuth2 Provider** - 完整的 OAuth2 服务端实现，支持第三方应用接入 +- 🗄️ **多数据库支持** - MySQL、PostgreSQL、SQLite 自动适配 +- 📱 **内置管理界面** - 基于 vhtml 的嵌入式管理后台 +- 🚀 **高性能** - 基于洋葱模型中间件架构，低延迟高并发 +- 🧪 **完整测试** - 集成测试脚本覆盖核心业务流程 + +## 快速开始 + +### 安装 + +```bash +go get github.com/veypi/vbase +``` + +### 作为独立服务运行 + +```bash +# 克隆项目 +git clone https://github.com/veypi/vbase.git +cd vbase + +# 配置数据库（编辑 dev.yaml 或使用环境变量） +export DSN="root:password@tcp(127.0.0.1:3306)/vbase?charset=utf8&parseTime=True" +export DB="mysql" + +# 启动服务 +go run ./cli/main.go + +# 或使用 Makefile（默认端口 4001） +make run +``` + +服务默认在 `http://localhost:4000` 启动，管理界面访问 `/vb/` 路径。 + +### 作为库集成 + +```go +package main + +import ( + "github.com/veypi/vbase" + "github.com/veypi/vigo" +) + +var Router = vigo.NewRouter() + +func init() { + // 挂载 VBase 路由到 /vb 前缀 + Router.Extend("/vb", vbase.Router) +} +``` + +更多集成方式请参考 [集成指南](./docs/integration.md)。 + +## 项目结构 + +``` +vbase/ +├── api/ # REST API 接口层 +│ ├── auth/ # 认证接口（登录、注册、Token 刷新） +│ ├── oauth/ # OAuth2 Provider 接口 +│ ├── org/ # 组织/租户管理 +│ ├── role/ # 角色管理 +│ └── user/ # 用户管理 +├── auth/ # 核心权限控制模块（RBAC 实现） +├── cfg/ # 配置管理 +├── cli/ # 命令行入口 +├── models/ # 数据模型（GORM） +├── ui/ # 前端管理界面（vhtml） +└── docs/ # 文档 +``` + +## 配置说明 + +VBase 支持通过配置文件或环境变量进行配置： + +```yaml +# 数据库配置 +dsn: "root:password@tcp(127.0.0.1:3306)/vbase?charset=utf8&parseTime=True" +db: "mysql" # 可选: mysql, postgres, sqlite + +# JWT 配置 +jwt: + secret: "your-secret-key-min-32-characters" + access_expiry: "1h" + refresh_expiry: "720h" + +# 应用配置 +app: + id: "myapp" + name: "My Application" + init_admin: + username: "admin" + password: "admin123" + email: "admin@example.com" + +# OAuth2 提供商配置 +providers: + github: + enabled: true + client_id: "your-github-client-id" + client_secret: "your-github-client-secret" +``` + +环境变量命名规则：直接使用配置项的大写下划线形式，例如 `JWT_SECRET`、`PROVIDERS_GITHUB_CLIENT_ID`。 + +## 权限系统 + +### 基础用法 + +```go +// 创建应用专属的权限实例 +var AppAuth = vbase.Auth.New("myapp") + +func init() { + // 定义角色 + AppAuth.AddRole("admin", "管理员", "*:*") + AppAuth.AddRole("editor", "编辑", "article:create", "article:update") +} + +// 使用权限中间件保护路由 +Router.Post("/articles", "创建文章", AppAuth.Perm("article:create"), createArticle) +Router.Patch("/articles/{id}", "更新文章", AppAuth.PermWithOwner("article:update", "id"), updateArticle) +``` + +### 权限格式 + +- `resource:action` - 基础格式，如 `user:read`, `org:create` +- `app:resource:action` - 带应用前缀，如 `myapp:article:delete` +- `resource:*` - 通配符权限，匹配资源的所有操作 + +更多权限用法请参考 [集成文档](./docs/integration.md)。 + +## API 概览 + +### 认证接口 + +| 方法 | 路径 | 描述 | +|------|------|------| +| POST | `/vb/api/auth/login` | 用户登录 | +| POST | `/vb/api/auth/register` | 用户注册 | +| POST | `/vb/api/auth/refresh` | 刷新 Token | +| POST | `/vb/api/auth/logout` | 退出登录 | +| POST | `/vb/api/auth/sms/send` | 发送短信验证码 | +| POST | `/vb/api/auth/sms/login` | 短信验证码登录 | + +### 用户管理 + +| 方法 | 路径 | 描述 | +|------|------|------| +| GET | `/vb/api/user/info` | 获取当前用户信息 | +| PATCH | `/vb/api/user/info` | 更新用户信息 | +| GET | `/vb/api/users` | 获取用户列表（管理员） | + +### 组织管理 + +| 方法 | 路径 | 描述 | +|------|------|------| +| POST | `/vb/api/orgs` | 创建组织 | +| GET | `/vb/api/orgs` | 获取组织列表 | +| GET | `/vb/api/orgs/{id}` | 获取组织详情 | +| POST | `/vb/api/orgs/{id}/members` | 添加组织成员 | +| GET | `/vb/api/orgs/{id}/members` | 获取组织成员列表 | + +### OAuth2 接口 + +| 方法 | 路径 | 描述 | +|------|------|------| +| GET | `/vb/api/oauth/authorize` | 授权端点 | +| POST | `/vb/api/oauth/token` | Token 端点 | +| GET | `/vb/api/userinfo` | 用户信息端点 | + +完整 API 文档请参考 [API 文档](./docs/api.md)。 + +## 多租户场景支持 + +VBase 的组织（Org）设计灵活，支持多种业务模式： + +| 场景 | 特点 | Org 使用方式 | +|------|------|--------------| +| **B2C 应用** | 单租户，所有用户直接面对平台 | 可选，权限绑定到全局 | +| **B2B SaaS** | 多租户，数据严格隔离 | 强制使用，请求需携带 `X-Org-ID` | +| **平台型** | 平台 + 商家 + 消费者 | 商家端使用 Org，消费者端可选 | + +## 架构设计 + +VBase 采用洋葱模型和分层架构： + +``` +Request -> [Global Middlewares] -> [Router] -> [Group Middlewares] + -> [Handler] + -> [Service/Logic] + -> [Model/DAO] -> Database + | +Response <- [Global After Middleware] <-------------+ +``` + +详细架构说明请参考 [架构设计文档](./docs/design.md)。 + +## 开发 + +### 运行测试 + +```bash +# 运行集成测试 +./scripts/tests/run_all.sh + +# 或单独运行测试 +./scripts/tests/01_basic_auth.sh +``` + +### 构建 + +```bash +go build -o vbase cli/main.go +``` + +### 命令行子命令 + +```bash +# 生成配置文件 +go run ./cli/main.go gen_cfg + +# 数据库操作 +go run ./cli/main.go db [migrate|seed|...] +``` + +## 技术栈 + +- **语言**: Go 1.24+ +- **Web 框架**: [Vigo](https://github.com/veypi/vigo) (洋葱模型) +- **ORM**: GORM +- **认证**: JWT + OAuth2 +- **前端**: vhtml/vhtml-ui +- **数据库**: MySQL / PostgreSQL / SQLite + +## 贡献 + +欢迎提交 Issue 和 Pull Request！ + +## 许可证 + +[Apache License 2.0](./LICENSE) + +--- + +

+ Made with ❤️ by veypi +