CSC Analytics

English | 中文

English

CSC Analytics is a lightweight, self-hosted analytics service for websites and client applications. It provides a small tracking script, event collection APIs, a browser-based dashboard, SQLite persistence, and Docker deployment support.

Features

• Website page view tracking with tracker.js
• Generic event collection API for desktop and mobile clients
• PV, UV, sessions, average duration, bounce rate, and 24-hour trends
• Page, referrer, source type, event, device, browser, and operating system reports
• Multi-site management with site-specific integration snippets
• Visit log filtering and CSV export
• SQLite backups, backup downloads, backup restore, and old data cleanup
• Optional admin password protection
• Privacy options for IP anonymization, Do Not Track, and data retention
• Docker and reverse proxy deployment examples
• Self-check script for local validation

Quick Start

Run locally:

python server.py

Open the dashboard:

http://127.0.0.1:8765

Run the self-check:

python scripts/self_check.py

Docker

Copy the example environment file and update the admin token before deployment:

Copy-Item .env.example .env
docker compose -p csc-analytics up -d --build

The container stores runtime data in the local data/ directory. Runtime databases and backups are intentionally ignored by Git.

Configuration

Common environment variables:

ANALYTICS_HOST=0.0.0.0
ANALYTICS_PORT=8765
ADMIN_TOKEN=replace-with-a-long-random-value
COOKIE_SECURE=true
IP_ANONYMIZE=true
RESPECT_DNT=true
DATA_RETENTION_DAYS=365

ADMIN_TOKEN enables password protection for dashboard and admin APIs. The public collection endpoint remains available so websites and applications can submit analytics events.

Website Integration

Add the tracking script before </head>:

<script defer src="https://analytics.example.com/tracker.js" data-site="official-site"></script>

Optional click tracking:

<script defer src="https://analytics.example.com/tracker.js" data-site="official-site" data-track-clicks="true"></script>
<button data-track="pricing_cta">View pricing</button>

Client Event API

Applications can submit JSON events:

POST /api/collect
Content-Type: application/json

{
  "site": "desktop-app",
  "event": "app_open",
  "path": "MainWindow",
  "visitorId": "anonymous-stable-id",
  "platform": "Windows",
  "appVersion": "1.0.0"
}

Useful Endpoints

• GET /api/health health check
• GET /api/config runtime configuration summary
• GET /api/stats dashboard statistics
• GET /api/visits visit log
• GET /api/export.csv CSV export
• GET /api/backup SQLite backup download

Project Structure

server.py                 # Application entry point
csc_analytics/app.py      # Backend application and APIs
public/                   # Dashboard and tracking script
scripts/self_check.py     # Local validation script
docs/reverse-proxy.md     # Reverse proxy examples

Documentation

• Quick Start
• Deployment Checklist
• Reverse Proxy Examples
• Changelog

License

MIT

中文

CSC Analytics 是一个轻量级、自托管的网站与客户端应用访问统计服务。它提供 Web 追踪脚本、事件上报 API、浏览器后台看板、SQLite 本地存储以及 Docker 部署支持。

功能

• 使用 tracker.js 统计 Web 页面访问
• 提供通用事件上报 API，适用于桌面端和移动端客户端
• PV、UV、会话数、平均停留时长、跳出率和最近 24 小时趋势
• 页面、来源、来源类型、事件、设备、浏览器和操作系统统计
• 多站点管理和站点专属接入代码
• 访问日志筛选和 CSV 导出
• SQLite 数据备份、下载、恢复和旧数据清理
• 可选后台访问密码保护
• IP 匿名化、Do Not Track 和数据保留周期等隐私选项
• Docker 与反向代理部署示例
• 本地自检脚本

快速开始

本地运行：

python server.py

打开后台：

http://127.0.0.1:8765

运行自检：

python scripts/self_check.py

Docker

复制环境变量示例文件，并在部署前更新后台访问密码：

Copy-Item .env.example .env
docker compose -p csc-analytics up -d --build

容器会把运行数据保存到本地 data/ 目录。运行时数据库和备份文件已被 Git 忽略，不会随源码提交。

配置

常用环境变量：

ANALYTICS_HOST=0.0.0.0
ANALYTICS_PORT=8765
ADMIN_TOKEN=replace-with-a-long-random-value
COOKIE_SECURE=true
IP_ANONYMIZE=true
RESPECT_DNT=true
DATA_RETENTION_DAYS=365

ADMIN_TOKEN 用于启用后台和管理接口的密码保护。公开的访问上报接口仍会保持可用，方便网站和应用提交统计事件。

Web 接入

把追踪脚本添加到 </head> 前：

<script defer src="https://analytics.example.com/tracker.js" data-site="official-site"></script>

可选点击采集：

<script defer src="https://analytics.example.com/tracker.js" data-site="official-site" data-track-clicks="true"></script>
<button data-track="pricing_cta">查看价格</button>

客户端事件 API

应用可以提交 JSON 事件：

POST /api/collect
Content-Type: application/json

{
  "site": "desktop-app",
  "event": "app_open",
  "path": "MainWindow",
  "visitorId": "anonymous-stable-id",
  "platform": "Windows",
  "appVersion": "1.0.0"
}

常用接口

• GET /api/health 健康检查
• GET /api/config 运行配置摘要
• GET /api/stats 后台统计数据
• GET /api/visits 访问日志
• GET /api/export.csv CSV 导出
• GET /api/backup SQLite 备份下载

项目结构

server.py                 # 应用启动入口
csc_analytics/app.py      # 后端应用和 API
public/                   # 后台页面和追踪脚本
scripts/self_check.py     # 本地自检脚本
docs/reverse-proxy.md     # 反向代理示例

文档

• 快速开始
• 部署检查清单
• 反向代理示例
• 更新日志

许可证

MIT