使用Python ipaddress模块进行离线IP校验与子网归属判定

本文由Gemini辅助撰写，示例代码已在Linux Python 3环境执行验证。

背景与应用场景

在服务端开发与基础运维脚本编写过程中，处理客户端来源 IP、校验防火墙白名单以及解析配置中的 CIDR 网段是常见的基础需求。直接使用正则表达式匹配 IP 地址往往容易遗漏复杂的边界条件，例如十进制溢出（如 192.168.1.300）、带掩码的复合格式混淆或 IPv6 的各种缩写变体。此外，对网络地址属性（如私网保留地址、环回地址、公网地址）以及子网归属的判定，若自行编写逻辑极易产生缺陷。

Python 3 自带的标准库 ipaddress 提供了完备的离线网络对象封装，能够安全地解析、操作 IPv4 与 IPv6 的地址与网络掩码，免除对第三方依赖的诉求。

核心概念与运行机制

1. 地址与网络的分离：
   ipaddress.ip_address 专门用于表示单个主机地址，若传入包含掩码的字符串（例如 10.0.0.1/24），该方法会将其视作格式错误并抛出 ValueError；而 ipaddress.ip_network 则表示一个网络网段或 CIDR 范围。
2. 严格网络模式（strict 模式）：
   当使用 ipaddress.ip_network 创建网段对象时，参数 strict 默认为 True。这意味着掩码指定前缀之外的主机位必须全为零。如果传入 10.0.1.0/16，由于 /16 掩码对应的网络前缀为前 16 位，而第三段（第 17~24 位）存在非零值 1，strict=True 将判定其非法并抛出 ValueError。若设置为 strict=False，模块会自动将所有主机位掩码清零，返回合法的基准网段对象。
3. 内置属性判断与包含检测：
   地址对象封装了布尔属性，如 is_private（私网地址）、is_loopback（环回地址）、is_global（全球单播公网地址）等，同时支持直接通过 Python 的 in 操作符判定某 IP 是否包含于特定的网络区间中。

验证代码实现

以下代码展示了如何对 IPv4 与 IPv6 地址进行有效性校验、网段包含判断以及处理非标准格式输入：

import ipaddress

# 1. 验证合法 IPv4 / IPv6 地址解析及属性识别
ip_v4 = ipaddress.ip_address("10.0.4.15")
assert ip_v4.version == 4
assert ip_v4.is_private is True
assert not ip_v4.is_loopback

# 显式校验 IPv6 文档保留网段(RFC 3849)与公网地址归属
doc_v6 = ipaddress.ip_address("2001:db8::1")
assert doc_v6.version == 6
assert doc_v6 in ipaddress.ip_network("2001:db8::/32")
assert doc_v6.is_private is True

public_v6 = ipaddress.ip_address("2606:4700:4700::1111")
assert public_v6.is_global is True
assert not public_v6.is_private

# 2. 验证非法 IP 字符串解析时准确抛出 ValueError
invalid_ips = ["192.168.1.300", "not_an_ip", "10.0.0.1/24"]
for raw in invalid_ips:
    try:
        ipaddress.ip_address(raw)
        assert False, f"Expected ValueError for {raw}"
    except ValueError:
        pass

# 3. 验证 CIDR 子网包含关系判定
trusted_network = ipaddress.ip_network("10.0.0.0/16")
assert ip_v4 in trusted_network

outside_ip = ipaddress.ip_address("10.1.0.1")
assert outside_ip not in trusted_network

# 4. 验证严格网络定义（strict=True 拒绝主机位非零的前缀）
try:
    ipaddress.ip_network("10.0.1.0/16", strict=True)
    assert False, "Expected ValueError when host bits are set in strict mode"
except ValueError:
    pass

relaxed_network = ipaddress.ip_network("10.0.1.0/16", strict=False)
assert relaxed_network.network_address == ipaddress.IPv4Address("10.0.0.0")

print("MATERIAL_OK")

执行结果说明

该脚本在 Linux Python 3 隔离环境中运行，所有断言验证均顺序通过，最终控制台输出标准结果：

MATERIAL_OK

运行过程验证了如下关键路径：

• 10.0.4.15 正确识别为 IPv4 私网地址，且不在环回区间（127.0.0.0/8）。
• 传入带掩码的 10.0.0.1/24 时，ip_address 抛出 ValueError，避免了配置解析时的格式歧义。
• ip_v4 in trusted_network 正确完成 CIDR 掩码位运算比对，而跨段的 10.1.0.1 则被精确识别为网段外地址。
• 严格模式下杜绝了脏网段配置被静默接收的隐患。

边界条件与排错指引

在将 ipaddress 模块应用于自动化白名单或地址过滤时，需注意以下边界情况：

1. 作用域与功能边界：
   ipaddress 属于纯粹的离线内存字符串和字节解析工具。它不发起任何底层网络 Socket 调用，不检查主机实际是否开机或可达，也不负责将域名（如 example.com）解析为 IP。如果输入源包含域名，必须先通过 DNS 模块完成解析。
2. 用户输入前导零或非法空白：
   Python 在部分版本中对包含前导零的十进制 IP（例如 192.168.01.1）解析较严格，可能直接抛出 ValueError 以防止混淆为八进制。在接收用户原始输入时，建议调用 .strip() 移除多余空白字符。
3. 接口地址与网段混淆：
   若配置中确实需要同时保存主机 IP 和其所属掩码（例如 192.168.1.10/24），应使用 ipaddress.ip_interface 类而不是 ipaddress.ip_address 或 ipaddress.ip_network。ip_interface 能够同时保留接口主机地址与完整网段信息。

参考文档

• Python 官方标准库文档：ipaddress — IPv4/IPv6 manipulation library (Python 3 官方文档（对应模块与章节）)