轻量级 Nginx 日志分析和可视化平台 NginxPulse安装

NginxPulse 整体介绍

NginxPulse 是一个开源（MIT 协议，GitHub: likaia/nginxpulse）的轻量级 Nginx 访问日志分析与可视化面板，定位是"GoAccess 的现代化替代品 + 不入侵架构的站内统计"。

技术栈 ：Go（Gin）后端 + Vue3 前端，打包成单一 Docker 镜像；新版本（>1.5.3）内置 PostgreSQL 做长期存储（老版本用 SQLite），也支持单机二进制运行。
核心能力
- 实时 PV/UV、QPS 趋势、状态码（2xx/3xx/4xx/5xx）分布
- 客户端 IP 归属地（本地 ip2region + 远程 ip-api 双策略）、UA/浏览器/OS 解析
- 热门 URL、Referer 来源、多站点统一管理
- 直接读 标准/自定义 Nginx 日志格式 、支持 .gz 压缩历史日志、按天切割通配、断点续传
- 可排除内网/爬虫 IP（PV_EXCLUDE_IPS），支持 SFTP/HTTP/S3 拉远端日志
- 移动端 /m 页面、首次启动有 Web 初始化向导
不是什么：不是 APM、不是告警系统、不替代 Prometheus+Grafana，纯粹是"把 access.log 变成图表"的轻量阅读器，适合个人站/中小运维快速看流量。

看下效果图：

Docker 安装教程（最常用路径）

1. 准备宿主机目录与日志

bash 复制代码

# 数据目录
mkdir -p /data/nginxpulse/{logs,nginxpulse_data,pgdata,configs}
chmod 777 /data/nginxpulse

# 假设你本机 Nginx 日志在 /var/log/nginx/access.log
# 确保容器能读到（挂载时用 :ro）

2. 单条 docker run（最快验证）

javascript 复制代码

docker run -d --name nginxpulse \
  -p 8088:8088 \
  -p 8089:8089 \
  -e WEBSITES='[{"name":"主站","logPath":"/share/log/nginx/access.log","domains":["example.com","www.example.com"]}]' \
  -v /var/log/nginx/access.log:/share/log/nginx/access.log:ro \
  -v /data/nginxpulse/nginxpulse_data:/app/var/nginxpulse_data \
  -v /data/nginxpulse/pgdata:/app/var/pgdata \
  -v /data/nginxpulse/configs:/app/configs \
  -v /etc/localtime:/etc/localtime:ro \
  magiccoders/nginxpulse:latest

8088 = 前端面板，8089 = 后端 API
浏览器开 http://服务器IP:8088 → 首次进初始化向导填日志路径也行，或直接用 WEBSITES 环境变量注入（推荐环境变量，避免向导踩坑）

3. docker-compose 部署（生产推荐）

/data/nginxpulse/docker-compose.yml：

javascript 复制代码

version: "3.8"
services:
  nginxpulse:
    image: magiccoders/nginxpulse:latest
    container_name: nginxpulse
    ports:
      - "8088:8088"
      - "8089:8089"
    environment:
      TZ: Asia/Shanghai
      WEBSITES: '[{"name":"主站","logPath":"/share/log/nginx/access.log","domains":["example.com"]}]'
    volumes:
      - /var/log/nginx/access.log:/share/log/nginx/access.log:ro
      - /data/nginxpulse/nginxpulse_data:/app/var/nginxpulse_data
      - /data/nginxpulse/pgdata:/app/var/pgdata
      - /data/nginxpulse/configs:/app/configs
      - /etc/localtime:/etc/localtime:ro
    stop_grace_period: 90s   # 给内置 PG 优雅关闭
    restart: unless-stopped

启动：

bash 复制代码

cd /data/nginxpulse
docker compose up -d
docker compose logs -f nginxpulse

4. 多站点 / 多日志配置

WEBSITES 是 JSON 数组，可配多个：

css 复制代码

[  {"name":"主站","logPath":"/share/log/nginx/access.log","domains":["example.com"]},
  {"name":"博客","logPath":"/share/log/blog.log","domains":["blog.example.com"]}
]

挂载时把对应日志都挂进容器，路径要跟 logPath 一致。logPath 支持通配如 /share/log/nginx/access-*.log。

5. 常见坑

PV 一直是 0 → 默认排除内网 IP，设 PV_EXCLUDE_IPS='[]' 可包含；或确认日志格式是否被自动识别（自定义格式需在向导里贴 log_format 或正则）。
日志明细空 → 宿主机日志文件权限、:ro 挂载、容器用户读权限；chmod 644 原日志试试。
时间对不上 → 必须挂 /etc/localtime:ro，或设 TZ=Asia/Shanghai。
PG 目录权限 → 首次启动 PG 初始化失败多因 pgdata 目录权限不对，建目录后 chmod 777 再起可避坑。
想换 SQLite 老版本 → 用 likaia/nginxpulse 早期 tag，新版已弃用 SQLite。