超腾开源平台统计模块

统计模块提供网站访问统计、爬虫日志记录等功能。

目录

• 站点统计
• 爬虫日志

站点统计

站点统计模块提供页面访问统计、数据分析等功能。

页面访问管理

创建页面访问记录

接口地址: POST /api/statistics/analytics/pageview

需要认证: 否（网站端公开接口）

请求体:

{
  "url": "/blog/article-1",
  "referrer": "https://google.com",
  "user_agent": "Mozilla/5.0...",
  "ip_address": "192.168.1.1",
  "session_id": "session_12345",
  "page_title": "文章标题",
  "duration": 30,
  "device_type": "desktop"
}

请求字段说明:

数据收集

收集访问数据

接口地址: POST /api/statistics/analytics/collect

需要认证: 否

说明: 用于前端批量收集和提交访问数据。

请求体:

{
  "events": [
    {
      "type": "pageview",
      "url": "/blog/article-1",
      "timestamp": 1640995200000
    },
    {
      "type": "click",
      "element": "button",
      "url": "/blog/article-1"
    }
  ],
  "user_info": {
    "user_id": "1",
    "session_id": "session_12345",
    "device_type": "desktop"
  }
}

统计数据

获取统计数据

接口地址: GET /api/statistics/analytics/stats

需要认证: 是

请求参数:

响应示例:

{
  "success": true,
  "code": 200,
  "msg": "操作成功",
  "data": {
    "total_visits": 10000,
    "unique_visitors": 5000,
    "total_page_views": 50000,
    "avg_session_duration": 180,
    "bounce_rate": 40.5,
    "top_pages": [
      {
        "url": "/home",
        "views": 10000,
        "unique_visitors": 5000
      },
      {
        "url": "/blog",
        "views": 8000,
        "unique_visitors": 4000
      }
    ],
    "traffic_sources": [
      {
        "source": "direct",
        "count": 3000
      },
      {
        "source": "google",
        "count": 4000
      }
    ],
    "devices": [
      {
        "device_type": "desktop",
        "count": 6000
      },
      {
        "device_type": "mobile",
        "count": 3000
      }
    ]
  }
}

获取单个页面统计数据

接口地址: GET /api/statistics/analytics/page-stats

需要认证: 是

请求参数:

响应示例:

{
  "success": true,
  "code": 200,
  "msg": "操作成功",
  "data": {
    "url": "/blog/article-1",
    "total_views": 1000,
    "unique_visitors": 800,
    "avg_duration": 120,
    "bounce_rate": 30,
    "views_over_time": [
      {
        "date": "2026-01-01",
        "views": 100
      },
      {
        "date": "2026-01-02",
        "views": 120
      }
    ]
  }
}

每日统计

爬虫日志

爬虫日志模块记录各种爬虫的访问情况。

爬虫日志管理

获取爬虫日志列表

接口地址: GET /api/statistics/spider_logs/list

需要认证: 是

请求参数:

响应示例:

{
  "success": true,
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "id": "1",
      "spider_type": "google",
      "spider_name": "Googlebot",
      "url": "/blog/article-1",
      "user_agent": "Mozilla/5.0 (compatible; Googlebot/2.1; ...)",
      "ip_address": "66.249.66.1",
      "request_method": "GET",
      "status_code": 200,
      "response_time": 100,
      "access_time": "2026-01-01T00:00:00Z"
    }
  ]
}

枚举类型说明

设备类型 (DeviceType)

事件类型 (EventType)

流量来源 (TrafficSource)

使用示例

Python 示例

import requests

base_url = 'http://localhost:8000/api/statistics'

# 收集访问数据（无需认证）
response = requests.post(
    f'{base_url}/analytics/collect',
    json={
        'events': [
            {
                'type': 'pageview',
                'url': '/blog/article-1',
                'timestamp': 1640995200000
            }
        ],
        'user_info': {
            'session_id': 'session_12345',
            'device_type': 'desktop'
        }
    }
)
print(response.json())

# 获取统计数据（需要认证）
token = 'your_access_token'
headers = {'Authorization': f'Bearer {token}'}

response = requests.get(
    f'{base_url}/analytics/stats',
    headers=headers,
    params={
        'start_date': '2026-01-01',
        'end_date': '2026-01-31'
    }
)
print(response.json())

# 获取爬虫日志
response = requests.get(
    f'{base_url}/spider_logs/list',
    headers=headers,
    params={'spider_type': 'google'}
)
print(response.json())

JavaScript 示例

// 收集页面访问数据
function trackPageView(url, referrer) {
  fetch("http://localhost:8000/api/statistics/analytics/collect", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      events: [
        {
          type: "pageview",
          url: url,
          referrer: referrer,
          timestamp: Date.now(),
        },
      ],
      user_info: {
        session_id: getSessionId(),
        device_type: getDeviceType(),
      },
    }),
  });
}

// 获取统计数据
async function getStats(token, startDate, endDate) {
  const response = await fetch(
    `http://localhost:8000/api/statistics/analytics/stats?start_date=${startDate}&end_date=${endDate}`,
    { headers: { Authorization: `Bearer ${token}` } }
  );
  return await response.json();
}

// 获取单个页面统计
async function getPageStats(token, url) {
  const response = await fetch(
    `http://localhost:8000/api/statistics/analytics/page-stats?url=${encodeURIComponent(
      url
    )}`,
    { headers: { Authorization: `Bearer ${token}` } }
  );
  return await response.json();
}

注意事项

1. 隐私保护: 统计数据不记录个人敏感信息，符合隐私保护要求。
2. 性能影响: 统计接口设计为异步写入，不影响主流程性能。
3. 数据清理: 建议定期清理过期数据，避免数据库膨胀。
4. 爬虫识别: 通过 User-Agent 识别爬虫，但需要注意伪装的情况。
5. 统计延迟: 统计数据有轻微延迟，实时性要求不高的场景可以使用。
6. 批量收集: 建议使用批量收集接口，减少请求次数。

相关文档

• 数据模型参考
• 工具模块 API
• 网站模块 API
• API 概览