黑名单机制

概述

黑名单机制是热排行系统反作弊体系中的核心组件之一。通过对已知恶意用户、设备、IP 地址等进行标识和拦截,可以有效防止刷榜、灌水等作弊行为对排行系统的污染。

一、黑名单类型

1.1 用户黑名单

用户黑名单是最直接的封禁方式,主要针对已确认的作弊账号。

1.2 设备黑名单

设备黑名单通过设备指纹识别作弊设备,即使用户更换账号也无法绕过。

1.3 IP 黑名单

IP 黑名单用于拦截来自特定网段的恶意请求。

1.4 内容黑名单

内容黑名单用于过滤恶意内容,包括关键词、链接等。

二、黑名单存储设计

2.1 存储架构

┌─────────────────────────────────────────────────────┐
│                   黑名单服务                          │
├─────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐ │
│  │   Redis     │  │   MySQL     │  │   Kafka     │ │
│  │  (热数据)   │  │  (持久化)   │  │  (审计日志)  │ │
│  └─────────────┘  └─────────────┘  └─────────────┘ │
└─────────────────────────────────────────────────────┘

2.2 Redis 数据结构设计

Redis 承担黑名单的在线检查职责,因此数据结构要围绕「一次请求能否在一次往返内完成判定」来设计。

需要支持四类黑名单目标(用户、设备、IP、内容),每类的取值特征和过期策略都不同:

类型目标取值特征典型过期时长
用户用户 ID精确匹配,数量大天级到永久
设备设备指纹精确匹配,设备可被重置天级到永久
IPIP 或网段需要支持网段前缀匹配小时级到天级
内容内容 ID 或关键词内容可重复出现,可批量小时级到天级

对应的 key 设计:

# 用户黑名单:值为空表示只需判断"在不在",用 Set 更省内存
SADD bl:user:10086 1
EXPIRE bl:user:10086 2592000

# 设备黑名单
SADD bl:device:9f2a7c1e-4b3d-4e8a-9c11-7d2e5f6a8b90 1
EXPIRE bl:device:9f2a7c1e-4b3d-4e8a-9c11-7d2e5f6a8b90 2592000

# IP 黑名单:精确 IP 与网段分开存放,查询时先查精确再查网段
SADD bl:ip:203.0.113.45 1
SADD bl:ip:cidr:203.0.113.0/24 1

# 内容黑名单
SADD bl:content:content_88213 1

# 关键词黑名单:内容入库时做敏感词匹配
SADD bl:keyword:敏感词集合 违禁词A 违禁词B

# 黑名单元信息:记录原因、来源、过期时间,便于审计和申诉
HSET bl:meta:user:10086 reason "批量投票" source "rule:vote_speed_limit" created_at "2026-03-31T10:00:00Z" expires_at "2026-04-30T10:00:00Z" evidence "60s 内 240 次投票"

几个设计决策及其理由:

  • 判定用 Set,元信息用 Hash。黑名单的在线逻辑只关心”这个目标在不在”,Set 的单元素内存开销最小,且 SISMEMBER 是 O(1)。原因、证据、过期时间这些信息只在管理后台和申诉流程里用到,单独放在 Hash 中,不会拖慢热路径的内存占用。
  • 元信息用 Hash 而不是把原因塞进 Set 的 value。如果把原因写进 Set 的 value,每次判断命中与否都会把这段字符串一起拉回网络,浪费带宽且占用连接缓冲区。拆开之后,正常请求(未命中)根本不触碰元信息。
  • IP 网段单独建 key。Redis 的 Set 不支持前缀匹配,因此网段黑名单用「网段前缀」作为 key 的一部分单独存储。查询时把请求 IP 拆成若干个前缀逐个匹配。需要注意前缀拆分会放大查询次数,建议只对 /24 及更粗的网段建黑名单条目,并在应用层做前缀数量上限控制。
  • 必须设置 TTL。黑名单不应该无限期占用内存,但也不要用统一的 TTL:设备黑名单可能需要永久保留,IP 黑名单可能几小时后自然失效。永久条目单独放在一个不带 TTL 的 Set 里,与带 TTL 的条目分开,清理时也互不影响。
# 永久黑名单与临时黑名单分开存放
SADD bl:perm:device:9f2a7c1e 1          # 永久条目,不设 TTL
SADD bl:temp:device:9f2a7c1e 1          # 临时条目,带 TTL

内存估算:单条黑名单记录(Set 成员加元信息)在实际环境中大约占用几百字节量级。以百万级黑名单条目估算,仍然是可控的规模,但前提是必须定期清理过期条目——这正是第五节要解决的问题。

2.3 MySQL 表结构

数据设计要点

  • 核心是在 blacklist 里保存业务事实,而不是把规则散落在应用逻辑里。
  • 索引服务于高频查询,重点是缩小扫描范围,而不是堆更多字段。
  • 关键字段包括 id、target_id、reason、evidence、created_by、created_at、expires_at、blacklist_id,它们决定后续查询和管理能力。

三、黑名单检查流程

3.1 检查流程图

请求进入
    │
    ▼
┌─────────────┐
│ 提取识别信息 │
│ (用户/设备/IP)│
└─────────────┘
    │
    ▼
┌─────────────┐
│  Redis 检查  │◄─────── 缓存命中
└─────────────┘
    │ 未命中
    ▼
┌─────────────┐
│  数据库检查  │
└─────────────┘
    │
    ▼
┌─────────────┐
│  返回结果    │
│ + 更新缓存   │
└─────────────┘

3.2 检查方案落地

把检查流程图落成代码,核心是一次 Pipeline 完成多目标判定,避免逐个目标查询带来的多次往返。

import java.util.ArrayList;
import java.util.List;

import redis.clients.jedis.Jedis;
import redis.clients.jedis.JedisPool;
import redis.clients.jedis.Pipeline;
import redis.clients.jedis.Response;

/**
 * 黑名单在线检查服务。
 */
public class BlacklistChecker {

    /** 待检查的请求上下文。 */
    public record RequestContext(String userId, String deviceId, String ip) {}

    /** 检查结果。 */
    public record CheckResult(boolean hit, String blacklistType, String targetId) {}

    private final JedisPool jedisPool;

    public BlacklistChecker(JedisPool jedisPool) {
        this.jedisPool = jedisPool;
    }

    /**
     * 检查请求是否命中黑名单。
     *
     * 命中任意一个目标即认为命中,返回最先命中的那一条,便于定位拦截原因。
     */
    public CheckResult check(RequestContext context) {
        List<String> keys = buildKeys(context);
        if (keys.isEmpty()) {
            return new CheckResult(false, null, null);
        }

        try (Jedis jedis = jedisPool.getResource()) {
            Pipeline pipeline = jedis.pipelined();
            List<Response<Boolean>> responses = new ArrayList<>(keys.size());
            for (String key : keys) {
                responses.add(pipeline.sismember(key, "1"));
            }
            pipeline.sync();

            for (int i = 0; i < keys.size(); i++) {
                if (Boolean.TRUE.equals(responses.get(i).get())) {
                    return new CheckResult(true, typeOf(keys.get(i)), targetOf(keys.get(i)));
                }
            }
            return new CheckResult(false, null, null);
        } catch (Exception e) {
            // 检查链路异常时不能阻断主流程,记录后放行,由后续限流兜底
            return new CheckResult(false, null, null);
        }
    }

    /**
     * 构造本次请求需要检查的所有 key。
     *
     * IP 网段按前缀由粗到细逐级匹配,最多检查有限个前缀。
     */
    private List<String> buildKeys(RequestContext context) {
        List<String> keys = new ArrayList<>(7);
        if (context.userId() != null) {
            keys.add("bl:temp:user:" + context.userId());
            keys.add("bl:perm:user:" + context.userId());
        }
        if (context.deviceId() != null) {
            keys.add("bl:temp:device:" + context.deviceId());
            keys.add("bl:perm:device:" + context.deviceId());
        }
        if (context.ip() != null) {
            keys.add("bl:temp:ip:" + context.ip());
            keys.add("bl:perm:ip:" + context.ip());
            // 只做有限层级的网段匹配,避免前缀数量膨胀
            keys.add("bl:temp:ip:cidr:" + networkPrefix(context.ip(), 24));
        }
        return keys;
    }

    /**
     * 取 IPv4 地址的前若干段作为网段前缀。
     */
    private String networkPrefix(String ip, int bits) {
        String[] parts = ip.split("\\.");
        int keep = Math.max(1, Math.min(bits / 8, parts.length));
        StringBuilder sb = new StringBuilder();
        for (int i = 0; i < keep; i++) {
            if (i > 0) {
                sb.append('.');
            }
            sb.append(parts[i]);
        }
        sb.append(".0/").append(keep * 8);
        return sb.toString();
    }

    private String typeOf(String key) {
        if (key.contains(":user:")) {
            return "user";
        }
        if (key.contains(":device:")) {
            return "device";
        }
        return "ip";
    }

    private String targetOf(String key) {
        return key.substring(key.lastIndexOf(':') + 1);
    }
}

实现上的三个要点:

  • 一次 Pipeline 完成全部判定。一次请求要检查用户、设备、IP 三类目标,如果逐个 SISMEMBER,就是三次网络往返。用 Pipeline 把它们打包成一次请求,判定延迟能降到接近单次往返的水平。Pipeline 不是原子操作,但对「只读判定」这个场景来说完全够用。
  • 异常必须放行。Redis 不可用时返回「未命中」而不是抛异常。理由是黑名单检查属于风控增强手段,不能因为它挂了就把整个业务链路拖垮;真正的兜底应该由限流和异常检测来承担。但要记录日志并告警,否则会出现「黑名单形同虚设却没人知道」的情况。
  • 负缓存防止穿透。如果攻击者用大量不存在的用户 ID 发起请求,每次都会打到数据库。给未命中的查询也加一个短 TTL 的负缓存,可以让重复的无效查询不再回源。

四、黑名单管理

4.1 添加黑名单

添加操作要保证持久化与缓存一致,并且全程可审计。推荐的执行顺序是:先写 MySQL,再写 Redis,最后发审计事件。

import java.time.Duration;
import java.time.Instant;
import java.util.Map;

/**
 * 黑名单管理服务。
 */
public class BlacklistService {

    /** 黑名单类型。 */
    public enum TargetType { USER, DEVICE, IP, CONTENT }

    /** 添加请求。 */
    public record AddRequest(
            TargetType type,
            String targetId,
            String reason,
            String source,
            String evidence,
            Instant expiresAt
    ) {}

    private final BlacklistRepository repository;
    private final JedisPool jedisPool;
    private final AuditPublisher auditPublisher;

    public BlacklistService(
            BlacklistRepository repository,
            JedisPool jedisPool,
            AuditPublisher auditPublisher) {
        this.repository = repository;
        this.jedisPool = jedisPool;
        this.auditPublisher = auditPublisher;
    }

    /**
     * 添加一条黑名单记录。
     *
     * @return 新记录的 ID
     */
    public long add(AddRequest request) {
        validate(request);

        // 第一步:先落库,保证即使后续步骤失败也能通过定时任务补齐缓存
        long id = repository.insert(
                request.type().name().toLowerCase(),
                request.targetId(),
                request.reason(),
                request.source(),
                request.evidence(),
                request.expiresAt()
        );

        // 第二步:写入 Redis 供在线检查
        writeToCache(request);

        // 第三步:发布审计事件,供下游同步与追溯
        auditPublisher.publish("blacklist.added", id, request);

        return id;
    }

    /**
     * 校验添加请求。
     */
    private void validate(AddRequest request) {
        if (request.targetId() == null || request.targetId().isBlank()) {
            throw new IllegalArgumentException("目标标识不能为空");
        }
        if (request.reason() == null || request.reason().isBlank()) {
            throw new IllegalArgumentException("封禁原因不能为空");
        }
        // 证据是申诉和复核的依据,不允许为空
        if (request.evidence() == null || request.evidence().isBlank()) {
            throw new IllegalArgumentException("必须提供判定证据");
        }
        if (request.expiresAt() != null && request.expiresAt().isBefore(Instant.now())) {
            throw new IllegalArgumentException("过期时间不能早于当前时刻");
        }
    }

    /**
     * 写入 Redis。永久条目与临时条目分开存放。
     */
    private void writeToCache(AddRequest request) {
        String typeKey = request.type().name().toLowerCase();
        boolean permanent = request.expiresAt() == null;

        try (Jedis jedis = jedisPool.getResource()) {
            String key = (permanent ? "bl:perm:" : "bl:temp:") + typeKey + ":" + request.targetId();
            jedis.sadd(key, "1");
            if (!permanent) {
                long ttl = Duration.between(Instant.now(), request.expiresAt()).getSeconds();
                jedis.expire(key, Math.max(ttl, 1));
            }
            // 元信息单独存放,热路径不会读取
            jedis.hset(
                    "bl:meta:" + typeKey + ":" + request.targetId(),
                    Map.of(
                            "reason", request.reason(),
                            "source", request.source(),
                            "evidence", request.evidence(),
                            "created_at", Instant.now().toString(),
                            "expires_at", request.expiresAt() == null ? "permanent" : request.expiresAt().toString()
                    )
            );
        }
    }
}

为什么是「先落库再写缓存」:

  • 如果先写缓存再落库,落库失败时缓存里就留下了一条没有持久化记录的黑名单。这条记录没有证据、没有来源、也没有过期时间,既无法审计,也无法通过定时清理回收,最终变成一条永久且无法解释的封禁。
  • 先落库则相反:即使写缓存失败,数据库里还有记录,可以由定时任务补偿。缓存永远可以从数据库重建,数据库是唯一的事实来源。

几个必须校验的字段:

  • 原因和证据不能为空。没有证据的封禁既无法通过申诉,也无法在事后复盘时被证明是合理的。
  • 过期时间不能是过去。写入一个已经过期的时间,等于立即失效,但数据库里会留下一条「曾经封禁过」的记录,污染统计。

4.2 解除黑名单

解除操作与添加操作的差别在于语义:添加是新增一条记录,解除是让某条记录失效。

/**
 * 解除黑名单。
 *
 * 注意:数据库记录不做物理删除,只标记为已解除,保留审计痕迹。
 */
public long remove(TargetType type, String targetId, String operator) {
    validateExists(type, targetId);

    // 先从 Redis 移除,保证在线检查立即生效
    deleteFromCache(type, targetId);

    // 再更新数据库状态,保留记录用于审计
    repository.markRevoked(type.name().toLowerCase(), targetId, operator, Instant.now());

    auditPublisher.publish("blacklist.removed", 0,
            new AddRequest(type, targetId, "手动解除", "manual", operator, null));

    return 0;
}

/**
 * 从 Redis 中移除黑名单元数据。
 */
private void deleteFromCache(TargetType type, String targetId) {
    String typeKey = type.name().toLowerCase();
    try (Jedis jedis = jedisPool.getResource()) {
        // 临时与永久两个 key 都要删,漏删会导致解封不生效
        jedis.del("bl:temp:" + typeKey + ":" + targetId);
        jedis.del("bl:perm:" + typeKey + ":" + targetId);
        jedis.del("bl:meta:" + typeKey + ":" + targetId);
    }
}

解除操作有三个容易忽略的细节:

  1. 临时和永久两个 key 都要删除。添加时永久和临时条目分开存放,如果解除时只删其中一个,另一份仍然会拦截请求。这是解封不生效最常见的原因。
  2. 元信息也要清理。bl:meta 里的记录如果留着,会让后台显示「该目标已被封禁」,但实际已经解封,造成运营误判。
  3. 数据库记录不物理删除。把状态改成「已解除」并记录操作人和时间,既保留了完整的处置历史,也能在事后统计「这个账号被封了多少次」,辅助判断处置力度是否过重。

解封后的处理策略要区别对待:

情形处理方式
误封(检测规则误判)直接解除,并记录误判原因用于优化规则
轻度违规到期自动解除,不做额外标记
严重违规申诉通过解除并下调该目标的信任分,让后续行为在评分中略微降权
作弊设备被重置解除账号级封禁,但保留设备级封禁

最后一条尤其重要:设备黑名单往往是唯一能防住「换个账号继续刷」的防线,解除账号封禁时不应连带解除设备封禁。

4.3 批量操作

批量场景很常见:一次性导入一批已确认的黑产设备、或者在发现大规模攻击后快速拉黑一批 IP。批量操作的核心要求是分片处理、可中断、可核对。

import java.time.Duration;
import java.time.Instant;
import java.util.List;
import java.util.Map;

/**
 * 批量拉黑。
 */
public int batchAdd(List<AddRequest> requests, int batchSize) {
    if (requests.isEmpty()) {
        return 0;
    }

    int success = 0;
    int failed = 0;

    // 按批次处理,避免一次性写入过多导致 Redis 阻塞
    for (int offset = 0; offset < requests.size(); offset += batchSize) {
        List<AddRequest> batch = requests.subList(
                offset, Math.min(offset + batchSize, requests.size()));

        try (Jedis jedis = jedisPool.getResource()) {
            Pipeline pipeline = jedis.pipelined();

            for (AddRequest request : batch) {
                validate(request);
                String typeKey = request.type().name().toLowerCase();
                boolean permanent = request.expiresAt() == null;
                String key = (permanent ? "bl:perm:" : "bl:temp:") + typeKey + ":" + request.targetId();

                pipeline.sadd(key, "1");
                if (!permanent) {
                    long ttl = Duration.between(Instant.now(), request.expiresAt()).getSeconds();
                    pipeline.expire(key, Math.max(ttl, 1));
                }
                pipeline.hset("bl:meta:" + typeKey + ":" + request.targetId(),
                        Map.of("reason", request.reason(),
                               "source", request.source(),
                               "evidence", request.evidence(),
                               "created_at", Instant.now().toString(),
                               "expires_at", request.expiresAt() == null ? "permanent" : request.expiresAt().toString()));
                success++;
            }
            pipeline.sync();
        } catch (Exception e) {
            // 单批失败不影响其他批次,失败条目单独记录以便重试
            failed += batch.size();
            logBatchFailure(batch, e);
        }
    }

    auditPublisher.publish("blacklist.batch_added", success, requests.size());
    return success;
}

批量操作的几条纪律:

  • 分批大小要有上限。Pipeline 里塞进几万条命令,会让 Redis 单线程处理过久,阻塞其他请求。批大小建议控制在千级以内,具体取决于单条命令的复杂度和 Redis 的配置。
  • 批量导入应该走异步任务。几十上百条可以同步处理,几万条必须改成异步任务加进度查询,否则请求会超时。
  • 导入前先做格式校验和去重。批量文件里重复的目标、格式错误的目标,要在下线前清理掉。校验失败要在导入报告里逐条列出,而不是静默跳过。
  • 提供 dry-run 模式。先只做校验并输出将要执行的变更摘要,由人工确认后再真正执行。
  • 保留导入批次号。每批操作生成一个批次号,Redis 里的元信息和审计日志都带上这个批次号。出现误操作时,可以按批次号精确回滚,而不是全量清空黑名单。

批量解除的逻辑与批量添加对称,同样需要分批和批次号。

五、过期清理机制

5.1 定时清理任务

定时清理要解决两件事:释放过期条目占用的内存、让数据库与缓存保持一致。

import java.time.Duration;
import java.time.Instant;
import java.util.List;
import java.util.Set;

/**
 * 黑名单定时清理任务。
 */
public class BlacklistCleanupJob {

    /** 单次扫描处理的最大 key 数量,避免一次任务占用过久。 */
    private static final int SCAN_BATCH = 500;

    /** 单次任务的处理时长上限(毫秒)。 */
    private static final long TIME_BUDGET_MILLIS = 2000L;

    private final JedisPool jedisPool;
    private final BlacklistRepository repository;

    public BlacklistCleanupJob(JedisPool jedisPool, BlacklistRepository repository) {
        this.jedisPool = jedisPool;
        this.repository = repository;
    }

    /**
     * 清理已过期的临时黑名单。
     *
     * 使用 SCAN 而不是 KEYS:KEYS 会阻塞 Redis 单线程,
     * 在生产环境上是不可接受的。
     */
    public CleanupReport cleanupExpired() {
        long start = System.currentTimeMillis();
        int scanned = 0;
        int removed = 0;

        try (Jedis jedis = jedisPool.getResource()) {
            String cursor = "0";
            do {
                // 每次只取一小批,控制单次处理时长
                ScanResult<String> result = jedis.scan(cursor, Set.of("bl:temp:*"), SCAN_BATCH);
                cursor = result.getCursor();

                for (String key : result.getKey()) {
                    scanned++;
                    Long ttl = jedis.ttl(key);
                    // TTL 为 -2 表示 key 已不存在,为 -1 表示没有设置过期时间
                    if (ttl != null && ttl == -1) {
                        // 临时条目却永久不过期,说明写入时漏设 TTL,清理掉
                        jedis.del(key);
                        removed++;
                    }
                    if (System.currentTimeMillis() - start > TIME_BUDGET_MILLIS) {
                        return new CleanupReport(scanned, removed, true, cursor);
                    }
                }
            } while (!"0".equals(cursor));
        }

        return new CleanupReport(scanned, removed, false, "0");
    }

    /**
     * 缓存补偿:把数据库中已生效但缓存缺失的记录补回 Redis。
     *
     * 写缓存失败、Redis 重启等场景都会造成缓存与数据库不一致,
     * 这个任务负责把差异抹平。
     */
    public int reconcile(List<BlacklistRecord> activeRecords) {
        int restored = 0;
        try (Jedis jedis = jedisPool.getResource()) {
            for (BlacklistRecord record : activeRecords) {
                String key = "bl:temp:" + record.type() + ":" + record.targetId();
                if (!jedis.sismember(key, "1")) {
                    jedis.sadd(key, "1");
                    if (record.expiresAt() != null) {
                        long ttl = Duration.between(Instant.now(), record.expiresAt()).getSeconds();
                        jedis.expire(key, Math.max(ttl, 1));
                    }
                    restored++;
                }
            }
        }
        return restored;
    }
}

清理任务的三个设计点:

  • 必须用 SCAN 而不是 KEYS。KEYS 是 O(N) 且会阻塞 Redis 单线程,在生产环境执行一次可能造成数秒的服务停顿。SCAN 是增量式的,每次只返回一部分结果,可以安全地在生产运行。
  • 设置单次任务的时长上限。清理可能涉及上百万个 key,一次跑完会占用连接和 CPU。设置时间预算,超时就退出并把游标保存下来,下次任务接着扫。游标要持久化,否则每次任务都从头开始,永远扫不完。
  • 清理任务同时承担缓存补偿职责。数据库里记着有效封禁、缓存里却没有,说明写缓存那一步失败了。补偿任务按数据库记录逐条核对,把缺失的补回 Redis。这一步同时也是对「先落库再写缓存」策略的兜底保障。

清理任务的执行频率建议按黑名单规模来定:条目少的时候几分钟一次足够,条目多的时候可以拉长间隔,或者拆成多个分片任务并行执行。

5.2 惰性清理

除了定时清理,还可以在查询时进行惰性清理:

定时清理是主动的——任务跑起来,把该删的删掉。惰性清理是被动的——条目在被读到的时候,顺手判断它是否已经失效,失效就当场删掉。两者不是二选一,而是互补的:定时清理保证内存不会无限膨胀,惰性清理保证「已过期的条目不会继续生效」。

为什么两者都需要:

场景只有定时清理只有惰性清理两者结合
过期条目仍在生效取决于任务间隔,最长一个周期立即失效立即失效
无人访问的冷条目靠定时任务回收永远不回收,内存持续增长定时任务回收
定时任务故障过期条目全部继续生效影响有限影响有限,可告警
资源消耗集中在大批量扫描时摊薄到每次查询平滑

惰性清理要清理的不只是黑名单 key。临时条目靠 TTL 自动过期,但元信息 bl:meta 是一个 Hash,没有 TTL,也不会自动消失——它才是真正的内存泄漏点。另外还有一类异常:临时条目在写入时漏设了 TTL(代码缺陷或异常中断),这类条目既不会自动过期,也不会被定时任务按预期回收,只能靠惰性清理兜住。

实现的关键是在读路径上做一次廉价的额外判断,而不是额外发起一轮查询。EXPIRESAT(Redis 6.0+)可以在一次往返内同时拿到 TTL 和成员判断结果:

# EXPIRESAT 一次往返返回:成员是否存在、剩余 TTL、绝对过期时间戳
EXPIRESAT bl:temp:user:10086
# 1) "1"          —— 成员存在
# 2) (integer) 2592000   —— 剩余秒数
# 3) (integer) 1777622400 —— 绝对过期时间
import java.time.Instant;
import java.util.List;
import java.util.Map;

/**
 * 带惰性清理的黑名单检查服务。
 *
 * 在原有检查逻辑上增加一步:读到元信息时顺便判断条目是否已过期,
 * 过期则当场删除黑名单 key 与元信息。
 *
 * 这样做的代价是每个命中条目多一次 DEL,
 * 换来的是过期条目永远不会继续生效,也不依赖定时任务是否按时跑。
 */
public class LazyCleanupBlacklistChecker extends BlacklistChecker {

    /** 允许元信息提前过期的宽限期(秒)。 */
    private static final long GRACE_PERIOD_SECONDS = 60L;

    private final JedisPool jedisPool;

    public LazyCleanupBlacklistChecker(JedisPool jedisPool) {
        super(jedisPool);
        this.jedisPool = jedisPool;
    }

    /**
     * 惰性清理:判断一个目标是否已经失效,失效则删除并返回 true。
     *
     * @return true 表示该条目已过期并被清理
     */
    public boolean evictIfExpired(String type, String targetId) {
        String metaKey = "bl:meta:" + type + ":" + targetId;

        try (Jedis jedis = jedisPool.getResource()) {
            Map<String, String> meta = jedis.hgetAll(metaKey);
            if (meta.isEmpty()) {
                // 元信息不存在,条目本身大概率也已失效,一并清掉残留 key
                jedis.del("bl:temp:" + type + ":" + targetId);
                jedis.del("bl:perm:" + type + ":" + targetId);
                return true;
            }

            String expiresAt = meta.get("expires_at");
            if (expiresAt == null || "permanent".equals(expiresAt)) {
                // 永久条目不参与过期判断
                return false;
            }

            long expireAtMillis = Instant.parse(expiresAt).toEpochMilli();
            long now = System.currentTimeMillis();

            // 留一段宽限期,避免时钟偏差导致条目提前失效
            if (now - GRACE_PERIOD_SECONDS * 1000 < expireAtMillis) {
                return false;
            }

            // 过期条目:先删元信息,再删黑名单 key
            // 顺序不能反,先删 key 会让在线检查在元信息还在时失去依据
            jedis.del(metaKey);
            jedis.del("bl:temp:" + type + ":" + targetId);
            jedis.del("bl:perm:" + type + ":" + targetId);
            return true;
        } catch (Exception e) {
            // 清理失败不能影响主流程,记录后放行
            logCleanupFailure(type, targetId, e);
            return false;
        }
    }

    /**
     * 查询时顺带做惰性清理。
     *
     * 只对命中的条目做清理——未命中的条目本来就不占用在线判定成本,
     * 而元信息的清理可以交给定时任务兜底。
     */
    public CheckResult checkAndCleanup(RequestContext context) {
        CheckResult result = check(context);
        if (result.hit()) {
            evictIfExpired(result.blacklistType(), result.targetId());
        }
        return result;
    }
}

几个需要注意的地方:

  • 惰性清理只能清理「被访问到」的条目。一个封禁了 30 天、这 30 天里没人碰过的条目,惰性清理永远碰不到它。这类条目的回收仍然只能靠定时任务。这也是为什么两个机制不能互相替代。
  • 宽限期是必需的。分布式环境下多台机器的时钟不完全同步,没有宽限期的话,一台时钟稍快的机器可能提前删掉一个还没到期的封禁,造成「解封」的假象。
  • 删除顺序不能颠倒。先删 bl:meta 再删黑名单 key。反过来做的话,中间存在一个极短的窗口:在线检查已经查不到黑名单 key,但元信息还在,管理后台会显示「该目标已被封禁」而实际已放行。
  • 清理失败必须放行。和黑名单检查本身一样,清理逻辑挂在主路径上,异常时不能抛给调用方。
  • 临时与永久两个 key 都要删。这与解除黑名单是同一条纪律:漏删任何一个,都会留下一个仍然生效的封禁。

推荐的组合方式:

机制清理对象触发时机兜底关系
Redis TTL临时条目的黑名单 key自动最基础的一层
惰性清理元信息、漏设 TTL 的异常条目查询时兜住 TTL 覆盖不到的部分
定时清理全量扫描,冷条目与异常条目周期任务兜住惰性清理碰不到的条目

六、监控与告警

6.1 关键指标

黑名单系统的监控要覆盖四个层面:入口流量、判定结果、存储健康和运营处置。只看其中一层都会漏掉问题——比如入口流量平稳但误封激增,只看流量是发现不了的。

指标说明采集方式关注点
检查请求量每秒进入黑名单检查的请求数埋点计数突增通常意味着有攻击流量
命中率命中黑名单的请求占比命中数 / 检查数持续上升可能是策略过严或出现大规模攻击
目标维度分布命中中用户、设备、IP 各自占比按类型分组计数某一维度占比畸高说明该维度规则需要调整
误封申诉率用户申诉中判定为误封的比例申诉工单统计最直接的策略质量指标
缓存命中率Redis 命中 / 总查询客户端埋点命中率过低说明负缓存或 TTL 设置有问题
缓存与库差异数库中有效但缓存缺失的条数补偿任务统计持续大于 0 说明写入链路有故障
存储占用黑名单占用的内存Redis 内存指标增长过快说明清理任务没跟上
清理任务时长单次清理耗时与是否超时任务监控频繁超时说明数据量已超出当前清理能力
批量操作成功率批量导入成功与失败的条数任务报告失败条目需要人工重试
封禁时长分布各类封禁的时长分布数据库统计用于校准封禁力度是否过重

几个指标的解读要点:

  • 命中率要结合流量一起看。命中率单独看没有意义,必须结合绝对量。命中率从 0.1% 涨到 1% 看起来很严重,但如果这 1% 全部来自一次已知的大规模攻击并且已被妥善处置,那就是系统在正常工作。
  • 误封申诉率是滞后指标。用户不一定都会申诉,因此申诉率会低估真实误封率。它的价值在于趋势:一旦持续上升,说明阈值或规则需要调整了。
  • 缓存与库差异数应该是 0。这个指标不为 0 就意味着有封禁没有生效,属于功能性故障,应该配置成强告警。
  • 存储占用要画趋势而不是看绝对值。黑名单的正常增长是线性的,突然的曲线抬升往往对应一次批量导入或一次攻击事件。

告警的分级建议:

级别触发条件响应动作
P0缓存与库差异数大于 0 持续超过一个补偿周期立即排查写入链路
P1误封申诉率环比大幅上升当天复核阈值与最近上线的规则
P1命中率绝对值突破上限确认是否为攻击流量,必要时启用应急封禁
P2清理任务连续超时扩容清理任务或调整分片
P2单个维度命中占比畸高检查该维度的规则配置

6.2 告警规则

配置要点

  • 配置表达的是环境差异和运行参数,不是业务规则本身。
  • 队列、缓存、存储和服务参数决定系统在高峰期的缓冲能力。

七、最佳实践

7.1 分级封禁策略

级别适用场景用户感知解封方式
soft轻度违规部分功能受限自动/手动
hard严重作弊完全无法使用申诉审核
shadow疑似作弊无感知,内容不可见自动观察

7.2 封禁时长建议

违规类型首次二次三次
轻度灌水1 小时24 小时7 天
恶意刷榜7 天30 天永久
黑产设备永久--
恶意攻击永久--

7.3 注意事项

  1. 避免误伤:封禁前应有充分证据,支持申诉机制
  2. 灰度发布:大规模封禁应分批执行,观察影响
  3. 审计日志:所有操作必须记录,便于追溯
  4. 权限控制:封禁操作需要相应权限,避免滥用
  5. 定期审查:定期审查黑名单,清理无效记录

八、总结

黑名单机制是热排行系统反作弊的重要防线。通过合理设计黑名单类型、存储架构和检查流程,可以有效拦截恶意行为。同时,完善的管理体系和监控告警机制能够确保黑名单系统的稳定运行。

在实际应用中,黑名单机制应与限流、行为分析、机器学习等其他反作弊手段配合使用,形成多层次、立体化的防护体系。

发现内容有问题?

告诉我们哪里需要改进。