likaia / nginxpulse

English | 简体中文 NginxPulse 轻量级 Nginx 访问日志分析与可视化面板，提供实时统计、PV 过滤、IP 归属地与客户端解析。 源码仓库：https://github.com/likaia/nginxpulse 文档站点（推荐） > **在线文档站点： ** > > Wiki 仍可访问（历史资料）：https://github.com/likaia/nginxpulse/wiki > ⚠️注意：此文档只讲解了如何使用这个项目，详细文档与示例配置请移步Wiki：https://github.com/likaia/nginxpulse/wiki 目录 • 项目开发技术栈 • IP 归属地查询策略 • 如何使用项目 • 1) Docker • 2) Docker Compose • 时区设置（重要） • 3) 手动构建（前端、后端） • 4) 单体部署（单进程） • 5) Makefile 常用命令 • Docker 部署权限说明 • 常见问题 • 目录结构与主要文件 • 致谢 项目开发技术栈 **重要提示（版本 > 1.5.3）**：已完全弃用 SQLite；单体部署必须自备 PostgreSQL 并配置 （或 ）。 • **后端**： · · • **数据**： • **IP 归属地**： （本地库） + （远程批量） • **前端**： · · · · · • **容器**： · （前端静态部署） IP 归属地查询策略 • **快速过滤**：空值/本地/回环地址返回“本地”，内网地址返回“内网/本地网络”。 • **解析解耦**：日志解析阶段仅入库并标记“待解析”，IP 归属地由后台任务异步补齐并回填。 • **缓存优先**：持久化缓存 + 内存缓存命中直接返回（默认上限 1,000,000 条）。 • **本地优先（IPv4/IPv6）**：优先查 ip2region，本地结果可用时直接使用。 • **远程补齐**：本地返回“未知”或解析失败时，调用远端 API（默认 ，可配置）批量查询（超时 1.2s，单批最多 100 个）。 • **远程失败**：返回“未知”。 > 归属地解析未完成时，页面会显示“待解析”，地域统计可能不完整。 > 本地数据库 与 内嵌在二进制中，首次启动会自动解压到 ，并尝试加载向量索引提升查询性能。 > 本项目会访问外网 IP 归属地 API（默认 ），部署环境需放行该域名的出站访问。同时也支持自己搭建IP归属地查询服务，详见下文。 如何使用项目 1) Docker 单镜像（前端 Nginx + 后端服务）： > 镜像内置 PostgreSQL，启动时会自动初始化数据库（未自备数据库时）。**必须挂载数据目录**： 与 。未挂载时容器会直接退出并报错。 > 如果你准备在**初始化向导**里配置外部数据库，可先不挂载 ，容器能正常启动；配置完成后重启容器即可生效。 一键启动（极简配置，首次启动进入初始化向导）： > 注意：docker_local请替换为你宿主机存在的目录，确保文件权限设置正确，能被容器正常访问，否则会出现无日志的情况。 > 如果更偏好配置文件方式，可将 挂载到容器内的 。 > 若未提供配置文件/环境变量，首次启动会进入“初始化配置向导”。保存后会写入 ，需重启容器生效（建议挂载 以持久化）。 2) Docker Compose 使用远程镜像（Docker Hub）： > 建议保留 （如 ），让内置 PostgreSQL 在 时有足够时间完成一致性关闭，避免下次启动进入恢复重试。 时区设置（重要） 本项目使用**系统时区**进行日志时间解析与统计，请确保运行环境时区正确。 **Docker / Docker Compose** • 推荐挂载宿主机时区： （Linux） • 若宿主机提供 ，可额外挂载： • 若你只想指定时区，可设置 ，但需保证容器内有时区数据（例如安装 或挂载 ） **单体部署（单进程）** • 默认使用当前系统时区 • 可通过环境变量临时指定： 移动端访问（/m） • 入口地址： • 移动端仅提供 **概览 / 日报 / 实时 / 日志** 四个页面 • **首次初始化必须在电脑端完成**，移动端会提示在电脑打开 3) 手动构建（前端、后端） 前端构建： 移动端构建（/m）： 后端构建： 本地开发（前后端一起跑）： > 前端开发服务默认端口 8088，并会将 代理到 。 > 本地开发前请准备好日志文件，放在 下（或确保 的 指向对应文件）。 4) 单体部署（单进程） **重要提示（版本 > 1.5.3）**：已彻底弃用 SQLite。单体部署必须自备 PostgreSQL 并配置 （或在 填好 ）。 从仓库的releases下载对应平台的二进制文件，执行即可。 执行后会生成单体可执行文件（已内置前端静态资源），启动后即可同时提供前后端服务： • 前端： • 后端： 单体部署的配置方式 单体运行时读取配置有两种方式（任选其一）： **方式 A：配置文件（默认）** • 在运行目录创建 • 放入 • 启动： **方式 B：环境变量注入（无需文件）** 注意事项： • 配置文件路径为相对路径 ，请确保运行时工作目录正确。 • 如果使用 systemd，请设置 ，或改用 注入。 • 数据目录 也是相对路径；找不到目录时请先确认当前进程的工作目录。 5) Makefile 构建 此项目也支持了通过Makefile来构建相关资源，命令如下： 指定版本号示例： 说明： • 默认构建 与 ，产物在 与 。 • 单平台构建时，产物在 ，配置在 （端口默认 ），gzip 示例在 。 Docker 部署权限说明 镜像默认以非 root 用户（ ）运行。容器里能否读取日志、写入数据，**取决于宿主机目录的权限**。你在容器里用 看到日志，通常是因为 默认是 root，不代表应用用户有权限。 推荐做法：**让容器内用户的 UID/GID 与宿主机日志/数据目录的属主一致**。 步骤 1：查看宿主机目录的 UID/GID 步骤 2：启动容器时传入 （与上面一致） 步骤 3：确保目录对该 UID/GID 可读/可写 如果你使用外部数据库（设置 ），可以不挂载 。外置 PG **推荐使用 16 版本**。 若你通过**初始化向导**配置外部数据库，同样可以不挂载 ，保存后重启容器生效。 SELinux 说明（RHEL/CentOS/Fedora 等）： • 这些系统默认启用 SELinux，Docker 挂载目录可能因安全上下文导致“看得见但不可访问”。 • 解决办法是在 volume 后加 或 重新打标签： • 让该目录仅供当前容器使用（更严格）。 • 让该目录可被多个容器共享使用。 不推荐做法：直接 。这虽然省事，但权限过宽不安全，仅建议临时排查时使用。 常见问题 1) 日志明细无内容 通常是容器内无权限访问宿主机日志文件。请先阅读《Docker 部署权限说明》并按步骤处理权限。 2) 日志存在，但 PV/UV 无法统计 默认规则会排除内网 IP。若你希望统计内网流量，请将 设为空数组并重启： 重启后在“日志明细”页面点击“重新解析”按钮。 3) 日志时间不正确 通常是运行环境时区未同步导致。请确认 Docker/系统时区正确，并按“时区设置（重要）”章节调整后重新解析日志。 4) 无法启动 报错 tmp 目录无权限写入问题（旧版本可能出现），如果容器启动后出现如下所示的报错，请确认 可写（具体权限问题请阅读《Docker 部署权限说明》），或设置 到可写目录。 解决办法（任选其一）： 5) 解析入库的数据会一直保留吗 不会。入库后的访问数据会按 定时清理（默认 30 天）。 例如你一次解析了几个月数据，后续仍会逐步清理掉保留天数之外的数据。 注意：该参数不影响原始 Nginx 日志文件，也不等于系统运行日志（ ）的轮转策略。 目录结构与主要文件 --- 如需更详细的统计口径或 API 扩展，建议从 与 开始。 致谢 非常感谢诸位好兄弟/姐妹对此项目的投币支持。 写在最后 本项目大部分代码通过codex生成，我投喂了很多开源项目和资料让他做参考，在此感谢大家对开源社区的贡献。 • 有没有好用的 nginx 日志看板展示项目 • nixvis • goaccess • prometheus监控nginx的两种方式原创 • 通过nginx-prometheus-exporter监控nginx指标 • Prometheus 监控nginx服务 • Prometheus监控Nginx