尧图网页设计 
简介本资源面向需要做IP归属地查询与地域分析的开发者提供qqzeng-ip-china数据库及多语言调用示例可用于日志分析、风控识别、访问统计等场景。压缩包共6个文件约4.25MB包含utf8与gbk两种编码的dat数据文件以及Python、Go、Java、PHP四种语言的查询代码方便不同技术栈直接接入。数据已更新至2025年8月8日覆盖国内IP段与地区映射编码版本可适配不同系统环境。目前已有759人学习下载适合需要快速集成IP定位能力、减少自行维护数据成本的中初级开发者参考使用。1. 从一次线上事故说起为什么我重新翻出了 qqzeng-ip 这套 dat 库上个月帮朋友排查一个订单风控误判日志里同一批请求的 IP 归属地一会儿显示「广东深圳」一会儿显示「北京北京」最后定位到是两套 IP 库版本不一致——一套是某云厂商 API 返回的一套是本地缓存的旧 dat 文件。这件事让我重新把 qqzeng-ip-china 这套纯真风格的离线库翻出来认真过了一遍。它本质上就是两个二进制数据文件qqzeng-ip-china-utf8.dat和qqzeng-ip-china-gbk.dat配套 Python、Go、Java、PHP 四种语言的查询示例代码打包在Ipsearch.zip里。核心价值在于离线、零依赖、单文件查询不需要联网调 API也不吃内存适合做日志分析、风控初筛、埋点补全这类高频低延迟场景。如果你正在找一份能直接塞进项目、不用申请 key、不用管配额的 IP 归属地库这套东西值得花二十分钟拆一遍。下面我按「文件结构 → 各语言接入 → 踩坑 → 进阶校验」的顺序把能复现的细节都摊开。2. 拆包看结构两个 dat 文件到底差在哪四种语言怎么选2.1 utf8 与 gbk 两个 dat 的编码差异与选用原则拿到Ipsearch.zip解压后根目录下是这几个文件IpSearch.py、IpSearch.go、IpSearch.java、IpSearch.php加上qqzeng-ip-china-utf8.dat和qqzeng-ip-china-gbk.dat。两个 dat 文件的数据内容完全一致区别只在字符串编码utf8 版本里省市区名称按 UTF-8 存储gbk 版本按 GBK 存储。这个设计不是多余的早年很多 Windows 下的 PHP 环境和老版 Java 项目默认字符集是 GBK如果直接读 utf8 的 dat中文会变成乱码反过来在 Linux 容器里读 gbk 文件同样会翻车。选用原则很简单新项目、Docker 环境、Go 和 Python 一律用 utf8只有当你明确知道运行环境的file.encoding或 PHP 的default_charset是 GBK且不方便改全局配置时才用 gbk 版本。我一般会在项目里同时保留两个文件通过环境变量切换避免部署到不同机器时临时改代码。提示两个 dat 文件的记录条数和 IP 段划分是完全对齐的切换编码不会导致查询结果偏移只影响中文字节流。2.2 二进制格式与查询原理为什么它比 CSV 快这套 dat 不是文本文件不能直接用记事本打开看。它的结构大致是文件头 索引区 数据区。索引区按 IP 段起始地址排序每条索引记录包含起始 IP、结束 IP 和数据区偏移量数据区存放「国家-省-市-运营商」这样的字符串。查询时把目标 IP 转成 32 位整数在索引区做二分查找命中后按偏移量去数据区取字符串。这个结构决定了它的两个特性第一查询复杂度是 O(log n)几万条段也是微秒级第二文件可以整个读进内存也可以按需 seek内存占用可控。相比之下 CSV 要全量加载再遍历几百万行直接吃满内存。常见做法是把 dat 文件路径配置化启动时只加载一次查询时复用文件句柄。2.3 四种语言示例代码的文件职责Ipsearch.zip里的四个源码文件不是互相调用的而是各自独立的查询实现你可以只拿自己需要的那一个。IpSearch.py用struct解包二进制IpSearch.go用encoding/binary配合os.OpenIpSearch.java用RandomAccessFileIpSearch.php用fopenfseek。它们都实现了同一套逻辑IP 转整数 → 二分查找索引 → 读数据区 → 按编码解码。文件语言关键依赖适用场景IpSearch.pyPython 3struct, bisect脚本、数据分析、临时排查IpSearch.goGoencoding/binary高并发服务、CLI 工具IpSearch.javaJava 8RandomAccessFile传统后端、Spring 项目IpSearch.phpPHP 7fopen/fseek老 Web 项目、运维脚本选语言的原则是跟着你的主服务走不要为了查 IP 单独起一个进程。Python 适合离线批处理Go 适合塞进网关做实时判断Java 和 PHP 就看你现有项目用什么。3. Python 与 Go 接入实战从读文件到封装成函数3.1 Python 读取 utf8 dat 的完整代码与参数说明Python 版本最直观适合先跑通验证文件是否完好。下面这段代码是我在IpSearch.py基础上整理的可直接运行版本核心是用struct.unpack解析索引记录。import struct import bisect class IPQuery: def __init__(self, dat_path): self.f open(dat_path, rb) # 读取文件头前4字节通常是索引区起始偏移 self.f.seek(0) header self.f.read(4) self.index_start struct.unpack(I, header)[0] # 索引区每条记录固定长度常见为 13 字节4441 self.record_size 13 self.f.seek(0, 2) file_size self.f.tell() self.count (file_size - self.index_start) // self.record_size # 预加载所有起始IP用于二分查找 self.starts [] self.f.seek(self.index_start) for i in range(self.count): buf self.f.read(self.record_size) start_ip struct.unpack(I, buf[0:4])[0] self.starts.append(start_ip) def ip_to_int(self, ip): parts ip.split(.) return (int(parts[0]) 24) | (int(parts[1]) 16) | \ (int(parts[2]) 8) | int(parts[3]) def query(self, ip): target self.ip_to_int(ip) idx bisect.bisect_right(self.starts, target) - 1 if idx 0: return None self.f.seek(self.index_start idx * self.record_size) buf self.f.read(self.record_size) start_ip, end_ip, data_offset struct.unpack(III, buf[0:12]) if target end_ip: return None # 数据区字符串以 \0 结尾 self.f.seek(data_offset) raw b while True: ch self.f.read(1) if ch b\x00 or ch b: break raw ch return raw.decode(utf-8) if __name__ __main__: q IPQuery(qqzeng-ip-china-utf8.dat) print(q.query(114.114.114.114))逻辑说明index_start是索引区在文件中的起始位置record_size是每条索引的字节数这两个参数必须和 dat 文件实际格式一致不同版本可能不同跑之前先用十六进制工具看一眼文件头。bisect_right找到最后一个起始 IP 小于等于目标 IP 的索引再校验目标 IP 是否落在该段的结束 IP 之内。数据区读取用逐字节方式直到遇到\0这是纯真系 dat 的常见约定。参数说明dat_path传 utf8 或 gbk 文件路径如果换成 gbk 版本最后一行decode(utf-8)要改成decode(gbk)否则中文乱码。record_size如果对不上查询会整体错位表现为返回 None 或乱码这时候要回去核对文件头。3.2 Go 语言版本的内存映射与并发安全写法Go 版本适合放进高并发服务IpSearch.go原始实现是每次查询都 seekQPS 高了会有锁竞争。我一般会改成启动时把索引区全量读进内存切片数据区保留文件句柄按需读这样查询路径无锁。package main import ( encoding/binary fmt os ) type IPQuery struct { f *os.File indexStart int64 recordSize int64 starts []uint32 } func NewIPQuery(path string) (*IPQuery, error) { f, err : os.Open(path) if err ! nil { return nil, err } q : IPQuery{f: f, recordSize: 13} header : make([]byte, 4) f.ReadAt(header, 0) q.indexStart int64(binary.LittleEndian.Uint32(header)) stat, _ : f.Stat() count : (stat.Size() - q.indexStart) / q.recordSize q.starts make([]uint32, 0, count) buf : make([]byte, q.recordSize) for i : int64(0); i count; i { f.ReadAt(buf, q.indexStarti*q.recordSize) q.starts append(q.starts, binary.LittleEndian.Uint32(buf[0:4])) } return q, nil } func (q *IPQuery) Query(ip uint32) (string, error) { lo, hi : 0, len(q.starts)-1 for lo hi { mid : (lo hi 1) / 2 if q.starts[mid] ip { lo mid } else { hi mid - 1 } } buf : make([]byte, q.recordSize) if _, err : q.f.ReadAt(buf, q.indexStartint64(lo)*q.recordSize); err ! nil { return , err } endIP : binary.LittleEndian.Uint32(buf[4:8]) if ip endIP { return , nil } dataOffset : int64(binary.LittleEndian.Uint32(buf[8:12])) var out []byte tmp : make([]byte, 1) for { if _, err : q.f.ReadAt(tmp, dataOffset); err ! nil { break } if tmp[0] 0 { break } out append(out, tmp[0]) dataOffset } return string(out), nil } func main() { q, _ : NewIPQuery(qqzeng-ip-china-utf8.dat) ip : uint32(11424 | 11416 | 1148 | 114) loc, _ : q.Query(ip) fmt.Println(loc) }逻辑说明NewIPQuery在初始化阶段把索引区的起始 IP 全部读进starts切片查询时只做内存二分不再碰索引区文件。Query接收的是已经转成 uint32 的 IP避免每次查询重复解析字符串。数据区读取用ReadAt它是并发安全的多个 goroutine 同时查不会互相干扰。参数说明recordSize同样是 13如果 dat 版本变了要同步改。ip的构造用位运算比net.ParseIP再转 uint32 快适合热点路径。如果返回空字符串说明该 IP 不在库覆盖范围内业务上要兜底成「未知」。3.3 把查询封装成可复用模块的目录建议不管用哪种语言我都建议把 dat 文件和查询代码放在独立目录比如pkg/ipdb/对外只暴露一个Query(ip string) (string, error)。这样以后换库、加缓存、做降级都只改一个地方。Python 里可以做成单例Go 里用sync.Once初始化Java 里用静态块PHP 里用静态变量。别把 dat 路径硬编码在业务代码里用配置文件或环境变量传进去。4. Java 与 PHP 接入老项目里怎么少改代码4.1 Java RandomAccessFile 查询与字符集处理Java 版本用RandomAccessFile最省事不用引入任何第三方库。IpSearch.java的核心是seek加readInt但要注意字节序dat 是小端Java 的readInt是大端必须手动翻转。import java.io.RandomAccessFile; import java.nio.charset.Charset; public class IPQuery { private RandomAccessFile raf; private long indexStart; private int recordSize 13; private long count; private long[] starts; public IPQuery(String path, String charset) throws Exception { raf new RandomAccessFile(path, r); raf.seek(0); indexStart readLittleEndianInt(); long fileSize raf.length(); count (fileSize - indexStart) / recordSize; starts new long[(int) count]; for (int i 0; i count; i) { raf.seek(indexStart (long) i * recordSize); starts[i] readLittleEndianInt() 0xFFFFFFFFL; } } private int readLittleEndianInt() throws Exception { int b1 raf.read(); int b2 raf.read(); int b3 raf.read(); int b4 raf.read(); return (b4 24) | (b3 16) | (b2 8) | b1; } public String query(String ip) throws Exception { long target ipToLong(ip); int lo 0, hi starts.length - 1; while (lo hi) { int mid (lo hi 1) 1; if (starts[mid] target) lo mid; else hi mid - 1; } raf.seek(indexStart (long) lo * recordSize); long startIP readLittleEndianInt() 0xFFFFFFFFL; long endIP readLittleEndianInt() 0xFFFFFFFFL; long dataOffset readLittleEndianInt() 0xFFFFFFFFL; if (target endIP) return null; raf.seek(dataOffset); byte[] buf new byte[64]; int len 0; while (true) { int b raf.read(); if (b 0 || b -1) break; buf[len] (byte) b; } return new String(buf, 0, len, Charset.forName(charset)); } private long ipToLong(String ip) { String[] p ip.split(\\.); return (Long.parseLong(p[0]) 24) | (Long.parseLong(p[1]) 16) | (Long.parseLong(p[2]) 8) | Long.parseLong(p[3]); } }逻辑说明readLittleEndianInt手动按小端拼字节这是整个 Java 版本最容易出错的地方直接用readInt会得到完全错误的偏移量。starts数组存的是无符号 32 位值用 0xFFFFFFFFL转成 long 避免负数比较出错。字符集通过构造参数传入utf8 版本传UTF-8gbk 版本传GBK。参数说明path是 dat 文件路径charset决定解码方式。如果查询返回 null先确认 IP 是否在库范围内再检查recordSize是否匹配。Java 项目里建议把这个类做成 Spring 的Component启动时初始化一次。4.2 PHP 读取 gbk dat 的 fseek 实现PHP 版本在IpSearch.php里用的是fopenfseek适合老 Web 项目。gbk 版本在 PHP 里反而更省事因为很多老环境的默认输出就是 GBK不用转码。?php class IPQuery { private $fp; private $indexStart; private $recordSize 13; private $starts []; public function __construct($path) { $this-fp fopen($path, rb); fseek($this-fp, 0); $header fread($this-fp, 4); $this-indexStart unpack(V, $header)[1]; fseek($this-fp, 0, SEEK_END); $fileSize ftell($this-fp); $count intval(($fileSize - $this-indexStart) / $this-recordSize); for ($i 0; $i $count; $i) { fseek($this-fp, $this-indexStart $i * $this-recordSize); $buf fread($this-fp, 4); $this-starts[] unpack(V, $buf)[1]; } } public function query($ip) { $target ip2long($ip); $lo 0; $hi count($this-starts) - 1; while ($lo $hi) { $mid ($lo $hi 1) 1; if ($this-starts[$mid] $target) $lo $mid; else $hi $mid - 1; } fseek($this-fp, $this-indexStart $lo * $this-recordSize); $buf fread($this-fp, $this-recordSize); $data unpack(Vstart/Vend/Voffset, $buf); if ($target $data[end]) return null; fseek($this-fp, $data[offset]); $str ; while (($ch fgetc($this-fp)) ! false $ch ! \0) { $str . $ch; } return $str; } }逻辑说明unpack(V, ...)直接按小端解析省去手动翻转。ip2long在 32 位 PHP 上可能返回负数64 位环境正常如果遇到负数比较异常用sprintf(%u, ip2long($ip))转成无符号字符串再比较。gbk 版本读出来的$str直接就是 GBK 字节流输出到 GBK 页面不用转码。参数说明$path传 gbk 或 utf8 文件路径。如果页面是 UTF-8 而 dat 是 gbk需要mb_convert_encoding($str, UTF-8, GBK)。recordSize同样要核对。4.3 四种语言接入的共性检查清单不管用哪种语言接入后先跑这三个 IP 验证114.114.114.114江苏南京、223.5.5.5浙江杭州、8.8.8.8通常返回国外或未知。如果三个结果都合理说明文件头和 recordSize 对上了。如果全部返回 null八成是indexStart读错如果返回乱码是编码选错如果返回的省市明显错位是recordSize不对。这三个检查点能覆盖九成接入问题。5. 避坑与排查那些让我加班到凌晨的细节5.1 现象查询结果全是 null一条都命中不了原因indexStart读成了大端或者文件头长度不是 4 字节。有些 dat 版本文件头是 8 字节前 4 字节是魔数后 4 字节才是索引偏移。解决用十六进制工具打开 dat看前 16 个字节确认索引区起始位置。如果前 4 字节是固定魔数就往后偏移 4 字节再读。5.2 现象中文显示为「锟斤拷」或问号原因utf8 的 dat 用 gbk 解码或者反过来。解决确认 dat 文件名后缀和代码里的 decode 字符集一致。Python 里decode(utf-8)对应 utf8 文件decode(gbk)对应 gbk 文件。Java 里Charset.forName(UTF-8)同理。PHP 里如果页面是 UTF-8 而 dat 是 gbk必须显式转码。5.3 现象部分 IP 查询结果偏移返回了隔壁省市的归属地原因recordSize和实际索引记录长度不一致导致二分查找定位到的索引条目错位。解决核对 dat 版本的索引记录长度常见是 13 字节4 起始 4 结束 4 偏移 1 标志也有 12 字节或 14 字节的版本。用文件总大小减去索引起始位置除以记录数反推 recordSize。5.4 现象高并发下查询变慢CPU 飙高原因每次查询都重新打开文件或重复解析索引。解决初始化时把索引区加载到内存文件句柄复用。Go 里用ReadAt保证并发安全Java 里用synchronized包一层或每个线程独立RandomAccessFilePython 里用单例加锁。别在热点路径里反复open。5.5 现象dat 文件更新后查询报错或结果异常原因新版本 dat 的格式可能微调旧代码的recordSize或文件头解析不兼容。解决每次更新 dat 后先用一个已知 IP 跑一遍验证再上线。我一般会在 CI 里加一个冒烟测试固定查三个 IP结果不对就阻断发布。6. 进阶把 dat 库接进日志管道与校验脚本跑通基础查询之后真正省事的是把它接进日志处理链路。我现在的做法是在日志采集端做一次 IP 富化Nginx 日志里的$remote_addr在写入时就用这套库补上省市字段后面做地域聚合、异常登录检测就不用再回头查了。Python 脚本里可以用concurrent.futures批量处理Go 里直接在日志中间件里调Query延迟增加不到一微秒。另一个值得做的是版本校验脚本。dat 文件更新到 2025 年 08 月 08 日这个版本后我会跑一个固定 IP 列表把结果和上一版对比输出差异行。这样能快速发现新版本是否引入了归属地漂移。下面这个 Python 片段就是我做差异对比用的import json def diff_versions(old_file, new_file, ip_list): from ip_query import IPQuery # 假设上面的类放在 ip_query.py old_q IPQuery(old_file) new_q IPQuery(new_file) diffs [] for ip in ip_list: o old_q.query(ip) n new_q.query(ip) if o ! n: diffs.append({ip: ip, old: o, new: n}) return diffs if __name__ __main__: ips [114.114.114.114, 223.5.5.5, 119.29.29.29, 180.76.76.76] result diff_versions(qqzeng-ip-china-utf8-old.dat, qqzeng-ip-china-utf8.dat, ips) print(json.dumps(result, ensure_asciiFalse, indent2))逻辑说明diff_versions同时加载新旧两个 dat对同一批 IP 查询并比对结果输出差异。ip_list建议覆盖三大运营商和常见公共 DNS这样能同时验证电信、联通、移动、教育网的段是否更新。参数上old_file是上一版备份new_file是刚下载的版本跑完确认差异在预期范围内再替换生产文件。还有一个习惯每次更新 dat 后我会把文件大小和 MD5 记在项目的CHANGELOG里方便回滚时确认拿的是哪一版。这套库本身不复杂但 IP 归属地这东西差一个版本就可能让风控规则误伤一批用户。从那以后我每次替换 dat 文件都强制走一遍「三 IP 冒烟 新旧差异对比 MD5 记录」再也没出现过上线后归属地漂移的事。希望帮到你。本文还有配套的精品资源点击获取 离线IP归属地库技术解析：qqzeng-ip dat文件格式与多语言查询实践
简介本资源面向需要做IP归属地查询与地域分析的开发者提供qqzeng-ip-china数据库及多语言调用示例可用于日志分析、风控识别、访问统计等场景。压缩包共6个文件约4.25MB包含utf8与gbk两种编码的dat数据文件以及Python、Go、Java、PHP四种语言的查询代码方便不同技术栈直接接入。数据已更新至2025年8月8日覆盖国内IP段与地区映射编码版本可适配不同系统环境。目前已有759人学习下载适合需要快速集成IP定位能力、减少自行维护数据成本的中初级开发者参考使用。1. 从一次线上事故说起为什么我重新翻出了 qqzeng-ip 这套 dat 库上个月帮朋友排查一个订单风控误判日志里同一批请求的 IP 归属地一会儿显示「广东深圳」一会儿显示「北京北京」最后定位到是两套 IP 库版本不一致——一套是某云厂商 API 返回的一套是本地缓存的旧 dat 文件。这件事让我重新把 qqzeng-ip-china 这套纯真风格的离线库翻出来认真过了一遍。它本质上就是两个二进制数据文件qqzeng-ip-china-utf8.dat和qqzeng-ip-china-gbk.dat配套 Python、Go、Java、PHP 四种语言的查询示例代码打包在Ipsearch.zip里。核心价值在于离线、零依赖、单文件查询不需要联网调 API也不吃内存适合做日志分析、风控初筛、埋点补全这类高频低延迟场景。如果你正在找一份能直接塞进项目、不用申请 key、不用管配额的 IP 归属地库这套东西值得花二十分钟拆一遍。下面我按「文件结构 → 各语言接入 → 踩坑 → 进阶校验」的顺序把能复现的细节都摊开。2. 拆包看结构两个 dat 文件到底差在哪四种语言怎么选2.1 utf8 与 gbk 两个 dat 的编码差异与选用原则拿到Ipsearch.zip解压后根目录下是这几个文件IpSearch.py、IpSearch.go、IpSearch.java、IpSearch.php加上qqzeng-ip-china-utf8.dat和qqzeng-ip-china-gbk.dat。两个 dat 文件的数据内容完全一致区别只在字符串编码utf8 版本里省市区名称按 UTF-8 存储gbk 版本按 GBK 存储。这个设计不是多余的早年很多 Windows 下的 PHP 环境和老版 Java 项目默认字符集是 GBK如果直接读 utf8 的 dat中文会变成乱码反过来在 Linux 容器里读 gbk 文件同样会翻车。选用原则很简单新项目、Docker 环境、Go 和 Python 一律用 utf8只有当你明确知道运行环境的file.encoding或 PHP 的default_charset是 GBK且不方便改全局配置时才用 gbk 版本。我一般会在项目里同时保留两个文件通过环境变量切换避免部署到不同机器时临时改代码。提示两个 dat 文件的记录条数和 IP 段划分是完全对齐的切换编码不会导致查询结果偏移只影响中文字节流。2.2 二进制格式与查询原理为什么它比 CSV 快这套 dat 不是文本文件不能直接用记事本打开看。它的结构大致是文件头 索引区 数据区。索引区按 IP 段起始地址排序每条索引记录包含起始 IP、结束 IP 和数据区偏移量数据区存放「国家-省-市-运营商」这样的字符串。查询时把目标 IP 转成 32 位整数在索引区做二分查找命中后按偏移量去数据区取字符串。这个结构决定了它的两个特性第一查询复杂度是 O(log n)几万条段也是微秒级第二文件可以整个读进内存也可以按需 seek内存占用可控。相比之下 CSV 要全量加载再遍历几百万行直接吃满内存。常见做法是把 dat 文件路径配置化启动时只加载一次查询时复用文件句柄。2.3 四种语言示例代码的文件职责Ipsearch.zip里的四个源码文件不是互相调用的而是各自独立的查询实现你可以只拿自己需要的那一个。IpSearch.py用struct解包二进制IpSearch.go用encoding/binary配合os.OpenIpSearch.java用RandomAccessFileIpSearch.php用fopenfseek。它们都实现了同一套逻辑IP 转整数 → 二分查找索引 → 读数据区 → 按编码解码。文件语言关键依赖适用场景IpSearch.pyPython 3struct, bisect脚本、数据分析、临时排查IpSearch.goGoencoding/binary高并发服务、CLI 工具IpSearch.javaJava 8RandomAccessFile传统后端、Spring 项目IpSearch.phpPHP 7fopen/fseek老 Web 项目、运维脚本选语言的原则是跟着你的主服务走不要为了查 IP 单独起一个进程。Python 适合离线批处理Go 适合塞进网关做实时判断Java 和 PHP 就看你现有项目用什么。3. Python 与 Go 接入实战从读文件到封装成函数3.1 Python 读取 utf8 dat 的完整代码与参数说明Python 版本最直观适合先跑通验证文件是否完好。下面这段代码是我在IpSearch.py基础上整理的可直接运行版本核心是用struct.unpack解析索引记录。import struct import bisect class IPQuery: def __init__(self, dat_path): self.f open(dat_path, rb) # 读取文件头前4字节通常是索引区起始偏移 self.f.seek(0) header self.f.read(4) self.index_start struct.unpack(I, header)[0] # 索引区每条记录固定长度常见为 13 字节4441 self.record_size 13 self.f.seek(0, 2) file_size self.f.tell() self.count (file_size - self.index_start) // self.record_size # 预加载所有起始IP用于二分查找 self.starts [] self.f.seek(self.index_start) for i in range(self.count): buf self.f.read(self.record_size) start_ip struct.unpack(I, buf[0:4])[0] self.starts.append(start_ip) def ip_to_int(self, ip): parts ip.split(.) return (int(parts[0]) 24) | (int(parts[1]) 16) | \ (int(parts[2]) 8) | int(parts[3]) def query(self, ip): target self.ip_to_int(ip) idx bisect.bisect_right(self.starts, target) - 1 if idx 0: return None self.f.seek(self.index_start idx * self.record_size) buf self.f.read(self.record_size) start_ip, end_ip, data_offset struct.unpack(III, buf[0:12]) if target end_ip: return None # 数据区字符串以 \0 结尾 self.f.seek(data_offset) raw b while True: ch self.f.read(1) if ch b\x00 or ch b: break raw ch return raw.decode(utf-8) if __name__ __main__: q IPQuery(qqzeng-ip-china-utf8.dat) print(q.query(114.114.114.114))逻辑说明index_start是索引区在文件中的起始位置record_size是每条索引的字节数这两个参数必须和 dat 文件实际格式一致不同版本可能不同跑之前先用十六进制工具看一眼文件头。bisect_right找到最后一个起始 IP 小于等于目标 IP 的索引再校验目标 IP 是否落在该段的结束 IP 之内。数据区读取用逐字节方式直到遇到\0这是纯真系 dat 的常见约定。参数说明dat_path传 utf8 或 gbk 文件路径如果换成 gbk 版本最后一行decode(utf-8)要改成decode(gbk)否则中文乱码。record_size如果对不上查询会整体错位表现为返回 None 或乱码这时候要回去核对文件头。3.2 Go 语言版本的内存映射与并发安全写法Go 版本适合放进高并发服务IpSearch.go原始实现是每次查询都 seekQPS 高了会有锁竞争。我一般会改成启动时把索引区全量读进内存切片数据区保留文件句柄按需读这样查询路径无锁。package main import ( encoding/binary fmt os ) type IPQuery struct { f *os.File indexStart int64 recordSize int64 starts []uint32 } func NewIPQuery(path string) (*IPQuery, error) { f, err : os.Open(path) if err ! nil { return nil, err } q : IPQuery{f: f, recordSize: 13} header : make([]byte, 4) f.ReadAt(header, 0) q.indexStart int64(binary.LittleEndian.Uint32(header)) stat, _ : f.Stat() count : (stat.Size() - q.indexStart) / q.recordSize q.starts make([]uint32, 0, count) buf : make([]byte, q.recordSize) for i : int64(0); i count; i { f.ReadAt(buf, q.indexStarti*q.recordSize) q.starts append(q.starts, binary.LittleEndian.Uint32(buf[0:4])) } return q, nil } func (q *IPQuery) Query(ip uint32) (string, error) { lo, hi : 0, len(q.starts)-1 for lo hi { mid : (lo hi 1) / 2 if q.starts[mid] ip { lo mid } else { hi mid - 1 } } buf : make([]byte, q.recordSize) if _, err : q.f.ReadAt(buf, q.indexStartint64(lo)*q.recordSize); err ! nil { return , err } endIP : binary.LittleEndian.Uint32(buf[4:8]) if ip endIP { return , nil } dataOffset : int64(binary.LittleEndian.Uint32(buf[8:12])) var out []byte tmp : make([]byte, 1) for { if _, err : q.f.ReadAt(tmp, dataOffset); err ! nil { break } if tmp[0] 0 { break } out append(out, tmp[0]) dataOffset } return string(out), nil } func main() { q, _ : NewIPQuery(qqzeng-ip-china-utf8.dat) ip : uint32(11424 | 11416 | 1148 | 114) loc, _ : q.Query(ip) fmt.Println(loc) }逻辑说明NewIPQuery在初始化阶段把索引区的起始 IP 全部读进starts切片查询时只做内存二分不再碰索引区文件。Query接收的是已经转成 uint32 的 IP避免每次查询重复解析字符串。数据区读取用ReadAt它是并发安全的多个 goroutine 同时查不会互相干扰。参数说明recordSize同样是 13如果 dat 版本变了要同步改。ip的构造用位运算比net.ParseIP再转 uint32 快适合热点路径。如果返回空字符串说明该 IP 不在库覆盖范围内业务上要兜底成「未知」。3.3 把查询封装成可复用模块的目录建议不管用哪种语言我都建议把 dat 文件和查询代码放在独立目录比如pkg/ipdb/对外只暴露一个Query(ip string) (string, error)。这样以后换库、加缓存、做降级都只改一个地方。Python 里可以做成单例Go 里用sync.Once初始化Java 里用静态块PHP 里用静态变量。别把 dat 路径硬编码在业务代码里用配置文件或环境变量传进去。4. Java 与 PHP 接入老项目里怎么少改代码4.1 Java RandomAccessFile 查询与字符集处理Java 版本用RandomAccessFile最省事不用引入任何第三方库。IpSearch.java的核心是seek加readInt但要注意字节序dat 是小端Java 的readInt是大端必须手动翻转。import java.io.RandomAccessFile; import java.nio.charset.Charset; public class IPQuery { private RandomAccessFile raf; private long indexStart; private int recordSize 13; private long count; private long[] starts; public IPQuery(String path, String charset) throws Exception { raf new RandomAccessFile(path, r); raf.seek(0); indexStart readLittleEndianInt(); long fileSize raf.length(); count (fileSize - indexStart) / recordSize; starts new long[(int) count]; for (int i 0; i count; i) { raf.seek(indexStart (long) i * recordSize); starts[i] readLittleEndianInt() 0xFFFFFFFFL; } } private int readLittleEndianInt() throws Exception { int b1 raf.read(); int b2 raf.read(); int b3 raf.read(); int b4 raf.read(); return (b4 24) | (b3 16) | (b2 8) | b1; } public String query(String ip) throws Exception { long target ipToLong(ip); int lo 0, hi starts.length - 1; while (lo hi) { int mid (lo hi 1) 1; if (starts[mid] target) lo mid; else hi mid - 1; } raf.seek(indexStart (long) lo * recordSize); long startIP readLittleEndianInt() 0xFFFFFFFFL; long endIP readLittleEndianInt() 0xFFFFFFFFL; long dataOffset readLittleEndianInt() 0xFFFFFFFFL; if (target endIP) return null; raf.seek(dataOffset); byte[] buf new byte[64]; int len 0; while (true) { int b raf.read(); if (b 0 || b -1) break; buf[len] (byte) b; } return new String(buf, 0, len, Charset.forName(charset)); } private long ipToLong(String ip) { String[] p ip.split(\\.); return (Long.parseLong(p[0]) 24) | (Long.parseLong(p[1]) 16) | (Long.parseLong(p[2]) 8) | Long.parseLong(p[3]); } }逻辑说明readLittleEndianInt手动按小端拼字节这是整个 Java 版本最容易出错的地方直接用readInt会得到完全错误的偏移量。starts数组存的是无符号 32 位值用 0xFFFFFFFFL转成 long 避免负数比较出错。字符集通过构造参数传入utf8 版本传UTF-8gbk 版本传GBK。参数说明path是 dat 文件路径charset决定解码方式。如果查询返回 null先确认 IP 是否在库范围内再检查recordSize是否匹配。Java 项目里建议把这个类做成 Spring 的Component启动时初始化一次。4.2 PHP 读取 gbk dat 的 fseek 实现PHP 版本在IpSearch.php里用的是fopenfseek适合老 Web 项目。gbk 版本在 PHP 里反而更省事因为很多老环境的默认输出就是 GBK不用转码。?php class IPQuery { private $fp; private $indexStart; private $recordSize 13; private $starts []; public function __construct($path) { $this-fp fopen($path, rb); fseek($this-fp, 0); $header fread($this-fp, 4); $this-indexStart unpack(V, $header)[1]; fseek($this-fp, 0, SEEK_END); $fileSize ftell($this-fp); $count intval(($fileSize - $this-indexStart) / $this-recordSize); for ($i 0; $i $count; $i) { fseek($this-fp, $this-indexStart $i * $this-recordSize); $buf fread($this-fp, 4); $this-starts[] unpack(V, $buf)[1]; } } public function query($ip) { $target ip2long($ip); $lo 0; $hi count($this-starts) - 1; while ($lo $hi) { $mid ($lo $hi 1) 1; if ($this-starts[$mid] $target) $lo $mid; else $hi $mid - 1; } fseek($this-fp, $this-indexStart $lo * $this-recordSize); $buf fread($this-fp, $this-recordSize); $data unpack(Vstart/Vend/Voffset, $buf); if ($target $data[end]) return null; fseek($this-fp, $data[offset]); $str ; while (($ch fgetc($this-fp)) ! false $ch ! \0) { $str . $ch; } return $str; } }逻辑说明unpack(V, ...)直接按小端解析省去手动翻转。ip2long在 32 位 PHP 上可能返回负数64 位环境正常如果遇到负数比较异常用sprintf(%u, ip2long($ip))转成无符号字符串再比较。gbk 版本读出来的$str直接就是 GBK 字节流输出到 GBK 页面不用转码。参数说明$path传 gbk 或 utf8 文件路径。如果页面是 UTF-8 而 dat 是 gbk需要mb_convert_encoding($str, UTF-8, GBK)。recordSize同样要核对。4.3 四种语言接入的共性检查清单不管用哪种语言接入后先跑这三个 IP 验证114.114.114.114江苏南京、223.5.5.5浙江杭州、8.8.8.8通常返回国外或未知。如果三个结果都合理说明文件头和 recordSize 对上了。如果全部返回 null八成是indexStart读错如果返回乱码是编码选错如果返回的省市明显错位是recordSize不对。这三个检查点能覆盖九成接入问题。5. 避坑与排查那些让我加班到凌晨的细节5.1 现象查询结果全是 null一条都命中不了原因indexStart读成了大端或者文件头长度不是 4 字节。有些 dat 版本文件头是 8 字节前 4 字节是魔数后 4 字节才是索引偏移。解决用十六进制工具打开 dat看前 16 个字节确认索引区起始位置。如果前 4 字节是固定魔数就往后偏移 4 字节再读。5.2 现象中文显示为「锟斤拷」或问号原因utf8 的 dat 用 gbk 解码或者反过来。解决确认 dat 文件名后缀和代码里的 decode 字符集一致。Python 里decode(utf-8)对应 utf8 文件decode(gbk)对应 gbk 文件。Java 里Charset.forName(UTF-8)同理。PHP 里如果页面是 UTF-8 而 dat 是 gbk必须显式转码。5.3 现象部分 IP 查询结果偏移返回了隔壁省市的归属地原因recordSize和实际索引记录长度不一致导致二分查找定位到的索引条目错位。解决核对 dat 版本的索引记录长度常见是 13 字节4 起始 4 结束 4 偏移 1 标志也有 12 字节或 14 字节的版本。用文件总大小减去索引起始位置除以记录数反推 recordSize。5.4 现象高并发下查询变慢CPU 飙高原因每次查询都重新打开文件或重复解析索引。解决初始化时把索引区加载到内存文件句柄复用。Go 里用ReadAt保证并发安全Java 里用synchronized包一层或每个线程独立RandomAccessFilePython 里用单例加锁。别在热点路径里反复open。5.5 现象dat 文件更新后查询报错或结果异常原因新版本 dat 的格式可能微调旧代码的recordSize或文件头解析不兼容。解决每次更新 dat 后先用一个已知 IP 跑一遍验证再上线。我一般会在 CI 里加一个冒烟测试固定查三个 IP结果不对就阻断发布。6. 进阶把 dat 库接进日志管道与校验脚本跑通基础查询之后真正省事的是把它接进日志处理链路。我现在的做法是在日志采集端做一次 IP 富化Nginx 日志里的$remote_addr在写入时就用这套库补上省市字段后面做地域聚合、异常登录检测就不用再回头查了。Python 脚本里可以用concurrent.futures批量处理Go 里直接在日志中间件里调Query延迟增加不到一微秒。另一个值得做的是版本校验脚本。dat 文件更新到 2025 年 08 月 08 日这个版本后我会跑一个固定 IP 列表把结果和上一版对比输出差异行。这样能快速发现新版本是否引入了归属地漂移。下面这个 Python 片段就是我做差异对比用的import json def diff_versions(old_file, new_file, ip_list): from ip_query import IPQuery # 假设上面的类放在 ip_query.py old_q IPQuery(old_file) new_q IPQuery(new_file) diffs [] for ip in ip_list: o old_q.query(ip) n new_q.query(ip) if o ! n: diffs.append({ip: ip, old: o, new: n}) return diffs if __name__ __main__: ips [114.114.114.114, 223.5.5.5, 119.29.29.29, 180.76.76.76] result diff_versions(qqzeng-ip-china-utf8-old.dat, qqzeng-ip-china-utf8.dat, ips) print(json.dumps(result, ensure_asciiFalse, indent2))逻辑说明diff_versions同时加载新旧两个 dat对同一批 IP 查询并比对结果输出差异。ip_list建议覆盖三大运营商和常见公共 DNS这样能同时验证电信、联通、移动、教育网的段是否更新。参数上old_file是上一版备份new_file是刚下载的版本跑完确认差异在预期范围内再替换生产文件。还有一个习惯每次更新 dat 后我会把文件大小和 MD5 记在项目的CHANGELOG里方便回滚时确认拿的是哪一版。这套库本身不复杂但 IP 归属地这东西差一个版本就可能让风控规则误伤一批用户。从那以后我每次替换 dat 文件都强制走一遍「三 IP 冒烟 新旧差异对比 MD5 记录」再也没出现过上线后归属地漂移的事。希望帮到你。本文还有配套的精品资源点击获取