FastAPI 安全认证教学项目

📚 项目简介

这是一个完整的 FastAPI 安全认证教学项目，通过实际代码演示如何在 FastAPI 应用中实现：

• ✅ OAuth2 密码流认证
• ✅ JWT Token 生成和验证
• ✅ 密码加密存储（Bcrypt）
• ✅ 基于角色的访问控制（RBAC）
• ✅ 多层级权限管理
• ✅ RESTful API 设计

🎯 学习目标

通过本项目，你将学会：

1. 认证基础：理解 OAuth2 和 JWT 的工作原理
2. 安全实践：掌握密码加密、Token 管理等安全技术
3. 权限控制：实现不同级别的访问权限管理
4. FastAPI 特性：深入使用依赖注入、路由保护等特性

📖 文档导航

建议按以下顺序阅读文档：

1. OAuth2 与 JWT 基础 - 理解核心概念
2. 快速开始 - 运行项目
3. 认证流程详解 - 深入理解认证机制
4. 权限控制 - 学习权限管理
5. API 接口文档 - 查看所有接口
6. 安全最佳实践 - 生产环境注意事项

🏗️ 项目结构

FastAPI-secure/
├── app/
│   ├── __init__.py
│   ├── main.py              # 应用入口
│   ├── config.py            # 配置管理
│   ├── models/              # 数据库模型
│   │   └── user.py
│   ├── schemas/             # Pydantic 模型
│   │   ├── user.py
│   │   └── token.py
│   ├── auth/                # 认证相关
│   │   ├── jwt.py           # JWT 处理
│   │   ├── password.py      # 密码加密
│   │   └── dependencies.py  # 认证依赖
│   ├── routers/             # 路由
│   │   ├── auth.py          # 认证路由
│   │   ├── users.py         # 用户管理
│   │   └── items.py         # 示例资源
│   └── db/                  # 数据库
│       ├── database.py      # 数据库连接
│       └── init_db.py       # 初始化脚本
├── docs/                    # 教学文档
├── requirements.txt         # 依赖清单
├── .env.example            # 环境变量示例
├── run.py                  # 启动脚本
└── README.md               # 本文件

🚀 快速开始

1. 安装依赖

pip install -r requirements.txt

2. 配置环境变量（可选）

cp .env.example .env
# 编辑 .env 文件，修改 SECRET_KEY 等配置

3. 运行应用

python run.py

或者：

uvicorn app.main:app --reload

4. 访问 API 文档

打开浏览器访问：

• Swagger UI: http://127.0.0.1:8000/docs
• ReDoc: http://127.0.0.1:8000/redoc

🧪 测试账号

项目启动时会自动创建以下测试账号：

角色	用户名	密码	说明
管理员	admin	admin123	拥有所有权限
普通用户	user1	user123	基本用户权限
普通用户	user2	user123	基本用户权限

💡 快速体验

1. 登录获取 Token

curl -X POST "http://127.0.0.1:8000/auth/login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin&password=admin123"

返回：

{
  "access_token": "eyJhbGc...",
  "token_type": "bearer"
}

2. 使用 Token 访问受保护接口

curl -X GET "http://127.0.0.1:8000/users/me" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

🔑 核心技术

• FastAPI: 现代化的 Python Web 框架
• SQLAlchemy: ORM 数据库操作
• Pydantic: 数据验证
• python-jose: JWT 处理
• passlib: 密码加密
• SQLite: 轻量级数据库

📚 学习资源

• FastAPI 官方文档
• OAuth 2.0 RFC
• JWT 官网

⚠️ 注意事项

本项目仅用于学习和教学目的。在生产环境中使用前，请注意：

1. 修改 SECRET_KEY 为强随机字符串
2. 使用 PostgreSQL 或 MySQL 替代 SQLite
3. 配置 HTTPS
4. 实现 Token 刷新机制
5. 添加请求限流
6. 实现日志记录
7. 添加单元测试

📝 许可证

本项目仅供学习使用。

🤝 贡献

欢迎提出问题和改进建议！

---

开始学习： OAuth2 与 JWT 基础 →