214 lines
5.1 KiB
Markdown
214 lines
5.1 KiB
Markdown
# 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地址
|
||
- 詳細的訪問日誌記錄 |