Skip to content

IP_WHITELIST.md

Latest commit

 

History

History
313 lines (244 loc) · 6.35 KB

IP_WHITELIST.md

File metadata and controls

313 lines (244 loc) · 6.35 KB
Raw

IP 白名单功能

本文档介绍 SNI 代理服务器的 IP 白名单功能。

功能概述

IP 白名单功能允许你限制只有特定 IP 地址或 IP 网段的客户端才能使用 SNI 代理服务。这为代理服务器提供了额外的访问控制层，可以有效防止未授权的访问。

工作原理

当客户端尝试连接到代理服务器时：

  1. IP 检查（如果配置了 IP 白名单）

    • 服务器首先检查客户端的 IP 地址是否在白名单中
    • 如果不在白名单中，连接会立即被拒绝，不会进行后续的 SNI 解析和域名白名单检查
    • 如果在白名单中，继续进行下一步

  2. SNI 解析

    • 解析 TLS Client Hello 中的 SNI（Server Name Indication）字段
    • 提取目标域名

  3. 域名白名单检查

    • 检查目标域名是否在域名白名单中
    • 根据配置决定直连或通过 SOCKS5 代理

配置格式

在 config.json 中添加 ip_whitelist 字段：

{
  "listen_addr": "0.0.0.0:8443",
  "whitelist": [
    "www.google.com",
    "github.com"
  ],
  "ip_whitelist": [
    "127.0.0.1",           // 单个 IPv4 地址
    "192.168.1.0/24",      // IPv4 CIDR 网段
    "10.0.0.0/8",          // IPv4 私有网段
    "::1",                 // 单个 IPv6 地址
    "fe80::/10",           // IPv6 链路本地地址
    "2001:db8::/32"        // IPv6 CIDR 网段
  ]
}

支持的 IP 格式

1. 单个 IPv4 地址

"ip_whitelist": [
  "192.168.1.100",
  "10.0.0.5"
]

2. IPv4 CIDR 网段

"ip_whitelist": [
  "192.168.1.0/24",      // 192.168.1.0 - 192.168.1.255
  "10.0.0.0/8",          // 10.0.0.0 - 10.255.255.255
  "172.16.0.0/12"        // 172.16.0.0 - 172.31.255.255
]

3. 单个 IPv6 地址

"ip_whitelist": [
  "::1",                 // IPv6 localhost
  "2001:db8::1"
]

4. IPv6 CIDR 网段

"ip_whitelist": [
  "fe80::/10",           // 链路本地地址
  "2001:db8::/32",       // 文档用例
  "::/0"                 // 所有 IPv6 地址（不推荐）
]

常用配置示例

示例 1: 仅允许本地访问

{
  "ip_whitelist": [
    "127.0.0.1",
    "127.0.0.0/8",
    "::1"
  ]
}

示例 2: 允许内网访问

{
  "ip_whitelist": [
    "127.0.0.0/8",         // 本地回环
    "10.0.0.0/8",          // 私有网段 A
    "172.16.0.0/12",       // 私有网段 B
    "192.168.0.0/16",      // 私有网段 C
    "::1",                 // IPv6 本地
    "fe80::/10"            // IPv6 链路本地
  ]
}

示例 3: 允许特定子网

{
  "ip_whitelist": [
    "192.168.1.0/24",      // 办公网络
    "192.168.2.0/24",      // 开发网络
    "203.0.113.0/24"       // 公网 IP 段
  ]
}

示例 4: 混合 IPv4 和 IPv6

{
  "ip_whitelist": [
    "192.168.1.0/24",
    "10.0.0.1",
    "2001:db8::/32",
    "fe80::1"
  ]
}

禁用 IP 白名单

如果不想限制 IP 访问，有两种方式：

方式 1: 省略 ip_whitelist 字段

{
  "listen_addr": "0.0.0.0:8443",
  "whitelist": [
    "www.google.com"
  ]
  // 没有 ip_whitelist 字段
}

方式 2: 设置为空数组

{
  "listen_addr": "0.0.0.0:8443",
  "whitelist": [
    "www.google.com"
  ],
  "ip_whitelist": []
}

检查优先级

代理服务器的检查顺序如下：

客户端连接
    ↓
1. IP 白名单检查（如果配置了）
    ├─ 不通过 → 拒绝连接
    └─ 通过 → 继续
    ↓
2. 读取并解析 TLS Client Hello
    ↓
3. 提取 SNI 域名
    ↓
4. 域名白名单检查
    ├─ SOCKS5 白名单（优先）
    ├─ 直连白名单
    └─ 不匹配 → 拒绝连接
    ↓
5. 建立连接并转发数据

性能考虑

  • 精确 IP 匹配: O(1) 时间复杂度（使用 HashSet）
  • CIDR 网段匹配: O(n) 时间复杂度（n 为 CIDR 规则数量）
  • 早期拒绝: IP 不匹配的连接会在 SNI 解析之前被拒绝，节省资源

日志输出

启用 IP 白名单后，日志中会显示：

[INFO] 加载了 5 个 IP 白名单规则
  [IP 1] 127.0.0.1
  [IP 2] 192.168.1.0/24
  [IP 3] 10.0.0.0/8
  [IP 4] ::1
  [IP 5] 2001:db8::/32

被拒绝的连接会记录：

[WARN] IP 203.0.113.45 不在白名单中，拒绝连接

通过的连接会记录（debug 级别）：

[DEBUG] IP 192.168.1.100 通过白名单检查

安全建议

  1. 最小权限原则: 只添加必要的 IP 地址或网段到白名单
  2. 定期审查: 定期检查和更新 IP 白名单，移除不再需要的条目
  3. 监控日志: 关注被拒绝的连接，识别潜在的未授权访问尝试
  4. 分层防护: IP 白名单应与域名白名单结合使用，提供多层安全防护
  5. 避免 0.0.0.0/0: 不要使用 0.0.0.0/0 或 ::/0，这会允许所有 IP 访问

示例配置文件

完整的配置示例请参考：

  • config-ip-whitelist.json - IP 白名单配置示例
  • config.example.json - 包含 IP 白名单的完整配置示例

故障排除

问题: 本地测试连接被拒绝

解决方案: 确保 IP 白名单中包含 127.0.0.1 或 127.0.0.0/8

{
  "ip_whitelist": ["127.0.0.1"]
}

问题: 内网机器无法连接

解决方案: 添加内网 IP 段到白名单

{
  "ip_whitelist": [
    "192.168.0.0/16",
    "10.0.0.0/8",
    "172.16.0.0/12"
  ]
}

问题: 不确定客户端 IP

解决方案: 临时禁用 IP 白名单（设置为空数组），查看日志中的客户端 IP

{
  "ip_whitelist": []
}

然后从日志中找到客户端 IP：

[DEBUG] 接受来自 192.168.1.100:54321 的新连接

与其他功能的组合

与双白名单结合使用

{
  "listen_addr": "0.0.0.0:8443",
  "whitelist": [
    "github.com",
    "*.github.io"
  ],
  "socks5_whitelist": [
    "*.anthropic.com",
    "claude.ai"
  ],
  "ip_whitelist": [
    "192.168.1.0/24"
  ],
  "socks5": {
    "addr": "127.0.0.1:1080"
  }
}

在这个配置中：

  • 只有 192.168.1.0/24 网段的 IP 可以连接
  • 这些 IP 访问 *.anthropic.com 和 claude.ai 时使用 SOCKS5
  • 访问 github.com 和 *.github.io 时直连

参考资料