NginxPulse：轻量高效的Nginx日志分析与实时监控工具部署指南

运维人员或个人服务器管理者通常都需要监控自己网站的访问情况。以往尝试 GoAccess 或 ELK 等方案，要么配置复杂，要么体系过于庞大。最近发现了一个名为 NginxPulse 的项目，使用体验不错，特此分享。

工具简介

简单来说，这是一个轻量级的 Nginx 日志分析面板。主要功能包括：

• 实时查看 PV/UV 数据
• IP 归属地查询（国内使用 ip2region 本地库，国外通过 ip-api）
• 客户端与浏览器解析
• 支持多站点管理
• 支持自定义日志格式

以下是其界面效果：

技术栈

项目后端采用 Go 语言搭配 Gin 框架，前端基于 Vue3 + Vite + PrimeVue，数据库仅使用轻量的 SQLite。其 IP 归属地查询策略颇为巧妙：优先查询内存缓存，其次调用远程 API 进行批量查询，若失败则使用本地 ip2region 库作为兜底方案，有效兼顾了查询速度与准确率。

如何部署运行

Docker 一键部署

最简单的方式是使用 Docker 命令：

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

请将 /your/nginx/logs/access.log 替换为你自己服务器的 Nginx 日志实际路径。

Docker Compose 部署

若习惯使用 Docker Compose，可创建 docker-compose.yml 文件：

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

部署完成后：

• 前端管理面板地址：http://localhost:8088
• 后端 API 地址：http://localhost:8089

多站点配置

若需监控多个网站，只需在 WEBSITES 环境变量中传入 JSON 数组即可：

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

如果日志文件按日期切割，支持使用通配符进行匹配：

{"logPath": "/logs/access-*.log"}

项目还支持直接解析 .gz 压缩格式的日志文件，无需手动解压。

核心实用功能

1. 远端日志拉取

如果日志文件不在部署 NginxPulse 的主机上，支持通过 SFTP、HTTP 或 S3/OSS 等方式从远端拉取。例如，配置 SFTP 拉取：

{
  "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"
}

2. Push Agent 模式

对于位于内网或边缘节点的服务器，可以使用 Agent 主动推送日志。在日志源服务器上运行一个轻量级 Agent，即可将日志实时推送到 NginxPulse 主服务。

3. 自定义日志格式

如果 Nginx 未使用默认的 combined 日志格式，可以自定义解析规则。
方式一：直接使用 Nginx log_format 语法

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

方式二：使用正则表达式（命名分组）

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

4. 支持 Caddy 日志

对于使用 Caddy 服务器的用户，只需在网站配置中指定 "logType": "caddy"，NginxPulse 便会按照 JSON 格式解析 Caddy 的日志。

5. 访问控制

在生产环境部署时，建议启用访问密钥以提高安全性：

ACCESS_KEYS='["your-secret-key"]'

启用后，访问前端面板或调用 API 时需在请求头中携带 X-NginxPulse-Key，前端面板会自动弹出密钥输入框。

常见问题排查

Q：部署后日志明细页面为空，没有数据？
A：这通常是文件权限问题所致。请确保 NginxPulse 容器有权限读取日志目录和数据目录，可尝试执行：

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

Q：网站有访问流量，但面板上 PV/UV 统计始终为 0？
A：默认配置会排除内网 IP 地址的访问统计。若需要统计内网流量，可将 PV_EXCLUDE_IPS 环境变量设置为空数组：

PV_EXCLUDE_IPS='[]'

单体二进制部署

如果不希望使用 Docker，项目也支持构建成单个可执行文件。运行项目自带的构建脚本即可：

./scripts/build_single.sh

该脚本会生成一个内嵌前端资源的二进制文件，直接运行即可同时提供前后端服务，支持 amd64 和 arm64 架构。

项目信息

• GitHub 仓库: https://github.com/likaia/nginxpulse
• 在线演示: https://nginx-pulse.kaisir.cn/

该项目目前已在 GitHub 上获得超过 1.4k 星标，采用 MIT 开源协议，可放心使用。如果你正在寻找一个介于重量级 ELK 和纯命令行 GoAccess 之间的 Nginx 日志分析解决方案，NginxPulse 是一个非常值得尝试的轻量级选择。欢迎在 云栈社区 交流更多服务器监控与运维经验。