一、背景
Web 服务器访问日志记录每次请求的来源、状态、耗时等原始数据,但日志文件本身是线性文本,无法直观反映 PV/UV、热门页面、状态码分布、响应时间分布等运营与运维指标。GoAccess 是一个开源的实时 Web 日志分析器,用 C 语言写成,能对 Nginx/Apache/IIS 等常见 Web 服务器的访问日志做实时解析、内存聚合,输出终端仪表盘与可实时刷新的 HTML 报告,无需数据库依赖,适合单机日志快速分析与离线报告生成。
- 首次发布:2010 年
- 语言:C
- 许可证:MIT
- 仓库:https://github.com/allinurl/goaccess
二、工作原理
2.1 解析流程
日志源(文件/tail -F/管道)→ 词法解析(按 log-format 拆字段)→ 内存聚合(哈希表按维度计数)→ 输出(终端/HTML/CSV/JSON)
GoAccess 并非把整个日志读入再统计,而是逐行流式解析:
- 按配置的
log-format用分隔符与格式说明符将每行拆成字段(IP、时间、请求、状态、字节、Referer、UA 等)。 - 每行解析后立即在内存中按多个维度聚合(独立访客 IP、请求 URL、状态码、UA 解析出的浏览器/操作系统等)。
- 终端模式下聚合结果实时刷屏;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 | 帮助 |