wish-pool/IP-WHITELIST-README.md

IP 白名單功能說明

功能概述

本系統已實現完整的 IP 白名單功能，可以根據客戶端的 IP 地址來控制訪問權限。

功能特點

1. IP 顯示

• 在頁面右上角顯示當前用戶的 IP 地址
• 支援桌面版和手機版的不同顯示方式
• 顯示 IP 白名單狀態（允許/拒絕）

2. IP 白名單檢查

• 支援多種 IP 格式：
  • 單一 IP：192.168.1.100
  • IP 範圍：192.168.1.0/24 (CIDR 格式)
  • 多個 IP：用逗號分隔，如 192.168.1.100, 10.0.0.50
• 實時檢查每個請求的 IP 地址
• 不在白名單內的 IP 會被拒絕訪問並顯示 403 錯誤頁面

3. 管理介面

• 提供 /admin/ip-whitelist 管理頁面
• 可以動態配置 IP 白名單
• 顯示當前 IP 狀態和訪問權限

配置方法

1. 環境變數配置

在 .env.local 檔案中添加以下配置：

# 允許訪問的IP地址或IP範圍，用逗號分隔
ALLOWED_IPS=127.0.0.1,::1,192.168.1.0/24,10.0.0.0/8

# 是否啟用IP白名單檢查
# true: 啟用IP檢查，不在白名單內的IP將被拒絕
# false: 禁用IP檢查，允許所有IP訪問
ENABLE_IP_WHITELIST=true

2. IP 格式說明

單一 IP

192.168.1.100

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

多個 IP 或範圍

192.168.1.100,10.0.0.50,172.16.0.0/16

使用步驟

1. 啟用 IP 白名單

1. 設置 ENABLE_IP_WHITELIST=true
2. 在 ALLOWED_IPS 中配置允許的 IP 地址
3. 重新啟動應用程式

2. 測試功能

1. 訪問主頁面，查看右上角的 IP 顯示
2. 使用不在白名單內的 IP 訪問，應該會看到 403 錯誤頁面
3. 訪問 /admin/ip-whitelist 查看管理介面

3. 管理 IP 白名單

1. 訪問 /admin/ip-whitelist 頁面
2. 查看當前 IP 狀態
3. 修改白名單設置
4. 保存設置

技術實現

1. 中間件 (middleware.ts)

• 攔截所有請求
• 檢查客戶端 IP 是否在白名單內
• 拒絕不在白名單內的訪問

2. IP 工具函數 (lib/ip-utils.ts)

• isIpAllowed(): 檢查 IP 是否被允許
• getClientIp(): 獲取客戶端真實 IP
• isIpInRange(): 檢查 IP 是否在指定範圍內

3. API 路由 (app/api/ip/route.ts)

• 提供 IP 信息查詢接口
• 返回當前 IP 和白名單狀態

4. IP 顯示組件 (components/ip-display.tsx)

• 顯示當前 IP 地址
• 顯示白名單狀態
• 支援響應式設計

安全注意事項

1. IP 偽造防護：系統會檢查多個 IP 來源頭，包括：

   • x-forwarded-for
   • x-real-ip
   • x-client-ip
   • cf-connecting-ip (Cloudflare)

2. 本地開發：開發環境中，127.0.0.1 和 ::1 通常會被自動允許

3. 代理環境：如果使用反向代理，請確保正確配置 IP 轉發

故障排除

1. IP 顯示不正確

• 檢查是否在代理環境中
• 確認 getClientIp() 函數的 IP 來源配置

2. 白名單不生效

• 確認 ENABLE_IP_WHITELIST=true
• 檢查 ALLOWED_IPS 格式是否正確
• 重新啟動應用程式

3. 403 錯誤頁面

• 檢查當前 IP 是否在白名單內
• 查看瀏覽器開發者工具中的網路請求
• 檢查伺服器日誌

開發建議

1. 測試環境：建議在測試環境中先配置 ENABLE_IP_WHITELIST=false
2. IP 範圍：使用 CIDR 格式可以更靈活地管理 IP 範圍
3. 日誌記錄：系統會記錄被拒絕的訪問，便於排查問題
4. 備份配置：建議備份 IP 白名單配置，避免誤操作

相關檔案

• env.template - 環境變數模板
• middleware.ts - Next.js 中間件
• lib/ip-utils.ts - IP 工具函數
• app/api/ip/route.ts - IP 信息 API
• components/ip-display.tsx - IP 顯示組件
• app/admin/ip-whitelist/page.tsx - 管理頁面