一、背景

Web 服务器访问日志记录每次请求的来源、状态、耗时等原始数据,但日志文件本身是线性文本,无法直观反映 PV/UV、热门页面、状态码分布、响应时间分布等运营与运维指标。GoAccess 是一个开源的实时 Web 日志分析器,用 C 语言写成,能对 Nginx/Apache/IIS 等常见 Web 服务器的访问日志做实时解析、内存聚合,输出终端仪表盘与可实时刷新的 HTML 报告,无需数据库依赖,适合单机日志快速分析与离线报告生成。


二、工作原理

2.1 解析流程

日志源(文件/tail -F/管道)→ 词法解析(按 log-format 拆字段)→ 内存聚合(哈希表按维度计数)→ 输出(终端/HTML/CSV/JSON)

GoAccess 并非把整个日志读入再统计,而是逐行流式解析:

  1. 按配置的 log-format 用分隔符与格式说明符将每行拆成字段(IP、时间、请求、状态、字节、Referer、UA 等)。
  2. 每行解析后立即在内存中按多个维度聚合(独立访客 IP、请求 URL、状态码、UA 解析出的浏览器/操作系统等)。
  3. 终端模式下聚合结果实时刷屏;HTML 模式下通过 WebSocket(默认 7890 端口)把最新指标推到浏览器。

2.2 与传统日志分析方式的对比

方式 依赖 实时性 适用
命令行 awk/grep/sort/uniq 无 离线,每次重算 临时单维度统计
GoAccess 单进程,无数据库 实时流式 单机快速多维分析
ELK(Elasticsearch + Logstash + Kibana) ES 集群 近实时(采集延迟) 多机聚合、长期存储、复杂查询
Loki + Grafana Loki 单体 近实时 标签过滤、低成本存储

GoAccess 的定位介于命令行与 ELK 之间:比 awk 强大(多维、UA 解析、HTML 报告),比 ELK 轻量(单进程、无 ES),适合单台或少量 Web 服务器的本地日志分析。

2.3 核心模块

终端仪表盘与 HTML 报告共用以下聚合维度:

模块 维度 说明
Unique Visitors 独立访客 IP 按 IP 去重,统计每个 IP 的命中次数与总字节数
Requested Files 请求 URL 按 URL 统计访问次数
Static Requests 静态资源 js/css/图片等
404 Not Found 失败请求 4xx 中 404 单独列出
Hosts 来源主机 IP 与反向解析
Operating Systems 操作系统 由 UA 解析
Browsers 浏览器 由 UA 解析
HTTP Status Codes 状态码 1xx-5xx 分布
Referrers 来源页 Referer 头
Referring Sites 来源站点 Referer 域名提取
Keyphrases 关键词 搜索引擎 referer 中的关键词
GeoIP Location 地理位置 需 GeoIP 数据库
Time Distribution 时间分布 按小时统计

三、安装

3.1 Ubuntu/Debian

apt install goaccess

源码编译(启用 GeoIP 与 UTF-8 支持):

apt install libncursesw5-dev libmaxminddb-dev libssl-dev
wget https://tar.goaccess.io/goaccess-1.9.4.tar.gz
tar -xzf goaccess-1.9.4.tar.gz
cd goaccess-1.9.4
./configure --enable-utf8 --enable-geoip=mmdb --with-openssl
make && make install

3.2 CentOS/RHEL

yum install goaccess

3.3 macOS

brew install goaccess

3.4 Docker

docker pull allinurl/goaccess

3.5 验证

goaccess --version

四、配置

4.1 配置文件位置

  • 全局:/etc/goaccess/goaccess.conf
  • 用户:~/.goaccessrc

配置文件由键值对组成,以 # 注释。最常用通过命令行参数覆盖,也可写入配置文件持久化。

4.2 三个格式说明符

GoAccess 解析日志需要先声明时间、日期、日志三者的格式,三者缺一不可:

配置项 作用 常见值
time-format 时间部分 %H:%M:%S(含时区 %H:%M:%S %z)
date-format 日期部分 %d/%b/%Y(nginx)、%Y-%m-%d(自定义)
log-format 整行字段布局 见 4.3

4.3 日志格式适配

Nginx combined(默认格式)

Nginx 的 combined 即 GoAccess 的默认格式,无需特别声明即可解析。

Nginx 日志格式:

$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"

GoAccess 对应:

log-format %h %^ %^ [%d:%t %^] "%r" %s %b "%R" "%u"

Nginx main(扩展格式,含响应时间)

参考 nginx 访问日志分析与在线监控 第十一章完整配置示例中的 main 格式:

$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" rt=$request_time urt=$upstream_response_time ua=$upstream_addr cs=$upstream_cache_status

GoAccess 对应:

log-format %h %^ %^ [%d:%t %^] "%r" %s %b "%R" "%u" rt=%T urt=%^ ua=%^ cs=%^

说明:%^ 表示跳过该字段不解析;%T 取请求耗时(秒),如需毫秒用 %D。main 格式中的 urt/ua/cs 用 %^ 跳过,因为 GoAccess 不直接支持 upstream 字段,跳过即可不影响其他维度。

Apache Combined

log-format %h %^ %^ %^ [%d:%t %^] "%r" %s %b "%R" "%u"

自定义 JSON 日志

若 Nginx 输出 JSON 结构化日志(参考 nginx 访问日志分析与在线监控 JSON 格式章节),GoAccess 1.4+ 支持解析 JSON 日志:

log-format {"time":"%t","host":"%h","request":"%r","status":"%s","size":"%b","referer":"%R","user_agent":"%u"}

4.4 常用说明符速查

说明符 含义
%h 客户端 IP
%^ 跳过该字段
%t 时间(配合 time-format)
%d 日期(配合 date-format)
%r 请求行(方法 URL 协议)
%s 状态码
%b 响应字节数
%R Referer
%u User-Agent
%T 请求耗时(秒)
%D 请求耗时(毫秒)
%v 虚拟主机 ServerName
%U URL 路径(不含查询串)
%q 查询串

五、终端仪表盘使用

5.1 启动

goaccess /var/log/nginx/access.log

默认进入交互式终端仪表盘。

5.2 操作键

键 作用
F1 帮助
Tab 在模块间切换
0-9 跳转到第 N 个模块
o / Enter 展开当前模块详细
j / k 上下移动
s 切换排序(访问数/字节数/响应时间)
/ 搜索
n 下一个搜索结果
q 退出

5.3 模块示例

打开终端后顶部为汇总(总请求数、独立访客、总流量、404 数等),下方为各模块表格。例如 Hosts 模块展示:

 1 - 独立访客
   独立文件: 5,887
   独立访客: 1,234
   总大小: 5.67 GiB
   404: 23

 2 - 请求的文件 (URLs)
   URL                        命中  占比
   /                         12,000  15.3%
   /api/data                  8,500  10.8%

 3 - 状态码
   200 OK    78,000  89.5%
   404 NF     5,000   5.7%
   500        1,000   1.1%

六、HTML 实时报告

6.1 生成静态报告

goaccess /var/log/nginx/access.log -o /var/www/html/report.html --log-format=COMBINED

-o 指定输出 HTML 文件,生成后浏览器打开即可查看完整仪表盘。

6.2 实时刷新报告

goaccess /var/log/nginx/access.log -o /var/www/html/report.html --log-format=COMBINED --real-time-html --daemonize
  • --real-time-html:开启 WebSocket(默认 7890 端口)向浏览器推送增量更新,无需手动刷新页面。
  • --daemonize:后台运行。
  • 浏览器访问 http://server_ip/report.html,页面会自动建立 WebSocket 连接实时更新。

6.3 端口与权限

7890 端口需在防火墙放行,或使用反向代理(Nginx)将 WebSocket 升级:

location /report.html {
    root /var/www/html;
}
location /ws {
    proxy_pass http://127.0.0.1:7890;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

参考 nginx 配置说明文档 WebSocket 代理章节。


七、实时跟踪日志

7.1 tail -F 管道

tail -F /var/log/nginx/access.log | goaccess --log-format=COMBINED -

末尾的 - 表示从标准输入读取,配合 tail -F 实现对新写入的日志行实时解析。

7.2 多日志合并

goaccess /var/log/nginx/access.log* --log-format=COMBINED

或用 zcat 处理已压缩的轮转日志:

zcat -f /var/log/nginx/access.log* | goaccess --log-format=COMBINED -

八、GeoIP 集成

8.1 编译启用

源码编译时加 --enable-geoip=mmdb,并安装 MaxMind DB:

apt install libmaxminddb-dev

8.2 配置数据库

在 goaccess.conf 中:

geoip-database /usr/share/GeoIP/GeoLite2-City.mmdb

下载 GeoLite2 数据库需到 MaxMind 官网注册账号获取 License Key。

8.3 验证

HTML 报告与终端会多出 "GeoIP Location" 模块,显示按国家/城市聚合的访问分布。


九、Docker 部署

9.1 单次分析

docker run --rm -i allinurl/goaccess < /var/log/nginx/access.log --log-format=COMBINED -o /dev/stdout --html-prefs='{"theme":"dark"}'

9.2 持续实时报告

docker run -d --name goaccess \
  -v /var/log/nginx:/var/log/nginx:ro \
  -v /var/www/html:/var/www/html \
  -p 7890:7890 \
  allinurl/goaccess \
  /var/log/nginx/access.log \
  -o /var/www/html/report.html \
  --log-format=COMBINED \
  --real-time-html

挂载日志目录与输出目录,容器持续运行输出实时报告。


十、常用命令示例

10.1 离线分析整份日志

goaccess /var/log/nginx/access.log --log-format=COMBINED -o report.html

10.2 实时分析并后台生成报告

goaccess /var/log/nginx/access.log -o /var/www/html/report.html --log-format=COMBINED --real-time-html --daemonize

10.3 输出 JSON

goaccess /var/log/nginx/access.log --log-format=COMBINED -a -o json > report.json

-a 开启详细列表(每个模块列出明细而非仅汇总)。

10.4 输出 CSV

goaccess /var/log/nginx/access.log --log-format=COMBINED -o csv > report.csv

10.5 过滤状态码

只分析 4xx/5xx:

goaccess /var/log/nginx/access.log --log-format=COMBINED --ignore-status=200,301,302

10.6 限制 IP 报告条数

goaccess /var/log/nginx/access.log --log-format=COMBINED --hl-ips --html-prefs='{"visitor":{"count":20}}'

十一、验证手段

11.1 格式自检

goaccess /var/log/nginx/access.log --log-format=COMBINED --no-progress

若格式不匹配,会报 Parsed 0 lines 或 No valid entries,需调整 log-format。可加 --debug 输出解析失败的原始行:

goaccess /var/log/nginx/access.log --log-format='%h %^ %^ [%d:%t %^] "%r" %s %b "%R" "%u"' --debug

11.2 用 curl 触发日志后验证

curl -I http://localhost/
# 观察终端仪表盘总请求数与 Hosts 模块是否新增一条 127.0.0.1

11.3 HTML 报告检查

浏览器打开 report.html,确认 WebSocket 连接已建立(浏览器开发者工具 Network 中 ws 状态为 101 Switching Protocols)。

11.4 与 awk 对照

独立访客数核对:

# GoAccess 报告中的独立访客数
awk '{print $1}' /var/log/nginx/access.log | sort | uniq | wc -l

两者结果应一致。

11.5 常见问题

现象 原因
Parsed 0 lines log-format 不匹配,检查说明符
HTML 报告不刷新 7890 端口未放行或被反向代理拦截
终端乱码 编码问题,启动加 --no-color 或检查终端 UTF-8
解析后总请求数远小于日志行数 date-format/time-format 与日志实际不符
GeoIP 模块不出现 未编译 mmdb 或数据库路径错误

十二、命令速查表

命令 作用
goaccess access.log 终端交互分析
goaccess access.log --log-format=COMBINED 显式指定 combined 格式
goaccess access.log -o report.html 生成静态 HTML 报告
goaccess access.log -o report.html --real-time-html 生成实时 HTML 报告
goaccess access.log -o report.html --real-time-html --daemonize 后台实时报告
goaccess access.log -o report.json -a 输出详细 JSON
goaccess access.log -o report.csv 输出 CSV
tail -F access.log \| goaccess --log-format=COMBINED - 实时跟踪
zcat -f access.log* \| goaccess --log-format=COMBINED - 合并压缩日志
goaccess --help 帮助