NginxPulse 實戰：Go + Vue3 寫的輕量 Nginx 日誌分析，可取代 GoAccess 與百度統計

跑 Nginx 服務久了，access log 是最容易被忽略的一塊。檔案躺在那邊每天默默長大，平常不看；一旦要追真實流量、找誰在掃站、看哪支 API 在發燒，才回頭翻好幾 GB 的 log，這時候就會開始想念一個能直接視覺化的儀表板。

過去這類需求大致有兩條路：一條是裝 GoAccess 在終端機看，速度快、純文字；另一條是上百度統計或 Google Analytics，前端埋 script 收資料。前者跑出來不太適合長期保存與多人查看，後者則必須讓使用者瀏覽器能連上外網，很多內網環境直接卡住。最近翻 magiccoders/nginxpulse 這個 Docker image，本來以為又是一個短命專案，結果發現背後是 GitHub 上的 likaia/nginxpulse，已經發了 30 多個版本，最新版甚至上了阮一峰的科技愛好者週刊。本文記錄一下這個工具的安裝、實際定位，以及與 GoAccess、AWStats、Matomo 之間的取捨。

一、為什麼需要再一個 Nginx log 分析工具

Nginx access log 的分析需求其實可以拆成兩塊：

即時監看：剛上線想知道有沒有人連進來、剛部署完想看 5xx 是不是爆量、被 DDoS 想看哪個 IP 在敲。這類需求要「當下就看到」，不能等。

長期統計：想知道過去一週的 PV、UV、熱門 API、來源國家分佈、瀏覽器佔比。這類需求要「資料留得住」，能跨日期比對。

GoAccess 在第一類做得很好，但它本質上是個 CLI 工具，HTML 報表是匯出快照式的，不太適合多站點長期累積資料。AWStats 跑得很久也很穩，但介面停留在十年前的審美，要排版要 Perl，新手不友善。Matomo 功能完整但體積偏重，一般小站架起來有點殺雞用牛刀。百度統計、Google Analytics 又得讓使用者瀏覽器發請求出去，講內部系統或政府專案根本不能用。

這就是 NginxPulse 想塞進去的縫：純後端讀 Nginx log file，不需要前端埋 script，介面是 Vue3 寫的現代化 dashboard，資料寫進 PostgreSQL 可以長期累積，整包打成一個 Docker image，連 DB 都內建。

二、NginxPulse 是什麼

NginxPulse 是一個開源的 Nginx access log 分析與視覺化面板，作者是 likaia，repo 在 github.com/likaia/nginxpulse，採 MIT License。它的角色就是：給它一個 log file 路徑，它幫你切詞、解析、入庫、畫圖。

2.1 技術組成

從 GitHub 的語言比例看，這個專案大約是 Go 42% + Vue 36% + TypeScript 8% + SCSS 8% + Shell 4%。對應到實際組成：

• 後端：Go 1.24，Web 框架 Gin，Logger 用 Logrus
• 前端：Vue 3 + Vite + TypeScript + PrimeVue + ECharts/Chart.js
• 資料庫：PostgreSQL（v1.5.3 之後正式拋棄 SQLite，改 pgx driver）
• IP 歸屬地：本地 ip2region 資料庫 + 遠端 ip-api.com 批次查詢
• 行動端：另外有一個 webapp_mobile，掛在 /m 路徑

整體架構大致長這樣：

特別值得提的是 IP 解析策略：先用 ip2region 本地查（快、不用對外），查不到再丟到 ip-api.com 補資料，整個 geo 解析是非同步的，UI 在資料還沒回來時會顯示 pending，不會卡住主流程。這個設計很實用，因為 ip-api.com 的免費版本有頻率限制，全部仰賴遠端查會在流量大時被擋；先打本地 ip2region 能消化掉九成請求，剩下少數冷門段才上遠端，整體查詢成本壓得很低。

2.2 主要功能

從 README 整理出來的核心功能：

• 即時展示 PV、UV、IP、訪問量
• 解析請求來源、裝置、瀏覽器、作業系統
• 統計熱門 API、訪問路徑、status code 分佈（200/404/500）
• 多站點統一管理，不需要每個站獨立部署一份
• IP 歸屬地解析（本地 + 遠端雙策略）
• PV 過濾規則：可透過 PV_EXCLUDE_IPS 排除內網 IP，避免自己人把數據灌爆
• 行動端介面 /m，手機看起來不彆扭
• 自動清理過期 log，避免 DB 無限長大

需要注意的是，README 沒有提到「告警」「webhook 推送」這類主動通知功能，定位很明確就是「事後分析儀表板」，不是 APM 也不是 SIEM。如果想把它當成監控替代品，會發現缺一塊主動推送的能力，那部分還是得搭 Prometheus + Alertmanager 或同類工具補齊。

另一個值得留意的細節是它把 PostgreSQL 直接打包進 image，第一次啟動會自動初始化 DB schema，這對於只想試用、不想另外架資料庫的人很友善；但同時也意味著 DB 升級、備份還原都要自己處理 volume，不要哪天順手 docker rm 連 volume 一起砍了，歷史資料就一去不回。建議線上環境把 pgdata 掛在獨立的備份目錄，配合 pg_dump 排程或 volume snapshot 規律備份。

三、安裝與部署

3.1 docker run 一行起

最快的試用法，把 log、資料、設定都放在當前目錄：

mkdir -p ./docker_local/{logs,nginxpulse_data,pgdata,configs}

docker run -d --name nginxpulse \
  -p 8088:8088 \
  -e PUID=1000 \
  -e PGID=1000 \
  -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

./docker_local/logs 就是丟 Nginx access log 的地方，可以是即時 tail 的檔案，也可以匯入歷史 log。PUID/PGID 是為了讓 container 內的 nginxpulse user 對得上 host 目錄擁有者，否則寫資料會吃 permission denied。

開好之後瀏覽器連 http://主機:8088，會跳第一次設定精靈，跟著走完就能看到 dashboard。

3.2 docker-compose 範例

實際線上我比較推薦 compose，方便和反向代理、其他服務一起管：

version: '3.8'

services:
  nginxpulse:
    container_name: nginxpulse
    image: magiccoders/nginxpulse:latest
    restart: unless-stopped
    ports:
      - "8088:8088"
    environment:
      - TZ=Asia/Taipei
      - PUID=1000
      - PGID=1000
      - PV_EXCLUDE_IPS=[]
    volumes:
      - /data/nginxpulse/logs:/share/logs:rw
      - /data/nginxpulse/nginxpulse_data:/app/var/nginxpulse_data
      - /data/nginxpulse/pgdata:/app/var/pgdata
      - /etc/localtime:/etc/localtime:ro
    stop_grace_period: 90s

stop_grace_period: 90s 是有意義的，因為 container 內含 PostgreSQL，正常 shutdown 需要時間做 checkpoint，太快 kill 容易讓 DB 進入 recovery 模式。

啟動：

docker compose up -d
docker ps              # 確認狀態
docker logs nginxpulse # 看啟動 log

3.3 環境變數與掛載對照

把官方文件整理成一張對照表，部署時直接抄：

時區這條一定要做，否則 log 上的時間和 dashboard 顯示的時間會差 8 小時，看 log 的時候會懷疑人生。

四、與 GoAccess / AWStats / Matomo 對比

實際選型時不會只看單一工具，列一張對比比較清楚：

簡單講：

• 想在終端機快速看一眼當下流量，GoAccess 還是最快
• 已經有 LAMP 架構、想要功能完整的行銷分析，上 Matomo
• 想要一個現代介面、長期累積資料、又不需要前端埋 script 的儀表板，NginxPulse 補的就是這個位置
• AWStats 除非是接手老系統，新案不太建議了

五、適合與不適合的場景

適合：

• 自架站、內網服務、後台系統，沒辦法埋 GA 但需要看流量
• 多個 Nginx 站點想集中管理，又不想為每個站裝一份分析工具
• 團隊裡有非技術人員需要看訪問報表（直接給 URL 就好）
• 想要 PV/UV/IP 歸屬地這類「站長等級」的指標，不需要 Matomo 那麼完整

不適合：

• 需要 funnel、event tracking、A/B test 這類產品分析
• 需要主動告警（伺服器掛了發 webhook 那種，這應該找 Beszel 或 Prometheus）
• 流量極大需要分散式採集（單機 Postgres 會是瓶頸）
• 需要完整的 SEO 分析（這還是 GA 的地盤）

六、踩雷與觀察

實際把它跑起來之後幾個比較容易踩到的點：

1. 權限問題最常見。PUID/PGID 沒設好，或者 host 目錄 owner 不對，container 裡的 nginxpulse user 寫不了 pgdata，PostgreSQL 起不來，整包就直接卡在初始化。標準解法是 chown -R 1000:1000 host 上的三個資料目錄。
2. 時區一定要設。沒掛 /etc/localtime、也沒設 TZ，dashboard 上時間軸就會錯位，特別是「最近一小時」這種 chart 完全看不懂。
3. 內網 IP 預設不算 PV。PV_EXCLUDE_IPS 預設會排除 RFC1918 的內網段，如果是純內網部署、想統計內網流量，記得改成 []，不然 dashboard 上 PV 永遠是 0。
4. SQLite 不再支援。如果看到舊文章說可以用 SQLite，那是 v1.5.3 之前的事，現在內建一定是 PostgreSQL，pgdata volume 一定要掛。
5. 單一 binary 模式要自備 DB。如果走 make single 編出來的單檔 binary，沒有內建 PG，必須自己準備 PostgreSQL 並設 DB_DSN，這跟 Docker 模式差很多。
6. 行動端要先在桌機完成設定。/m 路徑只是檢視，第一次設定精靈在桌機版，順序搞反會卡。

七、小結

NginxPulse 不是新發明，類似定位的工具一直都有，但它選了一個還不錯的技術組合：Go 跑得快、Vue3 介面看得舒服、PostgreSQL 撐得起資料量、Docker 一鍵部署。對於需要一個「能長期累積、有現代介面、不依賴前端埋點」的 Nginx log 分析方案，目前算是甜蜜點上的選擇。

如果只是要看當下、要極致輕量，GoAccess 還是首選；如果是 SaaS 等級的行銷分析，Matomo 才能滿足。但如果你正好卡在中間 — 自架站、內部系統、想要 dashboard 又不想養一坨後端 — 那 NginxPulse 值得一試。我自己會把它放在「個人/中小站長工具箱」的常駐名單裡。

參考資料

• GitHub: likaia/nginxpulse
• README_EN.md
• Docker Hub: magiccoders/nginxpulse
• 官方文件站
• Demo 站
• 阮一峰週刊推薦 Issue #8696
• GoAccess 官方
• Matomo 官方