封禁列表

security.blocklist 插件从发布地址列表的地方获取需要拒绝访问的地址：威胁情报源、信誉服务、服务器之间共享的封禁列表。用户配置来源后，Nginx UI 按每个来源的刷新间隔调用插件，把结果写成 nginx deny 规则保存到自己的文件中，并在列表变化时重载 nginx。

方法	必需	用途
blocklist.fetch	是	获取一个来源当前的完整列表。

插件必须请求 network 权限。

声明来源类型

"capabilities": ["security.blocklist"],
"permissions": ["network"],
"blocklist": {
  "sources": [
    {
      "code": "threatfeed",
      "name": "ThreatFeed",
      "refresh_seconds": 900,
      "configuration": {
        "fields": [
          { "key": "api_key", "display_name": "API key", "required": true, "secret": true },
          { "key": "min_score", "type": "number", "display_name": "Minimum score", "help_text": "Only list addresses scored at least this high" }
        ]
      }
    }
  ]
}

code、name 和 configuration.fields 的用法与通知渠道相同。refresh_seconds 是该类型来源的默认刷新间隔：0 或不填表示一小时，否则至少为 60，因为变化更快的列表无法靠重载 nginx 来提供。

获取

{ "jsonrpc": "2.0", "id": 48, "method": "blocklist.fetch", "params": { "source": "threatfeed", "config": { "api_key": "key_live_xxx", "min_score": "80" } } }

回复当前的完整列表，而不是自上次调用以来的变化：

{
  "jsonrpc": "2.0", "id": 48,
  "result": {
    "entries": [
      { "cidr": "198.51.100.23", "reason": "SSH brute force" },
      { "cidr": "203.0.113.0/24", "reason": "Botnet command and control" },
      { "cidr": "2001:db8:bad::/48" }
    ],
    "ttl_seconds": 900
  }
}

字段	含义
entries[].cidr	IPv4 或 IPv6 地址，或 CIDR 网段。不含端口、区域或主机名。
entries[].reason	来源列出它的原因，仅供显示。可选。
ttl_seconds	列表的有效期。0 表示由刷新间隔决定。

每个地址只发送一次，绝不要发送覆盖所有地址的条目（0.0.0.0/0、::/0）。

警告

无法获取列表时，回复错误，绝不要回复空列表。 空列表会让 Nginx UI 不拒绝任何地址，而错误会保留当前的列表。原因在于配置（包括必填字段为空）时回复带 data.field 的 -32003，其他情况回复 -32000。绝不要把 config 的值写入日志、错误或 reason。

Nginx UI 如何处理结果

• 它把每个条目解析为地址或网段，丢弃其他条目以及覆盖所有地址的条目，并报告丢弃的数量。结果中的其他文本（包括 reason）都不会进入配置。条目会被规范化、去重、排序，并且最多保留 100000 个。

• 它把每个来源的列表写入 <nginx 配置目录>/blocklists/<来源 ID>.conf：

  # generated by nginx-ui
  deny 198.51.100.23;
  deny 203.0.113.0/24;
  deny 2001:db8:bad::/48;

• 只有文件变化时才重载 nginx，重载前先测试配置，测试失败时恢复之前的文件。获取失败时保留当前文件。

• 它从不自行把文件加入某个 server，而是向用户显示需要添加在列表生效位置的那一行：include blocklists/<来源 ID>.conf;。

Nginx UI 在来源的间隔之后再次获取；上次结果的 ttl_seconds 更短时会提前获取，但最多每分钟一次。获取失败时，在 5 分钟和间隔两者中较短的时间后重试。最近一次获取的结果显示在来源旁边。blocklist.fetch 最多等待 60 秒。