NginxPulse整体介绍

NginxPulse 是一个开源的轻量级 Nginx 访问日志分析与可视化面板定位是“GoAccess 的现代化替代品 + 不入侵架构的站内统计”。

• 技术栈Go后端 + Vue3 前端，打包成单一 Docker 镜像；新版本内置 PostgreSQL 做长期存储，也支持单机二进制运行。

  

• 主要能力

  • 实时 PV/UV、QPS 趋势、状态码分布
  • 客户端 IP 归属地、UA/浏览器/OS 解析
  • 热门 URL、Referer 来源、多站点统一管理
  • 直接读标准/自定义 Nginx 日志格式。支持 .gz 压缩历史日志、按天切割通配、断点续传
  • 可排除内网/爬虫 IP，支持 SFTP/HTTP/S3 拉远端日志
  • 移动端 /m 页面、首次启动有 Web 初始化向导

• • 不是 APM、不是告警程序、不替代 Promeus+Grafana，纯粹是“把 access.log 变成图表”的轻量阅读器，适合个人站/中小运维快速看流量。

  效果图请自行查看项目文档。

Docker 安装教程

1. 准备宿主机目录与日志文件——先搞清楚权限问题！

# 创建数据目录
mkdir -p /data/nginxpulse/{logs,nginxpulse_data,pgdata。configs}
chmod -R 777 /data/nginxpulse
# 假设 Nginx 日志位于 /var/log/nginx/access.log
# 确保容器能读取
rsync -a /var/log/nginx/access.log /data/nginxpulse/logs/
chmod 644 /data/nginxpulse/logs/access.log

痛点提醒：若容器报 “log file not found” 或 “permission denied”，检查宿主机日志文件权限还有挂载是否正确。

2. 单条 docker run——最快验证安装成功与否！

docker run -d --name nginxpulse \
-p 8080:8080 \
-e WEBSITES='}]' \
-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

前端面板：http://服务器IP:8080/dashboard.html？token=... 后端 API：http://服务器IP:8080/api/v1/...

至于关键步骤拆解，

• 前后端分离方法固定：- 前端静态文件在容器内部默认方法为 /app/static/public/dashboard.html?token=...,后端 API 在同一域名下的路由前缀为 /api/v1//…​，
• 初始化向导或环境变量两种方式：- 若不使用环境变量，可在浏览器打开面板后按向导提示填写日志方法；但推荐使用环境变量避免手动配置错误。
• 时间同步非常关键：- 必须挂载时钟或设置 TZ，否则时间戳会错位导致图表显示错误。
• PostgreSQL 权限坑：- 若 PG 数据目录权限不对，首次启动会报错。建议创建空目录后执行 `chmod a+rwx` 再启动。
• 内网 IP 排除导致 PV 为零：- 默认排除内网 IP，可通过 `PV_EXCLUDE_IPS=''` 打开全部；如果想排除特定爬虫 IP，请在后台配置中添加。
• 自定义 log_format 无法识别：- 自定义格式需在向导中粘贴完整 `log_format` 或提供正则表达式，否则网站无法解析。若出现 “日志明细空” 请检查此项。
• 多站点配置需匹配 logPath 方法：- 每个站点的 `logPath` 必须与宿主机挂载方法一致。而且支持通配符，例如 `/share/log/nginx/access-*.log`。否则会出现 “找不到对应日志文件” 的错误。
• `PG 数据持久化 & 启动顺序注意事项`： • 第一次运行时需要等待 PostgreSQL 完成初始化； • 若出现 “database is not initialized” 错误。请确保 PG 数据目录已存在而且拥有正确权限，接下来重新启动容器。

3. docker-compose 部署——生产推荐方式，更易维护和

version: "3"
services:
nginxpulse:
说到image，magiccoders/nginxpulse:latest
container_name: nginxpulse
再看ports，- "8080:8080"
environment:
TZ的观点是。Asia/Shanghai
WEBSITES: '}]'
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.ngnixspulse/configs:/app/configs
- /etc/localtime:/etc/localtime:ro
stop_grace_period: "90s" # 给内置 PG 优雅关闭
restart: unless-stopped

 部署提示: 请根据实际需求修改 WEBSITES JSON 并保证所有挂载方法都存在且权限正确，否则容器可能无法正常读取日志或写入数据库。

常见坑汇总 — 一次性解决你最头疼的问题！">

• PLOG 始终为零: 默认排除内网 IP，可通过 PV_EXCLUDE_IPS='' 打开全部；或者确认是否使用了自定义 log_format 并在向导里粘贴完整格式或正则，否则网站无法解析。
• 日志明细为空: 检查宿主机日志文件权限及容器挂载是否使用 :ro 并确保容器使用者具有读权限。尝试执行 chmod 644 /path/to/access.log 再重启容器。
• 时间对不上: 一定要挂载 /etc/localtime RO 或设置 TZ 环境变量，例如 TZ=Asia/Hong_Kong。其实，否则所有时间轴都会偏移。 L I>P G 数据目录权限: 首次启动 PostgreSQL 初始化失败通常是因为 pgData 文件夹无写权限。创建后执行 chmod a+rwx /data/...pgdata && chown postgres…: 再重启即可。LH T ID = “” Heading‑UseSQLiteOldVersion"> L I>S Q L i t e 老版本: 如果你更喜欢 SQLite 而非 PostgreSQL。可以拉取旧版镜像：例如 Likaia/NginxPulse:v1.x.x，新版已弃用 SQLite。按理说，

 注意：SQLite 对磁盘 IO 较敏感。建议仅用于测试或极小规模场景。

 同时如果某些网站的访问量很低。建议开启 **PV_EXCLUDE_IPS** 排除规则，以免影响整体统计准确性。