Tortoise-ORM 时区配置的最佳实践

背景介绍

Tortoise-ORM 是一个优秀的 Python 异步 ORM 框架，广泛应用于 FastAPI 等异步 Web 开发中。在实际开发过程中，正确处理数据库时间戳的时区问题至关重要，特别是对于跨时区的应用场景。

时区配置问题分析

许多开发者在使用 Tortoise-ORM 连接 MySQL 等数据库时，会遇到时间戳比实际时间慢8小时的问题。这通常是由于数据库连接的时区设置不正确导致的。以中国开发者为例，东八区(Asia/Shanghai)的时间如果不正确配置，就会出现这种时间偏差。

解决方案演进

初始尝试

开发者最初尝试通过在数据库连接字符串中添加时区参数来解决：

mysql://root:123456@192.100.30.102:3306/energy_dispatch?charset=utf8&timezone=Asia/Shanghai

但这种方法会抛出异常，因为 asyncmy 驱动不支持直接在连接字符串中设置 timezone 参数。

深入源码

通过分析 Tortoise-ORM 源码，发现可以在初始化时直接传递 use_tz 和 timezone 参数：

await Tortoise.init(
    db_url=db_url,
    modules=modules,
    use_tz=False,
    timezone="Asia/Shanghai",
)

配置方式对比

Tortoise-ORM 提供了三种配置方式：

1. db_url：简单的连接字符串方式
2. config：详细的字典配置方式
3. config_file：配置文件方式

这三种方式是互斥的，只能选择其中一种使用。对于需要设置时区的场景，推荐使用 config 字典方式，因为它可以完整地支持所有配置参数。

最佳实践

使用 RegisterTortoise 配置时区

在 FastAPI 应用中，可以通过以下方式正确配置时区：

@asynccontextmanager
async def lifespan(app: FastAPI):
    async with RegisterTortoise(
        app,
        config={
            "connections": {"default": DB_URL},
            "apps": {"models": {"models": ["models"]}},
            "use_tz": True,
            "timezone": "Asia/Shanghai",
            "generate_schemas": True,
        },
    ):
        yield

参数说明

• use_tz：是否使用时区感知时间戳

  • True：存储 UTC 时间，应用层负责时区转换
  • False：使用本地时间，不进行时区转换

• timezone：指定数据库使用的时区

  • 例如 "Asia/Shanghai"、"UTC" 等

技术原理

Tortoise-ORM 的时区处理依赖于 Python 的 datetime 模块和 pytz 库。当 use_tz=True 时，所有时间戳都会转换为 UTC 时间存储，并在读取时根据当前时区转换回本地时间。当 use_tz=False 时，则直接使用本地时间，不进行任何转换。

对于中国开发者，典型的配置是：

use_tz=False
timezone="Asia/Shanghai"

这样可以确保数据库中的时间戳与本地时间一致，无需额外转换。

总结

正确处理时区问题是数据库应用开发中的重要环节。通过 Tortoise-ORM 的灵活配置，开发者可以根据实际需求选择最适合的时区处理方式。对于大多数国内应用场景，直接使用本地时间(Asia/Shanghai)并禁用时区转换(use_tz=False)是最简单可靠的解决方案。