IP 归属地设置
这页解决什么问题
IP 归属地设置 用来决定 fknock 从哪里查询两类数据：
IP 识别库：查询单个 IP 的国家、地区、城市和运营商CIDR 地址库：查询省市级 IP 地址段，供地区访问控制使用
路径：
系统设置 → 归属地
它会影响很多页面里的来源信息和地区选择能力，例如：
- 登录日志
- 会话管理
- 请求日志
- 事件中心
- 网关可见性
- SSH 安全
- IP 白名单
先理解两类服务
IP 识别库
负责回答：
这个 IP 大概来自哪里？
你会在这些地方看到它的结果：
- 登录记录里的来源位置
- 会话 IP 漂移轨迹
- 请求日志的客户端位置
- 事件中心里的 IP 归属地
- SSH 登录日志和封锁记录
fknock 查询自定义 IP 识别库时会请求：
GET /api/v1/ip/lookup?ip=8.8.8.8服务需要返回 code = 0，并且带有 result 字段。
CIDR 地址库
负责回答：
某个省、市对应哪些 IPv4 / IPv6 CIDR？
它主要服务于：
fknock 会用到这些接口：
GET /api/v1/provinces
GET /api/v1/provinces/{省份}/cities
GET /api/v1/cidrs?province=广东&city=深圳页面里点 测试连接 时，会先请求：
GET /api/v1/provinces服务需要返回 code = 0，并且带有 data 字段。
服务来源怎么选
两个服务都支持：
官方在线服务自定义服务
官方在线服务
适合大多数用户。
优点是：
- 不需要自己部署
- 数据源由官方服务维护
- 新手配置成本最低
默认地址是：
IP 识别库：https://ipaddress.fnknock.cn/api/v1
CIDR 地址库：https://cidr.wxlnk.com/api/v1自定义服务
适合这些场景：
- 你的设备无法稳定访问官方在线服务
- 你希望内网或离线部署
- 你有自己的 IP 数据源或合规要求
- 你希望把查询服务部署在自己控制的网络里
当前页面会提示可用的自部署服务：
go-ipaddress-apigo-cidr-api
自定义服务填写的是 Base URL，例如：
http://127.0.0.1:30661
http://127.0.0.1:30662如果你只填到端口，fknock 会自动补成 /api/v1。也就是说下面两种写法都可以：
http://127.0.0.1:30661
http://127.0.0.1:30661/api/v1保存时系统会自动去掉末尾多余的 /。
fknock 内部如何查询和缓存
IP 识别不是每次刷新页面都同步查询一次。
- 新 IP 会先进入后台队列
- 队列默认每秒检查一次
- 每批最多处理
3个 IP - 单次 IP 查询默认最多等待
8 秒 - 查询失败会重试，最多
5次 - 成功结果会缓存
7 天 - 失败状态会短暂保留约
5 分钟 - 本机、局域网、容器内网等不需要查归属地的地址会被跳过
所以你刚打开日志页面时，可能会短暂看到：
归属地解析中...归属地暂未获取
这不一定是错误，可能只是后台队列还没处理完。
CIDR 数据也会缓存。
- 省份列表
- 城市列表
- 省市 CIDR 查询结果
成功后会缓存约 30 天。如果你刚更新了自部署 CIDR 数据，但页面还显示旧结果，可以重启 fknock 或等待缓存过期后再验证。
Docker 一键部署
下面这个 Compose 会同时启动：
go-ipaddress-api：IP 识别库，端口30661go-cidr-api：CIDR 地址库，端口30662redis：给go-ipaddress-api做缓存
建议先只绑定到本机回环地址，避免把这两个辅助接口也暴露到公网。
创建一个目录，例如：
mkdir -p ~/fnknock-ip-location
cd ~/fnknock-ip-location创建 docker-compose.yml：
services:
ipaddress-api:
image: kcilnk/go-ipaddress-api:latest
container_name: fnknock-ipaddress-api
restart: unless-stopped
ports:
- "127.0.0.1:30661:30661"
environment:
- GIN_MODE=release
- SERVER__HOST=0.0.0.0
- SERVER__PORT=30661
- REDIS__HOST=redis
- REDIS__PORT=6379
- REDIS__PASSWORD=
- REDIS__DB=0
- CACHE__TTL=3600
- RATELIMIT__ENABLED=true
- RATELIMIT__REQUESTS_PER_SECOND=100
- RATELIMIT__BURST=200
- LOG__LEVEL=info
- LOG__FORMAT=json
depends_on:
redis:
condition: service_healthy
cidr-api:
image: kcilnk/go-cidr-api:latest
container_name: fnknock-cidr-api
restart: unless-stopped
ports:
- "127.0.0.1:30662:30662"
environment:
- RUN_MODE=http
- ADDR=:30662
- DATA_FILE=/app/china_city_cidrs.compact.json
redis:
image: redis:7-alpine
container_name: fnknock-iplocation-redis
restart: unless-stopped
command: redis-server --appendonly yes
volumes:
- redis-data:/data
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 5s
timeout: 3s
retries: 3
volumes:
redis-data:启动：
docker compose up -d查看状态：
docker compose ps查看日志：
docker compose logs -f验证 Docker 服务
先测 IP 识别库健康检查：
curl http://127.0.0.1:30661/health再测 IP 查询接口：
curl "http://127.0.0.1:30661/api/v1/ip/lookup?ip=8.8.8.8"成功时应能看到类似结构：
{
"code": 0,
"msg": "success",
"ip": "8.8.8.8",
"result": {
"version": "ipv4",
"country": "...",
"province": "...",
"city": "...",
"isp": "...",
"raw": "..."
}
}再测 CIDR 地址库健康检查：
curl http://127.0.0.1:30662/healthz测省份列表：
curl http://127.0.0.1:30662/api/v1/provinces测城市列表：
curl "http://127.0.0.1:30662/api/v1/provinces/广东/cities"测 CIDR 查询：
curl "http://127.0.0.1:30662/api/v1/cidrs?province=广东&city=深圳"如果这些命令都正常，再回到 fknock 后台继续配置。
在 fknock 后台怎么填写
进入：
系统设置 → 归属地
在 IP 识别库 里：
服务来源选择自定义服务Base URL填：
http://127.0.0.1:30661- 点击
测试连接
在 CIDR 地址库 里：
服务来源选择自定义服务Base URL填：
http://127.0.0.1:30662- 点击
测试连接
两个测试都成功后，点击：
保存更改
然后去这些页面验证实际效果：
- 登录日志
- 请求日志
- 事件中心
- 网关可见性
- SSH 安全
如果 fknock 自己也在 Docker 里
上面的 127.0.0.1 只适合 fknock 和自部署服务在同一个宿主机网络视角下访问。
如果 fknock 也运行在 Docker 容器里，容器内的 127.0.0.1 指的是 fknock 容器自己，不是宿主机，也不是另一个容器。
这时通常有三种处理方式：
- 把 fknock 和这两个服务放进同一个 Docker 网络
- 在 fknock 里填写服务名，例如
http://ipaddress-api:30661 - 或填写宿主机可被容器访问的地址
如果你用的是上面的 Compose，并且 fknock 也加进同一个网络，可以填写：
IP 识别库：http://ipaddress-api:30661
CIDR 地址库：http://cidr-api:30662如果 fknock 是飞牛应用形态安装，而这两个服务跑在同一台机器的 Docker 里，一般优先使用：
IP 识别库：http://127.0.0.1:30661
CIDR 地址库：http://127.0.0.1:30662如果测试失败，再改成这台机器的局域网 IP，例如：
http://192.168.1.10:30661
http://192.168.1.10:30662这种情况下，建议只在内网防火墙里允许可信来源访问这两个端口。
只部署其中一个服务可以吗
可以。
例如你只想自部署 IP 识别库：
IP 识别库选择自定义服务CIDR 地址库继续选择官方在线服务
反过来也可以。
常见组合是：
- 官方 IP 识别库 + 官方 CIDR 地址库：最省心
- 自部署 IP 识别库 + 官方 CIDR 地址库：适合只想减少 IP 查询外部依赖
- 官方 IP 识别库 + 自部署 CIDR 地址库：适合更关注地区访问控制稳定性
- 两者都自部署：适合内网、离线或私有化场景
和网关可见性的关系
网关可见性 允许你按省、市或自定义 CIDR 限制谁能碰到统一网关。
其中：
- 自定义
CIDR不依赖地区库 - 按省市选择时依赖
CIDR 地址库
所以如果你在网关可见性里遇到地区解析失败，应该回到：
系统设置 → 归属地
检查 CIDR 地址库 是否可用。
和 SSH 安全的关系
SSH 安全 也会用到这两类数据：
- 用
IP 识别库展示 SSH 登录和封锁记录的来源位置 - 用
CIDR 地址库把允许地区转换成 SSH 防火墙允许网段
如果你准备按地区限制 SSH，建议先确认归属地设置正常，再开启 SSH 安全。
常见排查思路
后台测试连接失败
优先检查：
- Docker 容器是否运行中：
docker compose ps - 端口是否映射正确：
30661和30662 - fknock 所在环境能否访问这个
Base URL - 服务地址是否以
http://或https://开头 - 如果 fknock 在 Docker 内，是否误填了
127.0.0.1
IP 识别库测试失败
fknock 测试 IP 识别库时会请求：
/api/v1/ip/lookup?ip=8.8.8.8所以优先在 fknock 所在机器上执行：
curl "http://127.0.0.1:30661/api/v1/ip/lookup?ip=8.8.8.8"如果这里不返回 code = 0 和 result，后台测试也不会成功。
CIDR 地址库测试失败
fknock 测试 CIDR 地址库时会请求：
/api/v1/provinces所以优先执行：
curl http://127.0.0.1:30662/api/v1/provinces如果省份列表能返回，再继续测：
curl "http://127.0.0.1:30662/api/v1/cidrs?province=广东&city=深圳"页面里一直显示归属地暂未获取
优先检查：
- 当前使用的是官方在线服务还是自定义服务
- 自定义服务是否能从 fknock 所在机器访问
- Redis 是否正常，因为 IP 识别库自身依赖 Redis 缓存
- 是否只是后台队列还没处理完成
- 是否查询的是本机、局域网、容器内网等会被跳过的地址
地区选择器无法解析出 CIDR
优先检查：
CIDR 地址库是否可用- 自定义服务数据是否包含目标省市
- 是否只是某个地区暂时没有全省范围，需要细化到城市
广东、浙江 会更倾向于让你细化到城市，不提供“全省”这个快捷项。
归属地和自己实际位置不完全一致
IP 归属地只能作为辅助判断。
运营商出口、代理、移动网络、云厂商线路都可能让归属地看起来和你所在城市不完全一致。涉及访问控制时，建议优先用你确认过的固定 CIDR 兜底。