Files
CardAuth/docs/blacklist-usage.md

2.0 KiB

黑名单功能使用说明

功能概述

黑名单功能用于限制特定用户或 IP 地址访问系统。管理员可通过后台管理界面添加、启用/禁用、删除黑名单对象,系统会自动拦截处于黑名单中的请求。

访问路径

登录后台管理后,依次点击:

订单与代理 > 黑名单管理

操作说明

1. 添加黑名单

  1. 点击页面右上角「添加黑名单」按钮
  2. 在弹窗中选择目标类型:
    • 用户ID:输入用户ID,对应已注册用户
    • IP地址:输入需要拦截的IP地址
  3. (可选)设置过期时间,留空表示永久生效
  4. (可选)填写备注信息
  5. 点击「保存」

2. 批量添加

通过「导入」功能上传 CSV 文件实现批量添加。CSV 格式要求:

target_type,target_value,expire_time,remark
ip,192.168.1.100,2026-12-31 23:59:59,恶意访问
user,10086,,违规用户
  • target_type 必填,取值为 user 或 ip
  • target_value 必填
  • expire_time 可选,格式为 YYYY-MM-DD HH:mm:ss
  • remark 可选

3. 启用/禁用

在列表中找到对应记录,点击「状态」列的开关即可切换。禁用后该黑名单不再生效,但记录会保留。

4. 删除黑名单

  • 单条删除:点击行尾「删除」按钮
  • 批量删除:勾选多行后点击「批量删除」

5. 导出黑名单

勾选需要导出的记录,点击「导出 > 导出 CSV」,系统会下载包含黑名单信息的 CSV 文件。

拦截效果

当黑名单处于启用状态且未过期时:

  • 被拉黑的用户登录后将无法访问任何需要认证的接口
  • 被拉黑的 IP 发起的请求将被直接拒绝,返回 403
  • 合法用户不受影响

注意事项

  1. 黑名单查询结果有 60 秒缓存,新增/修改后可能在缓存失效前才完全生效
  2. 单次批量操作最多支持 500 条记录
  3. 导入 CSV 单次最多支持 1000 条记录
  4. 请谨慎将管理员账号或当前访问 IP 加入黑名单,避免误操作导致无法登录