阅读全文

⭐⭐⭐ Spring Boot 项目实战	⭐⭐⭐ Spring Cloud 项目实战
《Dubbo 实现原理与源码解析 —— 精品合集》	《Netty 实现原理与源码解析 —— 精品合集》
《Spring 实现原理与源码解析 —— 精品合集》	《MyBatis 实现原理与源码解析 —— 精品合集》
《Spring MVC 实现原理与源码解析 —— 精品合集》	《数据库实体设计合集》
《Spring Boot 实现原理与源码解析 —— 精品合集》	《Java 面试题 + Java 学习指南》

摘要: 原创出处 http://www.iocoder.cn/Fight/5fenzhongdajian-Nginx-rizhijiankongzhongxinqingliangkaiyuanjikaijiyong/ 「芋道源码」欢迎转载，保留摘要，谢谢！

• 为什么需要它
• 功能概览
• 部署方式
• 多站点和压缩日志
• 权限踩坑
• 常见问题速查
• 和 GoAccess / ELK 怎么选

---

🙂🙂🙂关注微信公众号：【芋道源码】有福利：

1. RocketMQ / MyCAT / Sharding-JDBC 所有源码分析文章列表
2. RocketMQ / MyCAT / Sharding-JDBC 中文注释源码 GitHub 地址
3. 您对于源码的疑问每条留言都将得到认真回复。甚至不知道如何读源码也可以请教噢。
4. 新的源码解析文章实时收到通知。每周更新一篇左右。
5. 认真的源码交流微信群。

---

服务器跑着，Nginx 每天生成一堆访问日志，但大部分时候没人去看。等出问题了才翻出来逐行 grep、awk、tail -f，找个 IP 折腾半天。

nginxpulse 是一个轻量的 Nginx 访问日志分析面板——Docker 一条命令拉起来，自动解析日志，图表展示 PV/UV、IP 归属地、状态码分布、客户端占比。

为什么需要它

ELK 能力强但吃资源（内存至少几个 G），个人服务器扛不住。GoAccess 功能成熟但上手有门槛。Prometheus + Nginx Exporter 偏进程监控，对访问日志的分析维度有限。

nginxpulse 卡在中间位置：比 GoAccess 上手快，比 ELK 轻得多。适合不需要复杂日志管道、只想快速看清网站访问情况的场景。

技术栈：Go（Gin） + Vue 3 + TypeScript + ECharts，数据库 PostgreSQL（1.5.3 后已从 SQLite 迁移），IP 归属地用 ip2region + ip-api.com。Docker 镜像内置 PostgreSQL，不用单独装。

功能概览

PV / UV 统计：首次启动解析全量历史日志入库，之后持续监听新日志。统计维度：总 PV、UV、QPS、响应时间分布。默认排除内网 IP。

IP 归属地：先查本地 ip2region，查不到再请求 ip-api.com，结果缓存避免重复查询。页面偶尔显示”待解析”是正常的，后台任务还没跑完。

状态码分布：2xx/3xx/4xx/5xx 占比一目了然。4xx 飙高 → 有人扫路径或资源链接挂了；5xx 高 → 应用层出问题。

客户端解析：浏览器、操作系统、移动端/桌面端占比，个人站长可以指导移动端适配优先级。

实时流量：当前请求实时滚动，适合压测时盯着看或发版时确认流量正常。

数据日报：按天汇总，可对比不同日期的访问量变化。

移动端有 /m 入口，支持概览、日报、实时、日志四个页面。但首次初始化必须在电脑上完成。

部署方式

Docker（最快）

docker run -d --name nginxpulse \
  -p 8088:8088 \
  -v ./docker_local/logs:/share/logs:ro \
  -v ./docker_local/nginxpulse_data:/app/var/nginxpulse_data \
  -v ./docker_local/pgdata:/app/var/pgdata \
  -v ./docker_local/configs:/app/configs \
  -v /etc/localtime:/etc/localtime:ro \
  magiccoders/nginxpulse:latest

挂载路径	用途
/share/logs	日志目录（只读）
/app/var/nginxpulse_data	应用数据（必须挂载）
/app/var/pgdata	PostgreSQL 数据（必须挂载）
/app/configs	配置文件持久化
/etc/localtime	同步宿主机时区

启动后访问 http://IP:8088。时区一定要设置，否则日志时间解析偏差，统计数据全乱。

Docker Compose

services:
  nginxpulse:
    image: magiccoders/nginxpulse:latest
    container_name: local_nginxpulse
    ports:
      - "8088:8088"
      - "8089:8089"
    volumes:
      - ./docker_local/logs:/share/logs
      - ./docker_local/nginxpulse_data:/app/var/nginxpulse_data
      - ./docker_local/pgdata:/app/var/pgdata
      - ./docker_local/configs:/app/configs
      - /etc/localtime:/etc/localtime
    stop_grace_period: 90s
    restart: unless-stopped

stop_grace_period: 90s 不能省——内置 PostgreSQL 关闭时需要时间落盘，不给够会导致下次启动走恢复流程。

docker compose up -d

单体二进制

从 GitHub Releases 下载，直接运行。1.5.3 后需自备 PostgreSQL，在配置文件里填 database.dsn。

TZ=Asia/Shanghai ./nginxpulse

多站点和压缩日志

一台服务器跑多个站点时，把日志目录整体挂进去，配置里分别指定：

[
  {"name": "站点A", "logPath": "/share/log/nginx/access-site-a.log", "domains": ["a.example.com"]},
  {"name": "站点B", "logPath": "/share/log/nginx/access-site-b.log", "domains": ["b.example.com"]}
]

压缩日志直接支持，logPath 可指向 .gz 文件或通配符：

{"logPath": "/share/log/nginx/access-*.log.gz"}

历史日志不用解压，直接拿来用。

权限踩坑

nginxpulse 默认以非 root 用户运行。容器内能否读日志、写数据，取决于宿主机目录权限。

# 查看 UID/GID
ls -n /path/to/logs /path/to/nginxpulse_data

# 启动时传入
docker run ... -e PUID=1000 -e PGID=1000 ...

# 确保权限
chown -R 1000:1000 /path/to/nginxpulse_data /path/to/pgdata
chmod -R u+rx /path/to/logs

RHEL/CentOS/Fedora 开了 SELinux 的，volume 后面加 :z 或 :Z：

-v /path/to/logs:/var/log/nginx:ro,Z

不要 chmod 777——只能临时排查用，不适合生产。

常见问题速查

问题	原因	解决
日志明细没内容	权限问题	检查容器内用户对日志文件的读权限
PV/UV 一直是 0	默认排除内网 IP	把 PV_EXCLUDE_IPS 设为空，重新解析
日志时间不对	时区未同步	挂载 /etc/localtime，重新解析
数据会一直积累吗	有自动清理	按 logRetentionDays 清理，默认 30 天

和 GoAccess / ELK 怎么选

工具	优势	不足
nginxpulse	Docker 一键部署、图表直观、资源占用低	功能比 ELK 少
GoAccess	成熟稳定、命令行高效	上手有门槛、Web 界面较朴素
ELK	能力最强、可查询任意维度	资源消耗极高、部署运维复杂
Prometheus + Grafana	监控生态完善	偏进程监控，日志分析维度有限

开源地址：https://github.com/likaia/nginxpulse

文档站点：https://nginx-pulse-docs.kaisir.cn/