LabelingSystem/backend/JWT_AUTHENTICATION_GUIDE.md

JWT 认证系统快速指南

概述

本系统已成功集成 JWT（JSON Web Token）认证体系，提供完整的用户注册、登录、令牌刷新和基于角色的访问控制功能。

主要特性

✅ 用户注册和登录

• 用户名和邮箱唯一性验证
• 密码使用 bcrypt 加密存储
• 自动分配默认角色（annotator）

✅ JWT 令牌管理

• Access Token（15分钟有效期）
• Refresh Token（7天有效期）
• Token Rotation 机制

✅ 中间件认证

• 自动验证所有受保护端点
• 公开端点无需认证
• 用户信息自动附加到请求

✅ 基于角色的访问控制

• annotator：普通标注员
• admin：管理员（可删除资源）

✅ 自动用户关联

• 创建任务时自动分配给当前用户
• 创建标注时自动使用当前用户 ID
• 用户只能查看和修改自己的标注

快速开始

1. 配置环境变量

# 复制环境变量模板
cp .env.example .env

# 生成安全的 JWT 密钥
python -c "import secrets; print(secrets.token_urlsafe(32))"

# 编辑 .env 文件，设置 JWT_SECRET_KEY

2. 启动服务器

python main.py

服务器将在 http://localhost:8000 启动

3. 测试认证流程

运行测试脚本：

.\test_auth_flow.ps1

或手动测试：

# 注册用户
curl -X POST "http://localhost:8000/api/auth/register" \
  -H "Content-Type: application/json" \
  -d '{"username": "testuser", "email": "test@example.com", "password": "password123"}'

# 登录
curl -X POST "http://localhost:8000/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username": "testuser", "password": "password123"}'

# 使用 token 访问受保护端点
curl -X GET "http://localhost:8000/api/auth/me" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

API 端点

认证端点（公开）

端点	方法	描述
/api/auth/register	POST	用户注册
/api/auth/login	POST	用户登录
/api/auth/refresh	POST	刷新令牌

认证端点（需要 token）

端点	方法	描述
/api/auth/me	GET	获取当前用户信息

受保护端点

所有 /api/projects/*、/api/tasks/*、/api/annotations/* 端点都需要认证。

管理员专用端点

端点	方法	描述	角色要求
DELETE /api/projects/{id}	DELETE	删除项目	admin
DELETE /api/tasks/{id}	DELETE	删除任务	admin

权限规则

项目（Projects）

• ✅ 所有认证用户可以创建、查看、更新项目
• ❌ 只有管理员可以删除项目

任务（Tasks）

• ✅ 所有认证用户可以创建、查看、更新任务
• ✅ 创建任务时，如果未指定 assigned_to，自动分配给当前用户
• ❌ 只有管理员可以删除任务

标注（Annotations）

• ✅ 所有认证用户可以创建标注
• ✅ 创建标注时，自动使用当前用户 ID（忽略请求中的 user_id）
• ✅ 用户只能查看和修改自己的标注
• ✅ 管理员可以查看和修改所有标注

错误处理

401 Unauthorized

原因：

• 缺少 Authorization header
• Token 格式错误
• Token 已过期
• Token 无效

解决方案：

• 确保包含 Authorization: Bearer <token> header
• 使用 refresh token 获取新的 access token

403 Forbidden

原因：

• 用户角色权限不足
• 尝试访问其他用户的资源

解决方案：

• 联系管理员提升权限
• 只访问自己的资源

安全建议

开发环境

• ✅ 可以使用自动生成的 JWT_SECRET_KEY
• ✅ 使用 HTTP（localhost）

生产环境

• ⚠️ 必须设置强随机的 JWT_SECRET_KEY
• ⚠️ 必须使用 HTTPS
• ⚠️ 必须配置正确的 CORS 设置
• ⚠️ 建议启用速率限制
• ⚠️ 建议添加日志审计

令牌生命周期

注册/登录
    ↓
获得 Access Token (15分钟) + Refresh Token (7天)
    ↓
使用 Access Token 访问 API
    ↓
Access Token 过期
    ↓
使用 Refresh Token 获取新的 Access Token
    ↓
继续使用新的 Access Token
    ↓
Refresh Token 过期
    ↓
需要重新登录

数据库结构

users 表

字段	类型	描述
id	TEXT	用户唯一标识
username	TEXT	用户名（唯一）
email	TEXT	邮箱（唯一）
password_hash	TEXT	密码哈希
role	TEXT	用户角色
oauth_provider	TEXT	OAuth 提供商（预留）
oauth_id	TEXT	OAuth ID（预留）
created_at	TIMESTAMP	创建时间

测试结果

所有测试已通过 ✅

1. ✅ 用户注册
2. ✅ 用户登录
3. ✅ 访问受保护端点（带 token）
4. ✅ 拒绝未认证请求（无 token）
5. ✅ 创建项目（认证）
6. ✅ 创建任务（自动分配给当前用户）
7. ✅ 创建标注（自动使用当前用户 ID）
8. ✅ 令牌刷新
9. ✅ 拒绝非管理员删除操作

下一步

可选功能（未实现）

• 前端认证集成（React + Jotai）
• OAuth 2.0 集成（Google, GitHub）
• 邮箱验证
• 密码重置
• 用户资料管理
• 审计日志
• 速率限制
• 双因素认证（2FA）

实现前端认证

参考 .kiro/specs/jwt-authentication/tasks.md 中的 Task 14，包含：

1. 创建认证 Atoms（Jotai）
2. 创建认证服务
3. 配置 Axios 拦截器
4. 创建登录/注册组件
5. 实现路由保护

故障排除

问题：服务器启动时提示"使用默认生成的 JWT_SECRET_KEY"

解决方案：这是正常的开发环境提示。生产环境请在 .env 文件中设置 JWT_SECRET_KEY。

问题：Token 一直提示过期

解决方案：

1. 检查系统时间是否正确
2. 使用 refresh token 获取新的 access token
3. 如果 refresh token 也过期，需要重新登录

问题：无法访问其他用户的标注

解决方案：这是设计行为。普通用户只能访问自己的标注，管理员可以访问所有标注。

联系方式

如有问题或建议，请联系项目维护者。

---

文档版本: 1.0
最后更新: 2024-01-22
状态: ✅ 生产就绪