IP 归属地服务

IP 归属地服务由两个可独立配置的数据源组成：一个识别单个公网 IP，另一个把地区条件解析成 CIDR。它为会话、白名单、请求与 WAF 日志、事件中心、扫描器拦截、SSH 安全和网关可见性提供显示或规则数据。

归属结果用于辅助判断，不是精确定位，也不应成为高风险入口的唯一认证条件。

两类接口

接口	用途
IP 识别库	将单个公网 IP 转为国家、省市和运营商等信息
CIDR 地址库	提供省市列表，并把地区及运营商条件转换为规则使用的 CIDR

两个接口分别选择官方在线服务或自定义服务，可以混合使用。例如 IP 识别使用官方服务，CIDR 查询使用内网自建服务。

官方在线服务

选择“官方在线服务”后，系统使用：

• IP 识别：https://ipaddress.fnknock.cn/api/v1
• CIDR 地址库：https://cidr.fnknock.cn/api/v1

官方服务配置最少并自动维护地域数据，但 fn-knock 所在环境必须能解析域名并访问对应 HTTPS 服务。离线网络或对外访问受限时，应使用自定义服务。

自定义服务

页面推荐的兼容实现为：

服务	项目	默认填充值
IP 识别库	go-ipaddress-api	http://127.0.0.1:30661
CIDR 地址库	go-cidr-api	http://127.0.0.1:30662

在 系统设置 → 属地 选择“自定义服务”后填写服务根地址。地址必须以 http:// 或 https:// 开头，保存时会移除末尾斜杠。

如果填写的是域名根地址，例如 https://example.test，fn-knock 会自动补成 /api/v1 接口路径；如果地址已经带自定义路径，例如 https://example.test/custom/，则会直接在该路径下请求 ip/lookup、provinces 等接口。

Docker 中的 127.0.0.1 指向 fn-knock 容器本身。自建服务位于另一个容器或宿主机时，应使用同一 Docker 网络中的服务名、宿主机可达地址，或显式发布的端口。

测试和保存

“测试连接”使用当前输入值，不要求先保存：

• IP 识别测试会查询 8.8.8.8，并检查响应是否包含成功状态和识别结果；
• CIDR 测试会读取省份列表，并继续探测运营商筛选能力。

两个测试都通过后再保存。测试成功只表示接口与响应格式可用，不保证所有地址和地区数据都完整。

地区选择可按电信、联通或移动筛选 CIDR。自建 CIDR 地址库必须提供运营商数据才能使用该筛选；不支持时连接测试会提示更新地址库，但普通省市查询仍可使用。

数据如何进入页面

IP 归属查询由后台队列异步执行并缓存。首次打开会话、日志、白名单或事件详情时，可能先显示“解析中”，随后再补充属地。私网和回环地址会跳过公网归属查询。

已有记录中的属地可能来自创建时写入的数据或后续缓存回填，因此切换数据源后，不应假设所有历史记录会立即统一刷新。

验证与限制

保存后从以下位置抽查同一个公网 IP：

1. 请求日志或 WAF 日志；
2. 会话记录、白名单或通用黑名单；
3. 事件中心；
4. SSH 登录日志。

不同位置应显示一致或相近的结果。失败时检查 Base URL、协议、DNS、容器网络、TLS 证书、服务响应格式和 fn-knock 后台日志。

如果所有请求都显示为 CDN、反向代理、私网或回环地址，应先修复 真实客户端 IP，而不是调整属地数据库。

归属地数据库会滞后、IP 可能被运营商复用，地区规则也会误伤旅行、漫游或企业出口用户。将它与 CIDR、登录认证和日志观察组合使用，而不是单独作为高风险访问的唯一条件。

• 网关可见性
• SSH 安全
• 扫描器拦截