tokens-reef/deploy/docs-backup/MODULE_02_AUTH.md

# Sub2API 模块分析报告：认证与授权模块

## 1. 模块概述

### 1.1 模块定位
认证与授权模块是 Sub2API 的安全核心，负责验证用户身份、管理 API Key、配置访问权限。该模块确保只有授权用户才能访问系统资源，并实施精细的访问控制策略。

### 1.2 核心职责
- **用户认证**：支持密码登录、OAuth 第三方登录、JWT Token 认证
- **API Key 管理**：创建、验证、吊销 API Key
- **权限控制**：基于角色和分组的访问控制
- **二次验证**：TOTP 双因素认证支持

## 2. 代码结构分析

### 2.1 核心文件

| 文件路径 | 职责 | 代码行数 |
|---------|------|----------|
| `middleware/jwt_auth.go` | JWT Token 认证中间件 | ~300 行 |
| `middleware/api_key_auth.go` | API Key 认证中间件 | ~250 行 |
| `middleware/admin_auth.go` | 管理员权限验证 | ~150 行 |
| `service/auth_service.go` | 认证核心服务 | ~900 行 |
| `service/api_key_service.go` | API Key 服务 | ~900 行 |
| `service/totp_service.go` | TOTP 双因素认证 | ~400 行 |
| `handler/auth_handler.go` | 认证 API 处理器 | ~300 行 |
| `handler/api_key_handler.go` | API Key API 处理器 | ~300 行 |

### 2.2 目录结构

```
backend/internal/
├── server/middleware/
│   ├── jwt_auth.go           # JWT 认证
│   ├── api_key_auth.go       # API Key 认证
│   ├── admin_auth.go         # 管理员认证
│   └── auth_subject.go       # 认证主体解析
└── service/
    ├── auth_service.go       # 认证服务
    ├── api_key_service.go    # API Key 服务
    └── totp_service.go      # TOTP 服务
```

## 3. 功能详细分析

### 3.1 认证机制

#### 3.1.1 JWT Token 认证

**流程：**
```
用户登录 → 验证密码 → 生成 JWT Token → 返回给客户端
后续请求 → 验证 JWT → 解析用户信息 → 授权访问
```

**实现代码：** (`middleware/jwt_auth.go`)
```go
func NewJWTAuthMiddleware(cfg *config.Config) gin.HandlerFunc {
    return func(c *gin.Context) {
        // 1. 从 Header 获取 Token
        token := extractToken(c)
        
        // 2. 解析 Token
        claims, err := jwtUtils.ParseToken(token, cfg.JWT.Secret)
        if err != nil {
            c.AbortWithStatusJSON(401, gin.H{"error": "invalid token"})
            return
        }
        
        // 3. 设置用户上下文
        c.Set("user_id", claims.UserID)
        c.Set("role", claims.Role)
        c.Next()
    }
}
```

**配置参数：**
- Token 有效期：24 小时（可配置）
- 签名算法：HS256/HS384/HS512
- 刷新机制：支持 Refresh Token

#### 3.1.2 API Key 认证

**特点：**
- 永久有效（除非被吊销）
- 绑定用户和分组
- 支持 IP 白名单
- 支持速率限制

**验证流程：**
```go
// service/api_key_service.go - ValidateKey
func (s *APIKeyService) ValidateKey(ctx context.Context, key string) (*APIKey, *User, error) {
    // 1. 缓存查询（两级：L1 内存 + L2 Redis）
    if cached := s.getAuthCache(key); cached != nil {
        return cached.APIKey, cached.User, nil
    }
    
    // 2. 数据库查询
    apiKey, err := s.apiKeyRepo.GetByKey(ctx, key)
    if err != nil {
        return nil, nil, ErrInvalidAPIKey
    }
    
    // 3. 状态检查
    if apiKey.Status != StatusActive {
        return nil, nil, ErrAPIKeyDisabled
    }
    
    // 4. IP 白名单检查
    if !s.checkIPWhitelist(c, apiKey) {
        return nil, nil, ErrIPNotAllowed
    }
    
    return apiKey, user, nil
}
```

#### 3.1.3 OAuth 第三方登录

**支持的提供商：**
- **Anthropic OAuth**：Claude 账号授权
- **Google OAuth**：Gemini 账号授权
- **OpenAI OAuth**：OpenAI 账号授权
- **Linux.do OAuth**：社区账号登录

**实现结构：**
```go
// service/oauth_service.go
type OAuthProvider interface {
    GetAuthURL() string
    ExchangeCode(token string) (*OAuthToken, error)
    RefreshToken(token string) (*OAuthToken, error)
}
```

### 3.2 授权控制

#### 3.2.1 基于角色的访问控制 (RBAC)

**角色层级：**
```go
const (
    RoleUser   Role = "user"      // 普通用户
    RoleAdmin  Role = "admin"     // 管理员
    RoleSuperAdmin Role = "super_admin" // 超级管理员
)
```

**权限检查：**
```go
// middleware/admin_only.go
func AdminOnly() gin.HandlerFunc {
    return func(c *gin.Context) {
        role, exists := c.Get("role")
        if !exists || role != RoleAdmin {
            c.AbortWithStatusJSON(403, gin.H{"error": "admin access required"})
            return
        }
        c.Next()
    }
}
```

#### 3.2.2 分组级别的访问控制

```go
// API Key 绑定到分组
type APIKey struct {
    GroupID *int64  // 所属分组
    // 用户只能访问自己分组内的资源
}
```

### 3.3 API Key 管理

#### 3.3.1 创建 API Key

```go
// service/api_key_service.go - Create
func (s *APIKeyService) Create(ctx context.Context, userID int64, req CreateAPIKeyRequest) (*APIKey, error) {
    // 1. 生成 Key 值
    key := "sk-" + generateRandomKey(32)
    
    // 2. 设置默认值
    apiKey := &APIKey{
        Key:       key,
        UserID:    userID,
        Status:    StatusActive,
        Quota:     req.Quota,
        // IP 白名单、速率限制等
    }
    
    // 3. 存储到数据库
    return s.apiKeyRepo.Create(ctx, apiKey)
}
```

**Key 格式：** `sk-{随机32位字符}`

#### 3.3.2 缓存策略

**两级缓存架构：**
```
┌─────────────────────────────────────┐
│           L1 Cache (内存)           │
│  - 容量：10000 条                    │
│  - TTL：1 分钟                       │
│  - 命中率：~90%                      │
└─────────────────────────────────────┘
                ↑
                │ 缓存未命中
                ▼
┌─────────────────────────────────────┐
│           L2 Cache (Redis)          │
│  - 容量：无限制                      │
│  - TTL：5 分钟                       │
└─────────────────────────────────────┘
                ↑
                │ 缓存未命中
                ▼
┌─────────────────────────────────────┐
│           Database (PostgreSQL)     │
│  - 查询延迟：~10ms                   │
└─────────────────────────────────────┘
```

### 3.4 双因素认证 (TOTP)

#### 3.4.1 启用流程

```go
// service/totp_service.go - EnableTOTP
func (s *TOTPService) EnableTOTP(ctx context.Context, userID int64) (*TOTPSetup, error) {
    // 1. 生成密钥
    secret := generateTOTPSecret()
    
    // 2. 生成 QR 码（用户扫描到 authenticator app）
    qrCode := generateQRCode(secret, user.Email)
    
    // 3. 临时存储密钥（未验证前不生效）
    s.tempStore.Set(userID, secret)
    
    return &TOTPSetup{
        Secret: secret,
        QRCode: qrCode,
    }, nil
}
```

#### 3.4.2 验证流程

```go
// service/totp_service.go - VerifyTOTP
func (s *TOTPService) VerifyTOTP(ctx context.Context, userID int64, code string) error {
    // 1. 获取用户密钥
    secret := s.getUserSecret(userID)
    
    // 2. 验证 TOTP 码（支持 30s 窗口）
    valid := totp.Validate(code, secret)
    if !valid {
        return ErrInvalidTOTP
    }
    
    // 3. 标记为已启用
    s.markAsEnabled(userID)
    return nil
}
```

**安全特性：**
- 密钥加密存储（AES-256）
- 支持时间窗口（前一个、后一个码可用）
- 错误锁定（连续 5 次错误锁定 30 分钟）

## 4. 安全加固

### 4.1 密码安全

```go
// service/auth_service.go
func (s *AuthService) HashPassword(password string) string {
    // 使用 bcrypt，cost = 12
    hash, _ := bcrypt.GenerateFromPassword([]byte(password), 12)
    return string(hash)
}

func (s *AuthService) VerifyPassword(password, hash string) bool {
    err := bcrypt.CompareHashAndPassword([]byte(hash), []byte(password))
    return err == nil
}
```

**配置参数：**
- Bcrypt cost：12（可配置 10-15）
- 密码最小长度：8 字符
- 密码复杂度：无强制要求（建议启用）

### 4.2 速率限制

```go
// middleware/rate_limiter.go
func NewRateLimiter() gin.HandlerFunc {
    return func(c *gin.Context) {
        key := getRateLimitKey(c)
        
        // 基于 Token Bucket 算法
        if !allowRequest(key) {
            c.AbortWithStatusJSON(429, gin.H{
                "error": "rate limit exceeded",
                "retry_after": getRetryAfter(key),
            })
            return
        }
        c.Next()
    }
}
```

**限制级别：**
| 级别 | 限制 | 说明 |
|------|------|------|
| 用户 | 1000 RPM | 每用户请求速率 |
| API Key | 500 RPM | 每 Key 请求速率 |
| IP | 2000 RPM | 每 IP 请求速率 |

### 4.3 审计日志

```go
// 记录所有认证事件
func logAuthEvent(event AuthEvent) {
    logger.Info("auth_event",
        "user_id", event.UserID,
        "action", event.Action,
        "ip", event.IP,
        "success", event.Success,
        "timestamp", event.Timestamp,
    )
}

// 事件类型：
// - login_success / login_failed
// - logout
// - api_key_created / api_key_revoked
// - totp_enabled / totp_disabled
// - password_changed
```

## 5. 配置参数

### 5.1 认证配置（config.yaml）

```yaml
jwt:
  secret: "your-256-bit-secret"
  expire_hour: 24
  refresh_expire_hour: 168  # 7 天

api_key:
  # API Key 缓存配置
  cache:
    l1_size: 10000
    l1_ttl: 1m
    l2_ttl: 5m

rate_limit:
  user_rpm: 1000
  apikey_rpm: 500
  ip_rpm: 2000

totp:
  issuer: "Sub2API"
  enabled: true
```

### 5.2 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `JWT_SECRET` | JWT 签名密钥 | 必需 |
| `TOTP_ENCRYPTION_KEY` | TOTP 密钥加密密钥 | 必需 |
| `RATE_LIMIT_ENABLED` | 启用速率限制 | true |
| `TOTP_ENABLED` | 启用 TOTP | true |

## 6. 集成与扩展

### 6.1 外部系统集成

**管理员 API Key：**
```go
// 用于外部系统（如支付系统）调用 Admin API
type AdminAPIKey struct {
    Key:   string  // 格式：admin-<64位hex>
    Role:  string // admin 或 super_admin
}
```

**使用方式：**
```bash
curl -H "x-api-key: admin-xxxxxxxxxxxxxx" \
     https://your-domain/api/v1/admin/users
```

### 6.2 自定义认证提供者

要添加新的认证方式，需要：

1. **实现认证接口**
```go
type AuthProvider interface {
    Authenticate(credentials) (*User, error)
    Refresh(token) (*User, error)
}
```

2. **注册到路由器**
```go
// server/routes/auth.go
router.POST("/auth/custom", customAuthHandler)
```

## 7. 修改和扩展指南

### 7.1 常见修改场景

**场景 1：调整 API Key 缓存策略**

修改文件：`service/api_key_auth_cache_impl.go`
```go
func (s *APIKeyService) getAuthCache(key string) (*APIKeyAuthCacheEntry, bool) {
    // 调整 L1 缓存大小
    l1Size := 20000 // 从 10000 增加到 20000
    
    // 调整 L1 TTL
    l1TTL := 2 * time.Minute // 从 1 分钟增加到 2 分钟
}
```

**场景 2：添加新的 OAuth 提供商**

1. 在 `service/oauth/` 目录创建新服务
2. 实现 `OAuthProvider` 接口
3. 在 `auth_service.go` 注册

**场景 3：调整速率限制**

修改文件：`middleware/rate_limiter.go`
```go
const (
    UserRPM   = 2000  // 从 1000 增加到 2000
    APIKeyRPM = 1000  // 从 500 增加到 1000
)
```

### 7.2 安全注意事项

1. **JWT Secret 必须足够复杂**：至少 256 位随机字符串
2. **TOTP 密钥必须加密存储**：使用独立的加密密钥
3. **API Key 不得明文日志**：日志中应脱敏处理
4. **密码哈希不得使用弱算法**：禁止 MD5/SHA1

## 8. 测试覆盖

### 8.1 单元测试

| 测试文件 | 覆盖范围 |
|----------|----------|
| `jwt_auth_test.go` | JWT 解析和验证 |
| `api_key_auth_test.go` | API Key 认证流程 |
| `api_key_service_cache_test.go` | 缓存机制 |
| `totp_service_test.go` | TOTP 验证 |

### 8.2 集成测试

| 测试文件 | 场景 |
|----------|------|
| `e2e_user_flow_test.go` | 完整用户认证流程 |
| `auth_rate_limit_integration_test.go` | 速率限制验证 |

## 9. 监控与运维

### 9.1 关键指标

| 指标 | 告警阈值 | 说明 |
|------|----------|------|
| `auth_login_failures` | > 10/min | 登录失败过多 |
| `auth_api_key_validations` | - | API Key 验证次数 |
| `auth_cache_hit_rate` | < 80% | 缓存命中率低 |
| `auth_totp_errors` | > 5/min | TOTP 验证失败多 |

### 9.2 日志分析

关键日志字段：
- `user_id`：用户 ID
- `action`：认证动作
- `ip`：客户端 IP
- `user_agent`：客户端标识
- `success`：是否成功

## 10. 总结

认证与授权模块设计完善，具有以下特点：

- **多层认证**：支持 JWT、API Key、OAuth、TOTP
- **安全加固**：密码 bcrypt、密钥加密、速率限制
- **高性能缓存**：两级缓存提升验证效率
- **完整审计**：全面的认证事件日志

**潜在问题：**
1. 激活码和 API Key 验证未包含系统标识，可能被其他部署实例使用
2. 缺少登录尝试锁定机制（连续失败后临时封禁）

**修改建议：**
- 如需解决跨实例使用问题，需在 Key 中嵌入实例标识
- 添加登录失败锁定机制增强安全性

---
*文档版本：1.0*
*最后更新：2025-01*
*分析基于：Sub2API v0.1.104*