1. Project Overview

NginxPulse

A lightweight Nginx access log analysis and visualization dashboard featuring real-time statistics, PV filtering, IP geolocation, and client information parsing.

2. Open Source License

Licensed under MIT

3. Screenshots

4. Feature Overview

IP Geolocation Lookup Strategy

• Quick Filtering
  Empty values, local addresses, and loopback addresses return "Local", while private network addresses return "Private Network/Local Network".
• Cache First
  Return results directly when found in the in-memory cache (up to 50,000 entries).
• Remote First
  Use ip-api.com/batch for batch queries, with a timeout of 1.2s and a maximum of 100 addresses per batch.
• Local Fallback
  If the remote request fails or returns "Unknown", use the built-in ip2region database for local IPv4 lookups (50ms timeout).
• IPv6 Handling
  Only remote lookups are supported. If the remote request fails, return "Unknown".

The local ip2region.xdb database is embedded in the binary. On the first startup, it is automatically extracted to ./var/nginxpulse_data/ip2region.xdb, and the vector index is loaded when possible to improve query performance.

This project accesses an external IP geolocation API (ip-api.com). Ensure that outbound access to this domain is permitted in your deployment environment.

5. Tech Stack

Project Technology Stack

• Backend
  Go 1.23.x · Gin · Logrus
• Data
  SQLite (modernc.org/sqlite)
• IP Geolocation
  ip2region (local database) + ip-api.com (remote batch queries)
• Frontend
  Vue 3 · Vite · TypeScript · PrimeVue · ECharts/Chart.js · Scss
• Container
  Docker / Docker Compose · Nginx (frontend static deployment)

Notes for Further Development

Environment Dependencies

• Go 1.23.x (keep consistent with go.mod)
• Node.js 20+ / npm
• Docker (optional, for containerization)

How to Use the Project

1) Docker

See the README.md documentation for details

2) Docker Compose

See the README.md documentation for details

3) Manual Build (Frontend and Backend)

Frontend Build:

cd webapp
npm install
npm run build

Backend Build:

go mod download
go build -o bin/nginxpulse ./cmd/nginxpulse/main.go

Local Development (Run Frontend and Backend Together):

./scripts/dev_local.sh

The frontend development server uses port 8088 by default and proxies /api to http://127.0.0.1:8089. Before starting local development, prepare your log files and place them under var/log/ (or ensure that the logPath in configs/nginxpulse_config.json points to the corresponding files).

Directory Structure and Key Files

.
├── cmd/
│   └── nginxpulse/
│       └── main.go                 # Program entry point
├── internal/                       # Core logic (parsing, statistics, storage, API)
│   ├── app/
│   │   └── app.go                  # Initialization, dependency wiring, task scheduling
│   ├── analytics/                  # Statistical definitions and aggregation
│   ├── enrich/
│   │   ├── ip_geo.go               # IP geolocation (remote+local) and caching
│   │   └── pv_filter.go            # PV filtering rules
│   ├── ingest/
│   │   └── log_parser.go           # Log scanning, parsing, and database insertion
│   ├── server/
│   │   └── http.go                 # HTTP services and middleware
│   ├── store/
│   │   └── repository.go           # SQLite schema and data writing
│   └── web/
│       └── handler.go              # API routes
├── webapp/
│   └── src/
│       └── main.ts                 # Frontend entry point
├── configs/
│   ├── nginxpulse_config.json      # Core configuration entry point
│   └── nginx_frontend.conf         # Built-in Nginx configuration
├── scripts/
│   └── dev_local.sh                # One-click local startup
├── var/                            # Data directory (generated at runtime/or mounted)
├── Dockerfile
└── docker-compose.yml