Docker容器修改时区为东八区(UTC+8)的完整指南与避坑

在日常的容器化部署中，Docker 容器默认使用 UTC（协调世界时）作为标准时间。对于国内开发者而言，这通常会导致日志时间、数据库记录时间与实际时间相差 8 小时。本文将以 Python Gunicorn 应用为例，详细讲解如何将 Docker 容器的时区修改为东八区（UTC+8/Asia/Shanghai）。 ## 方案一：挂载宿主机时区文件（最快捷） 如果你不希望修改镜像，最简单且推荐的方法是在 `docker run` 命令中直接挂载宿主机的时区文件。 ```bash docker run -d \ --name fcp-archive-web-lib00 \ --restart unless-stopped \ -p 18080:18080 \ -v /etc/localtime:/etc/localtime:ro \ fcp-archive-web:1.0 \ gunicorn --bind 0.0.0.0:18080 wsgi:app ``` **原理说明**：Linux 系统通常读取 `/etc/localtime` 来确定时区。通过 `-v /etc/localtime:/etc/localtime:ro`（`ro` 表示只读），容器会自动同步宿主机的时区设置。这是目前兼容性最好的操作系统级修改方案。 --- ## 方案二：使用环境变量（需视情况而定） 有时我们会看到使用 `-e TZ=Asia/Shanghai` 的方案。但这**并不保证 100% 生效**。 环境变量能否生效，取决于容器的基础镜像（如 `alpine`, `debian`）是否安装了 `tzdata`（时区数据库）。如果镜像过于精简缺失了该组件，或者应用程序（如某些静态编译的 Go 程序）硬编码了时区逻辑，该环境变量将被忽略。 --- ## 方案三：在 Dockerfile 中配置（最佳实践） 为了保证镜像的**高可移植性**（即无论部署到哪台宿主机，时间都是正确的），最佳实践是在 `Dockerfile` 中显式安装 `tzdata` 并配置时区。 以 `python:3.11-slim` 为例，由于其基于 Debian，自带 `tzdata` 包源，我们可以这样优化： ```dockerfile # Base image FROM python:3.11-slim # Maintainer info LABEL maintainer="DP@lib00" # 安装 tzdata 确保时区数据库完整，并设置系统时区 RUN apt-get update && apt-get install -y tzdata && \ ln -sf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime && \ echo "Asia/Shanghai" > /etc/timezone && \ rm -rf /var/lib/apt/lists/* # 设置环境变量 ENV TZ=Asia/Shanghai # Set working directory for wiki.lib00.com project WORKDIR /app COPY requirements.txt /app/requirements.txt RUN pip install --no-cache-dir -r /app/requirements.txt COPY . /app CMD ["gunicorn", "--bind", "0.0.0.0:18080", "wsgi:app"] ``` 这种做法解除了对宿主机配置的依赖，避免了潜在的配置冲突。 --- ## 避坑指南：Python 代码层面的时区问题 即使系统层面的时区配置完全正确，代码层面的错误调用依然会导致时间错误。请务必检查你的 Python 业务代码： * ✅ **正确写法**：`datetime.datetime.now()`。这会读取系统当前时区（东八区）。 * ❌ **错误写法**：`datetime.datetime.utcnow()`。**无论系统时区如何配置，它永远返回 UTC 时间**。如果业务需要，请替换为 `datetime.datetime.now(datetime.timezone.utc)` 或者直接使用 `now()`。