Nginx日志分析工具NginxPulse：轻量级实时面板，支持Docker部署与多站点

对于运维工程师或个人服务器管理员来说，监控网站访问情况是一个常见需求。

此前，你可能尝试过 GoAccess、ELK Stack 等方案，它们要么配置过程繁琐，要么体系过于庞大。最近，我发现了一个名为 NginxPulse 的开源项目，实际体验下来感觉相当不错，值得分享。

NginxPulse 是什么？

简单来说，它是一个轻量级的 Nginx 日志分析可视化面板。

主要功能包括：

• 实时查看 PV（页面浏览量）、UV（独立访客）等核心数据。
• 查询 IP 归属地（国内使用 ip2region 本地库，国外调用 ip-api 接口）。
• 解析客户端设备与浏览器信息。
• 支持同时监控多个网站或服务。
• 支持自定义日志格式。

来看一下它的实际效果：

技术栈与设计

项目后端采用 Go 语言和 Gin 框架编写，前端基于 Vue3 + Vite + PrimeVue 构建，数据存储仅使用一个 SQLite 数据库，整体设计非常轻量。

其 IP 归属地查询逻辑设计得较为巧妙：优先查询内存缓存，未命中则通过远程 API 批量查询以提高效率，若 API 请求失败则回退至本地 ip2region 数据库。这套策略在保证查询速度的同时，也兼顾了准确率。

如何快速部署

使用 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，可以创建如下配置文件：

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://你的服务器IP:8088
• 后端 API 接口：http://你的服务器IP:8089

配置多站点监控

如果你需要监控多个网站，只需将 WEBSITES 环境变量配置为一个数组即可：

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

对于按日期切割的日志文件（例如 access-20231001.log），NginxPulse 支持通配符匹配：

{"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 格式，NginxPulse 提供了两种自定义解析方式：

方式一：直接使用 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 便会按照 Caddy 的 JSON 日志格式进行解析。

5. 访问控制与安全

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

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

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

常见问题排查

Q：服务运行后，日志明细页面为何为空？
A：这通常是文件权限问题所致。请确保 NginxPulse 容器有权限读取日志文件和数据目录。可以尝试执行以下命令（请根据实际情况调整路径）：

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

Q：明明有访问记录，但面板上显示的 PV/UV 始终为 0？
A：NginxPulse 默认会排除内网 IP 地址的访问统计。如果你需要统计内网流量，可以将 PV_EXCLUDE_IPS 环境变量设置为空数组：

PV_EXCLUDE_IPS='[]'

单体二进制文件部署

如果你不希望依赖 Docker 环境，也可以将 NginxPulse 构建为单一的可执行文件：

./scripts/build_single.sh

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

总结与项目信息

NginxPulse 是一个在 GitHub 上开源的项目，采用 MIT 协议，目前获得了超过 1.2k 的 Star。它定位清晰，在功能强大的 ELK Stack 和轻便但仅限命令行的 GoAccess 之间，提供了一个不错的折中选择。

如果你正在寻找一个部署简单、界面直观、功能实用的 Nginx 日志分析方案，不妨试试 NginxPulse。对于更复杂的监控需求或希望与其他运维、开发同行交流经验，也欢迎到 云栈社区 的相关板块进行探讨。