OptimusX
/
OneAuth
mirror of https://github.com/veypi/OneAuth.git
3
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs(readme): 完善项目 README.md

Browse Source 
- 添加项目介绍、核心特性、快速开始指南
- 添加项目结构说明和配置文档
- 添加权限系统使用示例和 API 概览
- 添加多租户场景支持和架构设计说明
v3
veypi 1 week ago
parent 51b3bbc89e
commit f846c27a51
1 changed files with 278 additions and 1 deletions
Show Stats Download Patch File Download Diff File

279
README.md
Unescape Escape View File

@ -1,3 +1,280 @@
# VBase # VBase
基于 vhtml/vigo 框架实现，提供用户认证、数据库存储、文件存储等功能。 <p align="center">
<img src="https://img.shields.io/badge/Go-1.24+-00ADD8?style=flat-square&logo=go" alt="Go Version">
<img src="https://img.shields.io/badge/License-Apache%202.0-blue?style=flat-square" alt="License">
<img src="https://img.shields.io/badge/Framework-Vigo-orange?style=flat-square" alt="Framework">
</p>
<p align="center">
<b>基于 Golang 的高性能身份认证与权限管理基础框架</b>
</p>
<p align="center">
<a href="#快速开始">快速开始</a> •
<a href="#核心特性">核心特性</a> •
<a href="#集成指南">集成指南</a> •
<a href="#api文档">API 文档</a> •
<a href="#架构设计">架构设计</a>
</p>
---
## 简介
**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)
---
<p align="center">
Made with ❤️ by <a href="https://github.com/veypi">veypi</a>
</p>

Write Preview
Loading…
Cancel
Save