flex-rate-limit
  • 简体中文

      • IP 白名单与限流配置场景说明

      项目: flex-rate-limit
      日期: 2026-02-05
      文档类型: 配置场景详解

      📋 四个核心问题解答

      问题 1: 限流配置了 /internal，但白名单没配置 /internal

      代码示例：

      // 只配置限流，不配置白名单
const internalLimiter = createRateLimiter({ max: 500 });

app.get('/api/internal/stats',
  internalLimiter,  // 只有限流，没有白名单中间件
  (req, res) => {
    // 业务处理
  }
);

      处理结果：

      所有 IP 都可以访问（无白名单限制）
  ↓
应用限流（500次/分钟）
  ↓
未超限 → 200 OK
超限 → 429 Too Many Requests

      关键逻辑：

      // 白名单配置的关键代码
isRouteWhitelisted(route, ip) {
  const whitelist = this.routeWhitelists[route];
  if (!whitelist || whitelist.length === 0) {
    return true; // ⚠️ 未配置白名单 = 允许所有 IP
  }
  // ...检查逻辑
}

      总结：

      • ✅ 不配置白名单 = 对所有 IP 开放
      • ✅ 所有 IP 都能访问，但要受限流限制
      • 📊 适用场景：公开 API（如 /api/public/data）

      问题 2: 白名单配置了 /internal，但限流没配置 /internal

      代码示例：

      // 只配置白名单，不配置限流
const internalWhitelist = ipWhitelistMiddleware('/api/internal');

app.get('/api/internal/stats',
  internalWhitelist,  // 只有白名单，没有限流中间件
  (req, res) => {
    // 业务处理
  }
);

      处理结果：

      检查白名单
  ↓ 不在白名单
403 Forbidden（拒绝访问）

  ↓ 在白名单内
继续执行（没有限流检查）
  ↓
200 OK（无限制访问）⚠️

      关键点：

      • ✅ 非白名单 IP → 403 Forbidden
      • ⚠️ 白名单 IP → 无限制访问（没有限流保护）
      • ❌ 安全隐患：白名单 IP 可以无限请求

      总结：

      • ⚠️ 不推荐这种配置
      • 建议：白名单 + 限流一起配置
      • 📊 极少场景：内部监控接口可能不需要限流

      问题 3: 白名单配置了 /internal，限流也配置了 /internal

      代码示例（推荐配置）：

      // 白名单 + 限流都配置（推荐）
const internalWhitelist = ipWhitelistMiddleware('/api/internal');
const internalLimiter = createRateLimiter({ max: 500 });

app.get('/api/internal/stats',
  internalWhitelist,  // 第一层：白名单验证
  internalLimiter,    // 第二层：限流控制
  (req, res) => {
    // 业务处理
  }
);

      处理结果：

      第一层：白名单验证
  ↓ 不在白名单
  403 Forbidden（立即拒绝）
  
  ↓ 在白名单内
第二层：限流检查
  ↓ 未超限
  200 OK
  
  ↓ 超限
  429 Too Many Requests

      详细流程：

      步骤IP 类型白名单验证限流检查最终结果
      1非白名单 IP❌ 不通过-403 Forbidden
      2白名单 IP（请求 1-500）✅ 通过✅ 未超限200 OK
      3白名单 IP（请求 501+）✅ 通过❌ 超限429 Too Many Requests

      配置示例：

      // config/ip-whitelist.json 或环境变量
{
  "routes": {
    "/api/internal": ["10.0.0.0/8", "192.168.0.0/16"]
  }
}

// 环境变量
INTERNAL_IP_WHITELIST=10.0.0.0/8,192.168.0.0/16

      总结：

      • ✅ 最推荐的配置方式
      • ✅ 双重保护：访问控制 + 速率控制
      • ✅ 完全独立：白名单验证不影响限流
      • 📊 适用场景：管理后台、内部 API、敏感操作

      问题 4: 白名单能否配置全局路由

      答案：✅ 可以，而且非常推荐！

      方式 1: 全局白名单（所有路由生效）

      配置方式：

      // 1. 环境变量配置
GLOBAL_IP_WHITELIST=127.0.0.1,192.168.1.100,192.168.1.200

// 2. 配置文件
{
  "global": ["127.0.0.1", "192.168.1.100", "192.168.1.200"]
}

// 3. 代码配置
ipConfig.globalWhitelist = ['127.0.0.1', '192.168.1.100'];

      工作原理：

      isGlobalWhitelisted(ip) {
  if (this.globalWhitelist.length === 0) return true;
  return this.globalWhitelist.includes(ip);
}

// 在白名单中间件中
if (ipConfig.isGlobalWhitelisted(clientIP)) {
  return next(); // ✅ 全局白名单直接通过
}

      效果：

      全局白名单 IP：
  → 所有路由都无需白名单验证
  → 但仍然受各自路由的限流限制 ✅
  
非全局白名单 IP：
  → 检查路由级白名单
  → 如果路由也没配置白名单 = 允许访问

      方式 2: 全局白名单 + 路由白名单组合

      配置示例：

      // 全局白名单（所有路由通用）
GLOBAL_IP_WHITELIST=127.0.0.1,192.168.1.100

// 路由级白名单（特定路由额外白名单）
ADMIN_IP_WHITELIST=192.168.1.10,192.168.1.11
INTERNAL_IP_WHITELIST=10.0.0.0/8,192.168.0.0/16

      优先级：

      全局白名单 > 路由白名单

如果在全局白名单：
  → 跳过路由白名单检查
  → 直接通过验证
  
如果不在全局白名单：
  → 检查路由白名单
  → 根据路由白名单判断

      使用场景对比

      场景全局白名单路由白名单推荐配置
      办公室网络✅ 所有员工 IP-全局白名单
      管理后台✅ 管理员 IP✅ 额外授权 IP全局 + 路由
      内部 API-✅ 内网 IP 段路由白名单
      VIP 功能-✅ VIP 客户 IP路由白名单
      公开 API--不配置白名单

      🎯 配置决策树

      开始：我要为 /api/internal 配置访问控制
│
├─ 问题 1：是否需要限制访问 IP？
│  ├─ 否 → 不配置白名单（所有 IP 可访问）
│  │      → 继续问题 2
│  └─ 是 ↓
│
├─ 问题 1.1：谁可以访问？
│  ├─ 所有办公室员工 → 配置全局白名单
│  ├─ 特定部门/角色 → 配置路由白名单
│  └─ 内网 IP 段 → 配置路由白名单（CIDR）
│  → 继续问题 2
│
├─ 问题 2：是否需要限流？
│  ├─ 否 → 不配置限流（不推荐）⚠️
│  └─ 是 ↓
│
└─ 问题 2.1：限流级别？
   ├─ 敏感操作（删除/修改）→ 低限流（10-50次/分钟）
   ├─ 普通操作（查询）→ 中限流（100-500次/分钟）
   └─ 高频操作（监控/统计）→ 高限流（1000-5000次/分钟）

      📋 完整配置示例

      示例 1: 公开 API（无白名单 + 限流）

      // 配置：不限制访问 IP，但有限流
const publicLimiter = createRateLimiter({ max: 100 });

app.get('/api/public/data',
  publicLimiter,  // 只限流
  handler
);

// 效果：
// - 任何 IP 都可以访问
// - 限流：100次/分钟

      示例 2: 管理后台（路由白名单 + 限流）

      // 配置：只允许特定 IP + 限流
// 环境变量：ADMIN_IP_WHITELIST=192.168.1.10,192.168.1.11

const adminWhitelist = ipWhitelistMiddleware('/api/admin');
const adminLimiter = createRateLimiter({ max: 200 });

app.get('/api/admin/users',
  adminWhitelist,  // 白名单验证
  adminLimiter,    // 限流控制
  handler
);

// 效果：
// - 非白名单 IP → 403 Forbidden
// - 白名单 IP（1-200次）→ 200 OK
// - 白名单 IP（201+次）→ 429 Too Many Requests

      示例 3: 内部 API（IP 段白名单 + 高限流）

      // 配置：只允许内网 IP 段 + 高限流
// 环境变量：INTERNAL_IP_WHITELIST=10.0.0.0/8,192.168.0.0/16

const internalWhitelist = ipWhitelistMiddleware('/api/internal');
const internalLimiter = createRateLimiter({ max: 5000 });

app.get('/api/internal/stats',
  internalWhitelist,
  internalLimiter,
  handler
);

// 效果：
// - 外网 IP → 403 Forbidden
// - 内网 IP（1-5000次）→ 200 OK
// - 内网 IP（5001+次）→ 429 Too Many Requests

      示例 4: 全局白名单 + 路由特定限流

      // 配置：
// 全局白名单：GLOBAL_IP_WHITELIST=127.0.0.1,192.168.1.100
// 不同路由不同限流

// 敏感操作：低限流
app.post('/api/data/delete',
  createRateLimiter({ max: 10 }),
  handler
);

// 查询操作：高限流
app.get('/api/data/query',
  createRateLimiter({ max: 1000 }),
  handler
);

// 效果：
// - 全局白名单 IP 可以访问所有路由
// - 但不同操作有不同的限流限制
// - 非全局白名单 IP 都可以访问（未配置路由白名单）

      示例 5: 混合配置（全局 + 路由白名单 + 不同限流）

      // 配置：
// 全局白名单：GLOBAL_IP_WHITELIST=127.0.0.1,192.168.1.100
// 管理后台额外白名单：ADMIN_IP_WHITELIST=192.168.1.10,192.168.1.11

const adminWhitelist = ipWhitelistMiddleware('/api/admin');
const adminLimiter = createRateLimiter({ max: 200 });

app.get('/api/admin/users',
  adminWhitelist,
  adminLimiter,
  handler
);

// 效果：
// - 全局白名单 IP（127.0.0.1, 192.168.1.100）
//   → 跳过路由白名单检查 → 限流检查 → 200 OK 或 429
// - 路由白名单 IP（192.168.1.10, 192.168.1.11）
//   → 通过路由白名单 → 限流检查 → 200 OK 或 429
// - 其他 IP
//   → 403 Forbidden

      🔧 配置管理

      环境变量配置（推荐生产环境）

      # .env 文件或启动命令

# 全局白名单
GLOBAL_IP_WHITELIST=127.0.0.1,192.168.1.100,192.168.1.200

# 路由级白名单
ADMIN_IP_WHITELIST=192.168.1.10,192.168.1.11
INTERNAL_IP_WHITELIST=10.0.0.0/8,192.168.0.0/16
VIP_IP_WHITELIST=192.168.1.200,192.168.1.201

# 启动
node app.js

      配置文件（推荐开发环境）

      文件: config/ip-whitelist.json

      {
  "global": [
    "127.0.0.1",
    "::1",
    "192.168.1.100"
  ],
  "routes": {
    "/api/admin": [
      "192.168.1.10",
      "192.168.1.11"
    ],
    "/api/internal": [
      "10.0.0.0/8",
      "192.168.0.0/16"
    ],
    "/api/vip": [
      "192.168.1.200"
    ]
  }
}

      动态管理（运行时）

      # 添加全局白名单
curl -X POST http://localhost:3500/api/whitelist/global/add \
  -H "Content-Type: application/json" \
  -d '{"ip":"192.168.1.150"}'

# 添加路由白名单
curl -X POST http://localhost:3500/api/whitelist/route/add \
  -H "Content-Type: application/json" \
  -d '{"route":"/api/internal","ip":"192.168.2.100"}'

# 查看配置
curl http://localhost:3500/api/whitelist/config

      ⚠️ 重要注意事项

      1. 未配置白名单 = 允许所有

      // ⚠️ 如果 routeWhitelists['/api/internal'] 为空或不存在
isRouteWhitelisted('/api/internal', '1.2.3.4') 
// → 返回 true（允许所有 IP）

// 解决方案：显式配置空数组表示拒绝所有
this.routeWhitelists['/api/internal'] = []; // ❌ 这样会导致所有 IP 被拒绝

      正确做法：

      • 不需要白名单 → 不配置白名单中间件
      • 需要白名单 → 必须配置具体 IP 列表

      2. 白名单与限流的独立性

      白名单通过 ≠ 不限流
白名单通过 = 继续到限流检查

      错误理解：

      ❌ 白名单 IP = 特权用户 = 不限流

      正确理解：

      ✅ 白名单 IP = 有权访问 = 但仍受限流

      3. 全局白名单的优先级

      全局白名单 > 路由白名单

全局白名单 IP：
  → 所有路由都无需路由白名单验证
  → 但仍需通过各自路由的限流检查

      4. 安全建议

      场景推荐配置原因
      管理后台白名单 + 低限流双重保护
      内部 APIIP 段白名单 + 高限流内网访问 + 防滥用
      公开 API不配置白名单 + 中限流开放访问 + 防 DDoS
      敏感操作严格白名单 + 极低限流最高安全级别

      📚 相关文档

      • 完整实现: examples/express-ip-whitelist-independent.js
      • 对比说明: docs/zh/whitelist-ratelimit-independence.md
      • 实现报告: reports/白名单与限流独立性实现报告.md
      • 快速指南: docs/zh/ip-whitelist-dynamic-config.md

      🎉 总结

      四个问题的简短答案

      问题答案说明
      1. 限流有，白名单无✅ 所有 IP 可访问 + 限流未配置白名单 = 允许所有
      2. 白名单有，限流无⚠️ 白名单 IP 无限制访问不推荐，建议都配置
      3. 白名单有，限流有✅ 双重保护（推荐）白名单验证 → 限流检查
      4. 能否全局白名单✅ 可以！非常推荐全局 + 路由组合更灵活

      文档完成时间: 2026-02-05
      状态: ✅ 完整解答