🔗 短網址系統

專業的 XOOPS 短網址模組，提供完整的短網址生成、管理與統計功能

系統概述

KIP.TW 短網址系統是一個功能完整、安全可靠的短網址服務模組。它不僅提供基本的網址縮短功能，還包含了智能去重、網頁資訊抓取、詳細統計分析、API 接口等進階功能，適合各種規模的網站使用。

為什麼選擇我們？

💎 功能特色

核心功能

• 短網址生成：支援 1-8 字元的自動生成或自訂代碼
• 智能去重：相同網址自動返回已存在的短網址，避免重複
• 網頁資訊抓取：自動獲取目標網頁的標題和縮圖
• 批量操作：支援批量創建、批量啟用/停用等操作
• 過期設置：可設定短網址的有效期限

管理功能

• 統計儀表板：總覽系統使用情況，包含圖表展示
• 短網址列表：完整的列表管理，支援搜尋、分頁、排序
• 詳細統計：查看每個短網址的詳細點擊資訊
• API 管理：管理 API 密鑰、設置限額、查看使用情況
• 黑名單管理：防止惡意網址，支援啟用/停用 NEW
• 系統設定：自訂各種參數和數據維護

安全防護

• SSRF 防護：阻止訪問內網和敏感地址
• 黑名單系統：封鎖惡意網址和釣魚網站
• 速率限制：防止惡意濫用和 DOS 攻擊
• CSRF 保護：所有表單操作都有 token 驗證 NEW
• IP 白名單：API 訪問限制特定 IP

API 功能

• RESTful API：符合標準的 API 設計
• 批量創建：一次請求創建多個短網址
• 統計查詢：通過 API 獲取統計資訊
• 靈活配置：支援自訂代碼、標題、過期時間等

📦 安裝指南

tar -xzf shorturl_module_v2_post_fixed.tar.gz
mv shorturl_module /var/www/xoops/modules/shorturl

cp /var/www/xoops/modules/shorturl/shorturl.php /var/www/xoops/

chmod 755 /var/www/xoops/modules/shorturl
chmod 644 /var/www/xoops/modules/shorturl/admin/*.php
mkdir -p /var/www/xoops/uploads/thumbnails
chmod 777 /var/www/xoops/uploads/thumbnails

location ~ "^/([a-zA-Z0-9]{1,8})$" {
    try_files $uri /shorturl.php?code=$1;
}

🚀 快速開始

創建您的第一個短網址

進階選項

• 自訂短代碼：勾選「使用自訂代碼」並輸入易記的代碼
• 設置標題：手動輸入標題或勾選自動抓取
• 設置有效期：選擇過期時間，到期後短網址自動失效

✨ 創建短網址

前台創建

訪問 /modules/shorturl/ 使用網頁介面創建短網址。

基本步驟：

1. 輸入要縮短的長網址（必填）
2. 選擇是否使用自訂短代碼（選填）
3. 輸入標題或勾選自動抓取（選填）
4. 設置過期時間（選填）
5. 點擊「生成短網址」

後台創建

管理員可以在後台創建並管理所有短網址。

操作路徑：

管理後台 → 短網址服務 → 短網址列表 → 新增短網址

通過 API 創建

開發者可以使用 API 在程式中自動創建短網址。詳見 API 文檔。

POST /modules/shorturl/api.php
Content-Type: application/json
X-API-Key: your_api_key

{
  "long_url": "https://www.example.com",
  "custom_code": "my-link",
  "title": "我的連結",
  "fetch_info": true
}

📋 管理短網址

列表管理

在管理後台可以查看和管理所有短網址。

可用操作：

搜尋功能

支援按短代碼、目標網址或標題搜尋短網址。

批量操作

選擇多個短網址進行批量啟用、停用或刪除操作。

📊 統計分析

儀表板

管理後台首頁提供系統總覽，包含：

• 短網址總數
• 總點擊次數
• 今日新增數量
• 今日點擊數
• 點擊趨勢圖表
• 熱門短網址排行

詳細統計

點擊任何短網址可查看詳細統計，包含：

基本資訊

• 短網址和目標網址
• 創建時間和最後訪問時間
• 總點擊次數
• 狀態（啟用/停用/已過期）

點擊分析

• 時間分佈：按小時、日期統計點擊
• 地理位置：訪問者的國家和城市
• 設備類型：桌面、手機、平板比例
• 瀏覽器：使用的瀏覽器類型
• 操作系統：Windows、Mac、Linux、iOS、Android
• 來源網站：訊問來源的網站

報表匯出

可將統計數據匯出為 CSV 或 Excel 格式，方便進一步分析。

🔑 API 管理

添加 API 密鑰

管理 API 密鑰

在 API 列表中可以進行以下操作：

• 啟用/停用：臨時禁用或恢復 API 密鑰
• 重置配額：清零今日使用次數
• 刪除：永久移除 API 密鑰

監控使用情況

可以實時查看：

• 今日已使用次數
• 使用率百分比
• 最後使用時間

🚫 黑名單管理

什麼是黑名單？

黑名單是一個安全防護功能，用於阻止惡意網址、釣魚網站、內網地址等被縮短。

添加黑名單項目

單個添加

1. 進入「黑名單管理」頁面
2. 在「單個添加」標籤中輸入網址模式
3. 填寫原因（選填）
4. 點擊「新增」

批量添加

1. 切換到「批量添加」標籤
2. 每行一個，格式：網址模式|原因
3. 點擊「批量添加」

malicious.com|惡意網站
phishing.net|釣魚網站
192.168.|內網地址

支援的模式類型

啟用與停用 NEW

v2.0 新增的功能，可以暫時停用黑名單規則而不需要刪除。

使用場景：

• 臨時允許：某個域名暫時需要使用
• 測試規則：測試黑名單規則是否會影響正常使用
• 保留記錄：保留黑名單項目的歷史記錄

預設黑名單

系統自動包含以下安全項目：

• 內網地址：127.0.0.1、192.168.、10.0.、172.16.、localhost
• 危險協議：file://
• 本地回環：::1

📡 API 接口文檔

基本資訊

1. 創建短網址

請求

POST /modules/shorturl/api.php
Content-Type: application/json
X-API-Key: your_api_key_here

{
  "long_url": "https://www.example.com",
  "custom_code": "my-link",
  "title": "我的網站",
  "fetch_info": true,
  "expired_at": "2025-12-31 23:59:59"
}

參數說明

響應（成功）

{
  "success": true,
  "short_url": "https://kip.tw/abc123",
  "short_code": "abc123",
  "title": "我的網站",
  "thumbnail": "https://kip.tw/uploads/thumbnails/abc123.jpg"
}

響應（失敗）

{
  "success": false,
  "error": "網址格式錯誤"
}

2. 批量創建短網址

請求

POST /modules/shorturl/api.php
Content-Type: application/json
X-API-Key: your_api_key_here

{
  "urls": [
    "https://www.example.com/page1",
    {
      "long_url": "https://www.example.com/page2",
      "custom_code": "page2",
      "title": "第二頁"
    }
  ]
}

響應

{
  "success": true,
  "results": [
    {
      "success": true,
      "short_url": "https://kip.tw/xyz789",
      "short_code": "xyz789"
    },
    {
      "success": true,
      "short_url": "https://kip.tw/page2",
      "short_code": "page2"
    }
  ]
}

3. 查詢統計

請求

GET /modules/shorturl/api.php?short_code=abc123
X-API-Key: your_api_key_here

響應

{
  "success": true,
  "short_code": "abc123",
  "long_url": "https://www.example.com",
  "title": "我的網站",
  "clicks": 1234,
  "status": 1,
  "created_at": "2025-01-26 10:30:00",
  "last_click": "2025-01-26 15:20:00"
}

錯誤代碼

💻 API 使用範例

PHP 範例

<?php
require_once 'ShortUrlClient.php';

$client = new ShortUrlClient(
    'https://kip.tw/modules/shorturl/api.php',
    'your_api_key_here'
);

// 創建短網址
$result = $client->create('https://www.example.com', [
    'custom_code' => 'my-link',
    'fetch_info' => true
]);

if ($result && $result['success']) {
    echo "短網址: " . $result['short_url'];
}
?>

Python 範例

import requests

api_url = 'https://kip.tw/modules/shorturl/api.php'
api_key = 'your_api_key_here'

headers = {
    'Content-Type': 'application/json',
    'X-API-Key': api_key
}

data = {
    'long_url': 'https://www.example.com',
    'custom_code': 'my-link',
    'fetch_info': True
}

response = requests.post(api_url, json=data, headers=headers)
result = response.json()

if result['success']:
    print(f"短網址: {result['short_url']}")

JavaScript (Node.js) 範例

const axios = require('axios');

const apiUrl = 'https://kip.tw/modules/shorturl/api.php';
const apiKey = 'your_api_key_here';

const createShortUrl = async (longUrl) => {
    try {
        const response = await axios.post(apiUrl, {
            long_url: longUrl,
            fetch_info: true
        }, {
            headers: {
                'Content-Type': 'application/json',
                'X-API-Key': apiKey
            }
        });
        
        if (response.data.success) {
            console.log('短網址:', response.data.short_url);
            return response.data.short_url;
        }
    } catch (error) {
        console.error('錯誤:', error.message);
    }
};

createShortUrl('https://www.example.com');

cURL 範例

curl -X POST https://kip.tw/modules/shorturl/api.php \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "long_url": "https://www.example.com",
    "custom_code": "my-link",
    "fetch_info": true
  }'

🔌 系統整合

WordPress 整合

// functions.php
function get_post_short_url($post_id) {
    $client = new ShortUrlClient(API_URL, API_KEY);
    
    // 檢查是否已有短網址
    $short_url = get_post_meta($post_id, 'short_url', true);
    if ($short_url) {
        return $short_url;
    }
    
    // 創建新短網址
    $result = $client->create(get_permalink($post_id), [
        'title' => get_the_title($post_id),
        'fetch_info' => true
    ]);
    
    if ($result && $result['success']) {
        update_post_meta($post_id, 'short_url', $result['short_url']);
        return $result['short_url'];
    }
    
    return get_permalink($post_id);
}

Laravel 整合

// config/services.php
'shorturl' => [
    'api_url' => env('SHORTURL_API_URL'),
    'api_key' => env('SHORTURL_API_KEY'),
],

// app/Services/ShortUrlService.php
class ShortUrlService {
    protected $client;
    
    public function __construct() {
        $this->client = new \ShortUrlClient(
            config('services.shorturl.api_url'),
            config('services.shorturl.api_key')
        );
    }
    
    public function shorten($url, $options = []) {
        $result = $this->client->create($url, $options);
        
        if ($result && $result['success']) {
            return $result['short_url'];
        }
        
        throw new \Exception($result['error'] ?? 'Failed to create short URL');
    }
}

❓ 常見問題

Q: 如何修改短網址的長度？

A: 在「模組設定」中可以設置短網址長度，範圍是 1-8 字元。預設為 6 字元。

Q: 可以使用中文作為短代碼嗎？

A: 不建議。短代碼應使用英文字母和數字（a-z, A-Z, 0-9），以確保最佳兼容性。

Q: 短網址會過期嗎？

A: 預設不會過期。但您可以在創建時設置過期時間，或在管理後台設置預設過期天數。

Q: 相同的網址會生成不同的短網址嗎？

A: 不會。系統會自動檢測重複，相同的網址會返回已存在的短網址，避免浪費。

Q: API 有請求限制嗎？

A: 有。每個 API 密鑰都有每日限額，預設為 1000 次/天。可以在管理後台調整。

Q: 如何備份短網址數據？

A: 定期備份 MySQL 數據庫即可。建議使用 mysqldump 工具：

mysqldump -u root -p database_name > backup.sql

Q: 可以匯入舊的短網址嗎？

A: 可以。準備 CSV 格式的數據，通過 SQL 導入到數據庫中。

Q: 統計數據可以清除嗎？

A: 可以。在「模組設定」→「數據維護」中可以清理舊的統計記錄。

🔒 安全說明

系統安全機制

1. SSRF 防護

系統會自動檢測和阻止以下類型的網址：

• 內網 IP 地址（192.168.x.x、10.x.x.x、172.16-31.x.x）
• 本地地址（127.0.0.1、localhost、::1）
• 危險協議（file://、ftp://）

2. 黑名單系統

管理員可以添加惡意域名到黑名單，防止縮短危險網址。

3. 速率限制

防止單一 IP 或 API 密鑰濫用系統資源。

4. CSRF 保護

所有表單操作都需要 token 驗證，防止跨站請求偽造攻擊。

5. SQL 注入防護

所有數據庫查詢都使用參數化或轉義處理。

安全建議

🔧 問題排查

短網址無法訪問

可能原因：

1. NGINX 重寫規則未配置
2. shorturl.php 文件未複製到根目錄
3. 短網址已停用或過期
4. 檔案權限設置錯誤

解決方法：

• 檢查 NGINX 配置並重啟服務
• 確認 shorturl.php 存在於 XOOPS 根目錄
• 在管理後台檢查短網址狀態
• 設置正確的檔案權限（644）

API 請求失敗

可能原因：

1. API 密鑰錯誤
2. IP 未加入白名單
3. 超過每日限額
4. 請求格式錯誤

解決方法：

• 確認 API 密鑰正確（64 字元）
• 在管理後台添加伺服器 IP
• 檢查並增加每日限額
• 參考 API 文檔檢查請求格式

統計數據不準確

可能原因：

1. 瀏覽器快取
2. CDN 快取
3. 機器人流量

解決方法：

• 在 NGINX 中禁用短網址的快取
• 配置 CDN 跳過短網址
• 啟用機器人過濾功能

縮圖無法顯示

可能原因：

1. 目標網站阻止爬蟲
2. uploads 目錄權限不足
3. 網頁沒有 Open Graph 標籤

解決方法：

• 手動上傳縮圖
• 設置 uploads/thumbnails 目錄為 777
• 使用預設縮圖