报表数字打架，多数时候不是数据错，而是口径不同。这份文档先固定日志字段含义，再固定统计口径，最后按同一份口径导出报表，保证不同时间、不同人算出的结果可以对比。

一、适用范围

• 适用：从 CDN 或源站访问日志统计访问量、独立访客、错误率与热门内容；建立周期性报表；核对监控面板与报表的数值差异。
• 不适用：应用错误日志与堆栈分析，需在应用日志系统内完成；用户行为埋点与漏斗分析；日志采集 Agent 的部署与运维。

二、准备工作

项目	要求	检查方法
日志文件	按天归档，命名含日期，例如 access-2026-05-19.log	ls /srv/axis/logs | tail -n 5
字段说明	已确认每列含义与顺序，格式与采集端一致	对照采集配置，抽查 5 行
时间口径	统计统一按 UTC+08:00 或 UTC，二者只用其一	在报表头部标注时区
存储	保留期满足报表周期，归档目录可读	du -sh /srv/axis/logs/archive
工具	awk、sort、uniq、jq 可用	awk --version、jq --version

• 统计前先声明口径：是否包含静态资源请求、是否去重、是否剔除爬虫。
• 原始日志只读，统计结果另存，不在原文件上直接改写。

三、操作步骤

本节拆成三个子步骤，建议按顺序执行；每一步完成后先确认结果，再进入下一步。

3.1 日志字段说明

逐列确认日志格式与字段含义，标出可用与不可用的列，形成字段对照表。列顺序由采集端决定，换 CDN 或改采集配置后必须重新核对，沿用旧脚本会静默算错。详见 3.1 日志字段说明。

3.2 统计口径

固定访问量、独立访客、错误率的计算方式与过滤条件，写入口径说明，避免同一指标出现多个版本。口径包含三件事：过滤哪些请求、按什么维度去重、时间边界如何切分，缺一项就无法复现。详见 3.2 统计口径。

3.3 报表导出

按口径聚合出日、周维度的数据，导出 CSV 或 JSON，并做一次抽样核验。导出后先校验字段数与行数，再抽一条路径与原始日志对照，最后才分发给使用方。详见 3.3 报表导出。

字段、口径、报表三步是一次性的建流程工作，之后每期只需重跑脚本。口径变更时要同时更新说明文件、脚本版本与报表标注，让读表的人知道数字为什么和上期不同。

四、验证方法

1. 执行 awk '{print NF}' /srv/axis/logs/access-2026-05-19.log | sort -u，预期列数唯一；出现多个列数说明日志格式混用或存在多行记录，必须先修正再统计。
2. 执行 awk '{print $9}' /srv/axis/logs/access-2026-05-19.log | sort | uniq -c | sort -nr，预期状态码集中在 200 与 304，无大量空值；空值占比高说明列位置判断错了。
3. 用 grep -c 统计某路径的请求数，与报表中该路径的数值一致；差异只能来自过滤条件，不能来自统计时间窗口。
4. 用 jq 校验导出的报表：jq -e 'length > 0' /srv/axis/reports/daily.json，预期返回 true，且记录数与 CSV 数据行数相等。

五、常见问题

现象	可能原因	处理方式
报表总量与监控不符	统计口径不同或时间窗口错位	对齐过滤条件与时间边界后重算
独立访客数偏高	未对 IP 去重或包含爬虫	按 IP 去重，按 UA 过滤已知爬虫
状态码分布异常	日志混入了其他站点或测试流量	按 Host 字段过滤，剔除测试来源
某天数据为空	日志未轮转成功或采集中断	检查归档目录与采集任务日志
热门路径全是静态资源	未排除图片与脚本后缀	增加后缀过滤条件

六、回滚与注意事项

• 回滚：统计脚本与口径说明纳入版本管理，口径调整后保留旧版脚本与旧报表，可随时重算；不要用新口径覆盖历史报表。
• 注意：口径一旦对外发布就不要中途修改，若必须调整，在报表中标注生效日期并说明差异原因，否则使用方会误以为是数据异常。
• 注意：报表中不要包含完整 IP 与个人标识，必要时做脱敏或聚合处理，对外分发前再检查一遍字段。

上一页3.3 回归检查

下一页3.1 日志字段说明