简介这是一套直接对接管局官网的ICP备案查询API接口源码适合网站开发者、站长以及需要批量核验域名备案信息的技术人员。数据源为管局官网与第三方站长工具接口相比更新更及时、整体更稳定请求时通过get方式传入domain参数支持带http或二级域名的查询。压缩包共7个文件大小仅4KB以PHP接口主文件、Markdown说明文档、txt备注、bat批处理及url快捷链接为主结构精简部署后调用index.php即可拿到包含icp、unitName、natureName等字段的JSON数据并用result字段判断查询是否成功。包内还附有安装教程和云服务器、域名商推荐链接帮助使用者快速完成环境配置。已有1119人学习下载。整体适合具备PHP基础、希望快速自建域名备案查询服务的中初级开发者直接部署使用也可作为接口二次开发或批量备案核验的基础脚本。1. 管局官网ICP备案查询API接口源码为批量核查域名而生做支付渠道审核、广告投放白名单、建站服务商核验客户域名都会碰到一个绕不开的动作查ICP备案。一个域名打开网页点一次还能忍受手里压着几百个待核验域名时人工点击就是灾难。于是把管局官网公开的ICP备案查询流程封装成HTTP接口交付一份可运行的源码成了这类业务里最实用的内部工具。这篇笔记就围绕这个需求展开——从F12抓包定位管局查询请求到用Python封装成Flask服务再到部署、缓存、监控的线上参数以及验证码、封IP、编码乱码这些绕不开的坑。适合要搭批量核验工具的开发者和企业IT照着复现就能跑起来。2. 管局备案查询的底层机制一次查询在浏览器里经历了什么先弄明白你在跟什么打交道。ICP备案查询在管局官网是公开入口但每个省的管局系统由不同厂商建设页面形态差异很大。有的还是老式的表单POST点完查询刷新整个页面结果直接嵌在返回的HTML里有的已经改成了前后端分离输入域名之后实际发了一个异步请求拿到JSON再渲染到表格。这两种形态决定了后面的解析代码怎么写也决定了复现时最容易被卡住的地方在哪。我在开始写代码前一定会先打开目标管局的查询页面手动点一次查询把Network面板完整看一遍。这个习惯帮我省掉了后面大量的返工——很多人拿到需求直接写Python去请求首页结果要么少带了参数要么把验证码当成了页面主体折腾一晚上还在原地打转。2.1 管局查询页的两类入口静态表格页与异步加载页区分两类入口的方法很简单在Network面板里点查询看是否多出一个XHR请求。多出来的基本就是异步接口没有多出来的就是整个页面刷新、结果直接混在HTML里。类型技术栈特征结果形态抓包时重点看传统表单页JSP / Asp.Net / PHP响应HTML结果在table里表单字段名、Cookie、字符集异步加载页Vue / Axios / jQuery响应JSON或HTML片段请求URL、Header、签名参数把这一步搞清楚后面解析代码的写法和难度完全是两码事。异步接口往往是一个干净的JSON返回解析逻辑几行就写完传统表单页则要跟表格结构、转义字符、编码问题缠斗半天。另外注意一点某些管局页面在输入域名时会强制给它拼接www前缀返回的记录可能跟你查根域名不完全一致这个细节后面验证用例里会专门讲到。2.2 用F12定位真正的查询接口找返回备案数据的那个网络请求定位接口的具体步骤我一般这么走打开目标管局查询页按F12切到Network面板。输入一个确定已备案的域名点查询按钮。在Network里点过滤XHR找触发后新出现的那个请求。确认它的请求方法POST居多、参数放在Form Data还是Query String里。看响应体的Content-Type记住charset值。完成之后把关键信息整理到一个临时文件里这一步看起来啰嗦但后面写代码时全部要引用。# 抓包后整理出的请求信息按你自己抓包得到的结果替换 QUERY_URL https://目标管局.example/search # 换成实际抓包地址 QUERY_METHOD POST QUERY_FORM { domain: , # 查询主键部分系统叫domainName searchType: 1, # 按域名查有的系统叫type或queryMode token: 从页面源码里看到的token, } def build_payload(domain: str) - dict: payload dict(QUERY_FORM) payload[domain] domain return payload代码里的token是从查询页面源码里取的有些系统把它放在隐藏input里有些是页面加载时通过异步接口下发的。token通常有时间戳签名长期不用会过期所以比较稳妥的做法是每次查询前先请求一次查询页、把新的token捞出来再发起查询。别直接把抓包看到的token写死八成用几个小时就失效了。2.3 解析结果页的两种路线正则提取与HTML解析库的选型如果返回的是JSON直接resp.json()就能拿到结构化数据没什么好讲的。真正麻烦的是返回HTML表格的管局系统。解析它有两种路线正则提取和HTML解析库。我的经验是不要一上来就写正则先把表格结构看一眼再决定。正则适合字段规律非常固定的页面。比如备案号这类的文本用一条正则就能精准抓住速度也快。但它的脆弱性同样明显——页面里多一个空格、换一个标签属性匹配就可能静默失败而且失败时不报错只返回空列表线上排错非常难受。import re from bs4 import BeautifulSoup def parse_with_regex(html: str) - list[dict]: # 备案号的常见形态京ICP备12345678号 / 粤ICP备12345678号-2 pattern re.compile( r([京津沪渝冀豫云辽黑湘皖鲁新苏浙赣鄂桂甘晋蒙陕吉闽贵粤青藏川宁琼]) rICP[备证]\d{8,}号(?:-\d)? ) icp_numbers pattern.findall(html) # 注意findall 在有分组时返回元组 return [{icp_no: n} for n in icp_numbers]这段代码有个初学者常踩的坑正则里加了分组括号findall就会返回元组而不是完整匹配串。上面这个写法里分组一是省份简称所以findall返回的是省份简称不是备案号整体必须改成非捕获分组或者用finditer提取group(0)。我在第一次写的时候就在这翻过车排查了半天以为页面结构变了。from lxml import etree def parse_with_xpath(html: str) - list[dict]: tree etree.HTML(html) rows tree.xpath(//table//tr[position()1]) # 跳过表头 result [] for row in rows: tds row.xpath(.//td/text()) if len(tds) 3: result.append({ icp_no: tds[0].strip(), company: tds[1].strip(), site_name: tds[2].strip(), }) return result选型的结论是非结构化文本用正则结构化表格用XPath。XPath按表格行的位置取值页面里加一个字段不影响已经写好的列顺序容错性明显更好。如果你确认目标管局的结果页永远只返回固定列正则也能用但建议给正则包一层异常捕获匹配不到时打印告警日志而不是静默返回空。2.4 抓包时就要记下charset解码方式决定后面少踩一个坑老管局系统里非常常见的是GBK或GB2312编码。抓包时看响应头的Content-Type如果写的是text/html; charsetgbk那么后面代码里就要用resp.content先取原始字节再手动按GBK解码而不是直接读resp.text。requests库的.text属性会按照响应头里的charset解码但很多老系统响应头里根本没写charsetrequests就默认按UTF-8去解解出来满屏的替换字符。这个坑我在多个省份的系统里都碰见过表现形式不一定是乱码——有时候是备案号能解出来但主办单位名称全是乱码因为数字和字母在两种编码里恰好重合中文全部错位。抓包时顺手记下charset比在代码里反复试编码要高效得多。3. 用Python封装ICP备案查询API接口请求、解析与Flask服务这一章直接动手。把上一章抓包得到的结论转成可运行的代码构造请求、解析结果、再用Flask包成一个HTTP接口。技术栈用Python的requests加Flask理由只有一个——这两块的坑我都踩过最稳。如果你更熟悉PHP思路完全一样把requests换成curl把解析逻辑平移成DOMDocument就好瓶颈不在语言上。3.1 构造查询请求requests.Session、请求头与超时参数查询请求必须用Session来发。原因有两个一是管局系统很多依赖Cookie维持会话第一次访问查询页时服务端会下发Cookie不带上它直接发查询请求经常被拒绝二是Session内部维护连接池批量查询时TCP握手开销能省掉一大截。import requests from requests.adapters import HTTPAdapter session requests.Session() session.headers.update({ User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36, Referer: https://目标管局.example/query, # 以抓包结果为准 }) adapter HTTPAdapter( pool_connections5, pool_maxsize10, max_retries0, ) session.mount(http://, adapter) session.mount(https://, adapter) def query_icp(domain: str, payload_builder) - requests.Response: payload payload_builder(domain) resp session.post( QUERY_URL, datapayload, timeout(5, 15), # 连接超时5秒读取超时15秒 ) resp.raise_for_status() return resp参数说明timeout(5, 15)这种写法是连接超时和读取超时分离管局老系统响应普遍慢连接超时给5秒、读取超时给15秒比较从容。max_retries0的意思是请求失败不自动重试重试逻辑后面单独做——因为自动重试很容易在管局限流时放大压力本来只是偶发超时重试几次就把IP打成封禁了。Referer必须填有些管局系统会校验来源页不填直接返回403。3.2 解析备案结果的容错写法备案号、主办单位与审核时间的提取把解析函数写成输入HTML、输出统一结构上层接口不需要关心具体是哪个省的页面。字段统一成四个icp_no、company、site_name、review_time也就是备案号、主办单位、网站名称和审核时间。解析时优先用XPath按表头关键字定位列索引而不是写死第几列这样能扛住不同管局列顺序不一致的问题。from lxml import etree def parse_icp_html(html: str) - list[dict]: tree etree.HTML(html) rows tree.xpath(//table//tr) if not rows: return [] # 从表头推断列位置常见叫法有「备案号/网站备案号/ICP备案号」 header_cells rows[0].xpath(.//th/text() | .//td/text()) header_cells [c.strip() for c in header_cells] col_no _find_col(header_cells, (备案号, ICP)) col_company _find_col(header_cells, (主办单位, 主办者, 主办方)) col_site _find_col(header_cells, (网站名称, 网站名)) col_time _find_col(header_cells, (审核时间, 通过日期, 备案时间)) result [] for row in rows[1:]: cells [c.strip() for c in row.xpath(.//td/text() | .//td//span/text())] if len(cells) max(col_no, col_company, col_site, col_time): continue result.append({ icp_no: cells[col_no] if col_no 0 else , company: cells[col_company] if col_company 0 else , site_name: cells[col_site] if col_site 0 else , review_time: cells[col_time] if col_time 0 else , }) # 过滤掉全空字段的脏行 return [r for r in result if any(r.values())]这个写法的好处是表头有「备案号」三个字就够定位列不需要关心它在第几列某个字段缺失时置空而不是把整行丢弃。很多管局的结果页会在表格里混入页码、操作按钮之类的干扰行通过any(r.values())过滤掉。注意表头单元格可能是th也可能是tdXPath里两条路径用|并起来这个细节不处理的话有一半省局的表头会解析成空。3.3 用Flask把查询逻辑包装成HTTP接口参数校验、限频与统一返回接口设计成POST加JSON body返回结构统一为code / data / msg三段式。code0表示成功data是记录数组查询无结果时data返回空数组而不是null这样调用方不用做空值判断。参数校验放在进入查询逻辑之前domain为空、超长、带明显注入特征尖括号、引号的一律返回400。from flask import Flask, request, jsonify import threading app Flask(__name__) lock threading.Lock() MIN_INTERVAL 2.0 # 两次真实查询之间的最小间隔单位秒 app.config[JSON_AS_ASCII] False app.post(/api/icp/query) def icp_query(): payload request.get_json(silentTrue) or {} domain str(payload.get(domain, )).strip().lower() if not domain or len(domain) 255: return jsonify({code: 400, msg: invalid domain, data: []}) if any(ch in domain for ch in (, , , , \n)): return jsonify({code: 400, msg: invalid domain, data: []}) lock.acquire() try: html _query_from_guangwang(domain) records parse_icp_html(html) return jsonify({code: 0, msg: ok, data: records}) finally: lock.release()这里的核心参数是MIN_INTERVAL一个全局线程锁保证所有查询请求串行通过每两次请求之间至少间隔2秒。为什么不用异步并发管局的查询接口是对公网开放的慢接口并发一上去验证码和IP封禁立刻就会来得不偿失。宁可让调用方排队等也要保证接口长稳。等到后续跑熟了再根据实际观察到的限流阈值把间隔往下调到1秒左右。4. 常见问题与避坑指南验证码、IP封禁、编码乱码的踩坑记录写这套接口源码的人十有八九都是在本机跑通、放到线上跑了一晚之后第二天发现接口全挂。我也一样。这个章节把最常翻车的四个问题按现象、原因、解决三个步骤写清楚都是真实排过的坑。4.1 验证码拦截把查询频率压到阈值以下而不是研究怎么自动过现象连续查询十来个域名之后响应HTML里出现了图片验证码或者返回提示「请输入验证码」之前正常解析的表格字段全部消失。原因管局系统对单IP的查询频率有隐式限制触发条件不透明连续请求十几到几十次不等就会弹出来。这东西在本地手动测试时几乎遇不到因为人点击的速度远低于脚本。解决不要想自动识别验证码那是跟安全机制硬碰硬既没把握又踩线。务实的做法是把请求频率主动压低。前面代码里的MIN_INTERVAL就是干这个的。如果验证码已经弹出来了最快的恢复方式是手动打开一次查询页人工填一次验证码拿到新Cookie重新灌到session.cookies里脚本就能继续跑。import time class RateLimiter: def __init__(self, min_interval: float 2.0): self.min_interval min_interval self._last_ts 0.0 def wait_if_needed(self) - None: now time.time() gap now - self._last_ts if gap self.min_interval: time.sleep(self.min_interval - gap) self._last_ts time.time() limiter RateLimiter(min_interval3.0)参数说明min_interval3.0表示同一时间只允许一个查询线程并且每次查询结束后至少等3秒才发下一次。这个值是我试出来比较稳的起点如果你目标管局的限制比较宽松可以逐步下调但每次调整后至少要跑满几百次查询再下结论短时间不出验证码不代表频率没问题。4.2 请求一多就被封IP退避重试与熔断的取舍现象跑了半小时左右日志里开始出现大量403 Forbidden或连接超时之前能正常返回的请求也全部失败过了一两个小时又自行恢复。原因触发IP维度的限流表现和验证码不同——验证码是页面里多了一个弹窗IP被封则是连请求都不再被处理。很多人的第一反应是换IP继续跑但如果你用的是内网工具通常没有那么多可用IP更该做的是控制速率和退避。解决遇到403和连读失败时立刻停止请求等一段时间再重试。给请求加一个带指数退避的重试装饰器连续失败超过5次就熔断不再发请求等60秒再放开。import time import functools import requests def retry_with_backoff(max_retries: int 3, base_delay: float 10.0): def decorator(func): functools.wraps(func) def wrapper(*args, **kwargs): for attempt in range(max_retries): try: return func(*args, **kwargs) except (requests.HTTPError, requests.ConnectionError) as exc: if attempt max_retries - 1: raise delay base_delay * (2 ** attempt) time.sleep(delay) return None return wrapper return decorator这里的参数比看起来重要base_delay10.0是第一次重试等10秒第二次20秒第三次40秒。指数退避的目的是不要在被限流的时候持续给对方的负载均衡施压。如果重试3次还失败基本可以确定是长时间限流这时候继续重试只会让封禁时间更久不如让接口返回503给调用方等几分钟后由外层任务重新提交。4.3 GBK编码乱码先嗅探再解码别一上来就utf-8现象解析出来的数据里数字和字母正常中文全是替换字符或者出现明显的乱码字体。备案号能提取到主办单位名称完全没法看。原因管局老系统返回的是GBK编码但响应头没写charsetgbkrequests库的.text属性默认按UTF-8解码中文全部变成了替换字符。解决用resp.content拿原始字节先做编码嗅探再手动解码。千万别用resp.text去赌服务器给对了charset。import chardet def safe_decode(raw: bytes) - str: detected chardet.detect(raw) guess detected.get(encoding) or utf-8 if guess.lower() in (gb2312, gbk, big5): return raw.decode(gbk, errorsreplace) try: return raw.decode(utf-8) except UnicodeDecodeError: return raw.decode(gbk, errorsreplace) # 使用方式 html safe_decode(resp.content)参数说明errorsreplace的意思是遇到无法解码的字节就替换成不让整个函数抛异常。实践中可以把嗅探结果打印到日志里看一次确认目标管局稳定返回GBK之后可以省略嗅探、直接按GBK解码省掉每次查询的检测开销。嗅探库本身有性能开销批量查询时每个响应都跑一次chardet.detect累积下来也不小。4.4 不同管局页面结构不一致统一字段清洗层收口现象同一个解析函数在A省管局能查到完整记录换B省管局就返回空数组或者在B省能查到但字段错位审核时间跑到主办单位那一列。原因各省管局系统由不同厂商建设表格列的顺序、表头叫法都不统一。有的叫「网站备案号」有的直接叫「备案号」还有的把ICP证和ICP备案混在一张表里。解决解析层不要只服务某一个省的页面——在解析结果后面再接一层字段清洗把同义的字段名映射到统一字段。表头识别时用模糊匹配不只匹配精确字符串比如备案 in cell这种判断能把「网站备案号」「ICP备案号」全部收进来。def _find_col(headers, keywords) - int: for idx, header in enumerate(headers): for kw in keywords: if kw in header: return idx return -1这个函数看起来简单但它是整个解析逻辑里复用率最高的一段。备案号 in 网站备案号成立ICP in ICP备案号也成立。你可能觉得这是不是太糙了实际跑下来它比精确匹配省事得多——不同管局的表头差异就是靠这层模糊匹配吸收掉的。遇到完全无法识别表头的页面日志里打印告警人工看一次页面结构补一个关键词就行不值得为个别老系统写死一套列顺序。5. 从本机到线上Linux部署、Redis缓存与接口监控参数本机跑通和线上稳定是两回事。本机只有一个用户、一个进程、偶尔调一次线上要考虑别人也在调、进程挂了要自动拉起、同一个域名不能反复去管局查。这一章解决三个问题用什么起服务、怎么缓存、怎么知道接口挂了。5.1 Linux部署gunicorn工作进程数与systemd常驻Flask自带的开发服务器不能用于线上这是第一条。常见做法是用gunicorn当WSGI服务器。这里有个反直觉的参数工作进程数不要因为机器核多就调大。管局查询接口耗时普遍在几秒如果gunicorn -w 8同时起8个worker意味着同一瞬间最多8个查询请求并发打到管局前面说过并发一多验证码和封IP就会来。gunicorn -w 2 --threads 4 --timeout 30 -b 0.0.0.0:8000 app:app参数说明-w 2只起2个进程--threads 4每个进程开4个线程这样总体并发能力是8但实际查询请求都被进程里的全局锁串行化了worker多一点只是为了不让HTTP连接排队太久。--timeout 30是gunicorn杀掉超时worker的阈值——管局查询慢的时候可能到15秒要给够余量但也不能无限等。如果读者是PHP背景把这一条换成PHP内置服务器加systemd也行但进程管理思路是一样的。再用systemd让它常驻。写一个service文件放到/etc/systemd/system/icp-api.service[Unit] DescriptionICP Query API Afternetwork.target [Service] Userwww-data WorkingDirectory/opt/icp-api ExecStart/opt/icp-api/venv/bin/gunicorn -w 2 --threads 4 --timeout 30 -b 0.0.0.0:8000 app:app Restartalways RestartSec5 [Install] WantedBymulti-user.targetRestartalways配合RestartSec5的意思是进程退出后5秒自动拉起。这个配置我建议直接写上不然半夜接口挂了调用方的任务队列全部失败第二天早上才发现就晚了。启动命令systemctl daemon-reload systemctl enable icp-api systemctl start icp-api5.2 查询结果缓存Redis的TTL怎么定ICP备案数据不是实时变化的。今天查不到的域名明天不一定能查到但今天能查到的半个月内基本不会有变化。所以查询结果必须做缓存否则同一个域名为啥要反复去管局打一次缓存的设计有两点要注意正常结果和空结果都要缓存。import redis import json r redis.Redis.from_url(redis://127.0.0.1:6379/0, decode_responsesTrue) def get_icp_from_cache(domain: str): key ficp:{domain} raw r.get(key) if raw is None: return None return json.loads(raw) def set_icp_cache(domain: str, records: list[dict], ttl: int 21600): key ficp:{domain} r.setex(key, ttl, json.dumps(records, ensure_asciiFalse))这里的ttl21600是6小时适合正常结果。空结果建议单独用一个更短的TTL比如30分钟。为什么不直接不缓存空结果因为新备案的域名可能今天查不到一小时后就能查到如果空结果也缓存一天用户会在这一整天里看到「未备案」的错误结论。负面缓存过期时间短可以在数据同步延迟和管局压力之间取得平衡。def query_with_cache(domain: str): cached get_icp_from_cache(domain) if cached is not None: return cached records _do_query(domain) if records: set_icp_cache(domain, records, ttl21600) else: set_icp_cache(domain, [], ttl1800) return records这段代码看起来没什么技术含量但它是线上接口的续命丸。管局接口再慢再容易限流有缓存顶着大部分查询请求根本不会触达管局服务器。如果做的是内网工具、不方便引入Redis用cachetools.TTLCache本地缓存也行只是多进程部署时每个进程各存一份命中率会低一些。5.3 健康监控超时率、失败率与告警阈值的经验值接口上线最怕的是挂了自己不知道。不需要上一套完整的监控系统但至少要记录三个数字请求总数、失败数、平均耗时。用一个简单的装饰器就能做到。import time import logging logger logging.getLogger(icp-api) # 每分钟滚动统计 stats {req: 0, fail: 0, total_cost: 0.0} def collect_metrics(func): def wrapper(*args, **kwargs): start time.time() stats[req] 1 try: result func(*args, **kwargs) except Exception as exc: stats[fail] 1 raise finally: stats[total_cost] (time.time() - start) return result return wrapper用的时候把这个装饰器挂在query_with_cache上然后在Flask里加一个内部接口把统计数据暴露出来app.get(/metrics) def show_metrics(): total stats[req] fail_rate stats[fail] / total if total else 0.0 avg_cost stats[total_cost] / total if total else 0.0 return jsonify({ request_count: total, fail_rate: round(fail_rate, 4), avg_cost_ms: round(avg_cost * 1000, 2), })告警阈值我给一个参考值失败率超过20%持续3分钟说明管局在限流或者接口本身有问题了平均耗时超过10秒说明管局响应变慢需要考虑降低频率。这些值不是玄学但也别照抄跑几天观察正常波动的基线再按基线上下浮动去定。一开始可以把告警做成日志里打印一条WARNING确认阈值合理后再接到企业微信或钉钉机器人。6. 上线前最后一步合规边界、三类验证用例与收尾技巧6.1 合规边界只查不存、限频、不外放ICP备案数据属于公开信息查询本身没有问题但封装成接口之后要做好边界控制接口只在内网环境使用不把备案结果批量落库也不对外提供公开查询。批量抓取和长期存储都有被认定为非正常访问的风险。管局页面里的数据更新有延迟新备案的域名可能在1到3个工作日后才能查到这个时间差要在接口文档里明确写出来否则业务方查不到就判定未备案容易出争端。6.2 三类验证用例备案域名、未备案域名、二级域名上线前用一段脚本把三类用例跑一遍。正向用例用一个你确定已备案的域名反向用例用一个随机生成的未备案域名边界用例查询带www的域名验证接口能否自动剥掉前缀再查根域名。def verify_api(): cases [ (baidu.com, expect_record), (jskdajksdh123.com, expect_empty), (www.baidu.com, expect_record), ] for domain, expectation in cases: resp client.post(/api/icp/query, json{domain: domain}) data resp.get_json() assert resp.status_code 200, f{domain} failed if expectation expect_record: assert len(data[data]) 0, f{domain} should have record else: assert len(data[data]) 0, f{domain} should be empty6.3 日志里带上trace_id线上排查不用靠猜最后补一个我自己吃过亏才养成的习惯每个请求进来时生成一个trace_id放在日志和响应头里。线上接口出问题调用方把X-Trace-Id发过来直接grep日志就能定位到那一次查询的全部过程。没有这个字段排查线上问题就是在日志汪洋里靠时间猜测。import uuid from flask import g app.before_request def set_trace_id(): g.trace_id uuid.uuid4().hex[:12] app.after_request def add_trace_header(resp): resp.headers[X-Trace-Id] g.trace_id return resp写这套源码的时候我最大的教训就是一开始只顾着把查询逻辑跑通没管频率、缓存和日志结果上线当晚接口就被管局限流第二天业务方投诉查询全挂。后来老老实实把限速、缓存和熔断补上才真正稳定下来。希望这篇笔记能帮你把那几个最深的坑直接绕过去写完就敢把接口交给业务方用。本文还有配套的精品资源点击获取
