FastAPI 角色權限管理（RBAC）：入門級思路

作者：Ss肥魚 2025-04-15 10:20:00

開發

本篇文章將手把手教你如何在 FastAPI 中實現角色權限系統，實現真正的多用戶訪問控制！

你是否想讓管理員擁有更多權限？
普通用戶只能訪問自己的內容？

RBAC（基于角色的訪問控制）是解決多角色權限管理的最佳實踐。本篇文章將手把手教你如何在 FastAPI 中實現角色權限系統，實現真正的多用戶訪問控制！

什么是 RBAC？

RBAC（Role-Based Access Control）是一種通過角色（Role）管理權限（Permission）的模型：

用戶（User） → 屬于一個或多個角色
角色（Role） → 擁有若干權限
權限（Permission） → 授權訪問接口、資源

好處：

權限解耦：權限不直接綁定用戶，而是抽象為角色
擴展性強：修改權限只需更新角色
更安全、更規范

目錄結構示例

app/
├── api/
│   └── user.py
├── auth/
│   ├── auth.py          # 登錄認證
│   └── deps.py          # 權限控制邏輯
├── core/
│   └── security.py
├── models/
│   ├── user.py          # 用戶模型
│   └── role.py          # 角色模型
├── schemas/
│   ├── user.py
│   └── role.py

用戶與角色模型定義

models/role.py：

from tortoise.models import Model
from tortoise import fields

class Role(Model):
    id = fields.IntField(pk=True)
    name = fields.CharField(max_length=50, unique=True)

    users: fields.ReverseRelation["User"]

models/user.py：

from tortoise.models import Model
from tortoise import fields
from .role import Role

class User(Model):
    id = fields.IntField(pk=True)
    username = fields.CharField(max_length=50, unique=True)
    hashed_password = fields.CharField(max_length=128)
    role = fields.ForeignKeyField("models.Role", related_name="users")

用戶注冊默認賦予角色

api/user.py：

@router.post("/register", response_model=UserOut)
async def register(user: UserCreate):
    default_role = await Role.get_or_create(name="user")  # 默認角色
    hashed_pwd = hash_password(user.password)
    role_obj, created = await Role.get_or_create(name="user")
    new_user = await User.create(
        username=user.username,
        hashed_password=hashed_pwd,
        role=role_obj
    )
    return new_user

權限控制依賴（auth/deps.py）

我們新增一個 require_role 方法來檢查用戶的角色：

from fastapi import Depends, HTTPException
from app.auth.auth import oauth2_scheme
from jose import jwt, JWTError
from app.models.user import User
from app.core.security import SECRET_KEY, ALGORITHM

asyncdefget_current_user(token: str = Depends(oauth2_scheme)):
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
        username = payload.get("sub")
    except JWTError:
        raise HTTPException(status_code=401, detail="Token 認證失敗")
    
    user = await User.get_or_none(username=username).prefetch_related("role")
    ifnot user:
        raise HTTPException(status_code=404, detail="用戶不存在")
    return user

defrequire_role(required_roles: list[str]):
    asyncdefchecker(current_user: User = Depends(get_current_user)):
        if current_user.role.name notin required_roles:
            raise HTTPException(status_code=403, detail="權限不足")
        return current_user
    return checker

使用示例：不同接口設定權限

@router.get("/admin-only")
async def admin_route(current_user=Depends(require_role(["admin"]))):
    return {"msg": f"歡迎管理員 {current_user.username}"}

@router.get("/user")
async def user_route(current_user=Depends(require_role(["user", "admin"]))):
    return {"msg": f"歡迎用戶 {current_user.username}"}

擴展建議（可選）

增加 Permission 表：實現更細粒度控制（如資源級權限）
支持多角色綁定：用戶擁有多個角色（ManyToMany）
引入菜單/接口授權系統：可視化配置權限
添加 RBAC 管理后臺界面

總結

通過本文你實現了：

用戶 ?? 角色 ?? 權限的完整閉環
FastAPI 中的權限依賴注入
管理員/用戶等不同訪問控制場景

責任編輯：趙寧寧來源： Ssoul肥魚