黑白名单
黑白名单
1. 引言
IoTDB 是一款针对物联网场景设计的时间序列数据库，支持高效的数据存储、查询和分析。随着物联网技术的广泛应用，数据安全性和访问控制变得至关重要。在开放环境中，如何保证合法用户对数据的安全访问成为了一项关键挑战。白名单机制仅允许可信 IP 或用户接入，从源头缩小攻击面；黑名单功能则能在边缘与云端协同场景下实时拦截恶意 IP，阻断非法访问、SQL 注入、暴力破解及 DDoS 等威胁，为数据传输提供持续、稳定的安全保障。
黑白名单同时支持 IPv4 地址、IPv6 精确地址和 IPv4/IPv6 CIDR 网段，并保留现有 IPv4 星号（*）通配能力。
注意：黑白名单功能从 V2.0.6.1 版本开始提供。
2. 白名单
2.1 功能描述
通过开启白名单功能、配置白名单列表，指定允许连接 IoTDB 的客户端地址，来限制仅在白名单范围内的客户端才能够访问 IoTDB，从而实现安全控制。
2.2 配置参数
管理员可以通过以下两种方式来启用/禁用白名单功能以及添加、修改、删除白名单ip/ip段。
- 编辑配置文件
iotdb-system.properties进行维护 - 通过 set configuration 语句进行维护
- 表模型请参考：set configuration
相关参数如下：
| 名称 | 描述 | 默认值 | 生效方式 | 示例 |
|---|---|---|---|---|
enable_white_list | 是否启用白名单功能。true：启用；false：禁用。字段值不区分大小写。 | false | 热加载 | set enable_white_list = 'true' |
white_ip_list | 添加、修改、删除白名单 IP/IP 段，支持精确匹配；多个条目以逗号分隔。支持 IPv4/IPv6 地址、CIDR 网段以及兼容的 IPv4 星号通配项。IPv4 前缀长度支持 0–32，IPv6 前缀长度支持 0–128；IPv6 支持完整写法、压缩写法和大小写混合写法。支持 IPv4-mapped IPv6（如 ::ffff:192.0.2.10），按 IPv6 规则处理。多个条目可以混合配置。IPv6 地址及 IPv4/IPv6 CIDR 网段自 V2.0.12.1 起支持。 | 空 | 热加载 | set configuration white_ip_list='127.0.0.1,::1,192.168.32.0/24,2001:db8:200::/48'兼容 IPv4 星号通配： set configuration white_ip_list='192.168.1.200,192.168.1.201,192.168.1.*' |
3. 黑名单
3.1 功能描述
通过开启黑名单功能、配置黑名单列表，阻止某些特定 IP 地址访问数据库，来防止非法访问、SQL注入、暴力破解、DDoS攻击等安全威胁，从而确保数据传输过程中的安全性和稳定性。
3.2 配置参数
管理员可以通过以下两种方式来启用/禁用黑名单功能以及添加、修改、删除黑名单 ip/ip 段。
- 编辑配置文件
iotdb-system.properties进行维护 - 通过 set configuration 语句进行维护
- 表模型请参考：set configuration
相关参数如下：
| 名称 | 描述 | 默认值 | 生效方式 | 示例 |
|---|---|---|---|---|
enable_black_list | 是否启用黑名单功能。true：启用；false：禁用。字段值不区分大小写。 | false | 热加载 | set enable_black_list = 'true' |
black_ip_list | 添加、修改、删除黑名单 IP/IP 段，支持精确匹配；多个条目以逗号分隔。支持 IPv4/IPv6 地址、CIDR 网段以及兼容的 IPv4 星号通配项。IPv4 前缀长度支持 0–32，IPv6 前缀长度支持 0–128；IPv6 支持完整写法、压缩写法和大小写混合写法。支持 IPv4-mapped IPv6（如 ::ffff:192.0.2.10），按 IPv6 规则处理。多个条目可以混合配置。IPv6 地址及 IPv4/IPv6 CIDR 网段自 V2.0.12.1 起支持。 | 空 | 热加载 | set configuration black_ip_list='192.0.2.10,2001:db8:bad::/48'兼容 IPv4 星号通配： set configuration black_ip_list='192.168.1.200,192.168.1.201,192.168.1.*' |
4. 注意事项
IPv6 地址支持完整写法、压缩写法和大小写混合写法。例如
2001:0db8:0000:0000:0000:0000:0000:0001、2001:db8::1和2001:DB8::1表示同一个地址；::在同一个 IPv6 地址中最多出现一次。IPv6 精确地址可写成不带前缀的地址，也可显式写成/128，例如2001:db8:200::bad和2001:db8:200::bad/128均表示单个地址。CIDR 前缀范围为 IPv4
/0–/32、IPv6/0–/128。推荐填写主机位为 0 的规范网络地址，例如2001:db8:200::/64。CIDR 地址主机位非零时，系统按最终产品配置的自动规范化或严格拒绝策略处理。IPv4 规则和 IPv6 规则按地址族分别匹配，不自动跨族匹配。例如，
192.0.2.10不自动匹配::ffff:192.0.2.10；如需同时允许两种连接地址，应分别配置white_ip_list=192.0.2.10,::ffff:192.0.2.10。黑白名单仅支持单个 IP 地址和 CIDR 网段。主机名或 DNS 名称（如
example.com）、带端口的地址（如[2001:db8::1]:6667）、IPv6 星号通配（如2001:db8::*）和起止地址范围（如2001:db8::1-2001:db8::ff）均为无效配置。加载配置文件时，系统应跳过无效条目并记录错误日志，其他有效条目继续生效；通过set configuration提交的配置若包含非法条目，命令应失败并保留上一份有效配置，不得将白名单清空。错误日志包含配置项和无效条目，便于定位配置问题。开启白名单后，只有命中白名单的客户端可以连接；白名单为空时拒绝所有连接。使用 IPv6 回环地址连接本机时，应将
::1加入白名单；使用其他本机 IPv6 地址时，应将对应地址或网段加入白名单。黑名单优先级高于白名单。同一地址同时命中两类规则时拒绝连接。黑白名单配置均支持热加载，规则更新后按现有产品行为处理新连接和不再符合规则的已有连接。
保留现有 IPv4 星号通配示例，并明确该通配能力仅适用于 IPv4；IPv6 网段应使用 CIDR 表示，例如
2001:db8:200::/48，不使用*表示地址段。配置支持重复IP，内存中会自动去重且无提示。如需去重请手动修改。
黑/白名单规则仅对新连接生效，功能开启前的现有连接不受影响，其后续重连才会被拦截。