143 lines
3.8 KiB
Markdown
143 lines
3.8 KiB
Markdown
# 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` - 管理頁面 |