AWStats 常用 CLI 命令详解（awstats.pl 与日志预处理链）

目标：详解 AWStats 全部命令行工具的主参数与真实回显：主程序 awstats.pl 的统计更新（-update）、报表输出（-output）、数据分库（-databasebreak），整站静态报表生成器 awstats_buildstaticpages.pl，多站批量调度（awstats_updateall.pl 与 Debian update.sh），以及多日志合并预处理器 logresolvemerge.pl 构成的日志预处理链。全部命令与回显均在 Ubuntu 22.04.5 LTS 实机（AWStats 7.8 与 8.0 双版本）逐条实测。

一、环境信息

项目	值
操作系统	Ubuntu 22.04.5 LTS
AWStats	7.8-2ubuntu0.22.04.1（apt）与 8.0 build 20240604（tar.gz）双版本对照
主程序	/usr/lib/cgi-bin/awstats.pl（7.8）；/usr/local/awstats/wwwroot/cgi-bin/awstats.pl（8.0）
示例站点	www.example.com（/etc/awstats/awstats.www.example.com.conf，LogFormat=1）
示例日志	/var/log/apache2/access.log（combined，约 322 行）

perl /usr/lib/cgi-bin/awstats.pl -version
# 实测回显：
# awstats 7.8 (build 20200416)

二、工具概览

AWStats 发行包内的全部命令行工具一览（路径为 apt 安装布局，8.0 tar.gz 版对应在 /usr/local/awstats/tools/ 与 wwwroot/cgi-bin/）：

工具	路径	用途
awstats.pl	/usr/lib/cgi-bin/	主程序：统计更新与报表输出，一切功能的入口
awstats_buildstaticpages.pl	/usr/share/awstats/tools/	循环调用主程序批量生成整站静态报表
awstats_updateall.pl	（Debian 包不含；8.0 在 tools/）	扫描配置目录批量 -update
update.sh / buildstatic.sh	/usr/share/awstats/tools/	Debian 打包专用批量更新/静态页脚本（cron 配套）
logresolvemerge.pl	/usr/share/awstats/tools/	多日志按时间排序合并 + 可选 DNS 反解（日志预处理链核心）
maillogconvert.pl	/usr/share/awstats/tools/	邮件日志日期格式转换（Postfix/qmail/Sendmail → 可解析格式）
awstats_configure.pl	（8.0 tools/）	交互式配置向导（创建站点配置）
awredir.pl / awdownloadcsv.pl	（8.0 wwwroot/cgi-bin/）	报表外链跳转计数 / 报表数据导出 CSV

本文按「更新 → 输出 → 批量 → 预处理」的工作流顺序详解，全部命令可独立执行。

三、前置条件

已完成安装与站点配置（《AWStats 裸机安装指南（apt + Apache CGI 集成实测）》）；
站点配置文件存在且 LogFile 指向可读日志：

grep -E '^(LogFile|LogFormat|SiteDomain|DirData)=' /etc/awstats/awstats.www.example.com.conf
# 实测回显：
# LogFile="/var/log/apache2/access.log"
# LogFormat=1
# SiteDomain="www.example.com"
# DirData="/var/lib/awstats"

四、awstats.pl 主程序命令详解

不带任何参数运行 awstats.pl -h 可输出完整帮助（本次实机全文的关键部分）：

perl /usr/lib/cgi-bin/awstats.pl -h
# 实测回显（节选，7.8）：
# ----- awstats 7.8 (build 20200416) (c) 2000-2018 Laurent Destailleur -----
# AWStats is a free web server logfile analyzer to show you advanced web
# statistics.
# ...
# Syntax: awstats.pl -config=virtualhostname [options]
#   This runs awstats in command line to update statistics (-update option) of a
#    web site, from the log file defined in AWStats config file, or build a HTML
#    report (-output option).
#   First, awstats tries to read awstats.virtualhostname.conf as the config file.
#   If not found, awstats tries to read awstats.conf, and finally the full path passed to -config=
#   Note 1: Config files (awstats.virtualhostname.conf or awstats.conf) must be
#    in /etc/awstats, /usr/local/etc/awstats, /etc or same directory than
#    awstats.pl script file.

帮助末尾还给出了当前版本的特征库规模（实测 7.8 输出原文）：280 domains/countries、1150 robots、107 operating systems、212 browsers (592 with phone browsers database)、1303 search engines。

4.1 统计更新：-update 及配套参数

基础形态（增量解析，完整实测回显）：

sudo /usr/lib/cgi-bin/awstats.pl -config=www.example.com -update
# 实测回显：
# 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"...
# Phase 1 : First bypass old records, searching new record...
# Searching new records from beginning of log file...
# Phase 2 : Now process new records (Flush history on disk after 20000 hosts)...
# Jumped lines in file: 0
# Parsed lines in file: 322
#  Found 0 dropped records,
#  Found 0 comments,
#  Found 0 blank records,
#  Found 0 corrupted records,
#  Found 0 old records,
#  Found 322 new qualified records.

回显逐行含义：Phase 1 跳过已入库的旧行（增量游标）；Phase 2 解析新行并按 20000 host 一批刷盘；dropped=被过滤规则（Skip*/Only*）丢弃、corrupted=不符合 LogFormat 的坏行、qualified=有效入库行。排查统计问题先看这五个计数。

-LogFile=x：临时覆盖配置里的 LogFile（实测把错误日志喂进去，观察坏行行为）：

sudo /usr/lib/cgi-bin/awstats.pl -config=www.example.com -update -LogFile='/var/log/apache2/error.log' -showcorrupted
# 实测回显（节选）：
#  Found 0 dropped records,
#  Found 0 comments,
#  Found 0 blank records,
#  Found 22 corrupted records,
#  Found 0 old records,
#  Found 0 new qualified records.

22 行 Apache error.log 内容全部被判 corrupted 且不入库——但注意增量游标已推进，误灌错误日志后应删当月数据文件重灌正确日志（见第八节）。

配套调试参数（来自 -h 实测原文）：

参数	作用
-showsteps	每处理 8192 行输出一次基准信息（大日志观察进度）
-showcorrupted	逐条输出坏行及原因
-showdropped	逐条输出被过滤行及原因（验证 Skip* 规则时必开）
-showunknownorigin	输出无法解析的 referer
-showdirectorigin	输出直达访问的行
-updatefor=n	解析 n 行后停止（分段导入大日志）

-LogFile 时间占位符（写进配置更常用）：LogFile="/var/log/apache2/access.log.1" 配合 logrotate；占位符形态如 %YYYY-24-%MM-24-%DD-24 表示「当前时间减 24 小时」的日期，可写 LogFile="/var/log/nginx/access.log.%YYYY-24-%MM-24-%DD-24" 实现每天自动分析昨天的日志。

4.2 报表输出：-output 系列

主报表（输出主 HTML 页，不更新统计）：

/usr/lib/cgi-bin/awstats.pl -config=www.example.com -output -staticlinks > /tmp/report.html
grep -oE '<title>[^<]*</title>' /tmp/report.html
# 实测回显：
# <title>Statistics for www.example.com (2026-10) - main</title>

-staticlinks 让页内链接变成静态文件名（配合 buildstaticpages 用）；输出到 stdout，自行重定向落盘。

单报表输出：-output=x，x 的全部取值来自 -h 实测原文：alldomains、allhosts、lasthosts、unknownip、allemails、lastemails、allemailr、lastemailr、alllogins、lastlogins、allrobots、lastrobots、urldetail（支持 :filter 过滤）、urlentry、urlexit、osdetail、browserdetail、unknownbrowser、unknownos、refererse、refererpages、keyphrases、keywords、errors404、allextraX。实测一例：

/usr/lib/cgi-bin/awstats.pl -config=www.example.com -output=urldetail -staticlinks > /tmp/urls.html
grep -cE '<tr' /tmp/urls.html
# 实测回显：11

历史月份报表：-month/-year 只切换查看的数据文件，不回溯解析日志：

/usr/lib/cgi-bin/awstats.pl -config=www.example.com -output -staticlinks -month=09 -year=2026 | grep -oE '<title>[^<]*</title>'
# 实测回显：
# <title>Statistics for www.example.com (2026-09) - main</title>

（9 月数据文件不存在时页面数值为空——先确认 /var/lib/awstats/ 里有 awstats092026.*.txt。）语言用 -lang=cn 指定（覆盖配置 Lang）。

4.3 配置定位：-config 与 -configdir

-config=<站点标识> 的查找顺序（-h 原文）：/etc/awstats/awstats.<站点标识>.conf → /usr/local/etc/awstats/ → /etc/ → 主程序所在目录的 awstats.model.conf（8.0）或 awstats.conf（兜底配置）。找不到站点配置时报错并给出查找路径。-configdir=/path 显式指定配置目录（多实例隔离时用）。另有环境变量 AWSTATS_FORCE_CONFIG 可强制指定 config 值（CGI 反代场景常用）。

4.4 数据分库：-databasebreak=day

默认按月建数据文件；-databasebreak=day 改为按日分文件，便于按天回溯/清理（实测）：

sudo /usr/lib/cgi-bin/awstats.pl -config=www.example.com -update -databasebreak=day
# 实测回显（节选）：
#  Found 0 old records,
#  Found 322 new qualified records.
ls /var/lib/awstats/
# 实测回显：
# awstats10202630.www.example.com.txt   ← 20261030，按日文件

⚠️ 月度模式与按日模式各自维护独立数据文件与游标，切换模式后必须清空 DirData 重灌全部日志，否则两套文件并存、报表口径混乱（本文实测切换后月度/日度文件同时存在）。

4.5 -version 与 -debug

-version 输出版本（所有排障的第一步）；-debug=X 输出低于级别 X 的调试信息（会拖慢速度，仅排查用）。

五、awstats_buildstaticpages.pl：整站静态报表

把主程序支持的全部 -output 页面逐个生成为静态 HTML（-h 实测原文要点）：

perl /usr/share/awstats/tools/awstats_buildstaticpages.pl -h
# 实测回显（节选）：
# ----- awstats_buildstaticpages 1.2 (build 20140126) (c) Laurent Destailleur -----
# awstats_buildstaticpages allows you to launch AWStats with -staticlinks option
# to build all possible pages allowed by AWStats -output option.
#
# Usage:
# awstats_buildstaticpages.pl (awstats_options) [awstatsbuildstaticpages_options]
#   where awstats_options are any option known by AWStats
#    -config=configvalue is value for -config parameter (REQUIRED)
#    -update             option used to update statistics before to generate pages
#    -lang=LL            to output a HTML report in language LL (en,de,es,fr,...)
#    -month=MM           to output a HTML report for an old month=MM
#    -year=YYYY          to output a HTML report for an old year=YYYY
#   and awstatsbuildstaticpages_options can be
#    -awstatsprog=pathtoawstatspl AWStats software (awstats.pl) path
#    -dir=outputdir               Output directory for generated pages
#    -diricons=icondir            Relative path to use as icon dir in <img> links
#    -builddate=%YY%MM%DD         Used to add build date in built pages filenames
#    -staticlinksext=xxx          Build pages with .xxx extension (default .html)
#    -buildpdf[=pathtohtmldoc]    Build a PDF file after building HTML pages.
#                                 Output directory must contains icon directory
#                                 when this option is used (need 'htmldoc')

完整实测（先更新统计再出全套页面）：

sudo mkdir -p /var/www/html/awstats
sudo perl /usr/share/awstats/tools/awstats_buildstaticpages.pl \
     -config=www.example.com -update -lang=cn \
     -dir=/var/www/html/awstats -awstatsprog=/usr/lib/cgi-bin/awstats.pl
# 实测回显（节选）：
# Build main page: "/usr/lib/cgi-bin/awstats.pl" -config=www.example.com -staticlinks -lang=cn -output
# ...
# 23 files built.
# Main HTML page is 'awstats.www.example.com.html'.

ls /var/www/html/awstats/ | wc -l
# 实测回显：23

实用变体：-builddate=%YY%MM%DD 给文件名加日期戳（做历史快照归档）；-buildpdf 需要另装 htmldoc 工具；-staticlinksext=php 可换成 .php 扩展名。输出目录必须先存在，否则报 Error: Couldn't open log file ".../awstats.www.example.com.html" for writing : No such file or directory.（实测复现）。

安全形态建议：cron 每夜生成静态页到专用目录，Apache 只 Alias 这个目录、不开 /cgi-bin 通道——静态页无执行面。

六、多站批量更新：awstats_updateall.pl 与 Debian 脚本

awstats_updateall.pl（8.0 tar.gz 版自带；Debian 包不含，用 update.sh 替代）：

perl /usr/local/awstats/tools/awstats_updateall.pl -h
# 实测回显（节选）：
# ----- awstats_updateall 1.0 (build 20140126) (c) Laurent Destailleur -----
# awstats_updateall launches update process for all AWStats config files (except
# awstats.model.conf) found in a particular directory, so you can easily setup a
# cron/scheduler job. The scanned directory is by default /etc/awstats.
#
# Usage:  awstats_updateall.pl now [options]
# Where options are:
#   -awstatsprog=pathtoawstatspl
#   -configdir=directorytoscan
#   -excludeconf=conftoexclude[,conftoexclude2,...] (Note: awstats.model.conf is always excluded)

注意调用语法是子命令 now 开头。实测一次（扫 /etc/awstats 全部配置，排除 local8）：

perl /usr/local/awstats/tools/awstats_updateall.pl now \
     -awstatsprog=/usr/local/awstats/wwwroot/cgi-bin/awstats.pl -excludeconf=local8
# 实测回显（节选）：
# Running '"/usr/local/awstats/wwwroot/cgi-bin/awstats.pl" -update -config=default -configdir="/etc/awstats"' to update config default
# Error: SiteDomain parameter not defined in your config/domain file. You must edit it for using this version of AWStats.
# Setup ('/etc/awstats/awstats.conf' file, web server or permissions) may be wrong.
# Check config file, permissions and AWStats documentation (in 'docs' directory).
#
# Running '"/usr/local/awstats/wwwroot/cgi-bin/awstats.pl" -update -config=www.example.com -configdir="/etc/awstats"' to update config www.example.com
# Create/Update database for config "/etc/awstats/awstats.www.example.com.conf" by AWStats version 8.0 (build 20240604)
# ...

两点实录经验：其一，模板/兜底配置 awstats.conf 没填 SiteDomain 时每个站点都会先报一次 Error 再继续下一个（它把 awstats.conf 当 default config 处理），8.0 比 7.8 对空 SiteDomain 更严格——建议填上或用 -excludeconf=awstats 排除；其二，多版本共存时同一站点数据目录只能归一个版本使用（本次实录中 8.0 扫到 7.8 建立的站点数据后输出 Direct access to last remembered record has fallen on another record. 警告——增量游标错位信号，出现即应停手清库重灌）。

Debian 打包专用脚本（apt 安装的用户日常只需要知道它们存在）：

/usr/share/awstats/tools/update.sh：遍历 /etc/awstats/awstats.*.conf 逐个 -update（nice -10 降优先级），由包自带的 /etc/cron.d/awstats 每 10 分钟调用一次；
/usr/share/awstats/tools/buildstatic.sh：按 /etc/default/awstats 的 AWSTATS_LANG/AWSTATS_ENABLE_BUILDSTATICPAGES 生成静态报表到 /var/cache/awstats/，每天 03:10 由 cron 调用。

手工触发一次全站更新：

sudo /usr/share/awstats/tools/update.sh
# 实测行为：逐个处理 awstats.*.conf，出错的配置输出
# "Error while processing /etc/awstats/awstats.<site>.conf" 后继续

七、日志预处理链：logresolvemerge.pl

真实服务器日志是滚动的：access.log（当前）+ access.log.1（上一轮）+ access.log.2.gz（归档）。AWStats 增量游标要求日志按时间有序，多文件不能乱序逐个喂——官方预处理工具 logresolvemerge.pl 把多文件按时间戳归并排序成单一输出流，顺带可选 DNS 反解。-h 实测原文（节选）：

perl /usr/share/awstats/tools/logresolvemerge.pl -h
# 实测回显（节选）：
# ----- logresolvemerge 1.2 (build 20140126) (c) Laurent Destailleur -----
# logresolvemerge allows you to get one unique output log file, sorted on date,
# built from particular sources:
#  - It can read several input log files,
#  - It can read .gz/.bz2/.xz log files,
#  - It can also makes a fast reverse DNS lookup to replace
#    all IP addresses into host names in resulting log file.
# ...
# Usage:
#   logresolvemerge.pl [options] file
#   logresolvemerge.pl [options] file1 ... filen
#   logresolvemerge.pl [options] *.*
#   logresolvemerge.pl [options] addfolder=dirname
#   perl logresolvemerge.pl [options] *.* > newfile
# Options:
#   -dnslookup      make a reverse DNS lookup on IP adresses
#   -dnslookup=n    same with a n parallel threads instead of serial requests
#   -dnscache=file  make DNS lookup from cache file first before network lookup
#   -showsteps      print on stderr benchmark information every 8192 lines
#   -addfilenum     if used with several files, file number can be added in first
#   -addfilename    if used with several files, file name can be added in first
#                   field of output file. This can be used to add a cluster id
#                   when log files come from several load balanced computers.
#   -stoponfirsteof Stop processing when any logfile reaches end-of-file.
#   -ignoremissing  will not fail if a log file is missing

三文件合并实测（当前日志 + 轮转副本 + gzip 归档，输出行数核对）：

cp /var/log/apache2/access.log /var/log/apache2/access.log.1
gzip -c /var/log/apache2/access.log > /var/log/apache2/access.log.2.gz
perl /usr/share/awstats/tools/logresolvemerge.pl \
     /var/log/apache2/access.log /var/log/apache2/access.log.1 /var/log/apache2/access.log.2.gz | wc -l
# 实测回显：954

与主程序串联的两种形态：

形态一，管道直灌（LogFile 支持命令，结尾 | 声明）——写进配置后每次 -update 自动走预处理链：

LogFile="/usr/share/awstats/tools/logresolvemerge.pl /var/log/apache2/access.log* |"

形态二，命令行一次性覆盖（重建历史数据时用）：

sudo /usr/lib/cgi-bin/awstats.pl -config=www.example.com -update \
     -LogFile='/usr/share/awstats/tools/logresolvemerge.pl /var/log/apache2/access.log* |'

参数选型：负载均衡多机日志加 -addfilename（输出行首插入源文件名做集群标识）；重建历史时 DNS 反解用 -dnslookup=20（20 线程）+ -dnscache 复用旧缓存；轮转期间某归档可能缺失时加 -ignoremissing 防中断。

💡 技术拓展：多日志源的合并方案不止 logresolvemerge——shell 层 zcat a.gz b.log | sort -k4 也能按时间排序，但 sort 需要全量载入内存且要手工指定时间列；logresolvemerge 是流式归并、对 Web 日志格式感知、内置 DNS 反解与缓存，是 AWStats 官方推荐路径。GoAccess 用户等价的操作是逐文件跑 goaccess 再合并 HTML（见《GoAccess 安装指南》），本质差异是 GoAccess 无状态、AWStats 有增量游标。

八、注意事项

增量游标是状态：数据文件记录「解析到日志第几行」。追加式增长的当前日志重复跑 -update 安全；但轮转后 LogFile 变成新文件时游标错位——logrotate 场景要么用占位符路径逐日分析，要么每次全量重建（删数据文件 + logresolvemerge 全量灌）；
必须按时间顺序喂日志：-h 原文明确 "Be care to process log files in chronological order when updating statistics"，乱序导致入口/出口页与访问时长计算错误；
过滤参数只影响新解析行：改 Skip*/Only* 后要重灌（删当月数据文件）才回溯生效；
同月数据文件重复灌同一日志会重复计数：用 wc -l access.log 与 -update 回显的 Parsed lines 对照确认范围；
7.8 与 8.0 不要共享 DirData：数据文件格式与游标有版本差异，混用出现 "Direct access to last remembered record..." 警告即应清库（实测见第六节）。

九、常见问题

Q1：-update 后报表数字没变化？ 增量游标已到日志末尾（Parsed lines in file: 0 属正常）。确认日志确实有新行：wc -l 前后对比；确认 -config 与数据目录对应。

Q2：corrupted records 很多怎么办？ 先开 -showcorrupted 看坏行原文。常见原因：LogFormat 与真实格式不符（见《AWStats 配置参数详解（awstats.<site>.conf）》 5.1 节）、日志首部有非日志行（如 IIS 头，用 NbOfLinesForCorruptedLog 容忍）、预处理管道输出混入错误信息。

Q3：大日志跑一次 -update 要很久，能否中断续跑？ 可以：游标定期刷盘（-showsteps 可见每 8192 行的进度），中断后重跑自动续。分批导入用 -updatefor=1000000。

Q4：怎么把报表数据给非技术同事？ buildstaticpages 出静态站（第五节）+ cron 每夜刷新，比发 CGI 权限安全；要机器可读格式用 BuildHistoryFormat=xml 或 8.0 的 awdownloadcsv.pl。

Q5：邮件日志怎么统计？ 站点配置改 LogType=M、LogFile 指向 /var/log/mail.log，Postfix 日志先用 maillogconvert.pl 转换日期格式，报表栏位自动切换为发件人/收件人/邮件大小（ShowEMailSenders/ShowEMailReceivers 等栏目）。

十、参考链接

官方文档：Work Around FAQ（含增量/轮转专题）：https://awstats.sourceforge.io/docs/awstats_faq.html
logresolvemerge 官方说明：https://awstats.sourceforge.io/docs/awstats_tools.html
源码仓库（tools/ 目录）：https://github.com/eldy/AWStats/tree/main/tools
本专栏相关：《AWStats 介绍与选型指南》、《AWStats 裸机安装指南（apt + Apache CGI 集成实测）》、《AWStats 配置参数详解（awstats.<site>.conf）》、《GoAccess 安装指南》