一、一句话概括
NginxPulse 是一款轻量级的 Nginx 访问日志分析与可视化面板，可以实时统计访问量（PV）、按多种维度过滤日志，并自动解析 IP 归属地和客户端信息，自带 Web 前端，适合部署在个人服务器、中小站点或内部环境中使用。
二、产品定位与核心价值
● 目标场景： 已经使用 Nginx 作为 Web 服务器 / 反向代理，希望通过访问日志做一些「轻量级」实时监控与分析。
○ 不想引入重量级监控/可观测平台（比如 ELK、Prometheus+Grafana 等），只想要一个开箱即用的小工具。
● 核心价值： 部署简单：Docker 一键跑起来，不需要复杂依赖。
○ 日志分析自动化：自动解析 Nginx 访问日志，PV/访问趋势、IP 归属地、客户端信息等全部自动完成。
○ 轻量：单容器内集成前端与后端，使用 SQLite 本地存储，不依赖外部数据库服务。
三、整体工作流程示意
下面是 NginxPulse 的大致工作流程：
flowchart TB A[Nginx 服务器<br/>access.log] --> B[NginxPulse 后端<br/>定时扫描日志] B --> C[日志解析<br/>提取 IP / URL / 状态码 / UA 等] C --> D[IP 归属地查询<br/>ip2region + ip-api.com] C --> E[写入 SQLite 数据库] E --> F[后端 API 提供<br/>统计与过滤查询] F --> G[前端可视化面板<br/>图表与多维筛选] G --> H[运维/开发人员<br/>查看访问情况与异常]
四、主要功能特性
1) 日志分析与实时统计
● 定时扫描你指定的 Nginx 访问日志文件，解析其中的字段（如 IP、时间、URL、状态码、User-Agent 等）。
● 将解析后的数据写入本地 SQLite 数据库，供后续查询与可视化使用。
● 支持按配置的时间间隔（TASK_INTERVAL）来定时扫描，默认为 1 分钟。
2) PV 统计与灵活过滤
● PV 统计可按指定 HTTP 状态码来统计（默认只统计 200 成功请求，也可自定义状态码列表）。
● URL 排除规则：支持配置 PV_EXCLUDE_PATTERNS（URL 正则数组），比如排除静态资源、爬虫路径等，避免污染 PV 统计。
● IP 排除规则：支持配置 PV_EXCLUDE_IPS，将指定 IP（如内部监控、健康检查）从统计中排除。
● Referer 与站内访问：通过 WEBSITES 中配置 domains，可以把来自指定域名的 referer 归类为「站内访问」，方便区分外部来源。
3) IP 归属地解析（多级策略）
NginxPulse 为 IP 归属地设计了一套“快速 + 准确”的多级策略：
● 快速过滤： 空值 / 本地 / 回环地址直接返回“本地”。
○ 内网地址直接返回“内网/本地网络”。
● 缓存优先： 内存缓存，最多缓存 50,000 条 IP 查询结果，重复 IP 直接命中缓存，减少外部 API 调用。
● 远程优先： 调用 ip-api.com/batch 批量接口查询归属地，超时时间 1.2s，每批最多 100 个 IP。
● 本地兜底： 当远程失败或者结果为“未知”时，IPv4 使用内置的 ip2region 数据库做本地查询，超时 50ms。
○ 本地数据库文件 ip2region.xdb 内嵌在二进制中，首次启动会自动解压到 ./var/nginxpulse_data/ip2region.xdb，并加载向量索引加速查询。
● IPv6 处理： IPv6 仅走远程 API，远程失败则返回“未知”。
● 注意： 项目会访问外网 IP 归属地 API（ip-api.com），部署环境需要放行该域名的出站访问。
4) 客户端解析
● 基于 HTTP 请求中的 User-Agent 等字段，识别客户端类型（浏览器、爬虫等）与基础设备信息（具体展示形式以前端页面为准）。
5) 可视化面板（Web UI）
● 前端技术栈：Vue 3 + Vite + TypeScript + PrimeVue + ECharts/Chart.js + Scss，使用组件化 UI 和图表库，便于做交互式展示。
● 提供在线演示：nginx-pulse.kaisir.cn（可直接访问体验可视化效果）。
● 常见可视化能力包括（以前端实际页面为准）： 访问量趋势图（按时间维度统计 PV）。
○ IP 访问分布（国家/地区分布、常见来源 IP）。
○ URL 热度排行（哪些路径被访问最多）。
○ 状态码分布（2xx/3xx/4xx/5xx 比例）。
○ 客户端/浏览器类型统计。
6) 多站点/多日志支持
● WEBSITES 支持传入数组，每个元素包含： name：站点名称。
○ logPath：容器内日志路径。
○ domains（可选）：与该站点关联的域名列表，用于 referer 站内访问分析。
● 通过挂载多个日志文件或整个日志目录，并在 WEBSITES 中配置多条记录，即可用一个 NginxPulse 实例同时分析多个站点或多组日志。
7) 演示模式（Demo Mode）
● 提供 DEMO_MODE 环境变量（默认 false），开启后： 定时生成模拟日志，并直接写入数据库。
○ 不再解析真实日志文件，适合演示、测试 UI 和功能，而不需要准备真实 Nginx 日志。
五、技术架构与组件
● 后端： 语言：Go 1.23.x。
○ Web 框架：Gin。
○ 日志库：Logrus。
○ 数据存储：SQLite（使用 modernc.org/sqlite）。
● 前端： 框架：Vue 3。
○ 构建工具：Vite。
○ 语言：TypeScript。
○ UI 组件：PrimeVue。
○ 图表：ECharts / Chart.js。
○ 样式：Scss。
● 容器与部署： 单容器镜像内包含： 后端服务（Go）。
■ 前端静态资源（由 Nginx 提供访问）。
○ 支持 Docker / Docker Compose 一键部署与编排。
六、部署与使用方式概览
1) 使用 Docker Hub 远程镜像（最简单）
● 示例命令（来自 README）：
docker run -d --name nginxpulse \
-p 8088:8088 \
-p 8089:8089 \
-e WEBSITES='[{"name":"主站","logPath":"/share/log/nginx/access.log","domains":["kaisir.cn","www.kaisir.cn"]}]' \
-v ./nginx_data/logs/all/access.log:/share/log/nginx/access.log:ro \
-v "$(pwd)/var/nginxpulse_data:/app/var/nginxpulse_data \
magiccoders/nginxpulse:latest● 访问： 前端：http://localhost:8088
○ 后端 API：http://localhost:8089
2) 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":["kaisir.cn","www.kaisir.cn"]}]'
volumes:
- ./nginx_data/logs/all/access.log:/share/log/nginx/access.log:ro
- ./var/nginxpulse_data:/app/var/nginxpulse_data
- /etc/localtime:/etc/localtime:ro
restart: unless-stopped● 启动：
docker compose up -d3) 手动构建与开发
● 前端构建：
cd webapp
npm install
npm run build● 后端构建：
go mod download
go build -o bin/nginxpulse ./cmd/nginxpulse/main.go● 本地开发（前后端一起跑）：
./scripts/dev_local.sh● 开发环境说明： 前端开发服务默认 8088，并把 /api 代理到 http://127.0.0.1:8089。
○ 本地开发前准备好日志文件（如放在 var/log/ 下，或修改配置中的 logPath）。
七、关键配置说明（环境变量）
主要环境变量与含义（无配置文件时尤为关键）：
● WEBSITES（必填）： JSON 数组，每个元素为站点对象，字段： name：站点名称。
■ logPath：容器内日志路径。
■ domains（可选）：站点域名列表，用于站内访问统计。
● CONFIG_JSON（可选）： 完整配置 JSON 字符串（等同 configs/nginxpulse_config.json）。
○ 设置后会忽略本地配置文件，其他环境变量仍可覆盖其中字段。
● LOG_DEST（可选，默认：file）： 日志输出位置：file 或 stdout。
● TASK_INTERVAL（可选，默认：1m）： 扫描间隔，支持 Go duration 格式（如 5m、25s）。
● DEMO_MODE（可选，默认：false）： 开启演示模式，生成模拟日志。
● SERVER_PORT（可选，默认：:8089）： 后端监听地址，可传 :8089 或 8089。
● PV_STATUS_CODES（可选，默认：[200]）： 统计 PV 的状态码列表，支持 JSON 数组或逗号分隔。
● PV_EXCLUDE_PATTERNS（可选，默认有内置规则）： 全局 URL 排除正则数组（JSON 数组）。
● PV_EXCLUDE_IPS（可选，默认为空或使用配置文件）： 排除 IP 列表（JSON 数组或逗号分隔）。
八、多日志与多站点实战建议
● 方式一：逐条挂载多个日志文件： WEBSITES 数组中为每个网站配置一个 logPath，volumes 分别挂载对应日志文件（只读）。
● 方式二：挂载日志目录，然后在 WEBSITES 里按需指定文件： 示例：volumes 挂载 ./nginx_data/logs:/share/log/nginx。
○ WEBSITES 中 logPath 写为 /share/log/nginx/access-site1.log、access-site2.log 等。
● 挂载 var/nginxpulse_data： 用于持久化 SQLite 数据库和解析缓存，推荐保留以便重启不丢数据。
九、适用场景与限制
● 适合： 个人博客、中小型站点、内部系统访问分析。
○ 想「从 0 到 1」快速搭建一套日志可视化面板，而不是搭建完整可观测平台。
● 限制： 面向 Nginx 访问日志，主要做访问统计与可视化，不提供全面的 APM/链路追踪能力。
○ 使用单机 SQLite，适合中小规模；如果日志量特别大或需要多节点协同分析，需要评估或扩展。
○ 使用外部 IP API（ip-api.com），内网环境需要保证能访问该域名，或者自行更换/禁用远程查询功能。
十、如何开始？
如果你现在就想试用：
● 最快方式： 使用上面的 Docker 命令或 docker-compose.yml，把你的 Nginx access.log 路径映射进去。
○ 设置好 WEBSITES，然后访问 http://your-host:8088 查看面板。
● 想先看效果： 直接打开演示站点：nginx-pulse.kaisir.cn 体验 UI 与交互。
十一、开源与许可
● 项目在 GitHub 上开源（likaia/nginxpulse），采用 MIT 许可证，可自由使用、修改和分发。