基于Nginx、Lua与Redis实现API请求黑名单过滤
在现代Web架构中，API接口的安全性和访问控制至关重要。本文将详细介绍如何结合Nginx作为高性能反向代理服务器、Lua脚本的灵活编程能力以及Redis的高速数据存储特性，共同构建一个针对特定GET请求API的黑名单过滤系统。该系统能够实时检查请求的客户端IP地址以及URI参数（如IMSI、电话号码等），并拒绝不符合安全策略的非法请求，从而提升API的防护能力。
一、系统设计思路
本方案旨在为特定API路径（例如：/api/v1/data/**）提供访问控制。核心需求包括：
- 所有针对该路径的请求必须是GET方法。
- 根据请求的客户端IP地址、URI参数中的
imsi和tel字段，过滤并拒绝黑名单中的请求。 - 对于被拒绝的请求，返回标准HTTP 403 Forbidden状态码。
实现方式是利用Nginx的access_by_lua_file指令在请求进入后端服务之前执行Lua脚本。Lua脚本负责连接Redis数据库，查询黑名单列表，并根据检查结果决定是否放行请求。
二、具体实现
1. Lua访问控制脚本
以下Lua脚本（例如：/etc/nginx/lua_scripts/api_blacklist_filter.lua）实现了黑名单逻辑。它会获取客户端IP和GET请求参数，并查询Redis中的黑名单集合。
-- api_blacklist_filter.lua 脚本路径：/etc/nginx/lua_scripts/api_blacklist_filter.lua
-- 引入 OpenResty 核心 API
local ngx_req = ngx.req
local ngx_var = ngx.var
local ngx_exit = ngx.exit
local ngx_HTTP_FORBIDDEN = ngx.HTTP_FORBIDDEN
local ngx_HTTP_INTERNAL_SERVER_ERROR = ngx.HTTP_INTERNAL_SERVER_ERROR
local ngx_log = ngx.log
local ngx_ERR = ngx.ERR
-- 引入 resty.redis 库用于 Redis 操作
local redis = require "resty.redis"
-- 读取请求体。在 access_by_lua_file 阶段，即使是 GET 请求，
-- 预读请求体也是安全的，且对于需要解析 POST body 的场景是必要的。
ngx_req.read_body()
-- 辅助函数：获取客户端真实IP地址
-- 优先从 X-Real-IP 和 X-Forwarded-For 头获取，最后使用 remote_addr
local function get_client_ip_address()
local ip = ngx_req.get_headers()["X-Real-IP"]
if not ip then
ip = ngx_req.get_headers()["X-Forwarded-For"]
end
if not ip then
ip = ngx_var.remote_addr
end
return ip
end
local current_client_ip = get_client_ip_address()
local request_path = ngx_var.uri
-- 针对特定API路径进行检查，例如 /api/v1/data/
if ngx.re.match(request_path, "^(/api/v1/data/).*$", "ijo") then
local http_request_method = ngx_var.request_method
-- 强制要求请求方法必须是 GET
if http_request_method ~= 'GET' then
ngx_log(ngx_ERR, "API path '", request_path, "' only allows GET requests. Received: ", http_request_method)
ngx_exit(ngx_HTTP_FORBIDDEN) -- 返回 403 错误
end
-- 尝试连接 Redis 数据库
local redis_client, err = redis.new()
if not redis_client then
ngx_log(ngx_ERR, "Failed to instantiate redis client: ", err)
ngx_exit(ngx_HTTP_INTERNAL_SERVER_ERROR)
end
local connect_ok, connect_err = redis_client.connect(redis_client, '127.0.0.1', 6379)
if not connect_ok then
ngx_log(ngx_ERR, "Failed to connect to Redis server: ", connect_err)
ngx_exit(ngx_HTTP_INTERNAL_SERVER_ERROR)
end
-- 获取 GET 请求的 URI 参数
local query_params = ngx_req.get_uri_args()
local request_imsi = query_params.imsi
local request_tel = query_params.tel
local is_ip_on_blacklist = false
local is_imsi_on_blacklist = false
local is_tel_on_blacklist = false
-- 检查客户端IP是否在黑名单中
if current_client_ip then
local res, redis_err = redis_client:sismember('api:blacklist:ips', current_client_ip)
if res == 1 then
is_ip_on_blacklist = true
elseif not res then
ngx_log(ngx_ERR, "Redis sismember 'api:blacklist:ips' error: ", redis_err)
end
end
-- 检查 IMSI 参数是否在黑名单中
if request_imsi then
local res, redis_err = redis_client:sismember('api:blacklist:imsis', request_imsi)
if res == 1 then
is_imsi_on_blacklist = true
elseif not res then
ngx_log(ngx_ERR, "Redis sismember 'api:blacklist:imsis' error: ", redis_err)
end
end
-- 检查电话号码参数是否在黑名单中
if request_tel then
local res, redis_err = redis_client:sismember('api:blacklist:tels', request_tel)
if res == 1 then
is_tel_on_blacklist = true
elseif not res then
ngx_log(ngx_ERR, "Redis sismember 'api:blacklist:tels' error: ", redis_err)
end
end
-- 尝试将 Redis 连接放回连接池
local keepalive_ok, keepalive_err = redis_client:set_keepalive(10000, 100) -- 10秒超时，100个空闲连接
if not keepalive_ok then
ngx_log(ngx_ERR, "Failed to set Redis keepalive: ", keepalive_err)
end
-- 如果任何一个黑名单条件被触发，则拒绝请求
if is_ip_on_blacklist or is_imsi_on_blacklist or is_tel_on_blacklist then
ngx_log(ngx_ERR, "Request blocked by blacklist: IP=", current_client_ip, ", IMSI=", request_imsi, ", TEL=", request_tel)
ngx_exit(ngx_HTTP_FORBIDDEN) -- 返回 403 错误
end
-- 如果所有检查通过，则请求继续处理
-- ngx.log(ngx_INFO, "Request passed blacklist check.")
end
2. Nginx服务器配置
在Nginx的server块中，为目标API路径配置一个location指令，并使用access_by_lua_file来引入上述Lua脚本。当请求匹配到此location时，Lua脚本将在请求实际处理前执行，从而实现访问控制。
# Nginx 配置文件示例 (通常位于 /etc/nginx/nginx.conf 或 /etc/nginx/conf.d/default.conf)
server {
listen 80;
server_name api.example.com; # 您的API域名
# 默认根目录，可根据实际情况调整
root /usr/share/nginx/html;
index index.html index.htm;
# 配置针对 /api/v1/data/ 路径的访问控制
location ~ ^/api/v1/data/ {
# 引入 Lua 脚本进行访问控制
access_by_lua_file /etc/nginx/lua_scripts/api_blacklist_filter.lua;
# Lua脚本通过后，请求将被放行到此处的逻辑。
# 这里仅为示例，在生产环境中通常会反向代理到后端服务。
default_type 'text/plain';
content_by_lua '{"message": "API请求已通过安全检查。" }';
}
# 其他静态文件、日志等配置
location / {
# 默认处理，例如提供静态内容或重定向
}
error_page 500 502 503 504 /50x.html;
location = /50x.html {
root /usr/share/nginx/html;
}
access_log /var/log/nginx/api.example.com_access.log;
error_log /var/log/nginx/api.example.com_error.log warn;
}
修改Nginx配置后，请务必重新加载Nginx服务以使配置生效：
sudo nginx -t # 检查配置语法
sudo nginx -s reload # 重新加载Nginx服务
3. Redis黑名单数据管理
使用redis-cli工具向Redis数据库中添加黑名单数据。我们创建了三个Redis Set来分别存储黑名单IP、IMSI和电话号码。
# 连接到 Redis 服务器
redis-cli -h 127.0.0.1 -p 6379
# 添加黑名单IP地址
SADD api:blacklist:ips "192.168.1.100"
SADD api:blacklist:ips "10.0.0.5"
SADD api:blacklist:ips "203.0.113.42" # 示例IP
# 添加黑名单IMSI号码
SADD api:blacklist:imsis "460001234567890"
SADD api:blacklist:imsis "460029876543210"
# 添加黑名单电话号码
SADD api:blacklist:tels "13800138000"
SADD api:blacklist:tels "13912345678"
# 验证黑名单成员列表
SMEMBERS api:blacklist:ips
SMEMBERS api:blacklist:imsis
SMEMBERS api:blacklist:tels
# 移除黑名单成员 (示例，如果需要解除某个黑名单项)
SREM api:blacklist:ips "192.168.1.100"
4. 功能验证
通过curl命令行工具或浏览器访问Nginx代理的API接口，验证黑名单功能是否按预期工作。
a. 测试非GET请求
发送一个POST请求到API路径，预期被拒绝并返回403状态码。
curl -X POST "http://api.example.com/api/v1/data/item?id=123" -d "param=value"
# 预期输出：HTTP 403 Forbidden 错误
b. 测试黑名单IP
首先，将您的测试IP（或伪造一个X-Real-IP）添加到Redis的api:blacklist:ips集合中。然后发送GET请求，预期被拒绝并返回403状态码。
# 假设您的当前IP是 203.0.113.42，并已将其添加到黑名单
# curl "http://api.example.com/api/v1/data/user?id=1" --header "X-Real-IP: 203.0.113.42"
# 或者直接使用黑名单中的IP进行测试 (如果Nginx直接接收真实客户端IP)
curl "http://api.example.com/api/v1/data/user?id=1"
# 预期输出：HTTP 403 Forbidden 错误
c. 测试黑名单IMSI或电话号码
发送GET请求，并在URI参数中包含黑名单中的IMSI或电话号码，预期被拒绝并返回403状态码。
# 使用黑名单中的IMSI
curl "http://api.example.com/api/v1/data/info?imsi=460001234567890"
# 预期输出：HTTP 403 Forbidden 错误
# 使用黑名单中的电话号码
curl "http://api.example.com/api/v1/data/details?tel=13800138000"
# 预期输出：HTTP 403 Forbidden 错误
d. 测试正常请求
发送一个符合所有规则（GET请求，IP、IMSI、TEL均不在黑名单中）的请求，预期通过并返回Nginx配置中content_by_lua指定的内容（HTTP 200状态码）。
curl "http://api.example.com/api/v1/data/status?imsi=non_blacklisted&tel=non_blacklisted"
# 预期输出：{"message": "API请求已通过安全检查。" }，HTTP 200 OK
您可以通过检查Nginx的access_log和error_log来观察请求的处理情况和潜在的错误信息，从而更好地调试和监控黑名单系统。
