核心机制

用户角色标记

  • 黑名单用户通过特殊角色值 RoleBlacklisted (值为9) 进行标识
  • 系统中用户角色分级：
    • 普通用户(1)
    • 管理员(0)
    • 书库管理员(3)
    • 黑名单用户(9)
  • 角色值储存在用户表(users)的role字段中

记录存储架构

  • 黑名单记录存储在独立的user_blacklist表中
  • 每条记录包含：
    • 用户ID
    • 封禁原因
    • 封禁时间
    • 解封时间等信息
  • 使用is_active字段(1/0)标记记录是否生效，采用软删除模式

封禁流程

封禁用户

  1. 在user_blacklist表创建封禁记录
  2. 将用户role字段更新为9(黑名单用户)
  3. 可设置unbanned_at为：
    • 具体时间(临时封禁)
    • NULL(永久封禁)

封禁状态检查

  • 通过IsUserBannedNow函数检查用户是否处于有效封禁状态
  • 查询条件：
    • 用户ID匹配
    • 记录处于活动状态(is_active=1)
    • 未到解封时间

访问限制

  • 系统在各功能入口处检查用户role值
  • 当检测到role=9时：
    • 拒绝用户访问相应功能
    • 或展示特定提示

解封机制

手动解封

  • 管理员通过RemoveFromBlacklist函数解除用户封禁
  • 操作步骤：
    1. 将黑名单记录标记为非活动(is_active=0)
    2. 将用户角色恢复为普通用户(role=1)

自动解封

  • 系统每5分钟执行一次CleanupExpiredBlacklist函数
  • 检查所有：
    • 已到解封时间
    • 但仍处于活动状态的记录
  • 处理方式：
    1. 将这些记录标记为非活动
    2. 恢复相应用户角色

技术实现细节

事务保证

  • 用户封禁和解封操作使用数据库事务包装
  • 确保：
    • 黑名单记录状态
    • 用户角色状态一致性
  • 避免出现：
    • 黑名单记录已解除
    • 但角色仍为黑名单的不一致情况

并发控制

  • 使用重试机制处理SQLite数据库锁冲突
  • 实现指数退避策略：
    • 逐步增加重试间隔(200ms起步)
    • 最多5次重试
  • 设置较长的busy_timeout(5000ms)避免锁冲突

历史记录

  • 解封用户不删除黑名单记录，仅标记为非活动
  • 通过GetUserBlacklistHistory可查询用户完整封禁历史
  • 系统保留所有：
    • 封禁原因
    • 时间
    • 操作人等审计信息

用户体验

  • 黑名单用户页面会显示：
    • 封禁信息
    • 原因
    • 剩余时间
  • 系统可区分显示：
    • 永久封禁
    • 临时封禁状态
  • 对于临时封禁，实时计算并显示剩余时间

总结

这套黑名单系统通过：

  • 用户角色标记(role=9)
  • 专用数据表相结合的方式

实现了：

  1. 灵活、可靠的用户限制机制
  2. 完善的自动解封功能
  3. 完整的历史记录功能

满足了网站用户管理的需求。