🔐 OAuth2/JWT 用户认证模块

🎯 项目背景

本认证模块是"基于 OpenClaw + Claude Code 的端到端研发自动化系统"的核心组件，为整个研发流程提供统一、安全、可扩展的用户身份认证与授权服务。 系统采用业界标准的 OAuth2.0 协议和 JWT（JSON Web Token）技术，支持多种认证场景，包括用户名密码登录、第三方 OAuth 登录、客户端凭证认证等。

🎯 设计目标

• 安全性优先：采用 bcrypt 密码哈希、JWT 签名验证、令牌轮换等安全机制
• 标准化协议：完整实现 OAuth2.0 授权码模式、刷新令牌模式、客户端凭证模式
• 高性能：基于 FastAPI 异步框架，支持高并发场景
• 易扩展：模块化设计，支持插件式扩展第三方认证提供商
• 可观测性：完整的审计日志、健康检查、监控指标
• 云原生：Docker 容器化部署，支持 K8s/KubeSphere 编排

📂 项目结构

auth_module/
├── __init__.py              # 包初始化
├── main.py                  # FastAPI 应用入口
├── models.py                # SQLAlchemy 数据模型
├── schemas.py               # Pydantic 数据验证模式
├── security.py              # 安全工具（JWT、密码哈希）
├── crud.py                  # 数据库 CRUD 操作
├── database.py              # 数据库连接配置
├── routes_auth.py           # 认证相关 API 路由
├── routes_oauth2.py         # OAuth2 相关 API 路由
├── tests/
│   ├── __init__.py
│   └── test_auth.py         # 单元测试套件
├── requirements.txt         # Python 依赖
├── Dockerfile               # Docker 镜像构建
├── docker-compose.yml       # Docker Compose 配置
└── .env.example             # 环境变量模板

🧩 技术栈

🛡️ 多层安全防护

🔐 JWT 令牌结构

# Access Token Payload 示例
{
    "sub": "user-uuid-12345",      # 用户唯一标识
    "username": "john.doe",     # 用户名
    "roles": ["developer"],     # 用户角色列表
    "department": "Engineering", # 所属部门
    "exp": 1710432000,          # 过期时间戳
    "iat": 1710428400,          # 签发时间戳
    "type": "access",           # 令牌类型
    "jti": "unique-token-id"   # 令牌唯一 ID
}

🔑 认证端点

🔗 OAuth2 端点

📝 请求示例

用户注册

curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newuser",
    "email": "user@example.com",
    "password": "SecurePass@123",
    "full_name": "New User",
    "department": "Engineering"
  }'

用户登录

curl -X POST http://localhost:8000/api/v1/auth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=testuser&password=Test@123456"

# 响应示例
{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "bearer",
    "expires_in": 3600
}

访问受保护资源

curl -X GET http://localhost:8000/api/v1/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

📊 核心数据表

🔗 ER 关系图

┌─────────────┐       ┌──────────────────┐       ┌──────────────┐
│   users     │◄──────│  refresh_tokens  │       │ oauth_clients│
├─────────────┤       ├──────────────────┤       ├──────────────┤
│ id          │       │ id               │       │ id           │
│ user_uuid   │       │ token_hash       │       │ client_id    │
│ username    │       │ user_id (FK)     │       │ client_secret│
│ email       │       │ expires_at       │       │ redirect_uris│
│ role        │       │ is_revoked       │       └──────────────┘
└──────┬──────┘       └──────────────────┘
       │
       │ 1:N
       ├──────────────────────────────────────────┐
       │                                          │
       ▼                                          ▼
┌─────────────┐                          ┌──────────────┐
│oauth_accounts│                         │  auth_codes  │
├─────────────┤                          ├──────────────┤
│ provider    │                          │ code_uuid    │
│ provider_id │                          │ user_id (FK) │
│ access_token│                          │ client_id    │
└─────────────┘                          └──────────────┘
       ▲
       │
       ▼
┌─────────────┐
│ audit_logs  │
├─────────────┤
│ action      │
│ user_id(FK) │
│ created_at  │
└─────────────┘

🐳 Docker 部署

# 开发环境启动
docker-compose up -d postgres redis
docker-compose --profile dev up -d

# 生产环境启动
docker-compose --profile production up -d

# 查看日志
docker-compose logs -f auth-service

# 运行测试
docker-compose exec auth-service pytest

☸️ Kubernetes 部署

# k8s-deployment.yaml 核心配置
apiVersion: apps/v1
kind: Deployment
metadata:
  name: auth-module
spec:
  replicas: 3
  selector:
    matchLabels:
      app: auth-module
  template:
    spec:
      containers:
      - name: auth-service
        image: registry.example.com/auth-module:1.0.0
        ports:
        - containerPort: 8000
        env:
        - name: DATABASE_URL
          valueFrom:
            secretKeyRef:
              name: auth-secrets
              key: database-url
        - name: JWT_SECRET_KEY
          valueFrom:
            secretKeyRef:
              name: auth-secrets
              key: jwt-secret
        livenessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 10
          periodSeconds: 30
        readinessProbe:
          httpGet:
            path: /ready
            port: 8000
          initialDelaySeconds: 5
          periodSeconds: 10
        resources:
          requests:
            memory: "128Mi"
            cpu: "250m"
          limits:
            memory: "512Mi"
            cpu: "1000m"

⚙️ 环境变量配置

🧪 单元测试覆盖

📋 测试用例分类

• 用户注册测试：正常注册、重复用户名、重复邮箱、弱密码验证
• 登录测试：正确凭据、错误密码、不存在的用户、非活跃用户
• 令牌刷新测试：正常刷新、已撤销令牌、过期令牌
• 受保护路由测试：有效令牌、无令牌、无效令牌
• 密码修改测试：正确旧密码、错误旧密码、弱新密码
• 登出测试：正常登出、令牌撤销验证
• 健康检查测试：服务状态、数据库连接
• 审计日志测试：日志记录完整性、分页查询

🔬 测试示例代码

def test_login_success(client, test_user):
    """测试成功登录"""
    response = client.post(
        "/api/v1/auth/token",
        data={
            "username": "testuser",
            "password": "Test@123456"
        }
    )
    
    assert response.status_code == 200
    data = response.json()
    
    assert "access_token" in data
    assert "refresh_token" in data
    assert data["token_type"] == "bearer"


def test_refresh_token_success(client, test_user):
    """测试成功刷新令牌"""
    # 先登录获取令牌
    login_response = client.post(
        "/api/v1/auth/token",
        data={"username": "testuser", "password": "Test@123456"}
    )
    
    refresh_token = login_response.json()["refresh_token"]
    
    # 刷新令牌
    refresh_response = client.post(
        "/api/v1/auth/refresh",
        json={"refresh_token": refresh_token}
    )
    
    assert refresh_response.status_code == 200
    assert "access_token" in refresh_response.json()

📊 运行测试

# 运行所有测试
pytest auth_module/tests/ -v

# 运行测试并生成覆盖率报告
pytest auth_module/tests/ --cov=auth_module --cov-report=html

# 运行特定测试类
pytest auth_module/tests/test_auth.py::TestLogin -v

# 运行测试并输出详细日志
pytest auth_module/tests/ -v --tb=long -s

📱 前端集成示例（React）

import { createContext, useContext, useState } from 'react';

const AuthContext = createContext();

export function AuthProvider({ children }) {
    const [token, setToken] = useState(localStorage.getItem('access_token'));
    
    const login = async (username, password) => {
        const response = await fetch('/api/v1/auth/token', {
            method: 'POST',
            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
            body: new URLSearchParams({ username, password })
        });
        
        const data = await response.json();
        localStorage.setItem('access_token', data.access_token);
        localStorage.setItem('refresh_token', data.refresh_token);
        setToken(data.access_token);
    };
    
    const refreshToken = async () => {
        const refresh_token = localStorage.getItem('refresh_token');
        const response = await fetch('/api/v1/auth/refresh', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ refresh_token })
        });
        
        const data = await response.json();
        localStorage.setItem('access_token', data.access_token);
        localStorage.setItem('refresh_token', data.refresh_token);
        setToken(data.access_token);
    };
    
    return (
        
            {children}
        
    );
}