网站/应用集成IP归属地查询功能：可上线、抗流量、可解释的落地指南
结论先行：网站/应用集成IP归属地查询，核心方案为：仅在可信上游解析真实客户端IP，经标准化与过滤后，通过“本地/Redis缓存+在线API+硬超时熔断”实现查询，失败时降级展示至省/国家，全程完善状态位。
核心避坑：① 取错IP（轻信XFF、未过滤内网段）是属地不准的主要根因；② 混淆展示与风控SLA（展示允许不确定，风控需可解释、可审计、可回滚）。
落地顺序：先定功能目标→解决IP获取问题→落地查询/缓存/降级→上线验收。
一. 先定目标：展示属地 vs 业务判定
1.1 展示型（评论/发帖/资料页）
- 粒度：默认省/国家，非必要不开启城市级（争议成本高）；
- 失败策略：宁可显示“未知”/不展示，不输出错误结果；
- 优先级：稳定＞精细，允许短时间不一致、长缓存。
1.2 业务判定型（反作弊/风控/推荐）
- 定位：属地仅为辅助信号，不单独作为强身份凭证；
- 字段要求：需包含运营商/ASN/疑似代理等可解释字段及全链路状态位；
- 数据模型：必须记录“不可信/缺失/来源”，便于误杀归因。
代码要求：分别封装展示模型（少字段+display_status）、风控模型（可解释字段+ip_trust/geo_source等）。
二. 核心前提：取对真实客户端IP
核心原则：仅当RemoteAddr来自可信上游，才解析XFF/X-Real-IP；否则忽略转发头，避免伪造。
2.1 定义可信上游
可信范围：CDN回源IP段、云LB内网段、Ingress Controller网段；无法维护时，边缘层固化真实IP至受控头。
2.2 解析优先级（封装为中间件）
- RemoteAddr不在可信上游：client_ip=RemoteAddr，忽略XFF/X-Real-IP；
- RemoteAddr在可信上游：优先XFF→其次X-Real-IP→均无则回退RemoteAddr。
XFF规范：从左到右取第一个有效公网IP（过滤私网/保留段），无有效IP则回退，输出ip_public/ip_invalid状态位。
2.3 过滤与标准化
过滤范围：IPv4私网/环回/链路本地、IPv6环回/链路本地/ULA（工程层面拦截）；属地不准先核查是否传入内网段。
- IPv6：统一小写、压缩表示；
- IPv4-mapped IPv6：转换为纯IPv4后缓存/查询；
- 解析失败：标记ip_invalid=true，终止查询。
三. 查询方案选择（默认最优路径）
中小团队默认：在线API+本地/Redis两级缓存+硬超时/熔断+失败降级，无需初始搭建离线库。
3.1 在线API（优先选择）
适用：展示型属地、轻量级反作弊，QPS中低、可接受外部依赖，需丰富字段；
工程底线：必须加缓存、硬超时+熔断、支持降级。
3.2 纯在线API禁忌（触发即换方案）
- 核心交易链路（对延迟/可用性要求极高）；
- 峰值QPS高（调用成本/配额不可控）；
- 合规要求高（内控闭环、数据出境限制）。
3.3 离线库与混合方案
离线库价值：低延迟、高吞吐、内网可控；风险：更新不及时、字段不全、发布异常。
混合方案（最优）：缓存命中→直接返回；未命中→调用在线API；调用成功→异步回填缓存。
四. 接口集成（封装为线上组件）
4.1 标准化输入输出
输入：标准化后的公网client_ip；输出：结构化结果（display+risk+meta）。
- display：国家/省（默认不展示城市）；
- risk：省市/运营商/ASN/代理标记等；
- meta：ip_trust/geo_source/geo_status/latency_ms。
4.2 字段分离与批量查询
展示模型：最小化字段+display_status；风控模型：可解释字段+风险标签（借助IP数据云API提升可解释性）；城市级不轻易展示，属地不单独作为强处置依据。
批量查询：仅用于离线任务（日志回填、画像计算），不进入用户主链路。
五. 缓存与稳定性
5.1 缓存策略
Key规范：geo:v1:；两级缓存：本地LRU（热点IP）+Redis（跨实例共享）。
- TTL分层：展示型7-30天，业务判定型1-6小时，代理标签更短；
- 负缓存：invalid/reserved/no_result缓存5-30分钟（防穿透）。
5.2 稳定性四件套（顺序不可乱）
- 超时：100-300ms硬上限，超时直接降级；
- 重试：仅瞬时网络错误重试1次，不突破超时上限；
- 限流：限制服务实例到外部API的并发；
- 熔断：外部错误率/超时升高时降级，半开探测恢复。
5.3 降级策略（写死到代码）
| 侧别 | 核心降级动作 | 核心目标 |
|---|---|---|
| 展示侧 | 正常展示省/国家；超时/错误用缓存旧值或显示“未知”；不可信IP仅展示国家或不展示 | 减少争议，保障体验 |
| 风控侧 | 代理标记IP降权；不可信/失败不触发强处置，仅记录证据 | 避免误杀，确保可回滚 |
5.4 必监控指标
geo.lookup.p95/p99、geo.cache.hit_rate（本地/Redis分开）、geo.api.error_rate/timeout_rate、geo.display.success_rate、ip.trust.false_rate。
六. 上线验收
6.1 最小样本集
覆盖：家庭宽带、移动网络、企业网络、海外网络、IPv6；记录：client_ip、ip_trust、归属地结果、geo_source/geo_status。
6.2 偏差归因顺序
| 优先级 | 偏差原因 | 实操动作 |
|---|---|---|
| 1 | 取IP错误 | 核查转发头、私网过滤、IP透传，修正获取逻辑 |
| 2 | 代理/VPN/企业出口 | 标记异常，降级粒度，不做强判定 |
| 3 | 移动网络漂移/NAT | 缩短TTL，不单一强处置 |
| 4 | 数据源问题 | 更换数据源或用混合方案 |
6.3 压测与验收指标
压测：验证缓存命中开销；控制1%-10%未命中比例调用在线API，验证超时、熔断、降级。
验收硬指标：未命中路径P95在超时预算内、熔断不影响主业务、降级比例可解释。
七. 隐私与合规
- 最小化展示：默认省/国家，不展示细粒度信息；
- 最小化存储：日志不落地原始IP，确需留存则脱敏/哈希，明确保留周期；
- 权限审计：管控原始IP/归属地访问权限，做好审计；
- 第三方调用：梳理在线API数据流向，确认合同与隐私政策，跨境业务重点审核。
八. 结论：最低可上线清单
- 真实IP：可信上游解析XFF/X-Real-IP，过滤私网，统一标准化；
- 查询：优先IP数据云在线API，搭配本地/Redis两级缓存；
- 稳定性：硬超时+熔断+限流，失败降级至省/国家或不展示；
- 验收：样本集验证IP获取，压测覆盖未命中场景，监控完善；
- 合规：展示/存储最小化，明确权限与审计。
三条红线（代码注释+评审标准）：
- 代理/移动漂移导致属地偏差，城市级不做强证据；
- 无可信上游不解析XFF，边缘层固化真实IP；
- 展示/存储最小化，规避投诉与对抗风险。
