强曰为道
与天地相似,故不违。知周乎万物,而道济天下,故不过。旁行而不流,乐天知命,故不忧.
文档目录

GoAccess 日志分析完全指南 / 03 - 基本使用

03 - 基本使用

3.1 快速开始

安装完成后,用最简单的一条命令即可启动 GoAccess:

# 使用 Apache Combined 格式分析 Nginx 日志
goaccess /var/log/nginx/access.log --log-format=COMBINED

如果一切正常,你将看到类似 top 命令的交互式终端面板:

- General Dashboard ---- Overall Analyzed Requests - Hits: 12,547 / Visitors: 1,234

 P1 - Unique Visitors          P2 - Requested Files
 ─────────────────────         ─────────────────────
 Hits  Vis.   Hostname         Hits  Vis.   File
 1200  350    10.0.0.1          3000  890    /
  800  220    10.0.0.2          1500  420    /index.html
  500  180    172.16.0.3         800  150    /about
  ...                           ...

最小化命令

# 分析单个日志文件
goaccess /var/log/nginx/access.log --log-format=COMBINED

# 分析多个日志文件
goaccess /var/log/nginx/access.log.1 /var/log/nginx/access.log --log-format=COMBINED

# 使用通配符
goaccess /var/log/nginx/access.log* --log-format=COMBINED

# 从管道读取(实时跟踪)
tail -f /var/log/nginx/access.log | goaccess --log-format=COMBINED -

# 从标准输入读取
cat /var/log/nginx/access.log | goaccess --log-format=COMBINED -

注意:当使用 - 作为文件名时,GoAccess 从标准输入读取数据。这对于管道操作至关重要。


3.2 终端面板操作

GoAccess 的终端面板基于 ncurses 库,支持丰富的键盘交互。

3.2.1 面板导航

快捷键 功能
F5 刷新当前面板
Tab / Shift+Tab 下一个/上一个面板
j / k 向下/向上滚动(类似 Vim)
/ 向上/向下移动光标
/ 切换到左/右侧面板
1-9, 0 直接跳转到对应编号的面板
s 选择排序字段
S 在面板间切换排序方式
/ 搜索(支持正则)
n 下一个搜索结果
q / Q 退出

3.2.2 面板切换快捷键

快捷键 面板
1 Unique Visitors (独立访客)
2 Requested Files (请求文件)
3 Requested Static Files (静态资源)
4 Not Found (404)
5 Hosts / IPs
6 Operating Systems
7 Browsers
8 Referring Sites
9 Referring URLs
0 HTTP Status Codes

3.2.3 面板详细说明

通用仪表盘 (General Dashboard)

这是默认显示的概览面板,包含以下指标:

┌────────────────────────────────────────────────────┐
│                   Overall Analyzed Requests         │
│────────────────────────────────────────────────────│
│  Hits: 12,547    Visitors: 1,234   Bandwidth: 2.5G │
│  Excl. Hits: 456 Excl. Bw: 120M   Ref. Sites: 89  │
│  Not Found: 12   Log Size: 500M   Generation Time: │
│                                            0.23s   │
└────────────────────────────────────────────────────┘
指标 说明
Hits 总请求数
Visitors 独立访客数(基于 IP 去重)
Bandwidth 总带宽消耗
Excl. Hits 排除静态资源后的请求数
Excl. Bw 排除静态资源后的带宽
Ref. Sites 来源站点数
Not Found 404 请求数
Log Size 分析的日志大小
Generation Time 分析耗时

3.3 HTML 静态报告

HTML 报告是最常用的输出方式,适合分享和离线查看。

3.3.1 生成基本 HTML 报告

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

生成的 HTML 文件包含完整的 CSS 和 JavaScript,无需外部依赖,可直接在浏览器中打开。

3.3.2 自定义报告标题

goaccess /var/log/nginx/access.log \
  --log-format=COMBINED \
  -o report.html \
  --html-title="我的网站分析报告" \
  --html-report-title="月度访问分析"

3.3.3 使用持久化数据生成报告

对于大型日志文件,推荐分两步操作:

# 第一步:将解析结果持久化到文件
goaccess /var/log/nginx/access.log \
  --log-format=COMBINED \
  -o /tmp/goaccess_data.db \
  --persist

# 第二步:从持久化数据生成 HTML
goaccess /tmp/goaccess_data.db \
  -o report.html \
  --restore

业务场景:当需要多次生成不同样式/时间段的报告时,避免重复解析日志。

3.3.4 指定 HTML 样式偏好

goaccess /var/log/nginx/access.log \
  --log-format=COMBINED \
  -o report.html \
  --html-prefs='{"theme":"bright","perPage":50,"layout":"horizontal"}'

可用的 HTML 偏好设置:

设置项 说明 可选值
theme 界面主题 bright, dark, monoGreen, monoPink, classic
perPage 每页显示条目数 数字(如 10, 20, 50)
layout 面板布局 horizontal, vertical

3.4 JSON 输出

JSON 格式适合程序化处理,例如导入到数据库、构建 API、与其他工具集成等。

3.4.1 生成 JSON 报告

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

3.4.2 JSON 输出结构

{
  "general": {
    "date_time": "2026/05/10 14:30:00",
    "total_requests": 12547,
    "valid_requests": 12500,
    "failed_requests": 47,
    "generation_time": 230,
    "unique_visitors": 1234,
    "unique_files": 567,
    "excluded_hits": 456,
    "referring_sites": 89,
    "not_found": 12,
    "log_size": 524288000,
    "bandwidth": 2684354560
  },
  "visitors": {
    "data": [
      {
        "hits": { "count": 1200, "percent": 9.57 },
        "visitors": { "count": 350, "percent": 28.36 },
        "data": "10.0.0.1"
      }
    ]
  },
  "requests": {
    "data": [...]
  },
  "static_requests": {
    "data": [...]
  },
  "not_found": {
    "data": [...]
  },
  "hosts": {
    "data": [...]
  },
  "os": {
    "data": [...]
  },
  "browsers": {
    "data": [...]
  },
  "referring_sites": {
    "data": [...]
  },
  "status_codes": {
    "data": [...]
  },
  "geolocation": {
    "data": [...]
  }
}

3.4.3 JSON 后处理示例

# 用 jq 提取状态码分布
goaccess /var/log/nginx/access.log --log-format=COMBINED -o - | \
  jq '.status_codes.data'

# 用 jq 获取访客排行前 10
goaccess /var/log/nginx/access.log --log-format=COMBINED -o - | \
  jq '.visitors.data[:10]'

# 导出 404 URL 列表
goaccess /var/log/nginx/access.log --log-format=COMBINED -o - | \
  jq -r '.not_found.data[].data' > 404_urls.txt

注意:使用 -o - 将 JSON 输出到标准输出,便于管道操作。需配合 --no-global-config 禁止读取全局配置。


3.5 CSV 输出

CSV 格式适合导入 Excel、Google Sheets 或数据库进行进一步分析。

3.5.1 生成 CSV 报告

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

3.5.2 CSV 输出示例

# Generated by GoAccess - 1.9.2
# Date: 2026-05-10 14:30:00 - Log size: 500.00 MiB

# Unique visitors (IPs)
"10.0.0.1",1200,350,"9.57","28.36"
"10.0.0.2",800,220,"6.38","17.83"

# Requested files
"/",3000,890,"23.93","72.16"
"/index.html",1500,420,"11.97","34.05"

# Status codes
"200",10500,"83.73"
"304",1200,"9.57"
"404",450,"3.59"
"500",47,"0.37"

3.5.3 CSV 后处理示例

# 导入到 SQLite 数据库
goaccess /var/log/nginx/access.log --log-format=COMBINED -o report.csv

# 用 Python 分析 CSV
python3 << 'EOF'
import csv

with open('report.csv', 'r') as f:
    reader = csv.reader(f)
    for row in reader:
        if row and not row[0].startswith('#'):
            print(row)
EOF

3.6 常用命令行参数速查

3.6.1 输入相关

参数 说明 示例
FILE 日志文件路径 goaccess /var/log/nginx/access.log
- 从标准输入读取 cat log | goaccess -
--stdin 同上,明确指定 goaccess --stdin
--fifo-in=PATH 从 FIFO 管道读取 --fifo-in=/tmp/goaccess.fifo

3.6.2 日志格式相关

参数 说明 示例
--log-format=FORMAT 指定日志格式 --log-format=COMBINED
--date-format=FORMAT 日期格式 --date-format=%d/%b/%Y
--time-format=FORMAT 时间格式 --time-format=%H:%M:%S

3.6.3 输出相关

参数 说明 示例
-o FILE 输出到文件 -o report.html
-o - 输出到标准输出 -o - | jq
--real-time-html 实时 HTML 模式 --real-time-html
--html-title=TITLE HTML 标题 --html-title="报告"
--html-prefs=JSON HTML 偏好设置 --html-prefs='{"theme":"bright"}'

3.6.4 面板相关

参数 说明 示例
--enable-panel=PANEL 启用指定面板 --enable-panel=GEO_LOCATION
--sort-panel=PANEL,KEY 面板排序 --sort-panel=VISITORS,BY_HITS
--no-color 禁用颜色输出 --no-color

3.6.5 过滤相关

参数 说明 示例
--exclude-ip=IP 排除 IP --exclude-ip=127.0.0.1
--ignore-panel=PANEL 忽略面板 --ignore-panel=REFERRING_SITES
--date-range=DATE-DATE 日期范围 --date-range=20260101-20260131
--exclude=PATTERN 排除请求 --exclude="\.(css|js)"

3.6.6 性能相关

参数 说明 示例
--process-and-exit 分析完成后退出 --process-and-exit
--num-comms=N 线程数(如果支持) --num-comms=4
--persist 持久化数据 --persist
--restore 恢复持久化数据 --restore

3.7 终端配色方案

GoAccess 内置多种终端配色方案:

# 使用暗色主题
goaccess access.log --log-format=COMBINED --color-scheme=1

# 使用亮色主题
goaccess access.log --log-format=COMBINED --color-scheme=2

# 使用 Mono Green 主题
goaccess access.log --log-format=COMBINED --color-scheme=3

# 使用 Monokai 主题
goaccess access.log --log-format=COMBINED --color-scheme=4

# 自定义颜色(在配置文件中设置)
# color-scheme 1

3.8 处理压缩日志

GoAccess 本身不支持直接读取 .gz.bz2 压缩文件,但可以通过管道间接处理:

# 处理 gzip 压缩的日志
zcat /var/log/nginx/access.log.*.gz | goaccess --log-format=COMBINED -

# 处理 bzip2 压缩的日志
bzcat /var/log/nginx/access.log.*.bz2 | goaccess --log-format=COMBINED -

# 同时处理压缩和未压缩的日志
cat /var/log/nginx/access.log.*.gz | zcat - /var/log/nginx/access.log | \
  goaccess --log-format=COMBINED -

# 使用 zgrep 过滤后再分析
zcat /var/log/nginx/access.log.*.gz | grep "2026/May" | \
  goaccess --log-format=COMBINED -

3.9 实战示例

示例一:快速查看今日访问

TODAY=$(date +%d/%b/%Y)
grep "$TODAY" /var/log/nginx/access.log | goaccess --log-format=COMBINED -

示例二:生成报告并自动在浏览器中打开

goaccess /var/log/nginx/access.log \
  --log-format=COMBINED \
  -o /tmp/report.html && \
  xdg-open /tmp/report.html  # Linux
  # open /tmp/report.html    # macOS

示例三:分析特定时间段的日志

# 分析 2026 年 5 月的日志
awk '/10\/May\/2026/' /var/log/nginx/access.log | \
  goaccess --log-format=COMBINED -

示例四:排除自身 IP 后生成报告

goaccess /var/log/nginx/access.log \
  --log-format=COMBINED \
  --exclude-ip=$(curl -s ifconfig.me) \
  -o report.html

3.10 小结

操作 命令
终端交互 goaccess access.log --log-format=COMBINED
HTML 报告 goaccess access.log --log-format=COMBINED -o report.html
JSON 输出 goaccess access.log --log-format=COMBINED -o report.json
CSV 输出 goaccess access.log --log-format=COMBINED -o report.csv
管道输入 cat access.log | goaccess --log-format=COMBINED -
压缩日志 zcat access.log.gz | goaccess --log-format=COMBINED -

下一章

下一章将深入讲解日志格式的配置,包括 Apache/Nginx 的各种日志格式、自定义格式的编写方法以及时间格式的解析。

04 - 日志格式详解


扩展阅读