前言
网站跑起来之后,总想知道每天有多少人访问、都看了哪些页面、来自哪里。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
注意事项
- docker 命令需要 root 权限(或把用户加进
docker组:sudo usermod -aG docker $USER,重新登录生效) - 首次运行会拉取镜像(约几十 MB),之后秒级启动
- 容器内时区默认是 UTC,如果报告里时段分布不对,加
-e TZ=Asia/Shanghai --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 分钟刷新
两条最重要的经验:
- GoAccess 1.8 解析 JSON 日志时,时间必须拆成
date和time两个字段,不要指望%x能吃下 ISO 8601 整串时间戳。在 nginx 层用map拆分是最干净的做法。 - 换日志格式后旧数据必须清掉,GoAccess 不做格式兼容,混跑必报错。
后续如果要接入真实流量,把 nginx 站点的 access_log 指到这个 JSON 格式即可,报告会自动随 timer 刷新。