[Go] Go+Vue3 轻量级 Nginx 日志分析工具 NginxPulse：实时可视化与智能 IP 归属地查询

数据指标：
⭐ stars : 1.2k | 🍴 forks : 89
项目地址：https://github.com/likaia/nginxpulse

数据日报

实时统计

访问明细

轻量高效的 Nginx 日志可视化利器

NginxPulse 是一款专为 Nginx 访问日志设计的轻量级分析与可视化面板。它最大的优势在于避免了复杂的依赖，仅仅基于 Go + Vue 技术栈就能实现对日志的实时解析、统计与图形化展示。项目内置了 SQLite 数据库，无需额外部署数据库服务，真正做到了下载即用、开箱即用。

其核心功能相当全面，涵盖了日常运维监控的多个维度：

• 实时 PV/UV 统计
• IP 归属地自动识别（全面支持 IPv4 与 IPv6）
• 客户端设备与浏览器信息解析
• 灵活的日志过滤规则（可轻松排除爬虫、内网 IP、特定访问路径等干扰数据）
• 多站点日志的统一管理与查看

创新亮点：智能 IP 归属地查询策略

在 IP 地理位置解析这个关键环节，NginxPulse 并没有采用单一方案，而是设计了一套多层混合策略，巧妙地在查询速度与结果准确性之间取得了平衡：

1. 本地快速过滤：对于空值、回环地址（如 127.0.0.1）、以及内网 IP 段，系统会直接返回“本地”或“内网”标签，完全避免发起无效的外部查询。
2. 内存缓存加速：系统会在内存中缓存最多 5 万条 IP 查询结果，对于重复的访问请求，可以实现秒级甚至毫秒级的响应。
3. 远程批量查询：对于需要外部查询的 IP，会通过 ip-api.com/batch 接口进行批量查询，一次最多可处理 100 个 IP，极大地提升了查询效率。
4. 本地兜底保障：当远程查询服务不可用或超时（默认 50ms 超时）时，系统会自动无缝切换至内嵌的 ip2region.xdb 本地数据库，确保服务不会中断。
5. IPv6 专项处理：对于 IPv6 地址，目前仅通过远程查询接口获取地理信息，以保证最佳的兼容性与准确性。

更值得一提的是，ip2region.xdb 这个本地地理信息数据库直接被内嵌在最终的可执行二进制文件中。项目首次启动时会自动解压并加载其向量索引，用户无需进行任何手动下载或配置，体验非常顺畅。

极简部署：5 种方式任你选

无论你是专业的 DevOps 工程师还是个人开发者，NginxPulse 都提供了极其灵活的部署方案来适应各种环境。

✅ 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 ./access.log:/share/log/nginx/access.log:ro \
  magiccoders/nginxpulse:latest

运行后，访问 http://localhost:8088 就能看到功能丰富的可视化监控面板。

✅ Docker Compose 多站点管理

如果你需要同时监控多个网站或服务的日志，使用 Docker Compose 并通过 WEBSITES 环境变量传入 JSON 数组配置会非常方便：

environment:
  WEBSITES: '[
    {"name":"博客","logPath":"/logs/blog.log","domains":["blog.example.com"]},
    {"name":"商城","logPath":"/logs/shop.log","domains":["shop.example.com"]}
  ]'
volumes:
  - ./logs:/logs

✅ 单体可执行文件（无依赖）

通过项目提供的 ./scripts/build_single.sh 脚本，可以编译生成一个独立的二进制文件。这个文件内部已打包了所有前端资源，真正做到“一个文件就是一个完整服务”。这种方式特别适合资源有限的边缘设备或需要离线运行的场景。

✅ 手动构建（开发友好）

项目采用前后端分离架构，前端基于 Vue 3 + Vite + TypeScript，后端基于 Go 1.23 + Gin 框架。开发者可以分别进行构建，并且后端支持热重载，非常适合进行二次开发或功能定制。

✅ Makefile 自动化

项目提供了完善的 Makefile，包含 make dev、make single 等常用命令，极大地简化了从开发到构建的整个流程。

强大扩展：支持远端日志与实时推送

🌐 远端日志拉取（sources）

你的 Nginx 日志不一定总在本地。为此，NginxPulse 提供了三种方式来接入远端日志：

• HTTP 服务：直接在日志所在服务器上通过 HTTP 暴露日志文件，或提供一个返回日志文件索引的 JSON API。
• SFTP：通过 SFTP 协议直接连接服务器拉取日志文件。
• 对象存储：支持从 AWS S3、阿里云 OSS 等主流对象存储服务中拉取已归档的日志文件（如 .gz 压缩包）。

📡 Push Agent 实时推送

对于内网隔离或无法直接挂载日志文件的场景，你可以在日志服务器上部署一个轻量级的 Push Agent。这个 Agent 会将日志以流式方式实时推送到 NginxPulse 分析服务器，延迟可以降低到秒级，实现了准实时的日志分析。

灵活适配：自定义日志格式与 Caddy 支持

• Nginx 自定义格式：如果你的 Nginx 使用了自定义的 log_format，别担心。NginxPulse 支持两种方式定义解析规则：使用 logFormat（类 Nginx 变量语法）或 logRegex（正则表达式命名分组）。
• Caddy 原生支持：如果你使用的是 Caddy 服务器，NginxPulse 能够自动解析其默认输出的 JSON 格式日志，无需任何额外配置。
• 压缩日志 (.gz) 直接读取：支持通配符模式匹配压缩日志文件，例如 /logs/access-*.log.gz，系统会自动解压并分析这些文件，非常适合处理历史日志。

安全可控：访问密钥与数据隔离

你可以通过 ACCESS_KEYS 环境变量配置访问密钥。启用后，所有前端页面访问和 API 调用均需通过密钥验证，有效防止未授权访问。同时，你还可以针对每个站点单独配置 PV_EXCLUDE_IPS（排除的 IP 列表）和 PV_EXCLUDE_PATTERNS（排除的 URL 模式），实现对无效流量、爬虫请求的精准过滤，让统计数据更真实、更有价值。

---

总结

NginxPulse 以极简的架构实现了强大的 Nginx 日志分析功能，无论是监控个人博客的访问情况，还是处理企业级的日志分析需求，它都能游刃有余。其创新的智能 IP 查询策略、对多来源日志的支持以及零外部依赖的部署特性，使其在众多日志分析工具中独具特色，非常值得一试。

如果你对这类轻量、高效的运维工具感兴趣，欢迎到 云栈社区 的 运维 & 测试 板块，发现更多实用的技术资源与解决方案。