前言

网站跑起来之后,总想知道每天有多少人访问、都看了哪些页面、来自哪里。nginx 自带的访问日志虽然信息齐全,但盯着原始日志行看实在费眼睛。GoAccess 可以把访问日志直接解析成终端图表或 HTML 页面,还带各种交互式图表,非常适合自建博客做访问分析。

本文记录在一台 Ubuntu 服务器(腾讯云)上从零部署 nginx + GoAccess 的完整过程,包括配置 JSON 结构化日志、生成 HTML 报告、用 systemd 定时自动刷新,以及过程中踩到的几个坑。

环境说明

  • 服务器:腾讯云 Ubuntu 24.04
  • nginx 1.24.0
  • GoAccess 1.8.1
  • 需要开放一个端口对外展示报告(本文用 8080)

一、安装 nginx 和 GoAccess

sudo apt update
sudo apt install -y nginx goaccess

安装完确认版本:

goaccess --version
# GoAccess - 1.8.1

二、配置 nginx 站点

先建一个独立的站点配置,监听 8080 端口,专门用来展示 GoAccess 报告:

# /etc/nginx/sites-available/goaccess
server {
    listen 8080;
    server_name _;

    root /var/www/goaccess;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}

启用站点并重载:

sudo ln -s /etc/nginx/sites-available/goaccess /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

三、配置 JSON 结构化访问日志

这是整个部署里最关键、也是最容易踩坑的一步。

为什么不用默认的 COMBINED 格式

nginx 默认的 combined 格式是一行文本,信息都挤在一起,靠空格和引号分隔。GoAccess 虽然支持解析它,但想补充自定义字段(比如响应耗时)就要手写一长串格式串,容易错。

JSON 格式就没这个问题:每个字段有名有值,一目了然,GoAccess 也原生支持。

踩坑一:GoAccess 1.8 不认单个 ISO 时间键

一开始最直觉的写法是把 nginx 的 $time_iso8601(形如 2026-10-28T16:13:04+08:00)整段塞进日志:

{"time": "2026-10-28T16:13:04+08:00", "remote_addr": "1.2.3.4", ...}

GoAccess 配置里用 %x 去匹配,结果直接报错:

Token '2026-10-28T16:13:04+08:00' doesn't match specifier '%x'
Format Errors - Verify your log/date/time format

GoAccess 1.8 的 %x 要求日期时间组合格式能被 date-format + time-format 拆开解析,而 ISO 8601 带时区后缀的整串时间它处理不了。把时区去掉、换成空格分隔,也照样报错。

解决办法:在 nginx 层用 map 把时间戳拆成 date 和 time 两个字段,GoAccess 分别用 %d 和 %t 去匹配,实测一次通过。

最终的日志格式配置

# /etc/nginx/conf.d/goaccess-log-format.conf

# 把 $time_iso8601 拆成日期和时间两个字段
map $time_iso8601 $ga_date {
    "~^(?<d>\d{4}-\d{2}-\d{2})T" $d;
    default "-";
}

map $time_iso8601 $ga_time {
    "~^(?<d>\d{4}-\d{2}-\d{2})T(?<t>\d{2}:\d{2}:\d{2})" $t;
    default "-";
}

log_format goaccess_json escape=json
  '{"date":"$ga_date","time":"$ga_time","remote_addr":"$remote_addr",'
  '"x_forwarded_for":"$http_x_forwarded_for","method":"$request_method",'
  '"uri":"$request_uri","protocol":"$server_protocol","status":"$status",'
  '"referer":"$http_referer","ua":"$http_user_agent",'
  '"reqsize":"$request_length","respsize":"$body_bytes_sent",'
  '"reqtime":"$request_time"}';

escape=json 会自动转义引号等特殊字符,保证每行都是合法 JSON。

生成的日志长这样:

{"date":"2026-10-28","time":"16:13:04","remote_addr":"223.104.3.77","method":"GET","uri":"/tools/base64","protocol":"HTTP/1.1","status":"304","referer":"https://example.com/","ua":"Mozilla/5.0 ...","reqsize":"722","respsize":"30964","reqtime":"0.555"}

四、GoAccess 配置文件

# /etc/goaccess/goaccess.conf

# 解析 nginx JSON 访问日志
log-format {"date":"%d","time":"%t","remote_addr":"%h","method":"%m","uri":"%U","protocol":"%H","status":"%s","referer":"%R","ua":"%u","respsize":"%b","reqtime":"%T"}
log-file /var/log/nginx/goaccess_access.log

date-format %Y-%m-%d
time-format %H:%M:%S

# 输出 HTML 报告
output /var/www/goaccess/report.html
html-report-title GoAccess 网站访问可视化分析

# 排除本机访问
exclude-ip 127.0.0.1
exclude-ip ::1

几个字段说明:

日志字段 GoAccess 占位符 含义
date / time %d / %t 拆分后的日期、时间
remote_addr %h 客户端 IP
method %m 请求方法
uri %U 请求路径
status %s 状态码
referer %R 来源页
ua %u User-Agent
respsize %b 响应字节数
reqtime %T 请求耗时(秒)

踩坑二:旧日志混在文件里会拖垮解析

调试期间日志文件里同时存在旧格式(单个 time 键)和新格式(date + time)的行,GoAccess 解析到旧格式就报错退出。处理方式很直接——调试阶段干脆清空重来:

sudo truncate -s 0 /var/log/nginx/goaccess_access.log

教训:改日志格式之后,旧格式的历史行要么过滤掉,要么清空,别指望 GoAccess 能兼容两种格式混跑。

五、写个生成脚本

把生成逻辑包成脚本,方便手动执行也给 systemd 用:

#!/bin/bash
# /usr/local/bin/goaccess-generate.sh
set -e
LOG=/var/log/nginx/goaccess_access.log
OUT=/var/www/goaccess/report.html

# 日志为空就不生成
[ -s "$LOG" ] || exit 0

goaccess "$LOG" \
  --no-global-config \
  --config-file=/etc/goaccess/goaccess.conf \
  --output="$OUT"

chown www-data:www-data "$OUT"
echo "报告已更新:$OUT"

赋予执行权限并跑一次:

sudo chmod +x /usr/local/bin/goaccess-generate.sh
sudo /usr/local/bin/goaccess-generate.sh

成功后 /var/www/goaccess/report.html 就是完整的可视化报告,浏览器打开 http://服务器IP:8080/report.html 即可查看。

六、systemd 定时自动刷新

静态报告不会自己更新,用 systemd timer 每 10 分钟重新生成一次。

# /etc/systemd/system/goaccess-report.service
[Unit]
Description=GoAccess 定时生成 HTML 报告
After=network.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/goaccess-generate.sh
# /etc/systemd/system/goaccess-report.timer
[Unit]
Description=每 10 分钟触发一次 GoAccess 报告生成

[Timer]
OnBootSec=2min
OnUnitActiveSec=10min

[Install]
WantedBy=timers.target

启用:

sudo systemctl daemon-reload
sudo systemctl enable --now goaccess-report.timer
sudo systemctl list-timers | grep goaccess

七、没有流量怎么办:造点演示数据

刚部署完日志是空的,报告干巴巴。写了个小脚本生成逼真的演示流量(随机页面、UA、来源、状态码分布),方便先看看可视化效果:

#!/usr/bin/env python3
# /usr/local/bin/gen-demo-log.py(节选)
import json, random
from datetime import datetime, timedelta, timezone

PAGES = [("/", 320), ("/blog/goaccess-deploy", 210),
         ("/tools/json", 140), ("/static/app.css", 310)]
UAS = [("Mozilla/5.0 (Windows NT 10.0 ...) Chrome/126.0", 380),
       ("Mozilla/5.0 (iPhone; ...) Safari/604.1", 300)]
REFERERS = [("https://www.google.com/", 420), ("-", 600)]

now = datetime.now(timezone.utc)
rec = {
    "date": ts.strftime("%Y-%m-%d"),
    "time": ts.strftime("%H:%M:%S"),
    "remote_addr": random.choice(IPS),
    "method": "GET",
    "uri": pick(PAGES),
    "status": str(random.choices([200, 304, 404], weights=[82, 6, 5])[0]),
    "referer": pick(REFERERS),
    "ua": pick(UAS),
    "reqtime": str(round(random.uniform(0.002, 0.85), 3)),
}
# 逐行写入 /var/log/nginx/goaccess_access.log

完整脚本 100 多行,原理就是按权重随机拼 JSON 行追加到日志,然后手动触发一次报告生成即可看到满屏图表。

八、验证

# 本机验证报告可访问
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8080/report.html
# 200

# 确认标题正常
curl -s http://127.0.0.1:8080/report.html | grep -o '<title>[^<]*</title>'
# <title>GoAccess 网站访问可视化分析</title>

报告页面包含:总请求量、独立访客、请求文件排行、状态码分布、来源站点、浏览器/操作系统、访问时段热力图等面板,都是交互式图表,可以按面板折叠、切换图表类型、导出 JSON。

附:Docker 方式运行 GoAccess

不想在系统里装包的话,可以用官方 Docker 镜像(allinurl/goaccess),特点是版本更新、免安装、随用随删。当前镜像内是 GoAccess 1.12,比 apt 源里的 1.8 新了不少。

一次性生成报告

把日志目录和输出目录挂进容器即可:

sudo docker run --rm \
  -v /var/log/nginx:/log \
  -v /var/www/goaccess:/out \
  allinurl/goaccess \
  /log/goaccess_access.log \
  --no-global-config \
  --log-format='{"date":"%d","time":"%t","remote_addr":"%h","method":"%m","uri":"%U","protocol":"%H","status":"%s","referer":"%R","ua":"%u","respsize":"%b","reqtime":"%T"}' \
  --date-format="%Y-%m-%d" \
  --time-format="%H:%M:%S" \
  -o /out/docker-report.html

说明:

  • --rm:跑完自动删容器,不留垃圾
  • -v /var/log/nginx:/log:把宿主机的 nginx 日志目录挂进去
  • -v /var/www/goaccess:/out:报告输出到 nginx 站点目录
  • --log-format 与前面 apt 版的配置完全一致,JSON 字段映射通用

定时刷新

配合 systemd timer 的话,把前面 goaccess-generate.sh 里的 goaccess 命令换成 docker run 即可;更简单的做法是直接用 crontab:

# 每 10 分钟刷新一次
sudo crontab -e
# 添加一行:
*/10 * * * * docker run --rm -v /var/log/nginx:/log -v /var/www/goaccess:/out allinurl/goaccess /log/goaccess_access.log --no-global-config --log-format='{"date":"%d","time":"%t","remote_addr":"%h","method":"%m","uri":"%U","status":"%s","referer":"%R","ua":"%u","respsize":"%b","reqtime":"%T"}' --date-format="%Y-%m-%d" --time-format="%H:%M:%S" -o /out/report.html

注意事项

  1. docker 命令需要 root 权限(或把用户加进 docker 组:sudo usermod -aG docker $USER,重新登录生效)
  2. 首次运行会拉取镜像(约几十 MB),之后秒级启动
  3. 容器内时区默认是 UTC,如果报告里时段分布不对,加 -e TZ=Asia/Shanghai
  4. --log-format 里的 JSON 双引号在 shell 里建议用单引号包住整串,避免转义混乱

apt 版和 Docker 版的日志格式配置完全互通,二选一即可;Docker 版的优势是版本新、不污染系统包,apt 版的优势是常驻进程更省心。

附二:Docker Compose 方式(推荐)

docker run 命令行太长不好维护,Docker Compose 把参数收进一个配置文件,docker compose up -d 一条命令拉起,配合 restart: unless-stopped 容器常驻、开机自启,是最省心的方案。

目录结构

goaccess/
├── docker-compose.yml
└── goaccess.conf

goaccess.conf

参数全部收进配置文件,避免在 compose 的 command 里写 JSON 转义:

# GoAccess 容器专用配置
log-format {"date":"%d","time":"%t","remote_addr":"%h","method":"%m","uri":"%U","protocol":"%H","status":"%s","referer":"%R","ua":"%u","respsize":"%b","reqtime":"%T"}
date-format %Y-%m-%d
time-format %H:%M:%S

# 实时报告:HTML 落盘 + WebSocket 推送(端口在 compose 里映射)
real-time-html true
port 7890
output /out/report.html

docker-compose.yml

services:
  goaccess:
    image: allinurl/goaccess:latest
    container_name: goaccess
    restart: unless-stopped
    volumes:
      - /var/log/nginx:/log:ro
      - /var/www/goaccess:/out
      - ./goaccess.conf:/etc/goaccess/goaccess.conf:ro
    command: /log/goaccess_access.log --config-file=/etc/goaccess/goaccess.conf
    ports:
      - "7890:7890"

启动:

docker compose up -d
docker compose ps      # 确认状态是 Up
docker compose logs -f # 看解析进度

这个方案的两个关键点(都是实测踩出来的坑)

1. 别把 --log-format 直接写进 compose 的 command

compose 的 YAML > 折叠语法会剥掉 JSON 里的双引号,--log-format={"date":"%d",...} 传到容器里变成 {"date":%d,...},GoAccess 直接报 Token ... doesn't match specifier '%d'。把参数收进 goaccess.conf 再用 --config-file 挂载进去,是最干净的做法。

2. 配置文件里布尔值要写 true,不能写 yes

GoAccess 1.12 会把 real-time-html yes 里的 yes 当成一个日志文件路径去打开,报 Unable to open the specified log file 'yes'。写 real-time-html true 就正常。(命令行参数 --real-time-html 是开关型,不受影响。)

实时报告和静态报告的关系

这个方案和前面的 systemd timer 定时刷新是两种思路:

  • Compose 常驻 + real-time-html:GoAccess 一直跑着,日志有新请求就通过 WebSocket(7890 端口)实时推到浏览器页面,报告秒级更新,/var/www/goaccess/report.html 也会自动落盘
  • docker run / systemd timer:按间隔重新解析全量日志生成静态报告,没有 WebSocket

如果服务器上已经有 apt 版的 systemd timer,注意别和 Compose 常驻容器同时写同一个 report.html,二选一。

展示报告

HTML 报告照旧落在 /var/www/goaccess/report.html,用 nginx 站点(或任意静态服务器)指向这个目录即可。浏览器打开报告后,只要 7890 端口可达,页面数据就会实时跳动;如果 nginx 反代了报告页面,记得给 /report 之类路径加上 WebSocket 升级配置:

location / {
    proxy_pass http://127.0.0.1:8081;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

总结

整个部署的核心链路:

nginx(JSON 日志) → /var/log/nginx/goaccess_access.log
    → goaccess 解析 → /var/www/goaccess/report.html
    → nginx 8080 对外展示
    → systemd timer 每 10 分钟刷新

两条最重要的经验:

  1. GoAccess 1.8 解析 JSON 日志时,时间必须拆成 date 和 time 两个字段,不要指望 %x 能吃下 ISO 8601 整串时间戳。在 nginx 层用 map 拆分是最干净的做法。
  2. 换日志格式后旧数据必须清掉,GoAccess 不做格式兼容,混跑必报错。

后续如果要接入真实流量,把 nginx 站点的 access_log 指到这个 JSON 格式即可,报告会自动随 timer 刷新。