Skip to content

Commit 806e4ef

Browse files
wu-clanwu-clan
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)