DOCSEARCHbyAlgolia
Submit Docs

Busuanzi Self-Hosted Visitor Statistics

repository·main·Indexed 42 days ago

https://github.com/soxft/busuanzi

A lightweight, self-hosted visitor statistics system built with Golang and Redis. It calculates Unique Visitors (UV) and Page Views (PV) for websites and subpages, supporting Pjax and one-click deployment via Docker. Includes tools like busuanzi-sync for migrating data from the original service and bsz-transfer for upgrading from versions 2.5.x - 2.7.x to 2.8.x.

Tokens
1.5K
Snippets
4
Records
10
Agent score
54%

What's inside Busuanzi

  1. Overview of Self-Hosted Busuanzi

    main

    Busuanzi is a lightweight visitor statistics system built with Golang and Redis. It is designed to track site-wide and page-specific metrics while maintaining privacy and compatibility with modern web technologies.

    Key Features:

    • Metrics Tracking: Tracks Unique Visitors (UV) and Page Views (PV) for both the entire site and individual sub-pages.
    • Privacy-Focused: Only stores hashed values to protect user privacy.
    • Modern Web Support: Compatible with Pjax (Pushstate and AJAX) for seamless tracking in single-page applications or dynamic content loading.
    • Deployment: Supports one-click deployment via Docker.
    • Migration: Supports data migration from the original Busuanzi service.

  2. How Busuanzi stores UV and PV data in Redis

    main

    Busuanzi utilizes Redis for high-performance data storage and retrieval, leveraging RDB and AOF for persistence. Data is organized using specific Redis data types and key patterns based on MD5 hashes of the host and path.

    MetricRedis TypeKey Pattern
    sitePvStringbsz:site_pv:md5(host)
    siteUvHyperLogLogbsz:site_uv:md5(host)
    pagePvZSetbsz:page_pv:md5(host) / md5(path)
    pageUvHyperLogLogbsz:site_uv:md5(host):md5(path)

  3. Quick Start with Docker

    main

    To deploy the self-hosted Busuanzi service quickly using Docker, follow these steps:

    1. Configure your settings in the docker-compose.yaml file.
    2. Start the service by running the following command in your terminal:
    docker-compose up -d
    1. Access the data dashboard at http://localhost:8080.

  4. Migrate data from the original Busuanzi

    main
    If you are moving from the original Busuanzi service (http://busuanzi.ibruce.info) to this self-hosted version, use the busuanzi-sync tool to synchronize your existing data.

  6. Upgrade Busuanzi and manage data compatibility

    main

    When upgrading Busuanzi, follow these precautions to prevent data loss:

    1. Backup Data: Always create a backup of your Redis data (dump.rdb) before performing an upgrade.
    2. Check Compatibility: New and old versions may have incompatible data formats. Always check the specific instructions in the GitHub/Gitee Release notes before upgrading.
    3. Version-Specific Migration: If you are upgrading from version 2.5.x - 2.7.x to 2.8.x, you must use the bsz-transfer tool to migrate your data.

  7. Upgrade and Data Migration precautions

    main

    When upgrading Busuanzi, follow these safety guidelines:

    • Backup: Always back up your dump.rdb file before performing any upgrade.
    • Compatibility: Check the Release notes for instructions, as new and old versions may have incompatible data formats.
    • Version Migration: To migrate data from versions 2.5.x - 2.7.x to version 2.8.x, use the bsz-transfer tool.

  8. Configure Busuanzi via Docker Compose

    main

    You can deploy and configure the self-hosted Busuanzi service using a docker-compose.yaml file. The setup requires a redis service for data storage and the bsz service which runs the Busuanzi application.

    Environment Variables

    The bsz service is configured using the following environment variables:

    VariableDescription
    WEB_LOGSet to true to enable logging.
    WEB_DEBUGSet to true to enable debug mode.
    WEB_CORSDefines allowed Cross-Origin Resource Sharing (CORS) origins (e.g., * for all).
    BSZ_EXPIREStatistical data expiration time in seconds. Use an integer. 0 means data never expires.
    BSZ_SECRETA random string used as the signature secret.
    API_SERVERThe full URL of your API server (e.g., http://127.0.0.1:8080).
    REDIS_ADDRESSThe connection address for the Redis instance (e.g., redis:6379).
    BSZ_PATHSTYLEBoolean flag for path-style configuration.
    BSZ_ENCRYPTThe encryption algorithm to use (e.g., MD516).

    Port Mapping

    By default, the service maps port 8080 of the container to port 8080 on the host. You can modify the left side of the mapping to change the host port.

    version: "3.8"

services:
  redis:
    image: "redis:alpine"
    volumes:
      - ./data/redis:/data

  bsz:
    image: "xcsoft/busuanzi:latest"
    ports:
      - "8080:8080"
    links:
      - redis
    depends_on:
      - redis
    environment:
      WEB_LOG: true
      WEB_DEBUG: false
      WEB_CORS: "*"
      BSZ_EXPIRE: 0
      BSZ_SECRET: "bsz"
      API_SERVER: http://127.0.0.1:8080
      REDIS_ADDRESS: redis:6379
      BSZ_PATHSTYLE: true
      BSZ_ENCRYPT: MD516

  9. Reference: Redis key patterns for UV and PV

    main

    The following Redis keys are used to store visitor statistics:

    MetricTypeKey Pattern
    sitePvStringbsz:site_pv:md5(host)
    siteUvHyperLogLogbsz:site_uv:md5(host)
    pagePvZSetbsz:page_pv:md5(host) / md5(path)
    pageUvHyperLogLogbsz:site_uv:md5(host):md5(path)

  10. Use the Index handler to serve the statistics dashboard

    main

    The Index function is an HTTP handler designed for use with the Gin web framework. It serves the index.html template, which provides the user interface for viewing statistics data. It is intended to be registered as a route handler for the root or dashboard path in your Gin router configuration.

    import (
	"github.com/gin-gonic/gin"
	"your-project/app/controller"
)

func main() {
	r := gin.Default()
	r.GET("/", controller.Index)
	r.Run()
}