出口 IP 查询 API一行 curl 拿到服务器公网 IP免费不限次服务上云之后「我现在的出口 IP 到底是哪个」变成一个高频但琐碎的问题容器重启换了 NAT 出口、爬虫要确认代理是否生效、给第三方平台填 IP 白名单、跨机房核对回源地址……靠curl ipinfo.io这类国外站点不稳定自己写又要处理反向代理头。ip.query接口专门解决这一件事一次 GET 请求返回调用方的公网 IP免费、无业务入参、平均十几毫秒。它也可以当作接入平台后的第一个连通性测试——能返回 IP说明 Key、网络、链路都是通的。接口速览关键事实说明接口地址https://api.xujian.tech/openapi/ip/query接口编码ip.query请求方式GET无 Query 参数鉴权方式请求头X-API-Key不做签名、时间戳或加密业务入参无只需要 API Key返回核心字段ip公网 IP 标准尾字段收费方式免费FREE0 元/次仍需有效 API Key是否写流水会。写一条amount 0的流水并累加调用次数可在控制台核对单次耗时平均约 12 毫秒响应体costMs为本次真实耗时一、哪些场景需要这一步场景具体用法出口 IP 变更监控定时任务打点出口 IP 变化时立刻告警避免白名单失效第三方平台白名单给支付、短信、银行通道登记 IP 前先确认当前真实出口代理 / 代理池有效性核验走代理请求本接口返回的ip与代理 IP 一致才算生效容器与弹性伸缩核对Pod 重建、弹性扩容后核对新节点出口是否落在预期网段多机房出口清单维护各机房各打一次自动生成出口 IP 台账爬虫反封策略验证批量验证出口轮换是否按预期切换联调排障客户报「请求被拒」时先让他打一次确认他实际用的出口接入自检新环境接入平台后第一个请求验证 Key 与网络连通日志审计补充在网关日志里补一条「当时出口是什么」的记录备案与合规材料填写服务器 IP 信息时以接口返回为准避免手抄错误二、请求参数请求头参数名必填说明X-API-Key是开发者 API Key缺失或无效直接返回失败业务参数无。接口只读服务端的请求头与连接信息不接受任何 Query 或 Body 参数。IP 取值顺序排障时很有用服务端按固定顺序取 IP多级代理取逗号分隔的第一段X-Forwarded-For → X-Real-IP → Proxy-Client-IP → WL-Proxy-Client-IP → remoteAddr两个推论如果你在 Nginx / 网关后面X-Forwarded-For的第一段就是客户端真实 IP如果你自己伪造了X-Forwarded-For返回的也会是伪造值——用它不能做安全判定它只回答「服务端看到了哪个 IP」。三、返回字段3.1 顶层字段类型说明codeint0成功非 0 失败统一为500msgString成功为success失败为具体原因dataObject业务数据失败时为null3.2 data 字段字段类型示例说明ipString203.0.113.8调用方公网 IPIPv4 / IPv6 随来源而定apiCodeStringip.query接口编码apiNameString查询自己的公网IP接口名称chargeTypeStringFREE计费类型FREE/PER_CALL/MONTHLY/YEARLYbalanceBigDecimal0.0000调用后的账户余额元免费接口不扣费costMsLong3本次调用耗时毫秒四、调用示例4.1 curlcurl-shttps://api.xujian.tech/openapi/ip/query\-HX-API-Key: 你的APIKey4.2 JavaHutoolimportcn.hutool.http.HttpRequest;importcn.hutool.json.JSONObject;importcn.hutool.json.JSONUtil;publicclassIpQueryClient{privatestaticfinalStringAPI_URLhttps://api.xujian.tech/openapi/ip/query;/** * 查询本机公网出口 IP * * param apiKey 开发者 API Key * return 公网 IP失败返回 null */publicstaticStringquery(StringapiKey){JSONObjectjsonJSONUtil.parseObj(HttpRequest.get(API_URL).header(X-API-Key,apiKey).timeout(5000).execute().body());if(json.getInt(code)null||json.getInt(code)!0){System.out.println(查询失败json.getStr(msg));returnnull;}returnjson.getJSONObject(data).getStr(ip);}publicstaticvoidmain(String[]args){System.out.println(query(你的APIKey));}}4.3 Pythonimportrequestsdefpublic_ip(api_key:str):返回本机公网出口 IP失败返回 Noneresprequests.get(https://api.xujian.tech/openapi/ip/query,headers{X-API-Key:api_key},timeout5,)resultresp.json()ifresult.get(code)!0:print(查询失败,result.get(msg))returnNonereturnresult[data][ip]if__name____main__:print(public_ip(你的APIKey))4.4 JavaScriptasyncfunctionpublicIp(apiKey){constrespawaitfetch(https://api.xujian.tech/openapi/ip/query,{headers:{X-API-Key:apiKey}});constresultawaitresp.json();if(result.code!0){thrownewError(result.msg);}returnresult.data.ip;}五、返回示例成功{code:0,msg:success,data:{ip:203.0.113.8,apiCode:ip.query,apiName:查询自己的公网IP,chargeType:FREE,balance:0.0000,costMs:3}}失败缺 Key{code:500,msg:缺少请求头 X-API-Key,data:null}六、可直接复用的两段代码6.1 出口 IP 变更告警importjsonimportosimportrequests STATE_FILElast_ip.jsondefwatch(api_key:str):出口 IP 变化时打印告警可接钉钉 / 企业机器人resprequests.get(https://api.xujian.tech/openapi/ip/query,headers{X-API-Key:api_key},timeout5,).json()ifresp.get(code)!0:print(探测失败,resp.get(msg))returncurrentresp[data][ip]lastNoneifos.path.exists(STATE_FILE):lastjson.load(open(STATE_FILE,encodingutf-8)).get(ip)iflastandlast!current:print(f[告警] 出口 IP 发生变化{last}-{current})json.dump({ip:current},open(STATE_FILE,w,encodingutf-8))6.2 代理池逐个验活importrequestsdefcheck_proxy(api_key:str,proxy:str):返回的 IP 与代理 IP 一致才算这个代理真的生效try:resprequests.get(https://api.xujian.tech/openapi/ip/query,headers{X-API-Key:api_key},proxies{http:proxy,https:proxy},timeout8,).json()exceptExceptionasexc:returnproxy,False,str(exc)ifresp.get(code)!0:returnproxy,False,resp.get(msg)returnproxy,True,resp[data][ip]七、实践建议别拿它做鉴权。X-Forwarded-For可伪造接口只回答「服务端看到了什么」不做安全判定。超时设小一点。接口本身十几毫秒5 秒超时足够探测类任务更要短避免挂住探测线程。结果可以缓存。同一个出口在短时间内不会变监控场景 1 ~ 5 分钟打一次足够没必要每秒打。IPv6 场景先确认格式。返回可能是 IPv6 长串写白名单时按字符串原样落库不要假定是点分十进制。免费也要带 Key。免费接口不扣费但必须有有效的X-API-Key否则返回缺少请求头 X-API-Key。控制台能看到调用量。每次调用都会写一条amount 0的流水并累加次数可用来核对探测任务是否真的在跑。多机房要分开打。每个机房各部署一个探测点才能拿到完整的出口清单。八、错误码与排查codemsg处理建议0success调用成功500缺少请求头 X-API-Key在请求头补充X-API-Key500API Key 无效核对 Key 是否正确或在控制台重新生成500API Key 已停用在控制台重新启用该 Key500客户不存在或已停用联系平台确认账号状态500接口不存在或已停用确认ip.query当前是否维护中免费接口不会返回「余额不足」如果将来后台把收费类型改成按次才会出现余额相关错误。九、计费与接入项目说明单价免费0 元/次收费方式FREE不扣费、不扣余额流水仍写一条amount 0的流水并累加调用次数是否需要授权否有 Key 即可调用返回条数固定 1 条接入流程注册开发者账号 → 控制台创建 API Key → 请求头带上X-API-Key即可调用无需签名或加密。控制台可查看调用量、扣费流水与余额。服务站点api.xujian.tech纯文本域名不做跳转。接口试用、数据与充值咨询可在控制台提交工单或联系 Vxujian_cq。十、小结这是平台里最简单的接口没有参数、没有筛选、没有分页一次请求返回一个 IP。把它用好的关键在于把它放进自动化里——出口监控、代理验活、白名单核对、接入自检都是「每天省几分钟、出故障时省几小时」的场景。三点值得记住免费不等于免鉴权仍然需要有效 API Key也会留流水方便事后核对IP 取值有固定顺序X-Forwarded-For优先多级代理取第一段可伪造别用于安全判定十几毫秒的返回适合高频探测但建议做缓存或降频别把探测任务写成死循环。同系列还有行政区划查询region.query免费、成品油调价周期查询oilprice.cycle免费都适合作为接入自检与低成本数据补充。