Python zoneinfo 实战：按本地日期统计日志，处理跨日与夏令时

服务器日志用 UTC，业务日报却按北京时间结算，直接截取时间戳前十个字符，会把午夜附近的记录分错天。沿用日志筛选与统计的思路，这篇教程把时间处理单独拿出来：用 Python 标准库把事件转换到指定时区，再按当地日期计数。

面向初学者到中级读者。输入是每行一个带偏移量的 ISO 8601 时间戳，不是完整 Nginx 日志；真实项目先从自己的日志格式中导出时间字段。脚本拒绝没有时区的记录，避免结果随服务器设置改变。

1. 方法：先确定时刻，再取当地日期

解析 Z 或 +08:00 等显式偏移量。
用 astimezone(ZoneInfo(...)) 转到报表时区。
最后调用 .date()，累计每个日期的事件数。

datetime 官方文档区分带时区的 aware 对象和无时区的 naive 对象。转换使用 astimezone()；replace(tzinfo=...) 只改时区标记，不会换算钟面时间。

例如样例中的 2026-10-14T16:00:00Z 在上海已经是 10 月 15 日零点。固定加八小时也不适合作为跨地区方案；下面用命名时区，并单独验证纽约夏令时回拨。

2. 准备：检查 Python 和时区数据

需要 Python 3.11 或更新版本，该版本的 fromisoformat()支持这里使用的末尾 Z。无第三方 Python 依赖；示例在 Linux、Python 3.11.4 下验证。

在新建的可写目录中实验；后续命令始终留在这个目录。先检查 Asia/Shanghai 能否加载，再创建五行测试数据：

python3 --version
python3 -c "from zoneinfo import ZoneInfo; print(ZoneInfo('Asia/Shanghai'))"
mkdir zoneinfo-demo
cd zoneinfo-demo
cat > timestamps.txt <<'EOF'
2026-10-14T15:59:59Z
2026-10-14T16:00:00Z
2026-10-15T00:00:00+08:00
2026-10-15T23:59:59+08:00
2026-10-16T00:00:00+08:00
EOF

将下一节完整代码保存为 log_days.py。每行代表一条事件；第二、三行虽然是同一时刻，仍按两条记录计数，脚本不做去重。

3. 实现：读取成功后才输出 JSON

"""Count offset-aware ISO 8601 timestamps by local date. Python 3.11+."""
import argparse
from collections import Counter
from datetime import datetime
import json
from pathlib import Path
import sys
from zoneinfo import ZoneInfo, ZoneInfoNotFoundError


def parse_instant(text):
    value = datetime.fromisoformat(text.strip())
    if value.tzinfo is None or value.utcoffset() is None:
        raise ValueError("timestamp needs Z or an explicit UTC offset")
    return value


def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("input", type=Path, help="UTF-8 file; one timestamp per line")
    parser.add_argument("--zone", default="Asia/Shanghai", help="IANA reporting zone")
    args = parser.parse_args()
    try:
        zone = ZoneInfo(args.zone)
    except (ZoneInfoNotFoundError, ValueError):
        parser.error("unknown zone or missing timezone data: " + args.zone)

    counts = Counter()
    records = 0
    try:
        with args.input.open(encoding="utf-8-sig") as source:
            for line_no, line in enumerate(source, 1):
                try:
                    day = parse_instant(line).astimezone(zone).date().isoformat()
                except (ValueError, OverflowError) as exc:
                    print(f"ERROR: line {line_no}: {exc}", file=sys.stderr)
                    return 1
                counts[day] += 1
                records += 1
    except (OSError, UnicodeError) as exc:
        print(f"ERROR: cannot read input: {exc}", file=sys.stderr)
        return 1
    if records == 0:
        print("ERROR: input contains no timestamps", file=sys.stderr)
        return 1

    report = {
        "zone": args.zone,
        "records": records,
        "days": dict(sorted(counts.items())),
    }
    print(json.dumps(report, indent=2))
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

程序逐行读取输入，只在内存保存各日期的计数；内存随不同日期数量增长。空行、空文件、解析失败和无偏移量的时间戳都会失败；末尾正常的换行符不算额外空行。错误写到 stderr，JSON 只在全部输入校验通过后写到 stdout。

4. 运行：生成北京时间日报

python3 log_days.py --help
python3 log_days.py timestamps.txt --zone Asia/Shanghai

应得到：

{
  "zone": "Asia/Shanghai",
  "records": 5,
  "days": {
    "2026-10-14": 1,
    "2026-10-15": 3,
    "2026-10-16": 1
  }
}

--zone UTC 会按 UTC 日期重新分组，属于不同报表口径；实际接入定时器时应固定这个参数。需要固定解释器和工作目录，可参照Linux 定时任务环境排查。

5. 验证：跨日、主机时区和夏令时

检查午夜边界与运行环境

分别给进程设置两个不同的 TZ，不修改服务器时区配置。cmp 成功时没有输出，随后断言确认五条事件的日期分组：

TZ=UTC python3 log_days.py timestamps.txt --zone Asia/Shanghai > utc-report.json
TZ=Pacific/Honolulu python3 log_days.py timestamps.txt --zone Asia/Shanghai > hawaii-report.json
cmp utc-report.json hawaii-report.json
python3 - <<'PY'
import json
from pathlib import Path

report = json.loads(Path("utc-report.json").read_text())
assert report["records"] == 5
assert report["days"] == {"2026-10-14": 1, "2026-10-15": 3, "2026-10-16": 1}
print("OK: date boundaries and explicit zone")
PY

检查夏令时重复的一小时

下面使用 2024 年纽约回拨的两个历史时刻，避免依赖实验当天的日期：

python3 - <<'PY'
from zoneinfo import ZoneInfo
from log_days import parse_instant

zone = ZoneInfo("America/New_York")
for text in ("2024-11-03T05:30:00Z", "2024-11-03T06:30:00Z"):
    local = parse_instant(text).astimezone(zone)
    print(local.isoformat(), "fold=" + str(local.fold))
PY

预期：

2024-11-03T01:30:00-04:00 fold=0
2024-11-03T01:30:00-05:00 fold=1

这是两个相隔一小时的时刻，虽然当地钟面都显示 01:30。zoneinfo 官方文档说明，从其他时区转换时会设置相应的 fold。保留偏移量的输入能确定是哪一次；没有偏移量的 01:30 不能凭报表时区自动补齐含义。

检查坏行不会输出部分统计

printf '%s\n' '2026-10-14T16:00:00Z' '2026-10-15T00:00:00' > bad.txt
python3 log_days.py bad.txt --zone Asia/Shanghai > bad-report.json
printf 'exit=%s\n' "$?"
test ! -s bad-report.json && printf 'OK: no partial report\n'

预期 stderr 包含 ERROR: line 2: timestamp needs Z or an explicit UTC offset，随后看到 exit=1 和 OK: no partial report。重定向会创建一个空文件；不要把文件存在当作任务成功，必须检查退出码。重复实验会覆盖这几个演示报告文件，请只在刚创建的测试目录中运行。

6. 排障：常见错误与修复

现象	原因与具体处理
`timestamp needs Z or an explicit UTC offset`	源数据没有偏移量。先确认导出工具的时间含义，再让它输出带 `Z` 或实际偏移量的完整时间；不要无条件给历史记录追加 `Z`。
`unknown zone or missing timezone data`，退出 2	检查 `--zone` 拼写并运行下面的诊断；确认容器或主机提供 IANA 时区数据。
`cannot read input`，退出 1	检查路径、读取权限和 UTF-8 编码；编码转换可参考 Python CSV 编码排障，不要用忽略解码错误来丢弃字节。
`Invalid isoformat string`	导出的字段含日志前缀、时区缩写或空行。按源格式解析，再导出完整 ISO 时间；本文不是任意日期格式的自动识别器。

检查时区搜索路径和命名时区：

python3 -c 'from zoneinfo import TZPATH, ZoneInfo; print(TZPATH); print(ZoneInfo("Asia/Shanghai"))'

zoneinfo 的数据来源说明指出，时区数据来自系统数据库或项目可用的 tzdata 包。如果精简环境确实缺数据，可由环境维护者补齐系统数据，或在项目虚拟环境声明 tzdata 依赖；这不需要改服务器的默认时区，也无需全局安装 Python 包。

7. 总结

事件时间保留明确偏移量，报表使用明确的命名时区，再取当地日期，就能验证跨日分组。把午夜边界、夏令时回拨和坏行退出加入样例检查，可以在定时任务生成日报前发现时间含义不明确的数据。这个脚本只统计事件日期，不负责调度执行时刻，也不根据无时区字符串猜测来源。