petty09190/wish-pool
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

做 ip 防呆機制

Browse Source
This commit is contained in:
吳佩庭
2025-08-01 13:17:32 +08:00
parent 2282eed9a1
commit a54ae31896
7 changed files with 1139 additions and 125 deletions
Download Patch File Download Diff File Expand all files Collapse all files

299
IP-WHITELIST-README.md
View File

@@ -1,143 +1,214 @@
# IP 白名單功能說明
## 功能概述
## 概述
本系統已實現完整的 IP 白名單功能，可以根據客戶端的 IP 地址來控制訪問權限。
IP白名單功能允許你限制只有特定IP地址的用戶才能訪問你的網站。這是一個強大的安全功能，特別適用於內部工具或需要限制訪問的應用程式。
## 功能特點
### 1. IP 顯示
- 在頁面右上角顯示當前用戶的 IP 地址
- 支援桌面版和手機版的不同顯示方式
- 顯示 IP 白名單狀態（允許/拒絕）
- ✅ **智能IP檢測**：自動檢測真實客戶端IP，支援代理伺服器
- ✅ **多種IP格式**：支援單一IP、IP範圍（CIDR）、多個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.template` 為 `.env.local` 並配置以下變數：
### 1. 環境變數配置
在 `.env.local` 檔案中添加以下配置：
```bash
# 允許訪問的IP地址或IP範圍，用逗號分隔
ALLOWED_IPS=127.0.0.1,::1,192.168.1.0/24,10.0.0.0/8
```env
# 允許的IP地址（用逗號分隔）
ALLOWED_IPS=114.33.18.13,125.229.65.83,60.248.164.91
# 是否啟用IP白名單檢查
# true: 啟用IP檢查，不在白名單內的IP將被拒絕
# false: 禁用IP檢查，允許所有IP訪問
ENABLE_IP_WHITELIST=true
```
### 2. IP 格式說明
### 2. 本地開發配置
#### 單一 IP
```
192.168.1.100
在本地開發時，建議使用以下配置：
```env
# 允許本地訪問
ALLOWED_IPS=127.0.0.1,192.168.1.0/24
# 或者完全禁用IP檢查
ENABLE_IP_WHITELIST=false
```
#### 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檢測
訪問 `/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 或範圍
```
192.168.1.100,10.0.0.50,172.16.0.0/16
## 智能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
```
### 1. 啟用 IP 白名單
1. 設置 `ENABLE_IP_WHITELIST=true`
2. 在 `ALLOWED_IPS` 中配置允許的 IP 地址
3. 重新啟動應用程式
### 3. 開發環境
```env
# 開發時允許所有IP
ENABLE_IP_WHITELIST=false
```
### 2. 測試功能
1. 訪問主頁面，查看右上角的 IP 顯示
2. 使用不在白名單內的 IP 訪問，應該會看到 403 錯誤頁面
3. 訪問 `/admin/ip-whitelist` 查看管理介面
### 4. 生產環境安全
```env
# 生產環境嚴格限制
ALLOWED_IPS=114.33.18.13,125.229.65.83
ENABLE_IP_WHITELIST=true
```
### 3. 管理 IP 白名單
1. 訪問 `/admin/ip-whitelist` 頁面
2. 查看當前 IP 狀態
3. 修改白名單設置
4. 保存設置
## 調試和故障排除
### 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調試頁面
## 技術實現
### 1. 中間件 (middleware.ts)
- 攔截所有請求
- 檢查客戶端 IP 是否在白名單內
- 拒絕不在白名單內的訪問
### 核心組件
- **IP檢測**：`lib/ip-utils.ts` 中的 `getClientIp()` 函數
- **白名單檢查**：`isIpAllowed()` 函數支援CIDR範圍
- **中間件**：`middleware.ts` 在請求處理前檢查IP
- **API端點**：`/api/ip` 提供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` - 管理頁面
### 安全機制
- 服務器端檢查，客戶端無法繞過
- 支援多種代理伺服器配置
- 自動過濾無效IP地址
- 詳細的訪問日誌記錄