A Lightweight Nginx Log Analyzer That Actually Works

Overview

Lightweight Nginx log analysis panel that shows real‑time PV/UV, IP geolocation (ip2region for China, ip‑api for overseas), client/browser parsing, multi‑site support, and custom log format handling.

Technology Stack

Backend: Go + Gin. Frontend: Vue3 + Vite + PrimeVue. Database: SQLite.

IP geolocation flow: check in‑memory cache → batch remote API query → fallback to local ip2region database.

Running the Service

Docker one‑liner

docker run -d --name nginxpulse \
  -p 8088:8088 \
  -p 8089:8089 \
  -e WEBSITES='[{"name":"主站","logPath":"/share/log/nginx/access.log","domains":["example.com"]}]' \
  -v /your/nginx/logs/access.log:/share/log/nginx/access.log:ro \
  -v $(pwd)/var/nginxpulse_data:/app/var/nginxpulse_data \
  magiccoders/nginxpulse:latest

Replace /your/nginx/logs/access.log with the actual log file path.

Docker Compose

version: "3.8"
services:
  nginxpulse:
    image: magiccoders/nginxpulse:latest
    container_name: nginxpulse
    ports:
      - "8088:8088"
      - "8089:8089"
    environment:
      WEBSITES: '[{"name":"主站","logPath":"/share/log/nginx/access.log","domains":["example.com"]}]'
    volumes:
      - ./nginx_logs/access.log:/share/log/nginx/access.log:ro
      - ./var/nginxpulse_data:/app/var/nginxpulse_data
    restart: unless-stopped

Frontend panel: http://localhost:8088. Backend API: http://localhost:8089.

Multi‑site Configuration

WEBSITES='[
  {"name":"主站","logPath":"/logs/main.log","domains":["www.example.com"]},
  {"name":"博客","logPath":"/logs/blog.log","domains":["blog.example.com"]}
]'

Wildcard paths such as "/logs/access-*.log" are supported; compressed .gz logs are parsed directly.

Practical Features

Remote Log Retrieval

Supported protocols: SFTP, HTTP, S3/OSS. Example SFTP configuration:

{
  "id": "sftp-main",
  "type": "sftp",
  "host": "1.2.3.4",
  "port": 22,
  "user": "nginx",
  "auth": {"keyFile": "/secrets/id_rsa"},
  "path": "/var/log/nginx/access.log"
}

Push Agent

Lightweight agent can push logs from NAT‑ed or edge servers to the NginxPulse server in real time.

Custom Log Formats

Method 1 – direct log_format syntax:

{
  "logFormat": "$remote_addr - $remote_user [$time_local] \"$request\" $status $body_bytes_sent"
}

Method 2 – regular expression with named groups:

{
  "logRegex": "^(?P<ip>\\S+) - (?P<user>\\S+) \[(?P<time>[^\\]]+)\]..."
}

Caddy Compatibility

Set logType: "caddy" to parse JSON‑formatted Caddy logs.

Access Control

Define ACCESS_KEYS='["your-secret-key"]' and include header X-NginxPulse-Key in requests; the frontend prompts for the key.

Common Issues

Empty log details after startup

Usually a permission problem. Grant read/write permissions:

chmod -R 777 /path/to/logs /path/to/nginxpulse_data

PV/UV values remain zero

Internal IPs are excluded by default. Set PV_EXCLUDE_IPS='[]' to include them.

Standalone Deployment

Build a single executable that bundles the frontend: ./scripts/build_single.sh The binary runs on amd64 and arm64 and serves both backend and frontend.

Repository

https://github.com/likaia/nginxpulse

MIT‑licensed, >1.4k stars.

Comparison

Positions between heavyweight ELK stacks and command‑line‑only tools such as GoAccess: lightweight, easy to deploy, and feature‑rich.