AWStats 配置参数详解（awstats.<site>.conf）

目标：以 AWStats 配置文件为底本逐组详解全部核心参数：日志源、站点身份、存储、Web 访问控制、统计过滤、URL 解析行为、特征检测级别、报表显示、栏目开关、插件与自定义报表十一组，标注真实默认值并给出可运行的生产模板。本文基于 Ubuntu 22.04 实机（apt 安装 7.8 与官方 8.0 两个版本的配置文件）逐项 grep 实证，过滤类参数附实测生效回显。

一、环境信息

AWStats 的配置体系只有一层文件约定：-config=<站点标识> 对应 /etc/awstats/awstats.<站点标识>.conf；每个被分析站点一份文件，文件间无继承关系（可用 Include 指令引入公共片段，见 5.11 节）。

二、前置条件

• 已按《AWStats 裸机安装指南（apt + Apache CGI 集成实测）》完成安装，/usr/lib/cgi-bin/awstats.pl -version 可输出版本；
• 有一份站点配置文件可作参照（7.8 在 /etc/awstats/awstats.conf；8.0 用模板 awstats.model.conf）：

grep -cE '^[A-Za-z0-9_]+=' /etc/awstats/awstats.conf
# 实测回显：136

三、参数查看与修改方式

AWStats 配置文件是纯文本 键=值 形式，# 为注释，### 无特殊含义（大段落标题用 #---- 分隔线+文字）。三个实用命令：

# 1. 查看某参数当前值（含所在行号）
grep -nE '^(LogFile|LogFormat|SiteDomain)=' /etc/awstats/awstats.www.example.com.conf
# 实测回显：
# 50:LogFile="/var/log/apache2/access.log"
# 126:LogFormat=1
# 157:SiteDomain="www.example.com"

# 2. 批量列出全部有效参数
grep -E '^[A-Za-z0-9_]+=' /etc/awstats/awstats.www.example.com.conf

# 3. 修改后语法自检（没有专门 lint 命令，跑一次 -update 看 Phase 1 是否正常即可）
sudo /usr/lib/cgi-bin/awstats.pl -config=www.example.com -update | head -2
# 实测回显：
# Create/Update database for config "/etc/awstats/awstats.www.example.com.conf" by AWStats version 7.8 (build 20200416)
# From data in log file "/var/log/apache2/access.log"...

修改过滤/解析类参数的生效规则（实测）：AWStats 是增量记账模型，Skip*/Only*/URLWithQuery 等解析期参数只影响「新解析的日志行」，已入库的历史统计不会回溯。要让其生效必须删除当月数据文件后重灌：

sudo rm -f /var/lib/awstats/awstats102026.www.example.com.txt
sudo /usr/lib/cgi-bin/awstats.pl -config=www.example.com -update

参数写错（键名拼错、值类型不对）不会报错，只会被静默忽略——AWStats 启动时只对未知键提示 Warning: ... unknown parameter（DebugMessages=1 时可见），改完必须用实际报表数值验证。

四、参数总览（分组索引）

136 个有效参数按功能分为十一组，核心参数如下表（默认值均为 7.8 实机 grep 结果，8.0 模板同值）：

五、核心参数分类详解

5.1 日志源参数（LogFile / LogType / LogFormat / LogSeparator）

LogFile（默认 /var/log/httpd/mylog.log）：被解析的日志路径。三个进阶用法：

• 相对路径按「前一天」滚动：LogFile="/var/log/nginx/access.log.%YYYY-24-%MM-24-%DD-24"——时间占位符 %YYYY-24 表示当前时间减 24 小时的年份，适合配合 logrotate 每日定时分析昨天的归档；
• 支持管道命令：LogFile="gzip -d </var/log/nginx/access.log.1.gz |"（结尾的 | 表示这是一个命令），直接消化 .gz 归档；
• 绝对路径无占位符 = 每次都从头解析该文件的「新增行」（增量游标记录在数据文件里）。

LogType（默认 W）：W=Web 访问、S=流媒体、M=邮件、F=FTP。决定报表形态与 5.6 节部分参数的适用性（邮件日志配套 ValidSMTPCodes，Web 日志配套 ValidHTTPCodes）。

LogFormat（默认 4）：预置代号——1=Apache/NCSA combined（XLF/ELF）、2=IIS 旧格式、3=WebStar、4=NCSA common（CLF）、5=W3C 扩展（IIS 5+）。非预置格式写自定义串，字段用空格分隔的 % 占位符表达，例如 Nginx 自定义格式的典型映射（实测 8.0 模板注释同款写法）：

# Nginx log_format 自定义时：$remote_addr 对应 %host，$time_local 对应 %time1，
# $request 对应 %methodurl，$status 对应 %code，$body_bytes_sent 对应 %bytesd，
# $http_referer 对应 %referer，$http_user_agent 对应 %uaquot
LogFormat="%host %other %other %time1 %methodurl %code %bytesd %referer %uaquot"

💡 技术拓展：LogFormat 与 Web 服务器日志格式的关系——Apache 默认 combined 对应代号 1；Nginx 默认 main 格式（$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"）与 combined 完全同构，同样用 1；只有自定义过 log_format 的 Nginx 才需要自定义串。判断标准：拿一行真实日志对照格式字段数，用 tail -1 /var/log/nginx/access.log 核对。Nginx 日志与配置指令体系详见《Nginx 配置参数详解》。

LogSeparator（默认 " "）：仅自定义 LogFormat 且分隔符非空格时设置（如制表符 "\t"）。

5.2 站点身份参数（SiteDomain / HostAliases / DNSLookup 系）

SiteDomain（默认 ""）：站点主域名，报表标题、入口页归一、内部链接判断都依赖它，必填。

HostAliases（默认 "localhost 127.0.0.1"）：站点全部可到达的别名（含不带 www 的裸域）。同一日志里出现多个虚拟主机时，AWStats 用它判断哪些行属于本站。支持 REGEX[\.example\.com$] 正则写法。

DNSLookup（默认 1）：反向 DNS 解析级别。0=不解析（IP 直接显示，最快）；1=仅「缺失时」解析（本次实测默认值）；2=全部解析（最慢，仅旧日志离线回灌时用）。解析结果写缓存文件。生产高流量站点建议 0，改用 geoip 插件出地理分布（见 5.10）。

DynamicDNSLookup（默认 0）：CGI 动态页即时更新时是否做 DNS 解析，默认关闭合理。

DNSStaticCacheFile（默认 dnscache.txt）/ DNSLastUpdateCacheFile（默认 dnscachelastupdate.txt）：解析结果缓存文件名，落在 DirData。实测数据目录中可见 dnscachelastupdate.www.example.com.hash 即由后者生成。

SkipDNSLookupFor（默认 ""）：跳过解析的 IP 列表（如已知的内部爬虫段）。

5.3 存储与数据文件参数（DirData 系）

DirData（默认 /var/lib/awstats）：分析数据库目录，运行用户需写权限。多站点用不同 DirData 可完全隔离数据（本文实测 8.0 实例即用 /var/lib/awstats80）。

DirCgi（默认 /cgi-bin）/ DirIcons（默认 /awstats-icon）：报表页内部链接用的 URL 前缀，须与 Apache 的 ScriptAlias/Alias 一致（对应《AWStats 裸机安装指南（apt + Apache CGI 集成实测）》 4.4 节的集成配置）。

CreateDirDataIfNotExists（默认 0）：DirData 不存在时自动创建，设 1 可省去手工 mkdir。

BuildHistoryFormat（默认 text）：数据文件格式，text 人类可读、xml 便于 XSLT 二次加工（8.0 支持）。改格式后旧数据文件不兼容，需重灌。

BuildReportFormat（默认 html）：报表输出格式，html 或 xhtml。

KeepBackupOfHistoricFiles（默认 0）：重灌当月数据前是否备份旧文件为 .bak，谨慎运维可开。

PurgeLogFile（默认 0）/ ArchiveLogRecords（默认 0）：解析后是否删除/归档源日志。保持 0——让 logrotate 管日志生命周期，AWStats 只做只读消费，误配 PurgeLogFile=1 会把日志删掉。

SaveDatabaseFilesWithPermissionsForEveryone（默认 0）：数据文件权限是否放宽为所有人可读，保持 0。

EnableLockForUpdate（默认 0）：更新加锁。多调度器并存（cron + 手工）时建议设 1，防两个 -update 同时写同一数据文件导致损坏。

5.4 Web 访问控制参数（CGI 模式安全）

AllowToUpdateStatsFromBrowser（默认 0）：报表页显示「Update now」按钮，点一下即时解析日志。方便但把解析负载挂到了 Web 请求路径上，高流量站点保持 0（定时 cron 负责）。

AllowFullYearView（默认 2）：跨年聚合视图权限，0=禁止、1=仅管理员（认证用户）、2=所有人。全年视图要聚合 12 个月数据文件，大站点内存开销显著，建议 1。

AllowAccessFromWebToAuthenticatedUsersOnly（默认 0）：设 1 后 CGI 页仅限认证用户；配合 AllowAccessFromWebToFollowingAuthenticatedUsers（默认 ""，名单）与 AllowAccessFromWebToFollowingIPAddresses（默认 ""，IP 白名单）。⚠️ 实测口径：这套参数是 AWStats 应用层的第二道防线，第一道永远是 Web 服务器的认证/授权（B1 篇 4.4 的 BasicAuth），两层叠加更稳。

5.5 统计过滤参数（Skip* / Only* / ValidHTTPCodes）

黑名单组（命中即丢弃，不进统计）：

白名单组（与 Skip* 相反，仅保留命中者）：OnlyHosts / OnlyUserAgents / OnlyUsers（HTTP 认证用户）/ OnlyFiles。

NotPageList（默认 "css js class gif jpg jpeg png bmp ico rss xml swf eot woff woff2"）：命中这些扩展名的请求计为 hit 而非 page，直接影响 Pages 指标口径。

ValidHTTPCodes（默认 "200 304"）：计入「正常访问」的状态码。要把跳转计入就补 30x，但会把爬虫重定向也算进流量——保持默认并在 SkipFiles/SkipHosts 层面治理噪音更可控。

过滤参数生效实测（本文实测记录）：给 8.0 实例配置 SkipFiles="/wp-login.php"，删除当月数据文件重灌 322 行日志：

sudo perl /usr/local/awstats/wwwroot/cgi-bin/awstats.pl -config=local8 -update 2>&1 | grep -E 'qualified|dropped'
# 实测回显：
#  Found 1 dropped records,
#  Found 321 new qualified records.

322 → 321（dropped 1）：/wp-login.php 那一条被滤掉，参数生效验证通过。

5.6 URL 与解析行为参数

5.7 特征检测级别参数（LevelFor* 八件套）

实测默认值与注释（7.8 与 8.0 同）：

grep -nE '^LevelFor' /etc/awstats/awstats.conf
# 实测回显：
# 867:LevelForBrowsersDetection=2         # 0 disables Browsers detection.
# 870:LevelForOSDetection=2               # 0 disables OS detection.
# 872:LevelForRefererAnalyze=2            # 0 disables Origin detection.
# 874:LevelForRobotsDetection=2           # 0 disables Robots detection.
# 876:LevelForSearchEnginesDetection=2    # 0 disables Search engines detection.
# 878:LevelForKeywordsDetection=2         # 0 disables Keyphrases/Keywords detection.
# 880:LevelForFileTypesDetection=2        # 0 disables File types detection.
# 882:LevelForWormsDetection=0            # 0 disables Worms detection.

0=关闭该类检测（省 CPU），2=标准级别（个别参数支持 4 的精细级别）。默认全部开启仅 Worms 关闭； Worms 检测特征库停留在 2000 年代的蠕虫家族，现代意义有限，保持 0。

5.8 报表显示参数

5.9 报表栏目开关（Show* 系列与列代码表）

Show* 系列控制主页面各报表的展示与列组合，值为列代码串。官方代码表（配置文件注释原文）：

值的三种形态：0=不显示；1=显示（默认列）；代码串=显示指定列。核心实测默认值：

grep -nE '^Show(Summary|MonthStats|HoursStats|HostsStats|PagesStats|OriginStats|HTTPErrorsStats)=' /etc/awstats/awstats.conf
# 实测回显：
# 980:ShowSummary=UVPHB
# 985:ShowMonthStats=UVPHB
# 1000:ShowHoursStats=PHB
# 1010:ShowHostsStats=PHBL
# 1045:ShowPagesStats=PBEX
# 1080:ShowOriginStats=PH
# 1100:ShowHTTPErrorsStats=1

另有两类配套：AddDataArray* 四项（默认 1，决定月/日/周/时分布是否保留明细数组，关掉可缩小数据文件）；邮件/流媒体专用栏目（ShowEMailSenders 等）在 LogType=W 下无效，保持默认 0。

5.10 插件参数（LoadPlugin）

插件是 .pm 文件，放 plugins 目录（7.8：/usr/share/awstats/plugins；8.0：wwwroot/cgi-bin/plugins），配置文件里用 LoadPlugin="插件名" 启用，可多行。实测 7.8 的 Debian 打包默认启用了一个：

grep -n '^LoadPlugin=' /etc/awstats/awstats.conf
# 实测回显：
# 1349:LoadPlugin="hashfiles"

常用插件与依赖（配置文件注释原文整理）：

启用示例（实测依赖安装 + 配置行）：

sudo apt install -y libgeo-ip-perl
# 在 awstats.<site>.conf 中：
# LoadPlugin="geoip GEOIP_STANDARD /usr/share/GeoIP/GeoIP.dat"

5.11 自定义报表（ExtraSection）与 INCLUDES

ExtraSection 是 AWStats 的报表扩展机制：按条件对日志行做分组统计（如「按商品 ID 统计下单页」「按文章 ID 统计阅读量」），每组参数后缀 1..N 可定义多张自定义报表。配置文件注释给出的完整模板（实测摘录）：

#ExtraSectionCodeFilter1="200 304"
#ExtraSectionCondition1="URL,\/cgi\-bin\/order\.cgi||URL,\/cgi\-bin\/order2\.cgi"
#ExtraSectionFirstColumnTitle1="Product ID"
#ExtraSectionFirstColumnValues1="QUERY_STRING,productid=([^&]+)"
#ExtraSectionFirstColumnFormat1="%s"
#ExtraSectionStatTypes1=PL
#ExtraSectionAddAverageRow1=0
#ExtraSectionAddSumRow1=1
#MaxNbOfExtra1=20
#MinHitExtra1=1

字段逻辑：CodeFilter 限定状态码 → Condition 限定命中行（URL,正则||URL,正则 或关系）→ FirstColumnValues 从指定字段提取分组键（正则捕获组）→ StatTypes 定义统计列（P/H/B/U 等）。全局保护参数 ExtraTrackedRowsLimit（实测默认 500）限制单张自定义报表最大行数，防止提取键过于发散打爆内存，超出时 AWStats 直接报错停止——做商品/文章级统计时按需调大。

INCLUDES：配置文件末尾支持 Include "公共片段路径" 把公共参数拆到独立文件维护，多站点服务器用它收敛 LogFormat/Skip* 等共性配置。

六、生产配置模板

模板一：通用 Web 站点（2C4G 服务器、单站、日志 <5GB/月，Apache combined）——在 7.8 默认配置基础上只改以下项：

LogFile="/var/log/apache2/access.log"
LogFormat=1
SiteDomain="www.example.com"
HostAliases="www.example.com localhost 127.0.0.1 REGEX[\.example\.com$]"
DNSLookup=0
DirData="/var/lib/awstats"
AllowToUpdateStatsFromBrowser=0
EnableLockForUpdate=1
SkipHosts="127.0.0.1 REGEX[^192\.168\.]"
SkipFiles="/healthcheck"
LoadPlugin="decodeutfkeys"
LoadPlugin="geoip GEOIP_STANDARD /usr/share/GeoIP/GeoIP.dat"
Lang="cn"
AllowFullYearView=1

模板二：高流量站点（16C32G、Nginx 自定义日志、日志 >50GB/月，多站隔离）——差异项：

LogFile="/var/log/nginx/example.access.log"
LogFormat="%host %other %other %time1 %methodurl %code %bytesd %referer %uaquot"
DirData="/var/lib/awstats/example.com"
CreateDirDataIfNotExists=1
DNSLookup=0
LevelForWormsDetection=0
MaxRowsInHTMLOutput=50000
URLWithQuery=1
URLWithQueryWithoutFollowingParameters="utm_source utm_medium utm_campaign"
ExtraTrackedRowsLimit=2000

两个模板的内存/磁盘口径：AWStats 分析期内存与「当月 host/page 组合数」正相关，单站百万级组合约需 1–2GB 峰值内存；数据文件（text 格式）约为当月去重组合数的几十倍字节，50GB 原始日志的单月数据文件通常在 100–500MB 量级——预留 2GB 内存与 5GB 数据磁盘是常规起配。

七、常见问题

Q1：改了 SkipFiles/SkipHosts 但报表数值没变？ 增量模型不回溯历史（见第三节生效规则）：删当月数据文件重灌。本文实测：SkipFiles 生效需 rm /var/lib/awstats/awstatsMMYYYY.<site>.txt 后重跑 -update，回显由 322 qualified 变为 1 dropped + 321 qualified。

Q2：-update 报 Error: SiteDomain parameter not defined？ SiteDomain 为空时 CGI/输出模式拒绝出页。填站点主域名即可。

Q3：Lang="cn" 后报表部分文字仍是英文？ lang 包缺失对应条目时回退英文（AWStats 中文包翻译不完全，属正常现象）；确认 DirLang 指向的目录里有 cn 语言文件：ls /usr/share/awstats/lang/ | grep cn。

Q4：多个站点日志混在一个 access.log 里怎么拆？ 若日志带 vhost 字段（%virtualname），用自定义 LogFormat 加 %virtualname，并让每个站点的 HostAliases 互斥；否则建议改 Web 服务器按站分开记录（Apache 的 CustomLog per-vhost，Nginx 的 access_log per-server）。

Q5：数据文件多久轮转一次？误删了怎么办？ 按自然月分文件（awstatsMMYYYY.site.txt），跨月自动新建。误删后只要原始日志还在，重跑 -update 即可完整重建（但要求 LogFile 覆盖全月，配合 5.1 的占位符路径逐日重灌）。

八、参考链接

• 官方配置文档：https://awstats.sourceforge.io/docs/awstats_config.html
• 模板文件全文（8.0）：https://github.com/eldy/AWStats/blob/main/wwwroot/cgi-bin/awstats.model.conf
• 官方插件清单：https://awstats.sourceforge.io/docs/awstats_contrib.html#PLUGINS
• ExtraSection 官方说明（FAQ EXTRASECTION）：https://awstats.sourceforge.io/docs/awstats_faq.html#EXTRA
• 本专栏相关：《AWStats 介绍与选型指南》、《AWStats 裸机安装指南（apt + Apache CGI 集成实测）》、《AWStats 常用 CLI 命令详解（awstats.pl 与日志预处理链）》、《Nginx 配置参数详解》