makemd/server/docs/auth-service.md

AuthService 文档

概述

AuthService 是一个功能强大的认证服务，支持 JWT、OAuth2.0 和多因子认证（MFA），为 Crawlful Hub 项目提供统一的身份认证和授权管理。

核心功能

1. JWT 认证

• 生成和验证 JWT 令牌
• 支持令牌刷新
• 携带 4-tuple TraceContext（tenantId, shopId, taskId, traceId）

2. OAuth2.0 认证

• 客户端管理
• 授权码流程
• 访问令牌生成和刷新
• 支持多种授权类型

3. 多因子认证（MFA）

• 基于时间的一次性密码（TOTP）
• 支持 SMS 和 EMAIL 验证（预留接口）

数据库表结构

cf_user

• id: 用户ID
• username: 用户名
• password_hash: 密码哈希
• role: 角色
• tenant_id: 租户ID
• shop_id: 店铺ID（可选）
• status: 状态（ACTIVE/DISABLED）
• created_at: 创建时间
• updated_at: 更新时间

cf_oauth_client

• id: 客户端ID
• client_id: 客户端标识符
• client_secret: 客户端密钥哈希
• redirect_uri: 重定向URI
• grant_types: 授权类型
• scope: 权限范围
• tenant_id: 租户ID
• created_at: 创建时间
• updated_at: 更新时间

cf_oauth_code

• id: 授权码ID
• code: 授权码
• client_id: 客户端ID
• user_id: 用户ID
• redirect_uri: 重定向URI
• scope: 权限范围
• expires_at: 过期时间
• created_at: 创建时间
• updated_at: 更新时间

cf_oauth_token

• id: 令牌ID
• access_token: 访问令牌
• refresh_token: 刷新令牌
• client_id: 客户端ID
• user_id: 用户ID
• scope: 权限范围
• expires_at: 过期时间
• created_at: 创建时间
• updated_at: 更新时间

cf_user_mfa

• id: MFA记录ID
• user_id: 用户ID
• method: 认证方法（TOTP/SMS/EMAIL）
• secret: 密钥
• enabled: 是否启用
• created_at: 创建时间
• updated_at: 更新时间

cf_refresh_token

• id: 刷新令牌ID
• user_id: 用户ID
• token: 刷新令牌
• expires_at: 过期时间
• created_at: 创建时间
• updated_at: 更新时间

API 接口

公开接口

POST /api/auth/login

• 功能：用户登录
• 请求参数：
  • username: 用户名
  • password: 密码
• 响应：
  • token: JWT令牌
  • refreshToken: 刷新令牌
  • user: 用户信息

POST /api/auth/refresh

• 功能：刷新令牌
• 请求参数：
  • refreshToken: 刷新令牌
• 响应：
  • token: 新的JWT令牌
  • user: 用户信息

POST /api/auth/register

• 功能：注册新用户
• 请求参数：
  • username: 用户名
  • password: 密码
  • role: 角色
  • tenantId: 租户ID
  • shopId: 店铺ID（可选）
• 响应：
  • user: 用户信息

POST /api/auth/oauth2/token

• 功能：获取OAuth2.0访问令牌
• 请求参数：
  • grant_type: 授权类型（authorization_code/refresh_token）
  • code: 授权码（当grant_type为authorization_code时）
  • refresh_token: 刷新令牌（当grant_type为refresh_token时）
  • client_id: 客户端ID
  • client_secret: 客户端密钥
  • redirect_uri: 重定向URI
• 响应：
  • access_token: 访问令牌
  • refresh_token: 刷新令牌
  • expires_in: 过期时间（秒）
  • scope: 权限范围

需要认证的接口

GET /api/auth/me

• 功能：获取当前用户信息
• 响应：
  • user: 用户信息

POST /api/auth/mfa/enable

• 功能：启用多因子认证
• 请求参数：
  • method: 认证方法（TOTP/SMS/EMAIL）
  • secret: 密钥
• 响应：
  • success: 是否成功

POST /api/auth/mfa/verify

• 功能：验证多因子认证码
• 请求参数：
  • method: 认证方法（TOTP/SMS/EMAIL）
  • code: 验证码
• 响应：
  • success: 是否成功

GET /api/auth/oauth2/authorize

• 功能：OAuth2.0授权
• 请求参数：
  • client_id: 客户端ID
  • redirect_uri: 重定向URI
  • scope: 权限范围
  • state: 状态参数
• 响应：
  • 重定向到redirect_uri，携带code和state参数

POST /api/auth/oauth2/client

• 功能：创建OAuth2.0客户端
• 请求参数：
  • clientId: 客户端ID
  • clientSecret: 客户端密钥
  • redirectUri: 重定向URI
  • grantTypes: 授权类型
  • scope: 权限范围
• 响应：
  • success: 是否成功

使用示例

JWT 认证

// 登录
const loginResponse = await fetch('/api/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    username: 'admin',
    password: 'admin123'
  })
});

const { token, refreshToken, user } = await loginResponse.json();

// 使用令牌访问受保护的接口
const protectedResponse = await fetch('/api/auth/me', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

// 刷新令牌
const refreshResponse = await fetch('/api/auth/refresh', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    refreshToken
  })
});

const { token: newToken } = await refreshResponse.json();

OAuth2.0 认证

// 1. 重定向用户到授权页面
const authorizationUrl = `/api/auth/oauth2/authorize?client_id=client1&redirect_uri=http://localhost:3000/callback&scope=read%20write&state=12345`;
window.location.href = authorizationUrl;

// 2. 处理回调（在redirect_uri指定的页面）
const urlParams = new URLSearchParams(window.location.search);
const code = urlParams.get('code');
const state = urlParams.get('state');

// 3. 使用授权码获取访问令牌
const tokenResponse = await fetch('/api/auth/oauth2/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    grant_type: 'authorization_code',
    code,
    client_id: 'client1',
    client_secret: 'secret1',
    redirect_uri: 'http://localhost:3000/callback'
  })
});

const { access_token, refresh_token, expires_in, scope } = await tokenResponse.json();

// 4. 使用访问令牌访问受保护的接口
const protectedResponse = await fetch('/api/protected', {
  headers: {
    'Authorization': `Bearer ${access_token}`
  }
});

// 5. 使用刷新令牌获取新的访问令牌
const refreshResponse = await fetch('/api/auth/oauth2/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    grant_type: 'refresh_token',
    refresh_token,
    client_id: 'client1',
    client_secret: 'secret1'
  })
});

const { access_token: newAccessToken } = await refreshResponse.json();

多因子认证

// 1. 生成TOTP密钥
const { secret, otpauthUrl } = AuthService.generateTOTPSecret();

// 2. 启用MFA
const enableResponse = await fetch('/api/auth/mfa/enable', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    method: 'TOTP',
    secret
  })
});

// 3. 验证MFA码
const verifyResponse = await fetch('/api/auth/mfa/verify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    method: 'TOTP',
    code: '123456' // 从认证器应用获取
  })
});

const { success } = await verifyResponse.json();

安全注意事项

1. 密码安全：使用 bcrypt 对密码进行哈希处理，避免明文存储
2. 令牌安全：JWT 令牌和 OAuth2.0 令牌都有过期时间，避免长期使用
3. 密钥管理：JWT 密钥和 MFA 密钥应该妥善保管，避免泄露
4. 权限控制：基于角色的访问控制（RBAC），确保用户只能访问授权的资源
5. 输入验证：所有用户输入都应该进行验证，避免注入攻击
6. HTTPS：在生产环境中使用 HTTPS，避免数据传输过程中的窃听

部署配置

环境变量

• JWT_SECRET：JWT 签名密钥，生产环境中应该使用强随机字符串
• JWT_EXPIRES_IN：JWT 令牌过期时间，默认 24h
• REFRESH_TOKEN_EXPIRES_IN：刷新令牌过期时间，默认 7d
• OAUTH2_ACCESS_TOKEN_EXPIRES_IN：OAuth2.0 访问令牌过期时间，默认 1h
• OAUTH2_AUTH_CODE_EXPIRES_IN：OAuth2.0 授权码过期时间，默认 10m

数据库配置

• 使用 MySQL 8.0
• 所有表都以 cf_ 为前缀
• 建立适当的索引，提高查询性能
• 使用外键约束，确保数据完整性

故障排查

常见问题

1. 令牌过期：如果收到 401 Unauthorized 错误，检查令牌是否过期，使用刷新令牌获取新令牌
2. 密码错误：如果登录失败，检查用户名和密码是否正确
3. MFA 验证失败：检查 TOTP 码是否正确，确保时间同步
4. OAuth2.0 授权失败：检查客户端 ID、密钥和重定向 URI 是否正确

日志

AuthService 会记录所有认证相关的操作和错误，日志文件位于 logs/ 目录下，可以通过查看日志来排查问题。

总结

AuthService 是一个功能完整、安全可靠的认证服务，支持多种认证方式，为 Crawlful Hub 项目提供统一的身份认证和授权管理。通过合理使用 AuthService，可以确保系统的安全性和可靠性，同时为用户提供良好的认证体验。