Skip to content

Commit 806e4ef

Browse files
committed
update docs
1 parent 372917d commit 806e4ef

File tree

4 files changed

+109
-48
lines changed

4 files changed

+109
-48
lines changed

docs/.vuepress/sidebar.ts

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,16 +20,17 @@ export const mySidebar: SidebarMulti = {
2020
prefix: 'reference/',
2121
items: [
2222
{text: '路由', link: 'router'},
23-
{text: 'JWT', link: 'jwt'},
2423
{text: 'CRUD', link: 'CRUD'},
2524
{text: '接口响应', link: 'response'},
2625
{text: '分页', link: 'pagination'},
2726
{text: '自定义异常', link: '/planet', icon: 'fluent-color:receipt-16'},
2827
{text: '切换数据库', link: 'db'},
29-
{text: '代码生成', link: 'code-generation'},
28+
{text: 'JWT', link: 'jwt'},
29+
{text: 'RBAC', link: 'RBAC'},
30+
{text: '鉴权', link: 'permission'},
3031
{text: '数据规则', link: '/planet', icon: 'fluent-color:video-16'},
32+
{text: '代码生成', link: 'code-generation'},
3133
{text: '跨域', link: 'CORS'},
32-
{text: 'RBAC', link: 'RBAC'},
3334
{text: '事务', link: 'transaction'},
3435
{text: 'Celery', link: '/planet', icon: 'fluent-color:video-16'},
3536
{text: 'APScheduler', link: 'apscheduler'},

docs/guide/reference/RBAC.md

Lines changed: 72 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -2,19 +2,21 @@
22
title: RBAC
33
---
44

5-
我们通过两个自定义依赖组件,实现了 RBAC 的轻松集成,在 Java 或其他语言中,常见的方式可能是注解,但在 FastAPI 中,依赖是它的亮点,也是核心
5+
我们通过自定义依赖组件,实现了 RBAC 的轻松集成,在 Java 或其他语言中,常见的方式可能是注解,但在 FastAPI 中,依赖是它的亮点,也是核心
66

77
## RBAC
88

9-
RBAC 内置了两种解决方案,分别为【角色菜单】、【Casbin】
9+
fba 内置了两种解决方案,分别为【角色菜单】、【Casbin】
1010

11-
【角色菜单】是各类语言 web 开发中比较常见的解决方案,它可以设置按钮级别的控制规则
11+
### 角色菜单
1212

13-
【Casbin】是 Go 语言中比较流行的解决方案,它非常灵活,可以通过模型定义多种控制规则
13+
::: tip
14+
fba 中默认未启用此鉴权方式
15+
:::
1416

15-
### 角色菜单
17+
此方案是各类语言 web 开发中比较常见的解决方案,它可以设置按钮级别的控制规则
1618

17-
要想实现此 RBAC 调用,涉及到三处相关配置
19+
要想实现此 RBAC 鉴权,需要修改以下相关配置
1820

1921
::: steps
2022

@@ -29,7 +31,7 @@ RBAC 内置了两种解决方案,分别为【角色菜单】、【Casbin】
2931

3032
2. 添加接口依赖
3133

32-
只有在接口中填加以下相关依赖时,才能自动应用此鉴权方式
34+
只有在接口中添加以下依赖时,才能自动调用此鉴权方式
3335

3436
```py{5-6}
3537
@router.post(
@@ -51,50 +53,82 @@ RBAC 内置了两种解决方案,分别为【角色菜单】、【Casbin】
5153

5254
### Casbin
5355

54-
我们在最初架构设计时,参考了 go-admin,gin-vue-admin... 等优秀的开源项目,同时引入了
55-
Casbin,它在众多 python web 开源项目中可能是极为罕见的,并且,它的学习成本非常高,如果你对此感兴趣,可以通过
56-
[Casbin 官网](https://casbin.org/docs/get-started) 进行学习,另外,可参考视频教程
57-
[半小时彻底弄懂Casbin基础模型](https://www.bilibili.com/video/BV1qz4y167XP/?spm_id_from=333.999.0.0&vd_source=958c4d7f9243c68a0ec9dcd327bad930)、
58-
[Casbin的代码使用、api调用、自定义比较方法](https://www.bilibili.com/video/BV13r4y1M7AC/?spm_id_from=333.999.0.0&vd_source=958c4d7f9243c68a0ec9dcd327bad930)
59-
,讲的是非常好
56+
::: tip
57+
fba 中默认使用此鉴权方式
58+
:::
59+
60+
此方案是 Go 语言中比较流行的解决方案,它非常灵活,可以通过模型定义多种控制规则
61+
62+
要想使用此 RBAC 鉴权,需要学习以下几点
63+
64+
::: steps
65+
66+
1. 了解 Casbin
67+
68+
我们在最初架构设计时,参考了 go-admin,gin-vue-admin... 等优秀的开源项目,同时引入了 Casbin,它在众多 python web
69+
开源项目中可能是极为罕见的,并且,它的学习成本非常高,如果你对此感兴趣,可以通过 [Casbin 官网](https://casbin.org/docs/get-started)
70+
进行学习,另外,可参考视频教程 [半小时彻底弄懂Casbin基础模型](https://www.bilibili.com/video/BV1qz4y167XP/?spm_id_from=333.999.0.0&vd_source=958c4d7f9243c68a0ec9dcd327bad930)、[Casbin的代码使用、api调用、自定义比较方法](https://www.bilibili.com/video/BV13r4y1M7AC/?spm_id_from=333.999.0.0&vd_source=958c4d7f9243c68a0ec9dcd327bad930)
71+
,讲的是非常好
72+
73+
2. 了解规则
74+
75+
通过以上学习之后,我们再来看内置规则(不学习 == 天书),你可以通过[编辑器](https://casbin.org/zh/docs/online-editor)
76+
进行模型规则验证
77+
78+
内置模型 `backend/plugin/casbin/utils/rbac.py`
79+
80+
```model
81+
[request_definition]
82+
r = sub, obj, act
83+
84+
[policy_definition]
85+
p = sub, obj, act
86+
87+
[role_definition]
88+
g = _, _
89+
90+
[policy_effect]
91+
e = some(where (p.eft == allow))
92+
93+
[matchers]
94+
m = g(r.sub, p.sub) && (keyMatch(r.obj, p.obj) || keyMatch3(r.obj, p.obj)) && (r.act == p.act || p.act == "*")
95+
```
96+
97+
3. 了解策略
6098

61-
通过以上学习之后,我们再来看内置规则(不学习 == 天书),
62-
你可以通过[编辑器](https://casbin.org/zh/docs/online-editor)进行模型规则验证
99+
p 策略:
100+
- 添加基于角色的访问权限(推荐)
63101

64-
模型:
102+
需要配合添加 g 策略才能实现用户访问权限,适合配置所有用户接口访问策略,拥有此角色的用户便能拥有相应的访问权限<br>
65103

66-
```
67-
[request_definition]
68-
r = sub, obj, act
104+
格式:`角色 role + 访问路径 path + 访问方法 method`
69105

70-
[policy_definition]
71-
p = sub, obj, act
106+
- 添加基于用户的访问权限(不推荐)
72107

73-
[role_definition]
74-
g = _, _
108+
不需要配合添加 g 策略就能实现用户访问权限,适合配置指定用户接口访问策略<br>
75109

76-
[policy_effect]
77-
e = some(where (p.eft == allow))
110+
格式:`用户 uuid + 访问路径 path + 访问方法 method`
78111

79-
[matchers]
80-
m = g(r.sub, p.sub) && (keyMatch(r.obj, p.obj) || keyMatch3(r.obj, p.obj)) && (r.act == p.act || p.act == "*")
81-
```
112+
g 策略(基于 p 策略):
113+
- 添加基于角色的访问权限
82114

83-
p 策略:
115+
格式:`用户 uuid + 角色 role`
84116

85-
- 推荐添加基于角色的访问权限, 需配合添加 g 策略才能真正拥有访问权限,适合配置全局接口访问策略<br>
86-
**格式**: 角色 role + 访问路径 path + 访问方法 method
117+
4. 添加策略
87118

88-
- 如果添加基于用户的访问权限, 不需配合添加 g 策略就能真正拥有权限,适合配置指定用户接口访问策略<br>
89-
**格式**: 用户 uuid + 访问路径 path + 访问方法 method
119+
在文件 `backend/plugin/casbin/api/v1/sys/casbin.py` 中,包含策略相关接口,依据模型和策略规则添加相关策略即可
90120

91-
g 策略 (**依赖 p 策略**):
121+
5. 检查接口依赖
92122

93-
- 如果在 p 策略中添加了基于角色的访问权限, 则还需要在 g 策略中添加基于用户组的访问权限, 才能真正拥有访问权限<br>
94-
**格式**: 用户 uuid + 角色 role
123+
只有在接口中添加以下依赖时,才能自动调用此鉴权方式
95124

96-
- 如果在 p 策略中添加了基于用户的访问权限, 则不添加相应的 g 策略能直接拥有访问权限,但是拥有的不是用户角色的所有权限,
97-
而只是单一的对应的 p 策略所添加的访问权限
125+
```python{1}
126+
@router.post('/hello', summary='你好', dependencies=[DependsRBAC])
127+
async def hello():
128+
....
129+
```
130+
131+
:::
98132

99133
## 解耦
100134

docs/guide/reference/jwt.md

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -45,12 +45,12 @@ class JwtAuthMiddleware(AuthenticationBackend):
4545

4646
## Token
4747

48-
内置遵循 [rfc6750](https://datatracker.ietf.org/doc/html/rfc6750) 标准实现的 HTTP 授权方式,如果您想使用自定义 header
49-
添加 token 进行授权,可以查看我们的 [非公开内容](../../planet.md#fastapi)
48+
内置遵循 [rfc6750](https://datatracker.ietf.org/doc/html/rfc6750) 标准实现的 HTTP 授权方式,如果您想通过自定义 header 添加
49+
token 进行授权,可以查看 [Header Token(自定义 header token 实现授权)](../../planet.md#fastapi)
5050

51-
### 验证码登录
51+
## 验证码登录
5252

53-
您可以通过验证码登录获取 token,在大多数情况下,这更适用于配合前端实现登录授权
53+
你可以通过此方式获取 token,在大多数情况下,这更适用于配合前端实现登录授权
5454

5555
我们在 fba 中使用 [fast_captcha](https://github.com/wu-clan/fast-captcha) 生成 base64 验证码,通过接口进行数据返回;您可以通过在线
5656
base64 转图片或配合前端项目将其转为图片进行预览,以下使其工作流程:
@@ -73,11 +73,11 @@ fast_captcha ->> Redis: 缓存验证码
7373
Token -->> 客户端: 成功
7474
```
7575

76-
### Swagger 登录
76+
## Swagger 登录
7777

78-
这是一种快捷的授权方式,但仅出于调试目的,在服务启动后,进入 Swagger 文档,可通过此调试接口快速获取授权 token(无需验证码)
78+
这是一种快捷的授权方式,仅用于调试目的,在服务启动后,进入 Swagger 文档,可通过此调试接口快速获取 token(无需验证码)
7979

80-
### OAuth 2.0
80+
## OAuth 2.0
8181

8282
这种授权方式通常适用于第三方平台认证登录,第三方授权成功后,将依据第三方平台信息自动创建本地用户并自动授权登录,这一切都是用户无感知的
8383

docs/guide/reference/permission.md

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
title: 鉴权
3+
---
4+
5+
在 fba 中,我们主要通过 [JWT](./jwt.md)[RBAC](./RBAC.md) 实现鉴权,但它们的控制方式有所不同
6+
7+
## JWT
8+
9+
在文件 `backend/common/security/jwt.py` 中,包含以下代码
10+
11+
```python
12+
# JWT authorizes dependency injection
13+
DependsJwtAuth = Depends(HTTPBearer())
14+
```
15+
16+
我们通过在接口函数中添加此依赖实现 JWT 快速校验,它可以帮助我们检查请求头中是否包含 Bearer Token,使用方式参考如下:
17+
18+
```python{1}
19+
@router.get('/hello', summary='你好', dependencies=[DependsJwtAuth])
20+
async def hello():
21+
...
22+
```
23+
24+
## RBAC
25+
26+
请参考 [RBAC](./RBAC.md#角色菜单) 相关内容

0 commit comments

Comments
 (0)