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

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 面板切换快捷键

快捷键面板
1Unique Visitors (独立访客)
2Requested Files (请求文件)
3Requested Static Files (静态资源)
4Not Found (404)
5Hosts / IPs
6Operating Systems
7Browsers
8Referring Sites
9Referring URLs
0HTTP 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 Found404 请求数
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=TITLEHTML 标题--html-title="报告"
--html-prefs=JSONHTML 偏好设置--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 - 日志格式详解


扩展阅读