# 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` 檔案中添加以下配置：

```bash
# 允許訪問的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` - 管理頁面