# IP 訪問記錄系統使用說明

## 📋 概述

此系統可以記錄所有訪問 `ex.php` 的 IP 地址及相關資訊，包括：
- IP 地址（支援 IPv4 和 IPv6）
- 訪問時間
- User Agent（瀏覽器和設備資訊）
- 請求方式（GET/POST）
- 請求參數
- 來源頁面（Referer）

---

## 🚀 安裝步驟

### 步驟 1：建立資料表

在您的 TSPSQL 資料庫中執行以下 SQL 腳本：

```bash
sqlcmd -S your_server -d your_database -i create_ip_log_table.sql
```

或者在 SQL Server Management Studio (SSMS) 中開啟並執行 `create_ip_log_table.sql`

### 步驟 2：驗證安裝

執行以下 SQL 查詢確認資料表已建立：

```sql
SELECT * FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_NAME = 'VerifyAPI_IP_LOG'
```

---

## 📝 檔案說明

### 1. `create_ip_log_table.sql`
- **用途**：建立 IP_LOG 資料表的 SQL 腳本
- **執行時機**：首次安裝時執行一次即可

### 2. `ip_logger.php`
- **用途**：IP 記錄功能的核心函式庫
- **主要函數**：
  - `getRealIpAddress()`：取得訪問者的真實 IP（考慮代理伺服器）
  - `logIpAccess($pdo, $pageName)`：記錄 IP 訪問資訊
  - `getIpLogs($pdo, $ipAddress, $limit)`：查詢 IP 記錄
  - `getIpStatistics($pdo, $limit)`：統計 IP 訪問次數

### 3. `ex.php`（已修改）
- **用途**：範例 API 測試頁面，現已整合 IP 記錄功能
- **修改內容**：在檔案開頭加入 IP 記錄功能，不影響原有功能

### 4. `view_ip_logs.php`
- **用途**：查詢和顯示 IP 記錄的網頁介面
- **功能**：
  - 查看最近訪問記錄
  - 搜尋特定 IP 的訪問記錄
  - 查看 IP 訪問統計（按訪問次數排序）

---

## 🔧 使用方法

### 自動記錄 IP

當有人訪問 `ex.php` 時，系統會自動記錄其 IP 及相關資訊到資料庫。

### 查詢 IP 記錄

#### 方法 1：使用網頁介面

在瀏覽器中開啟：
```
http://your_domain/VERIFY_src/view_ip_logs.php
```

功能：
- **最近訪問記錄**：顯示最近的訪問記錄，可搜尋特定 IP
- **訪問統計**：顯示各 IP 的訪問次數統計

#### 方法 2：直接查詢資料庫

```sql
-- 查詢最近 100 筆記錄
SELECT TOP 100 * FROM VerifyAPI_IP_LOG ORDER BY ACCESS_TIME DESC;

-- 查詢特定 IP 的記錄
SELECT * FROM VerifyAPI_IP_LOG WHERE IP_ADDRESS = '192.168.1.100' ORDER BY ACCESS_TIME DESC;

-- 統計各 IP 的訪問次數
SELECT
    IP_ADDRESS,
    COUNT(*) as ACCESS_COUNT,
    MIN(ACCESS_TIME) as FIRST_ACCESS,
    MAX(ACCESS_TIME) as LAST_ACCESS
FROM VerifyAPI_IP_LOG
GROUP BY IP_ADDRESS
ORDER BY ACCESS_COUNT DESC;
```

#### 方法 3：在 PHP 程式中使用

```php
<?php
require_once('ip_logger.php');

// 建立資料庫連線
$config = require('config.php');
$dsn = "sqlsrv:Server={$config['server']};Database={$config['database']}";
$pdo = new PDO($dsn, $config['user'], $config['password']);

// 取得最近 50 筆記錄
$logs = getIpLogs($pdo, null, 50);

// 取得特定 IP 的記錄
$ipLogs = getIpLogs($pdo, '192.168.1.100', 100);

// 取得 IP 訪問統計
$stats = getIpStatistics($pdo, 50);
?>
```

---

## 🔐 安全性考量

### 1. 密碼保護
請確保將敏感資訊（如密碼）從記錄中排除。`ip_logger.php` 已經自動過濾 `password` 和 `passwd` 欄位。

### 2. 資料量管理
建議定期清理舊記錄，避免資料表過大：

```sql
-- 刪除 90 天前的記錄
DELETE FROM VerifyAPI_IP_LOG WHERE ACCESS_TIME < DATEADD(day, -90, GETDATE());
```

可以建立 SQL Server Agent Job 定期執行此清理作業。

### 3. 存取權限
建議限制 `view_ip_logs.php` 的存取權限，只允許管理員查看。

可以在檔案開頭加入驗證：

```php
<?php
session_start();
if (!isset($_SESSION['admin']) || $_SESSION['admin'] !== true) {
    die('無權限存取此頁面');
}
?>
```

---

## 📊 資料表結構

```sql
CREATE TABLE VerifyAPI_IP_LOG (
    LOG_ID INT IDENTITY(1,1) PRIMARY KEY,      -- 記錄編號
    IP_ADDRESS VARCHAR(45) NOT NULL,            -- IP 地址
    ACCESS_TIME DATETIME DEFAULT GETDATE(),     -- 訪問時間
    USER_AGENT VARCHAR(500),                    -- User Agent
    REQUEST_METHOD VARCHAR(10),                 -- 請求方式
    REQUEST_URI VARCHAR(500),                   -- 請求 URI
    REQUEST_PARAMS TEXT,                        -- 請求參數（JSON）
    REFERER VARCHAR(500),                       -- 來源頁面
    PAGE_NAME VARCHAR(100),                     -- 頁面名稱
    CREATE_TIME DATETIME DEFAULT GETDATE()      -- 建立時間
);
```

---

## 🔄 整合到其他頁面

如果您想在其他 PHP 頁面也加入 IP 記錄功能，只需在檔案開頭加入：

```php
<?php
try {
    // 載入資料庫設定
    $config = require('config.php');

    // 建立資料庫連線
    $dsn = "sqlsrv:Server={$config['server']};Database={$config['database']}";
    $pdo = new PDO($dsn, $config['user'], $config['password']);
    $pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);

    // 載入 IP 記錄器
    require_once('ip_logger.php');

    // 記錄訪問 IP（將 'your_page.php' 改為實際頁面名稱）
    logIpAccess($pdo, 'your_page.php');

} catch (Exception $e) {
    error_log("IP 記錄失敗: " . $e->getMessage());
}
?>
```

---

## 🐛 疑難排解

### 問題 1：無法記錄 IP
**可能原因**：
- 資料表未建立
- 資料庫連線失敗
- 檔案權限問題

**解決方法**：
1. 檢查 `error_log` 查看錯誤訊息
2. 確認資料表已正確建立
3. 驗證資料庫連線設定

### 問題 2：IP 顯示為伺服器 IP
**可能原因**：
- 使用了負載平衡器或反向代理
- 需要設定正確的 HTTP 標頭

**解決方法**：
`getRealIpAddress()` 函數已經處理了常見的代理情況，如仍有問題請檢查伺服器設定。

### 問題 3：view_ip_logs.php 顯示空白
**可能原因**：
- PHP 錯誤
- 資料庫連線失敗

**解決方法**：
1. 啟用 PHP 錯誤顯示：`ini_set('display_errors', 1);`
2. 檢查伺服器錯誤日誌

---

## 📞 技術支援

如有任何問題，請聯繫系統管理員。

---

**建立日期**：2026-02-02
**作者**：YING
**版本**：1.0