· OpenWorks · it-trends

本番環境での『想定外のタイムゾーン問題』──UTCで統一しても現場では起きる理由

タイムゾーン 本番環境 設計判断 バッチ処理 日付処理

データベースはUTC、でも現場からのクレームは止まらない

システムをリリースして数週間経つと、ユーザーから「昨日の夜間バッチの実行時刻がおかしい」「領収書の日付がずれている」といった報告が入ります。開発チームは確認します。「データベースはUTC統一だし、タイムゾーン変換ライブラリも入れてある。何が問題なんだ」と。

こういう現場の判断は、実は珍しくありません。むしろ、タイムゾーン問題は「一度解決したと思ってから、別の層で再発する」という性質を持っています。

理由は単純です。アプリケーション層で「どこのタイムゾーンで時刻を扱うのか」という判断が、層ごと・機能ごとに分散しているからです。

層ごとに異なる「正解」が共存する

実装の現場では、こんな構成になりがちです。

  • データベース層: 全てUTC保存（正しい判断）
  • API層: ユーザーのタイムゾーン情報を取得して、レスポンスJSONにローカル時刻で返す（これも正しい）
  • バッチ処理: 「毎日午前2時に実行」という要件を、サーバー時刻（多くの場合UTC）で実装（ここで齟齬が生まれる）
  • フロントエンド: ブラウザのローカルタイムゾーンで表示（ユーザー側の環境に依存）
  • ログシステム: サーバーログはUTC、アプリケーションログはローカル時刻（調査時に混乱）

各層で「その層では正しい判断」をしているのに、全体では一貫性が欠ける状態です。

現場で起きやすい3つの失敗パターン

1. バッチ実行スケジュールの「日本時間での日付」が反映されない

顧客から「毎日夜間12時に集計を走らせてほしい」という要件が来ます。これは「日本時間の夜間12時」を意味します。しかし実装時に「UTC時刻で何時に実行するか」への変換が曖昧なままコードに落とします。

# 実装者の思考: 「毎日0時に実行」
0 0 * * * /path/to/batch.sh

# でも顧客は「日本時間で夜間12時」を期待している
# つまり UTC時間では 15:00（夏時間）または 15:00（冬時間）のはず

時間が経つと、「昨日の集計結果の日付がずれている」という報告が入ります。原因は、バッチが実行された瞬間のサーバーのタイムゾーン設定と、要件の「日本時間」の解釈がズレているのです。

2. ユーザー入力の日付範囲検索が予期しない結果を返す

ユーザーが「2025年1月15日の取引」を検索します。フロントエンドはこれをローカルタイムゾーンの日付として解釈し、ISO 8601形式（2025-01-15）で送信します。

バックエンドは、これを「2025-01-15 00:00:00 UTC」として解釈し、データベースで検索します。ところが、データベースに保存されているのは「ユーザーの行動時刻をUTCに変換したもの」です。日本のユーザーが「2025年1月15日」に行った操作は、実際にはUTC時刻では「2025年1月14日の15:00以降」に記録されています。

結果として、ユーザーが期待する日付の取引が検索結果に含まれません。

3. 監視アラートの時刻判定がズレる

「同じユーザーから1分以内に複数のログイン試行があったらアラート」という不正検知ルールを実装したとします。

このルール内で時刻比較をするとき、ログのタイムスタンプがUTCなのに、アラート判定ロジックがローカルタイムゾーンで時刻を操作していると、比較結果が不安定になります。特に日付が変わる時間帯（日本時間の深夜、UTC時間では午前中）で問題が顕在化しやすいです。

実装時に取るべき判断

ルール1: 保存はUTC、扱うのは明示的に

データベースにはUTCで保存する。これは変わりません。ただし、コード内で時刻を操作するときは、常にタイムゾーンを明示的に指定することが重要です。

from datetime import datetime, timezone
from zoneinfo import ZoneInfo

# ❌ 危険: タイムゾーン情報が不明
user_date = datetime.fromisoformat("2025-01-15")

# ✓ 安全: タイムゾーンを明示
user_date = datetime.fromisoformat("2025-01-15").replace(
    tzinfo=ZoneInfo("Asia/Tokyo")
)
utc_datetime = user_date.astimezone(timezone.utc)

ルール2: バッチ実行スケジュールは「ユーザーのタイムゾーン基準」で設計書に書く

cronやスケジューラーの設定値だけでなく、「この処理は日本時間の何時に実行するのか」を設計書に明記します。そのうえで、サーバーのタイムゾーン設定とは独立して、コード内で時刻変換を行います。

# スケジューラーは UTC時刻で実行
# ただし、処理の意図は「日本時間の夜間12時」

def nightly_aggregation():
    jst = ZoneInfo("Asia/Tokyo")
    now_jst = datetime.now(jst)
    
    # 日本時間の日付で集計対象を判定
    aggregation_date = now_jst.date()
    # ...

ルール3: ユーザー入力の日付は「その日の範囲全体」として扱う

ユーザーが「2025年1月15日」を入力したときは、「日本時間の2025年1月15日 00:00:00から23:59:59まで」と解釈します。これをUTC範囲に変換してから検索します。

search_date_jst = datetime.fromisoformat("2025-01-15").replace(
    tzinfo=ZoneInfo("Asia/Tokyo")
)

# その日の開始と終了（日本時間）
start_jst = search_date_jst.replace(hour=0, minute=0, second=0, microsecond=0)
end_jst = search_date_jst.replace(hour=23, minute=59, second=59, microsecond=999999)

# UTC に変換
start_utc = start_jst.astimezone(timezone.utc)
end_utc = end_jst.astimezone(timezone.utc)

# データベースクエリ
results = db.query(Event).filter(
    Event.timestamp >= start_utc,
    Event.timestamp <= end_utc
)

運用段階で気をつけること

本番環境に上がった後も、タイムゾーン問題は「ログの解釈」の段階で再発します。

  • サーバーログ: UTC時刻で記録
  • アプリケーションログ: ローカルタイムゾーンで記録
  • データベースのタイムスタンプ: UTC

障害調査時に、これら3つのログを並べて見ると、「同じ出来事なのに時刻が違う」という混乱が生じます。対策として、ログには必ずタイムゾーン情報を含めるか、全て統一したタイムゾーンで出力することが重要です。

# ❌ 曖昧
2025-01-15 23:45:30 User login

# ✓ 明確
2025-01-15T23:45:30+09:00 User login
# または
2025-01-15T14:45:30Z User login (UTC)

中小規模チームが現実的に取れるアクション

大規模なシステムで全層を一度に修正するのは難しいです。現実的には、以下の優先順位で対応します。

  1. 設計書に「タイムゾーン方針」を明記する（今すぐ）
  2. 新規機能から実装ルールを適用する（次のスプリント）
  3. 既存機能のうち、ユーザーからのクレームが多い部分から修正する（段階的）
  4. ログ出力の統一（並行して）

急いで全て直そうとすると、かえってバグが増えます。むしろ、チーム内で「タイムゾーン問題の起こりやすいパターン」を共有し、コードレビュー時に指摘できる体制を作ることが先です。

タイムゾーン問題は「一度解決したら終わり」ではなく、システムの複雑さが増すにつれて、新しい形で再発する課題です。だからこそ、実装時の小さな判断の積み重ねが、後々の保守性を大きく左右します。