极客工场

Appearance

共 2,307 字预计阅读约 8 分钟

容器时区不对速查：日志时间差 8 小时的分层排查 ​

更新时间：2026-10-24。FAQ 速查页，面向「容器里 date 显示 UTC、应用日志时间比宿主机慢 8 小时、定时任务总在凌晨跑偏」的同学。容器时区不对的本质一句话：镜像不继承宿主机时区——容器看到的时区只由镜像里的时区数据（/usr/share/zoneinfo）、/etc/localtime 文件、TZ 环境变量三者决定，基础镜像默认全是 UTC，你不在构建或运行期显式干预，容器里就永远是伦敦时间。病灶收敛在六根轴上。容器内时间相关的另一坑（信号与生命周期）看 容器收不到 SIGTERM 速查；字符集乱码问题看 docker 编码与 locale 速查。

本文要回答的问题 ​

  • 容器里的时区到底由什么决定，为什么和宿主机不一样？
  • 挂 /etc/localtime 和设 TZ 环境变量，两种解法差在哪？
  • 为什么设了 TZ=Asia/Shanghai 应用还是 UTC——tzdata 是什么角色？
  • alpine、distroless 这类精简镜像为什么改时区特别麻烦？
  • docker logs 的时间戳和容器内应用打的时间为什么会对不上？

一、报错原文与典型现象 ​

时区问题的指纹是「差固定的整数小时」——中国区场景几乎全是 8 小时（路径以 /proj/demo 占位，镜像源用 registry.example.com 占位）：

bash
# 指纹一：容器内 date 是 UTC，宿主机是 CST
$ docker exec app date
Fri Oct 24 02:15:03 UTC 2026
$ date
Fri Oct 24 10:15:03 CST 2026
bash
# 指纹二：应用日志时间戳慢 8 小时
$ docker logs app --tail 3
2026-10-24 02:15:01 INFO  request handled
2026-10-24 02:15:02 INFO  request handled    # 实际是上午 10 点发生的事
bash
# 指纹三：设了 TZ 但不生效 —— 镜像里根本没有时区数据
$ docker exec -e TZ=Asia/Shanghai app date
Fri Oct 24 02:15:03 UTC 2026        # 还是 UTC，tzdata 缺失

读现象抓三条判据：先 docker exec <容器> date 确认容器内时区，再对比宿主机——差 8 小时就是默认 UTC 没干预；设 TZ 不生效先查镜像里有没有 /usr/share/zoneinfo/Asia/Shanghai 这个文件，没有数据设什么变量都白搭；docker logs 的时间戳走 dockerd 的时钟（宿主机时区），应用自己打的时间走容器内时区——两者来源不同，对不上是两套时钟各走各的。

二、病因处置速查表 ​

报错现象 / 场景可能原因快速验证处置
容器 date 是 UTC镜像默认 UTC 未干预docker exec app date挂 localtime 或设 TZ
设 TZ 不生效镜像缺 tzdata 数据查 /usr/share/zoneinfo装 tzdata 或挂 zoneinfo
alpine 改时区无效精简镜像无 tzdata 包apk list 看 tzdataapk add tzdata 后设 TZ
distroless 无时区镜像根本不带时区文件ls /usr/share/zoneinfo构建期拷贝时区数据
日志慢 8 小时应用用容器内时区打时间对比 docker logs 时间修容器内时区统一
cron 定时跑偏容器内 crond 按 UTC 触发看任务触发时间差修时区或任务改用 UTC
JVM 仍用 UTCJVM 读 user.timezone 或 TZ看应用启动参数设 TZ 或 -Duser.timezone
挂载后时间仍错挂了 localtime 缺 zoneinfo查符号链接目标localtime 与 zoneinfo 都挂

三、排查决策图 ​

这张图是标准排查路线：红是时区错乱现象与根因，蓝是排查动作，绿是验证通过，橙是修复，紫是防复发沉淀。

engineering/docker/ts-docker-timezone-wrong.md D2 示意图

读这张图抓住关键一步：时区修复有两件套——「数据」和「指向」缺一不可：数据是 /usr/share/zoneinfo 下的时区文件，指向是 /etc/localtime 或 TZ。只设 TZ 而镜像没数据，等于指针指向空文件；只挂 localtime 而应用读 TZ 变量，也可能不生效。两件套齐了才稳。

四、逐条排查展开 ​

解法一：挂载宿主机时区文件，改运行不改镜像。 最直接的做法，把宿主机的时区配置灌进容器：

bash
docker run -d --name app \
  -v /etc/localtime:/etc/localtime:ro \
  registry.example.com/team/app:1.1

/etc/localtime 在多数发行版是指向 /usr/share/zoneinfo/Asia/Shanghai 的符号链接，只挂它而容器里没有 zoneinfo 数据时链接会悬空——稳妥做法是连数据目录一起挂：-v /usr/share/zoneinfo:/usr/share/zoneinfo:ro。优点是镜像不动、随时可改；缺点是容器和宿主机时区强绑定，换宿主机或宿主机改时区，容器跟着变。

解法二：TZ 环境变量，写进镜像或编排。 设 TZ=Asia/Shanghai，glibc 会拿这个名字去 /usr/share/zoneinfo 下找同名文件。compose 写法：

yaml
services:
  app:
    image: registry.example.com/team/app:1.1
    environment:
      TZ: Asia/Shanghai

前提是镜像里有时区数据——debian 系 apt-get install -y tzdata，alpine 是 apk add tzdata，装完 /usr/share/zoneinfo 才有 Asia/Shanghai 文件。这就是「设了 TZ 不生效」的第一嫌疑：变量有了、数据没有。

精简镜像是时区问题的重灾区。 alpine 默认不带 tzdata（镜像里连 /usr/share/zoneinfo 目录都不存在）；distroless 更绝，连包管理器都没有，只能在多阶段构建里从完整镜像拷贝：

dockerfile
FROM registry.example.com/base/debian:12 AS base
# distroless 阶段
FROM gcr.io/distroless/base-debian12
COPY --from=base /usr/share/zoneinfo /usr/share/zoneinfo
ENV TZ=Asia/Shanghai

应用层时区可能盖过系统时区。 JVM 读 -Duser.timezone 和 TZ，不显式设时有的发行版 JVM 默认 UTC；Node 读 TZ；Python 的 time 模块走系统时区但 pytz/zoneinfo 自己算。排查时别只验 date，要验「应用实际打出来的时间」——date 对了而应用日志还错，就是应用层配置在压系统时区。

docker logs 与应用日志是两套时钟。 --timestamps 的时间由 dockerd（宿主机时区）在收日志时打上；应用日志正文里的时间是容器内时区。修完容器时区后两者自然对齐；只对齐一半，说明你只改了其中一套。

挂载方案与 TZ 方案怎么选，一张账算清。 挂载 localtime 的好处是镜像零改动、存量容器直接生效，坏处是把容器绑死在宿主机上——同一镜像拖到另一台不同时区的机器，行为跟着变，这在多地域部署里是个坑。TZ 变量的好处是时区写进编排文件、随镜像和配置走、可移植性好，坏处是依赖镜像里装了 tzdata。团队的通用答案：基础镜像里装好 tzdata，编排模板默认写 TZ，挂载方案只留给「不能改镜像也不能改编排」的存量服务。

JDK 老版本还有一个独立坑。 JDK 8 早期版本的 JVM 启动时读 /etc/localtime 但会缓存结果，运行期改宿主机时区不生效，必须重启 JVM；且部分发行版打包的 JRE 精简了时区数据，需要挂 zoneinfo 或升级 JDK。Java 应用「容器 date 对了、日志还是慢 8 小时」，九成是 JVM 层的 user.timezone 或缓存问题，处置是启动参数显式加 -Duser.timezone=Asia/Shanghai，与系统时区双保险。

五、规范做法与预防 ​

  • 时区配置进基础镜像：tzdata 安装与 TZ 默认值在团队基础镜像里一次解决，业务镜像不重复踩坑。
  • compose 模板默认带 TZ：新建服务漏配时区由模板兜底。
  • 优先 TZ 变量、挂载做兜底：TZ 可移植性好（不依赖宿主机文件布局），挂载方案用于不能改镜像的场景。
  • 定时任务一律声明时区假设：crond 类任务在文档里写明「按容器内时区触发」，并验证时区后再上线。
  • 日志时间戳规范统一：应用日志与编排层时间戳同一时区，跨时区团队统一 UTC 并在展示层转换。
  • 发版 checklist 加一条 date 校验：新服务上线跑一次 docker exec <容器> date，慢 8 小时即拦截。

这一篇在知识体系里的位置 ​

本篇是 docker 排错速查簇的运行环境篇，定位「容器内外时间对不上」：容器内字符集与 locale 问题看 docker 编码与 locale 速查；容器信号与优雅退出看 容器收不到 SIGTERM 速查；容器磁盘写满看 docker 占满磁盘速查；镜像版本与运行环境不匹配看 docker 版本不匹配速查；容器路径与文件找不到看 docker 路径不存在速查。时区数据、指向配置、应用层校验，是容器时间正确的三层保障。

一句话总结 ​

容器时区不对的规律是「镜像不继承宿主机时区，默认全是 UTC」：日志差 8 小时先 docker exec 看容器 date，修复两条路——挂 /etc/localtime（连 zoneinfo 一起挂防悬空链接）或设 TZ=Asia/Shanghai（前提是镜像装了 tzdata，alpine 与 distroless 默认没有）；date 对了应用还错就查 JVM/框架的时区配置。排查的通式是先验系统时区、再验时区数据、最后验应用实际输出。治本靠 tzdata 与 TZ 进基础镜像、compose 模板默认时区、定时任务声明时区假设、发版 checklist 校验 date，让「慢 8 小时」在上线前被拦截。