petty09190/wish-pool
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
wish-pool/IP-WHITELIST-README.md
吳佩庭 a54ae31896 做 ip 防呆機制
2025-08-01 13:17:32 +08:00

5.1 KiB
Raw Permalink Blame History

IP 白名單功能說明

概述

IP白名單功能允許你限制只有特定IP地址的用戶才能訪問你的網站。這是一個強大的安全功能，特別適用於內部工具或需要限制訪問的應用程式。

功能特點

  • ✅ 智能IP檢測：自動檢測真實客戶端IP，支援代理伺服器
  • ✅ 多種IP格式：支援單一IP、IP範圍（CIDR）、多個IP
  • ✅ 地理位置信息：可選的IP地理位置檢測
  • ✅ 調試工具：內建IP檢測調試頁面
  • ✅ 靈活配置：可隨時啟用/禁用白名單功能

快速開始

1. 配置環境變數

複製 env.template 為 .env.local 並配置以下變數：

# 允許的IP地址（用逗號分隔）
ALLOWED_IPS=114.33.18.13,125.229.65.83,60.248.164.91

# 是否啟用IP白名單檢查
ENABLE_IP_WHITELIST=true

2. 本地開發配置

在本地開發時，建議使用以下配置：

# 允許本地訪問
ALLOWED_IPS=127.0.0.1,192.168.1.0/24

# 或者完全禁用IP檢查
ENABLE_IP_WHITELIST=false

3. 測試IP檢測

訪問 /test/ip-debug 頁面來測試IP檢測功能，查看：

  • 檢測到的真實IP地址
  • 所有可能的IP來源
  • 地理位置信息
  • 白名單狀態

IP 地址格式

支援的格式

  1. 單一IP地址

    192.168.1.100
114.33.18.13

  2. IP範圍（CIDR格式）

    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. 多個IP地址

    192.168.1.100,10.0.0.50,172.16.0.0/16

實際範例

使用 allowed_ips.txt 中的IP地址：

ALLOWED_IPS=114.33.18.13,125.229.65.83,60.248.164.91,220.132.236.89,211.72.69.222,219.87.170.253,125.228.50.228

智能IP檢測

系統會自動檢測真實的客戶端IP地址，支援以下情況：

代理伺服器支援

  • Cloudflare (cf-connecting-ip)
  • Nginx (x-real-ip)
  • Apache (x-forwarded-for)
  • 其他常見代理頭

自動過濾

  • 排除本地回環地址 (127.0.0.1, ::1)
  • 優先選擇公網IP地址
  • 處理IPv6格式的IPv4地址

使用場景

1. 內部工具限制

# 只允許公司內部網路訪問
ALLOWED_IPS=192.168.1.0/24,10.0.0.0/8
ENABLE_IP_WHITELIST=true

2. 特定客戶訪問

# 只允許特定客戶IP訪問
ALLOWED_IPS=203.0.113.1,198.51.100.50
ENABLE_IP_WHITELIST=true

3. 開發環境

# 開發時允許所有IP
ENABLE_IP_WHITELIST=false

4. 生產環境安全

# 生產環境嚴格限制
ALLOWED_IPS=114.33.18.13,125.229.65.83
ENABLE_IP_WHITELIST=true

調試和故障排除

1. 使用調試頁面

訪問 /test/ip-debug 查看詳細的IP檢測信息。

2. 常見問題

問題：IP顯示為 127.0.0.1

  • 解決方案：在本地開發時，將 127.0.0.1 加入白名單或禁用IP檢查

問題：無法訪問網站

  • 檢查：確認你的IP地址在白名單中
  • 檢查：確認 ENABLE_IP_WHITELIST=true 設置正確

問題：代理伺服器環境

  • 系統會自動檢測代理轉發的真實IP
  • 如果仍有問題，檢查代理伺服器配置

3. 日誌查看

在瀏覽器開發者工具中查看網路請求，或檢查服務器日誌。

安全建議

  1. 定期更新IP列表：定期檢查和更新允許的IP地址
  2. 監控訪問日誌：監控被拒絕的訪問嘗試
  3. 備用訪問方式：考慮設定VPN或其他備用訪問方式
  4. 測試環境：在測試環境中充分測試IP白名單功能
  5. 文檔記錄：記錄所有允許的IP地址和用途

API 端點

GET /api/ip

返回當前客戶端的IP檢測信息：

{
  "ip": "203.0.113.1",
  "isAllowed": true,
  "enableIpWhitelist": true,
  "allowedIps": ["114.33.18.13", "125.229.65.83"],
  "timestamp": "2024-01-01T12:00:00.000Z",
  "debug": {
    "allIpSources": {
      "x-forwarded-for": "203.0.113.1",
      "x-real-ip": null,
      // ... 其他IP來源
    },
    "environment": "production",
    "host": "example.com",
    "referer": "https://example.com/"
  },
  "location": {
    "country": "Taiwan",
    "city": "Taipei",
    "isp": "Chunghwa Telecom"
  }
}

部署注意事項

Vercel 部署

  1. 在 Vercel 項目設置中配置環境變數
  2. 確保 ENABLE_IP_WHITELIST 設置正確
  3. 測試IP檢測功能是否正常工作

其他平台

  1. 確保環境變數正確配置
  2. 測試代理伺服器IP轉發是否正常
  3. 檢查防火牆和網路配置

相關文件

  • allowed_ips.txt - IP地址清單文件
  • lib/ip-utils.ts - IP檢測工具函數
  • middleware.ts - IP白名單中間件
  • app/api/ip/route.ts - IP檢測API
  • app/test/ip-debug/page.tsx - IP調試頁面

技術實現

核心組件

  • IP檢測：lib/ip-utils.ts 中的 getClientIp() 函數
  • 白名單檢查：isIpAllowed() 函數支援CIDR範圍
  • 中間件：middleware.ts 在請求處理前檢查IP
  • API端點：/api/ip 提供IP檢測服務

安全機制

  • 服務器端檢查，客戶端無法繞過
  • 支援多種代理伺服器配置
  • 自動過濾無效IP地址
  • 詳細的訪問日誌記錄