# IP 白名單功能說明

## 概述

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

## 功能特點

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

## 快速開始

### 1. 配置環境變數

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

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

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

### 2. 本地開發配置

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

```env
# 允許本地訪問
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地址：

```env
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. 內部工具限制
```env
# 只允許公司內部網路訪問
ALLOWED_IPS=192.168.1.0/24,10.0.0.0/8
ENABLE_IP_WHITELIST=true
```

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

### 3. 開發環境
```env
# 開發時允許所有IP
ENABLE_IP_WHITELIST=false
```

### 4. 生產環境安全
```env
# 生產環境嚴格限制
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檢測信息：

```json
{
  "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地址
- 詳細的訪問日誌記錄