容器里的时区为什么总差 8 小时：从 TZ、/etc/localtime 到 Docker 日志时间

容器里的时间，为什么总是比宿主机「早」8 小时？这个坑几乎每个运维和开发都踩过：宿主机 date 显示 2026-11-11 10:30:00 CST，容器里 date 却输出 2026-11-11 02:30:00 UTC。本文把容器时区的来龙去脉讲清楚。

一、容器默认不带时区

绝大多数基础镜像（debian、ubuntu、python:slim、node:alpine 等）出于「最小化体积」的考虑，只内置了 UTC 时区，/etc/localtime 要么是空文件，要么指向 /usr/share/zoneinfo/UTC，/etc/timezone 根本不存在。容器启动时拿到的就是这个默认配置，所以 date 输出 UTC。

换句话说，容器「没有时区」不是 bug，是基础镜像的设计取舍——时区本来就是跟地域绑定的本地化配置，镜像作者没法替你决定你在中国还是美国。

二、决定时区的三个来源

进程判断当前时区的顺序如下：

优先级规则一句话：先看 TZ，没设置再读 /etc/localtime。注意 /etc/timezone 不是实时生效的，它只在系统初始化时被用来生成 /etc/localtime，所以直接改这个文件是没用的。

三、Docker 里设置时区的三种做法

1. 运行时挂载宿主机时区（改完即生效，不改镜像）

   docker run -d -v /etc/localtime:/etc/localtime:ro --name app nginx

适合临时验证或不想重建镜像的场景。注意只挂 localtime 时，部分应用仍会去读 /etc/timezone，此时可以一并挂上：-v /etc/timezone:/etc/timezone:ro。

1. 通过环境变量指定（最省事，但要确认镜像里有 tzdata）

   docker run -d -e TZ=Asia/Shanghai --name app nginx

TZ 优先级最高，覆盖 /etc/localtime。坑：如果镜像没装 tzdata，/usr/share/zoneinfo/ 目录不存在，设置 TZ 也不会生效——这是「环境变量没反应」的最常见原因。

1. 构建镜像时写进去（一劳永逸，推荐正式服务用这个）

   ARG TZ=Asia/Shanghai
   RUN apt-get update && apt-get install -y tzdata \
       && ln -snf /usr/share/zoneinfo/$TZ /etc/localtime \
       && echo $TZ > /etc/timezone

其中 ln -snf 的 -n 很关键：/etc/localtime 本身可能就是一个符号链接，不加 -n 会把链接替换成普通文件，后续更新时区会失效。

四、日志时间为什么和宿主机对不上

应用写日志用的是系统本地时间，容器是 UTC，日志自然就「早了 8 小时」。更麻烦的是，日志聚合链路上的每一环都可能再转一次时区：采集端打时间戳、传输到 ES/Loki、展示层渲染。所以同一个事件，在不同页面上显示的时间可能不一样——排查的第一步永远是先确认链路每一段用的时区，而不是急着改配置。

分布式系统更稳的做法是：存储和传输一律用 UTC，只在展示层转时区。这样无论容器、宿主机还是数据库，写进去的时间口径都是一致的。

五、实用技巧与注意事项

• 排查顺序：容器内 date 看是 UTC 还是 CST → cat /etc/timezone → docker inspect <容器> | grep -i tz 看 Config.Env，三步就能定位是环境变量问题还是镜像缺 tzdata。
• 不要在容器里改宿主机文件：容器里 /etc/localtime 只影响自己；反过来，也不要指望改宿主机配置能影响到所有容器。
• 时区不一致的代价不止是日志难看：定时任务（cron）、证书时间校验、日志聚合、跨机房对账都会错位，越早统一越好。
• Kubernetes 里没有「Pod 时区」这个概念：Pod 直接用节点的 /etc/localtime，需要时区就用 env: [{name: TZ, value: Asia/Shanghai}] 指定。