解读数据
最容易误解的是，“以前观测到这个 IP”并不等于“现在仍在封禁这个 IP”。
采集是定期执行的，并非实时事件流。使用数据之前，最好先弄清楚一条观测记录代表什么、时间字段反映的是什么。
观测单位
一条观测记录是 source、jail 与 ip 的组合。若同一 IP 被两个 jail 或两个采集源检测到，则会保留为多条观测记录。
例如，同一个 IP 同时出现在 SSH 和 Nginx 的日志中，就会形成两条观测。因此观测总数不一定等于唯一 IP 数。
在统计中，observations 是观测记录数，ips 是唯一 IP 数。文本订阅源同样会对 IP 去重。
时间与状态
| 字段 | 含义 |
|---|---|
first_seen | 该采集平台首次确认此地址的时间 |
last_seen | 最后一次确认此地址的采集时间 |
active = 1 | 存在于最新快照的封禁列表中 |
active = 0 | 在后续快照中已从列表移除 |
stale = 1 | 该 jail 已超过 48 小时未被采集 |
这里记录的是采集系统看到状态的时间，不是 Fail2ban 实际执行封禁的瞬间。采集源停止更新，也不代表封禁已经解除。存在陈旧更新的 jail 会被排除在当前列表、统计和订阅源之外。通过查询接口和 active=all 可以查看过去的观测记录。
定期采集的局限
除每日生成报告外，每个采集源还会将其当前封禁列表写为 JSON。没有变化时发送基于哈希的心跳；有变化时则基于完整快照应用差异（diff）。
如果某个 IP 在两次快照之间被封禁又被解除，这套系统就不会留下记录。它不是逐条记录 Fail2ban 事件的审计日志。本 API 并不用于还原过去所有的封禁列表。记录仅从该采集平台开始观测时起存在。
国家、ASN 与组织
这些是来自 GeoIP（IP 地理位置）与 RDAP（注册数据）的附加信息。未知值为 null。国家代码与 ASN（自治系统编号）描述的是网络，不能用于判断发起请求者的国籍、居住地、隶属关系或身份。
公开的内容
公开 API 提供 IP 地址、采集源的公开标识、jail 名称、观测时间、状态以及网络附加信息。原始访问日志、请求体、账号名称、凭据以及管理用排除列表均不公开。
不要把观测数据直接导入永久封禁列表。 单条 IP 记录无法证明恶意意图；请结合检测规则与状态进行判断。共享线路与动态 IP 分配意味着，当前使用该地址的用户可能与观测时不同。
报告误报或规范问题
你可以通过 f2b-api GitHub 仓库 报告解释上的疑问或规范中的不一致之处。请勿公开凭据、原始日志或个人信息。在审核更正时，我们会区分 jail、观测时间以及问题发生的条件。