黑名单机制
黑名单机制是热排行系统反作弊体系中的核心组件之一。通过对已知恶意用户、设备、IP 地址等进行标识和拦截,可以有效防止刷榜、灌水等作弊行为对排行系统的污染。
1.1 用户黑名单
用户黑名单是最直接的封禁方式,主要针对已确认的作弊账号。
1.2 设备黑名单
设备黑名单通过设备指纹识别作弊设备,即使用户更换账号也无法绕过。
1.3 IP 黑名单
IP 黑名单用于拦截来自特定网段的恶意请求。
1.4 内容黑名单
内容黑名单用于过滤恶意内容,包括关键词、链接等。
2.1 存储架构
┌─────────────────────────────────────────────────────┐
│ 黑名单服务 │
├─────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Redis │ │ MySQL │ │ Kafka │ │
│ │ (热数据) │ │ (持久化) │ │ (审计日志) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────┘
2.2 Redis 数据结构设计
Redis 承担黑名单的在线检查职责,因此数据结构要围绕「一次请求能否在一次往返内完成判定」来设计。
需要支持四类黑名单目标(用户、设备、IP、内容),每类的取值特征和过期策略都不同:
| 类型 | 目标取值 | 特征 | 典型过期时长 |
|---|---|---|---|
| 用户 | 用户 ID | 精确匹配,数量大 | 天级到永久 |
| 设备 | 设备指纹 | 精确匹配,设备可被重置 | 天级到永久 |
| IP | IP 或网段 | 需要支持网段前缀匹配 | 小时级到天级 |
| 内容 | 内容 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);
}
}
解除操作有三个容易忽略的细节:
- 临时和永久两个 key 都要删除。添加时永久和临时条目分开存放,如果解除时只删其中一个,另一份仍然会拦截请求。这是解封不生效最常见的原因。
- 元信息也要清理。
bl:meta里的记录如果留着,会让后台显示「该目标已被封禁」,但实际已经解封,造成运营误判。 - 数据库记录不物理删除。把状态改成「已解除」并记录操作人和时间,既保留了完整的处置历史,也能在事后统计「这个账号被封了多少次」,辅助判断处置力度是否过重。
解封后的处理策略要区别对待:
| 情形 | 处理方式 |
|---|---|
| 误封(检测规则误判) | 直接解除,并记录误判原因用于优化规则 |
| 轻度违规到期 | 自动解除,不做额外标记 |
| 严重违规申诉通过 | 解除并下调该目标的信任分,让后续行为在评分中略微降权 |
| 作弊设备被重置 | 解除账号级封禁,但保留设备级封禁 |
最后一条尤其重要:设备黑名单往往是唯一能防住「换个账号继续刷」的防线,解除账号封禁时不应连带解除设备封禁。
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 注意事项
- 避免误伤:封禁前应有充分证据,支持申诉机制
- 灰度发布:大规模封禁应分批执行,观察影响
- 审计日志:所有操作必须记录,便于追溯
- 权限控制:封禁操作需要相应权限,避免滥用
- 定期审查:定期审查黑名单,清理无效记录
黑名单机制是热排行系统反作弊的重要防线。通过合理设计黑名单类型、存储架构和检查流程,可以有效拦截恶意行为。同时,完善的管理体系和监控告警机制能够确保黑名单系统的稳定运行。
在实际应用中,黑名单机制应与限流、行为分析、机器学习等其他反作弊手段配合使用,形成多层次、立体化的防护体系。
发现内容有问题?
告诉我们哪里需要改进。
