GoAccess 配置参数详解

‍‍‌> 目标：逐段逐参数讲清 GoAccess 1.9.4 的 goaccess.conf 全部配置项——含义、真实默认值、改动后的影响，并给出常见日志格式的定义写法与一份可直接落地的生产模板。关键参数均附 Ubuntu 22.04 实测生效回显。

一、环境信息

本文参数与实测基于以下环境：

操作系统：Ubuntu 22.04.4 LTS（x86_64）
GoAccess 1.9.4（源码编译，--enable-utf8 --enable-geoip=mmdb），配置文件 /usr/local/etc/goaccess/goaccess.conf（782 行）
对照版本：apt 版 1.5.5 的 /etc/goaccess/goaccess.conf（730 行）
分析样本：nginx Combined 格式日志 /opt/data/goaccess-sample/access.log（53 行，含静态资源与 404）
GeoIP 库：GeoLite2-Country.mmdb（3.4MB）

二、前置条件

确认 GoAccess 已安装并核对配置文件存在：

goaccess --version | head -1
ls -la /usr/local/etc/goaccess/goaccess.conf

实测回显：

GoAccess - 1.9.4.
-rw-r--r-- 1 root root 21617 10月 17 16:14 /usr/local/etc/goaccess/goaccess.conf

三、参数查看与修改方式

GoAccess 的参数有三个来源，优先级从高到低为：命令行参数 > 项目配置文件（--config-file）> 全局配置文件。全局配置文件路径随安装方式不同：源码版 /usr/local/etc/goaccess/goaccess.conf，apt 版 /etc/goaccess/goaccess.conf。

查看全局配置的加载情况（version 输出中会显示实际加载的配置文件路径）：

goaccess --version

实测回显（输出节选）：

GoAccess - 1.9.4.
Config file: /usr/local/etc/goaccess/goaccess.conf

三种修改方式：

改全局配置文件（对所有调用生效）：直接编辑 /usr/local/etc/goaccess/goaccess.conf，去掉参数前的 # 并赋值，如 hl-header true。
项目专用配置：复制一份到 /opt/goaccess/prod.conf，调用时 goaccess --config-file=/opt/goaccess/prod.conf，其值覆盖全局配置。
命令行临时覆盖：goaccess --log-format=COMBINED ...，优先级最高。

⚠️ 注意：配置文件中布尔项写法是 参数名 true/false（无等号，如 json-pretty-print false），命令行则是 --json-pretty-print 开关式或 --json-pretty-print=true。文件格式为"每行一个参数 + 空格 + 值"，# 开头为注释。

💡 技术拓展：配置生效方式不止"改文件"一种，与大多数 Linux 服务类似有三层体系——

方式优先级适用场景
命令行 --参数 最高临时试验、单次分析
--config-file 指定项目配置中多站点/多格式并存
全局 goaccess.conf 最低服务器默认行为

生产上推荐：全局文件保持官方默认不动，每个业务一份项目配置文件，systemd 单元里用 --config-file 引用，便于灰度与回滚。

方式	优先级	适用场景
命令行 `--参数`	最高	临时试验、单次分析
`--config-file` 指定项目配置	中	多站点/多格式并存
全局 goaccess.conf	最低	服务器默认行为

验证参数确实生效的通用手法：同一份日志分别跑"默认 vs 修改后"两次，对比 JSON 输出差异。下文每个关键参数都用这一方法给出实测回显。

四、参数总览

goaccess.conf 按 7 大段组织，下表汇总各段全部参数与真实默认值（"未启用"指 conf 中默认被 # 注释、需手动开启；"列出默认"指文件中已有生效行）。

分组	参数（默认值）	作用一句话
时间/日期格式	`time-format %H:%M:%S`（未启用，预置 3 种）、`date-format %d/%b/%Y`（未启用，预置 4 种）、`datetime-format`（未启用）	告诉解析器日志里时间/日期怎么读
日志格式	`log-format`（未启用；预置 12 种命名格式 + 各家格式串）	告诉解析器一行日志的字段布局
UI	`config-dialog false`、`hl-header true`、`no-color false`、`no-column-names false`、`no-csv-summary false`、`no-progress false`、`no-tab-scroll false`、`json-pretty-print false`、`with-mouse false`、`real-os true`、`color-scheme`（未启用，可选 1/2/3）、`html-prefs`、`html-report-title`、`html-custom-css/js`、`no-html-last-updated`、`no-parsing-spinner`、`max-items 366`（未启用）、`tz`（未启用）、`color`（未启用）	终端与各输出形态的外观行为
Server	`addr 0.0.0.0`（未启用）、`port 7890`（未启用）、`daemonize`（未启用）、`pid-file`（未启用）、`real-time-html`（未启用）、`origin`、`ws-url`、`ssl-cert/ssl-key`、`ws-auth*`、`fifo-in/out`（未启用）	WebSocket 实时服务与守护化
File	`log-file`、`debug-file`、`config-file`、`invalid-requests`（均未启用）、`no-global-config false`	输入/调试/配置文件路径
Parse	`http-method yes`、`http-protocol yes`、`no-query-string false`、`no-term-resolver false`、`444-as-404 false`、`4xx-to-unique-count false`、`all-static-files false`、`double-decode false`、`ignore-crawlers false`、`crawlers-only false`、`unknowns-as-crawlers false`、`agent-list false`、`with-output-resolver false`、`real-os true`、`process-and-exit`（未启用）、`num-tests 10`（未启用）、`keep-last`（未启用）、`date-spec hr	min`（未启用）、`hour-spec min`（未启用）、`anonymize-ip`（未启用）、`no-ip-validation`（未启用）、`exclude-ip`（未启用）、`hide-referrer/ignore-referrer/ignore-status`（未启用）、`browsers-file`（未启用）、`enable-panel/ignore-panel`（文件中默认启用` ignore-panel REFERRERS`与`ignore-panel KEYPHRASES`）、`ignore-statics`（未启用）、`sort-panel`（未启用）、`static-file`（默认启用 39 个扩展名）
GeoIP	`std-geoip false`（未启用）、`geoip-database`（未启用）	地理库路径
Persistence	`db-path /tmp`（未启用）、`persist`（未启用）、`restore`（未启用）	磁盘持久化与恢复

解读要点：conf 中约 80% 参数默认关闭，保持"零配置可用"（配合命令行传 log-format 即可跑）；生产上真正必须显式配置的只有格式三件套与 GeoIP/持久化两类。

五、核心参数分类详解

本节按 conf 的分段逐参数展开。每个关键参数给出：真实默认值 → 改动写法 → 实测生效回显。

5.1 日志格式三件套（time-format / date-format / log-format）

这三个参数是 GoAccess 的灵魂：解析器按它们把一行日志切字段，三者必须与日志实际格式严格一致，否则整行解析失败。

time-format：日志中"时间"部分的 strftime 格式。conf 预置三种：

#time-format %H:%M:%S   # Apache/nginx 常规格式
#time-format %f         # Google Cloud Storage（微秒时间戳）
#time-format %s         # Squid / Caddy（秒级时间戳）

date-format：日志中"日期"部分的 strftime 格式，预置四种：

#date-format %d/%b/%Y   # Apache/nginx（如 17/Oct/2026）
#date-format %Y-%m-%d   # AWS ELB / CloudFront / IIS W3C
#date-format %f         # GCS 微秒时间戳
#date-format %s         # Squid / Caddy 秒级时间戳

log-format：整行字段布局。既可用 12 种预定义名（COMBINED、VCOMBINED、COMMON、VCOMMON、W3C、SQUID、CLOUDFRONT、CLOUDSTORAGE、AWSELB、AWSS3、CADDY、TRAEFIKCLF），也可用格式串。格式串中 %h 来源 IP、%^ 忽略字段、%d:%t 日期时间、%r 请求行、%s 状态码、%b 字节数、%R Referer、%u UA、%m 方法、%U URL、%v 虚拟主机、%T/%L 耗时、%D 微秒耗时。nginx 默认 Combined 格式的完整写法（conf 第 80 行原文）：

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

⚠️ 注意：命令行传 log-format 时若含空格必须整体加引号；使用预定义名（如 --log-format COMBINED）则不需要 date/time-format——预定义名已内置三者。自定义格式串时三件套缺一不可。

实测验证（自定义简版日志 + 自定义三件套）：构造无 Referer/UA 的简版日志：

printf '10.0.0.8 - [17/Oct/2026:09:00:01 +0800] "GET /api HTTP/1.1" 200 1024\n10.0.0.9 - [17/Oct/2026:09:00:02 +0800] "POST /login HTTP/1.1" 401 89\n' > /tmp/simple.log
goaccess /tmp/simple.log \
  --log-format='%h - [%d:%t %z] "%r" %s %b' \
  --date-format='%d/%b/%Y' --time-format='%H:%M:%S' \
  --output=/tmp/ga-custom.json
python3 -c 'import json; d=json.load(open("/tmp/ga-custom.json")); print(d["general"]["total_requests"], [(r.get("method"), r["data"], r["hits"]["count"]) for r in d["requests"]["data"]])'

实测回显：

2 [('GET', '/api', 1), ('POST', '/login', 1)]

两条日志按自定义格式成功切分出方法、URL、点击数，三件套生效。

5.2 UI 选项组

控制终端与三种输出形态的外观。文件内已有生效默认值的项如下（conf 原文摘录）：

config-dialog false     # 启动时不弹出格式配置窗口
hl-header true          # 终端高亮当前面板
no-color false          # 输出着色（终端不支持色彩时自动关闭）
no-column-names false   # 输出中保留列名
no-csv-summary false    # CSV 保留汇总指标
no-progress false       # 保留解析进度显示
no-tab-scroll false     # TAB 键可滚动切换面板
json-pretty-print false # JSON 压缩输出
with-mouse false        # 终端不支持鼠标
real-os true            # OS 面板显示具体版本名（如 Windows 10）

实测：json-pretty-print：

goaccess /opt/data/goaccess-sample/access.log --log-format=COMBINED --json-pretty-print --output=/tmp/ga-pretty.json
head -8 /tmp/ga-pretty.json
wc -l /tmp/ga-pretty.json

实测回显：

{
        "general": {
                "start_date": "17/10月/2026",
                "end_date": "17/10月/2026",
                "date_time": "2026-10-17 16:51:16 +0800",
                "total_requests": 53,
                "valid_requests": 53,
...
1973 /tmp/ga-pretty.json

对比关闭时的压缩单行（约 21KB/1 行），开启后 1973 行缩进缩排，便于人工阅读与 git diff。

未启用但常用的项：color-scheme 3（Monokai 配色，需 256 色终端）、html-report-title My Report（HTML 页头标题）、html-prefs {"theme":"darkGray","perPage":10}（HTML 默认主题与分页，单行 JSON）、max-items 366（每面板最大条目，仅 JSON/CSV 可超过 366）、tz Asia/Shanghai（报告时区，需配合 datetime-format）。

5.3 Server 选项组（实时服务）

参数	真实默认值	说明
`addr`	`0.0.0.0`（未启用）	WebSocket 绑定地址
`port`	`7890`（未启用，conf 注释原文 "By default GoAccess' WebSocket server listens on port 7890"）	WebSocket 端口
`real-time-html`	关（未启用）	开启实时推送
`daemonize`	`false`（未启用）	配合 real-time-html 守护化
`pid-file`	`/var/run/goaccess.pid`（未启用）	daemonize 时写 PID
`origin`	空（未启用）	强制校验 WebSocket 握手 Origin 头
`ws-url`	localhost（未启用）	浏览器端连接的 ws 地址（反代场景改此值，如 `ws-url goaccess.example.com:9999`）
`ssl-cert` / `ssl-key`	空（未启用）	配置后 WebSocket 走 wss（需编译带 openssl）
`ws-auth` / `ws-auth-expire` / `ws-auth-url` / `ws-auth-refresh-url`	空（未启用）	WebSocket JWT 鉴权
`fifo-in` / `fifo-out`	`/tmp/wspipein.fifo`、`/tmp/wspipeout.fifo`（未启用）	外部进程与 GoAccess 间的命名管道

实测：--port=7890 与 --real-time-html：

goaccess /opt/data/goaccess-sample/access.log --log-format=COMBINED \
  --real-time-html --port=7890 --output=/tmp/rt/report.html &
ss -tlnp | grep 7890

实测回显：

LISTEN 0      4096         0.0.0.0:7890       0.0.0.0:*    users:(("goaccess",pid=2294384,fd=8))
WebSocket服务器已准备接收来自客户的连接

端口监听成功。再用 curl 模拟 WebSocket 握手验证推送通道：

curl -s -i -H "Connection: Upgrade" -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" -H "Sec-WebSocket-Version: 13" \
  -H "Origin: http://127.0.0.1" http://127.0.0.1:7890/ | head -4

实测回显：

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=

握手返回 101 并立即推送第一帧统计 JSON，实时通道正常。7890 上直接发普通 HTTP 请求会得到 400（该端口仅服务 WebSocket），报告页面由 --output 写出的 HTML 承担。

5.4 File 选项组

参数	真实默认值	说明
`log-file`	空（未启用）	输入日志路径，优先级高于命令行 `-f`
`debug-file`	空（未启用）	调试日志输出文件
`config-file`	空（未启用）	项目配置文件（覆盖全局配置）
`invalid-requests`	空（未启用）	把解析失败的行写入该文件，调 log-format 神器
`no-global-config`	`false`	true 时不读全局配置

💡 说明：调格式阶段强烈建议开 --invalid-requests=/tmp/invalid.log——所有解析失败的行会原样落盘，配合 num-tests 能快速定位格式差异。

5.5 Parse 选项组（解析行为与过滤）

这是参数最多的一组，按"方法协议 → 过滤 → 粒度 → 面板开关 → 静态文件"五小类展开。

方法与协议：

http-method yes      # 把 GET/POST 等并入请求键（默认 yes）
http-protocol yes    # 把 HTTP/1.1 协议并入请求键（默认 yes）

改为 no 后 requests 面板的"请求方法/协议"两列为空，URL 聚合更纯粹。

过滤类：

#exclude-ip 127.0.0.1                # 排除单个 IP
#exclude-ip 192.168.0.1-192.168.0.100 # 排除网段（区间写法）
no-query-string false                # true 则去掉 ? 后参数再聚合
444-as-404 false                     # nginx 444 视作 404
4xx-to-unique-count false            # 4xx 是否计入独立访客
anonymize-ip false                   # IP 匿名化（末段置零）
no-ip-validation false               # 关闭 IP 合法性校验（日志 IP 被混淆时用）
hide-referrer *.google.com           # 隐藏但仍统计该来源
ignore-referrer *.domain.com         # 完全忽略该来源
ignore-status 400                    # 忽略指定状态码
ignore-crawlers false                # 忽略爬虫（计入总请求数）
crawlers-only false                  # 只看爬虫
double-decode false                  # 双重 URL 编码解码

实测：--exclude-ip：

goaccess /opt/data/goaccess-sample/access.log --log-format=COMBINED --exclude-ip=172.17.0.1 --output=/tmp/ga-excl.json
python3 -c 'import json; d=json.load(open("/tmp/ga-excl.json")); print("total:", d["general"]["total_requests"], "visitors:", d["general"]["unique_visitors"])'

实测回显：

total: 53 visitors: 0

总请求数仍为 53（行都解析了），但独立访客被过滤为 0——exclude-ip 的语义是"从统计面板中剔除该 IP 的访问者"，不是丢弃日志行。

粒度类：

#date-spec hr|min    # 访客面板按"小时/分钟"聚合（默认按日）
#hour-spec min       # 时段面板按"10 分钟"粒度（默认按小时）

实测：--date-spec=hr：

goaccess /opt/data/goaccess-sample/access.log --log-format=COMBINED --date-spec=hr --output=/tmp/ga-hr.json
python3 -c 'import json; d=json.load(open("/tmp/ga-hr.json")); print([x["data"] for x in d["visitors"]["data"]], [(x["data"], x["hits"]["count"]) for x in d["visit_time"]["data"]])'

实测回显：

['2026101708', '2026101707'] [('07', 19), ('08', 34)]

访客面板键从 20261017（日）变为 2026101707/08（小时级），时段面板按小时分布，参数生效。

面板开关类（ignore-panel 忽略解析与展示；enable-panel 反向启用）：全部 17 个面板名为 VISITORS、REQUESTS、REQUESTS_STATIC、NOT_FOUND、HOSTS、OS、BROWSERS、VISIT_TIMES、VIRTUAL_HOSTS、REFERRERS、REFERRING_SITES、KEYPHRASES、STATUS_CODES、REMOTE_USER、CACHE_STATUS、GEO_LOCATION、MIME_TYPE、TLS_TYPE。conf 默认生效两行：

ignore-panel REFERRERS    # 默认关闭"来源页"面板
ignore-panel KEYPHRASES   # 默认关闭"搜索关键词"面板

实测：--ignore-panel=REFERRING_SITES --ignore-panel=BROWSERS：

goaccess /opt/data/goaccess-sample/access.log --log-format=COMBINED --ignore-panel=REFERRING_SITES --ignore-panel=BROWSERS --output=/tmp/ga-ign.json
python3 -c 'import json; d=json.load(open("/tmp/ga-ign.json")); print(sorted(d.keys()))'

实测回显：

['general', 'hosts', 'not_found', 'os', 'requests', 'static_requests', 'status_codes', 'visit_time', 'visitors']

输出 JSON 中 browsers 与 referring_sites 两个面板已消失，命令行指定的面板被成功忽略。

静态文件类：ignore-statics 两个取值——req（静态请求不计入有效请求）与 panels（面板也不展示）；all-static-files false（含查询串的静态文件默认不算静态）；static-file .css 等默认启用 39 个扩展名（css/js/jpg/png/gif/ico/jpeg/pdf/csv/mpeg/mpg/swf/woff/woff2/xls/xlsx/doc/docx/ppt/pptx/txt/zip/ogg/mp3/mp4/exe/iso/gz/rar/svg/bmp/tar/tgz/tiff/tif/ttf/flv/dmg/xz/zst），less/webp 等冷门扩展需手动取消注释。

实测：--ignore-statics=req：

goaccess /opt/data/goaccess-sample/access.log --log-format=COMBINED --ignore-statics=req --output=/tmp/ga-igstatic.json
python3 -c 'import json; d=json.load(open("/tmp/ga-igstatic.json")); g=d["general"]; print("total:", g["total_requests"], "valid:", g["valid_requests"], "static:", g["unique_static_files"])'

实测回显：

total: 53 valid: 41 static: 3

53 次总请求中有 12 次静态资源（css/js/robots.txt 等）被排除出"有效请求"，静态面板仍保留 3 个文件，参数语义与预期一致。

解析测试类：num-tests 10（未启用）——解析前先用前 10 行试跑 log-format，0 表示不测试直接全量解析；process-and-exit（未启用）——只解析不输出（配合 persist 预处理大日志）；keep-last 7（未启用）——持久化只保留最近 7 天。

5.6 GeoIP 选项组

#std-geoip false                                    # Legacy .dat 库开关
#geoip-database /usr/local/share/GeoIP/GeoLiteCity.dat  # 库文件路径

实测（GeoLite2-Country.mmdb，配合 mmdb 编译参数）：

goaccess /opt/data/goaccess-sample/access.log --log-format=COMBINED \
  --geoip-database=/opt/data/goaccess-sample/geoip/GeoLite2-Country.mmdb \
  --output=/tmp/geoip-test.json
python3 -c 'import json; d=json.load(open("/tmp/geoip-test.json")); print("geolocation" in d)'

实测回显：

True

geolocation 面板出现即数据库加载成功（样本日志为内网 IP，国家显示 Unknown 属预期）。City 库可提供城市级明细，配置方式相同。

5.7 Persistence 选项组

#db-path /tmp     # 持久化目录（默认 /tmp）
#persist          # 退出时落盘
#restore          # 启动时从磁盘恢复

⚠️ 注意：1.9 版本起"从磁盘恢复"参数名为 --restore（旧文档中的 --load-from-disk 已废弃，实测传旧参数报 goaccess: unrecognized option '--load-from-disk'）。

实测完整闭环（持久化 → 恢复 → 增量）：

# 第一次：全量解析并落盘
goaccess /opt/data/goaccess-sample/access.log --log-format=COMBINED \
  --persist --db-path=/tmp/ga-db --output=/tmp/p1.json
ls /tmp/ga-db/*.db | wc -l

# 第二次：不喂日志，从磁盘恢复
goaccess --log-format=COMBINED --restore --db-path=/tmp/ga-db --output=/tmp/p2.json
python3 -c 'import json; d=json.load(open("/tmp/p2.json")); print(d["general"]["total_requests"])'

# 第三次：恢复 + 追加 1 行新日志 + 回写
tail -1 /opt/data/goaccess-sample/access.log > /tmp/new-line.log
goaccess /tmp/new-line.log --log-format=COMBINED --restore --persist --db-path=/tmp/ga-db --output=/tmp/p3.json
python3 -c 'import json; d=json.load(open("/tmp/p3.json")); print(d["general"]["total_requests"])'

实测回显：

151
53
54

落盘 151 个 .db 文件；空输入恢复出 53 条与源日志一致；喂 1 行后增量到 54——persist/restore 组合可支撑跨周期累积统计。

六、常见 log-format 定义与自定义写法

本节给出生产中最高频的日志格式与对应的 GoAccess 定义，可直接照抄。

表：常用预定义名与典型来源

预定义名	展开格式串	典型来源
COMBINED	`%h %^[%d:%t %^] "%r" %s %b "%R" "%u"`	nginx/Apache 默认 combined
VCOMBINED	`%v:%^ %h %^[%d:%t %^] "%r" %s %b "%R" "%u"`	combined + 虚拟主机
COMMON	`%h %^[%d:%t %^] "%r" %s %b`	nginx/Apache common
AWSELB	`%dT%t.%^ %^ %h:%^ %^ %T %^ %^ %^ %s %^ %b "%r" "%u"`	AWS ELB
CLOUDFRONT	`%d\t%t\t%^\t%b\t%h\t%m\t%^\t%r\t%s\t%R\t%u\t%^`	AWS CloudFront（制表符分隔）
CADDY	Caddy JSON 结构化格式串	Caddy JSON 日志
TRAEFIKCLF	`%h - %e [%d:%t %^] "%r" %s %b "%R" "%u" %^ "%v" "%U" %Lms`	Traefik CLF

自定义格式写法四步法：

抄一行真实日志作样本；
从左到右把每个字段替换为说明符，不想统计的字段一律用 %^；
常量字符（引号、空格、方括号）原样保留；
用 --num-tests=1 + --invalid-requests 试跑校准。

示例一（nginx 自定义格式，带响应耗时与请求体大小）：

# nginx.conf: log_format main '$remote_addr - $remote_user [$time_local] '
#                             '"$request" $status $body_bytes_sent '
#                             '"$http_referer" "$http_user_agent" $request_time';
time-format %H:%M:%S
date-format %d/%b/%Y
log-format %h %^[%d:%t %^] "%r" %s %b "%R" "%u" %L

示例二（带虚拟主机的前置格式）：

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

示例三（JSON 结构化日志：把 JSON 键当常量写、值用说明符，见 conf 中 CADDY 行的写法）。

七、生产配置模板

以下模板面向「单台 nginx Web 服务器、8GB 内存、每天数 GB 访问日志、每小时定时报告 + GeoIP」的典型场景，实测于本文环境，可直接保存为 /etc/goaccess/prod.conf 使用：

## ==== 日志格式（nginx combined）====
time-format %H:%M:%S
date-format %d/%b/%Y
log-format COMBINED

## ==== GeoIP ====
geoip-database /opt/geoip/GeoLite2-Country.mmdb

## ==== 解析行为 ====
http-method yes
http-protocol yes
no-query-string false
444-as-404 true
4xx-to-unique-count true
ignore-crawlers false
num-tests 10
# 调格式期开启，稳定后注释
#invalid-requests /var/log/goaccess-invalid.log

## ==== 面板 ====
ignore-panel REFERRERS
ignore-panel KEYPHRASES
static-file .css
static-file .js
static-file .woff2

## ==== 输出 ====
json-pretty-print false
max-items 366
hl-header true

## ==== 实时服务（systemd 常驻时启用）====
#real-time-html true
#port 7890
#daemonize true
#pid-file /var/run/goaccess.pid

## ==== 持久化（定时报告累积统计时启用）====
#db-path /var/lib/goaccess
#persist
#restore

## ==== 保留天数 ====
#keep-last 30

逐段说明：格式段用预定义名 COMBINED 免去三件套展开；GeoIP 指向集中部署的库文件；解析段开启 444 归并 404 与 4xx 计入访客（更真实的用户视角）；面板段与官方默认保持一致；实时与持久化段按服务形态二选一启用（实时常驻用 real-time-html 组，定时报告用 persistence 组）——两者同时启用没有意义，因为常驻进程自身就在累积内存数据。

八、常见问题（FAQ）

Q1：改了 goaccess.conf 但行为没变化？

排查顺序：确认改的是当前二进制实际加载的文件（goaccess --version 输出中的 Config file: 路径，实测为 /usr/local/etc/goaccess/goaccess.conf）→ 确认行首 # 已去掉 → 确认没有更高优先级的命令行参数或 --config-file 覆盖 → 布尔值写法是否为空格分隔（json-pretty-print true 而非 json-pretty-print=true）。

Q2：--log-format=COMBINED 报 Token '' doesn't match specifier '%h'？

这是格式与日志行不匹配的通用报错。实测遇到的一类根因是输入为空流（首行即空，%h 匹配到空串）。排查：head -3 日志文件 确认有完整日志行；再加 --num-tests=1 定位第一个不匹配字段；含查询串/特殊编码的日志尝试 --double-decode。

Q3：1.9.4 上 --load-from-disk 报 unrecognized option？

1.9 起该参数更名为 --restore，实测确认。旧脚本批量替换即可；1.5.5 等 1.8 及以下版本维持旧名。

Q4：exclude-ip 排除后 total_requests 没减少？

语义如此：exclude-ip 只把该 IP 从访客统计与各面板剔除，日志行仍计入总请求数（实测 53 条 total 不变、unique_visitors 归零）。想让行彻底不计入，用 ignore-status（状态码维度）或在采集层过滤。

Q5：JSON 输出想按行美化、报告想换主题？

--json-pretty-print（实测输出从压缩单行变为 1973 行缩进）与 html-prefs {"theme":"darkGray"}（HTML 主题，单行 JSON 写法）分别控制，均为 conf 中的 UI 组参数。

九、参考链接

官方配置文件示例（config/goaccess.conf）：https://github.com/allinurl/goaccess/blob/master/config/goaccess.conf
goaccess(1) 手册页（全参数）：https://man.archlinux.org/man/goaccess.1
strftime 格式符参考：https://man7.org/linux/man-pages/man3/strftime.3.html
MaxMind GeoLite2 数据库：https://dev.maxmind.com/geoip/docs/databases/
gwsocket（GoAccess 内置 WebSocket 实现）：http://gwsocket.io

相关文档：《Prometheus 3.x 配置参数详解》《Grafana 配置参数详解》