1、认证流程总览

EduAgent 用 JWT(JSON Web Token) 做登录认证。整个流程是这样的:

① 用户 POST /login(用户名+密码)
        │
        ▼
② 服务端查库、用 bcrypt 校验密码
        │  校验通过
        ▼
③ 签发一个 JWT Token(里面装着 user_id/role/tenant_id),返回给前端
        │
        ▼
④ 之后每次请求受保护接口,前端在请求头带上:Authorization: Bearer <token>
        │
        ▼
⑤ get_current_user 依赖解码 Token、验证有效性 → 拿到当前用户身份
JWT 的精髓:Token 本身就装着用户身份信息,且用密钥签名防篡改。服务端不需要存 session,只要能用密钥验签,就信任 Token 里的身份。这套涉及三块代码——密码哈希、登录接口(签发 Token)、鉴权依赖(验证 Token),下面逐个实现。

2、密码安全:bcrypt 哈希

我们用passlib 的 bcrypt 算法:注册时存哈希值,登录时校验。

from passlib.context import CryptContext
pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")

hashed = pwd_context.hash("Student@123456")        # 注册:算出哈希存库
ok = pwd_context.verify("Student@123456", hashed)  # 登录:校验明文是否匹配哈希

bcrypt 的特点是**单向不可逆**(无法从哈希反推明文)且**自带盐值**(同样的密码每次哈希结果都不同),很适合存密码。

3、补全鉴权依赖

 鉴权依赖。它负责从请求头取出 JWT、解码、验证,返回当前用户身份。

# backend/dependencies.py
# FastAPI 依赖注入:① 数据库会话 get_db  ② 当前用户鉴权 get_current_user

from typing import AsyncGenerator
from fastapi import Depends, HTTPException, status
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials  # 解析 Authorization: Bearer 头
from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine, async_sessionmaker
from jose import JWTError, jwt                       # python-jose:JWT 的编解码库

from backend.config import get_settings

settings = get_settings()

# ── PostgreSQL 异步连接池(与 3.2 相同)──────────────────────────
engine = create_async_engine(
    settings.database_url,
    pool_size=10,
    max_overflow=20,
    echo=False,
)
AsyncSessionLocal = async_sessionmaker(engine, expire_on_commit=False)


async def get_db() -> AsyncGenerator[AsyncSession, None]:
    """FastAPI 依赖:获取异步数据库会话,自动提交 / 回滚 / 关闭。"""
    async with AsyncSessionLocal() as session:
        try:
            yield session
            await session.commit()
        except Exception:
            await session.rollback()
            raise


# ── JWT 鉴权 ───────────────────────────────────────────────────
bearer_scheme = HTTPBearer()   # FastAPI 安全方案:自动从请求头解析 "Authorization: Bearer <token>"


async def get_current_user(
    # Depends(bearer_scheme):FastAPI 自动取出 Bearer Token;没带或格式错会直接 401
    credentials: HTTPAuthorizationCredentials = Depends(bearer_scheme),
) -> dict:
    """FastAPI 依赖:验证 JWT Token,返回当前用户信息。
    返回 {"user_id": str, "role": str, "tenant_id": str};Token 无效则抛 401。"""
    # 预先准备好「401 凭证无效」异常,多处复用
    credentials_exception = HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail="无效的认证凭证",
        headers={"WWW-Authenticate": "Bearer"},
    )
    try:
        # 用密钥和算法解码 Token;若签名不对/过期,会抛 JWTError
        payload = jwt.decode(
            credentials.credentials,            # 实际的 token 字符串
            settings.jwt_secret_key,            # 验签密钥(和签发时同一个)
            algorithms=[settings.jwt_algorithm],
        )
        user_id: str = payload.get("sub")                                  # 标准字段 sub = 用户ID
        role: str = payload.get("role", "student")                         # 角色
        tenant_id: str = payload.get("tenant_id", settings.default_tenant_id)  # 租户

        if not user_id:                         # Token 里没有用户ID,视为无效
            raise credentials_exception

    except JWTError:                            # 解码失败(签名错/过期等)
        raise credentials_exception

    return {"user_id": user_id, "role": role, "tenant_id": tenant_id}

四个场景全部符合预期:

  • ① 正确密码登录成功,返回 JWT;
  • ② 带上 Token 访问受保护接口,get_current_user 成功解析出身份;
  • ③ 密码错误被拦在 401;
  • ④ 不带 Token 直接 401——get_current_user 把未认证请求挡在门外。

这验证了整条认证链路:密码哈希校验 → 签发 Token → 解码鉴权。 至此你已经能真正登录系统了。

Logo

更多推荐