FastAPIでAPIを作ると、重い処理はすぐに非同期ジョブへ逃がしたくなります。画像変換、レポート生成、外部API連携、メール配信など、Celeryは非常に便利です。ですが、本番で問題になるのは「動くかどうか」ではなく、失敗したときに壊れないか です。

• 同じジョブが二重実行される
• 一時障害で永遠にリトライしてキューが詰まる
• ワーカー再起動で中途半端な状態が残る
• 完了通知が先に飛んで実データがない

本記事では FastAPI + Celery + Redis 構成を前提に、再実行安全性（idempotency）と運用信頼性を上げる実装手順をまとめます。

1. まず守るべき設計原則

非同期基盤の事故は、ほぼ次の4原則で防げます。

1. At-least-once前提（同一タスク再実行は必ず起こる）
2. 副作用は冪等化（何回実行されても結果が壊れない）
3. 状態遷移を明示（PENDING/RUNNING/SUCCEEDED/FAILED）
4. 失敗を可観測化（リトライ回数・死活・滞留時間を計測）

この原則を外すと、障害時に「何が完了して何が未完了か」が追えなくなります。

2. 参照アーキテクチャ

• API: FastAPI
• Queue Broker: Redis
• Worker: Celery
• Result Store: PostgreSQL（業務状態）
• Monitoring: Flower + Prometheus + Sentry

ポイントは、業務上重要な状態はRedis結果バックエンドに依存しない ことです。Redisは一時的に使い、真実の状態はRDBに持たせます。

3. 実装の土台: タスク受付API

3.1 受け付け時に idempotency_key を必須化

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from sqlalchemy import select

app = FastAPI()

class JobRequest(BaseModel):
    idempotency_key: str
    report_type: str
    user_id: str

@app.post("/reports")
def create_report(req: JobRequest):
    existing = find_job_by_key(req.idempotency_key)
    if existing:
        return {"job_id": existing.id, "status": existing.status}

    job = create_job_record(
        idempotency_key=req.idempotency_key,
        status="PENDING",
        report_type=req.report_type,
        user_id=req.user_id,
    )
    generate_report.delay(job.id)
    return {"job_id": job.id, "status": "PENDING"}

これでクライアント再送が来てもジョブ多重作成を防げます。

3.2 DB制約で最終防衛線を張る

idempotency_key に UNIQUE 制約を入れ、アプリバグ時も二重作成を防ぎます。

1

ALTER TABLE async_jobs ADD CONSTRAINT uq_async_jobs_idempotency UNIQUE (idempotency_key);

4. Celeryタスクの実践設定

4.1 推奨設定

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

from celery import Celery

celery_app = Celery(
    "worker",
    broker="redis://redis:6379/0",
    backend="redis://redis:6379/1",
)

celery_app.conf.update(
    task_acks_late=True,
    task_reject_on_worker_lost=True,
    worker_prefetch_multiplier=1,
    task_time_limit=900,
    task_soft_time_limit=840,
    task_default_retry_delay=30,
    task_routes={"tasks.generate_report": {"queue": "reports"}},
)

• acks_late=True: 実行完了後にACK。途中クラッシュ時は再配信
• prefetch_multiplier=1: 取り込み過多を防ぎ、偏りを減らす
• time limit: ハング抑止

4.2 リトライは指数バックオフ + 上限

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

@celery_app.task(
    bind=True,
    autoretry_for=(TemporaryExternalError,),
    retry_backoff=True,
    retry_backoff_max=300,
    retry_jitter=True,
    max_retries=7,
)
def generate_report(self, job_id: str):
    ...

無制限リトライは障害増幅装置です。必ず上限を設定します。

5. 冪等タスクの実装パターン

5.1 状態遷移をトランザクションで管理

1
2
3
4
5
6
7
8

def start_job(job_id: str):
    with session.begin():
        job = session.get(Job, job_id, with_for_update=True)
        if job.status in ("RUNNING", "SUCCEEDED"):
            return False
        job.status = "RUNNING"
        job.started_at = utcnow()
    return True

FOR UPDATE を使い、同時実行で状態が競合しないようにします。

5.2 副作用前に“実行済みチェック”

外部API呼び出しやファイル生成前に、既に成果物が存在するか確認します。

• 既に同名レポートが生成済みならスキップ
• 外部通知は送信履歴テーブルで重複防止
• 決済や課金は必ず業務ID単位で一意化

5.3 完了処理はCompare-and-Setで確定

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

def complete_job(job_id: str, result_url: str):
    updated = session.execute(
        """
        UPDATE async_jobs
        SET status='SUCCEEDED', result_url=:url, finished_at=now()
        WHERE id=:id AND status='RUNNING'
        """,
        {"id": job_id, "url": result_url},
    )
    return updated.rowcount == 1

これで二重完了更新を防げます。

6. 失敗時の設計（DLQ相当の運用）

Celeryに“標準DLQ”はありませんが、実運用では次の形で代替できます。

• リトライ上限超過時に FAILED_PERMANENT へ遷移
• 失敗理由とスタックトレースをDB保存
• 再実行API（手動リカバリ）を提供
• 重大失敗はSentry + Pagerで通知

この構成で「黙って死ぬジョブ」をなくせます。

7. 監視設計（最低限）

メトリクス

• キュー滞留数（queue length）
• oldest message age
• タスク成功率 / 失敗率
• p95 実行時間
• リトライ回数分布

アラート例

• 滞留数が通常の3倍を10分継続
• 失敗率 > 5% が15分継続
• oldest message age > 20分
• worker heartbeat消失

「CPU高い」より「キューが古い」がユーザー影響に直結します。

8. デプロイ時の落とし穴

8.1 ローリング更新での重複実行

• acks_late + graceful shutdown を設定
• TERM 後にタスク完了待ち時間を確保
• 長時間ジョブは分割し、中断耐性を持たせる

8.2 スキーマ変更の順序

非同期基盤では、ワーカーとAPIが異なるバージョンで同居します。

安全な順序:

1. 先に後方互換なDB変更を適用
2. ワーカーを先に更新
3. APIを更新
4. 非互換削除は次リリースで

これを守らないと、古いタスクが新スキーマで失敗します。

9. ローカル・ステージングでの検証手順

1. 正常系: ジョブ作成→完了→結果取得
2. 再送系: 同一 idempotency_key で2回POST
3. 障害系: 外部APIタイムアウトを強制しリトライ確認
4. クラッシュ系: 実行中にworker再起動し再配信確認
5. 負荷系: 1000ジョブ投入で滞留時間と失敗率確認

この5ケースを自動テストに入れるだけで、運用品質は大幅に上がります。

10. 本番チェックリスト

• idempotency_key のUNIQUE制約あり
• 冪等な状態遷移実装（RUNNING/SUCCEEDED）
• リトライ上限 + バックオフ設定済み
• 手動再実行導線あり
• 失敗通知（Sentry/Pager）有効
• 滞留監視とアラート運用あり
• デプロイ手順に互換性ルール明記

まとめ

FastAPI + Celeryの本質は、非同期化そのものではなく 失敗しても壊れない設計 にあります。

• At-least-once を前提に設計する
• 冪等性をDB制約と状態遷移で担保する
• リトライと監視を“運用可能”な形で実装する
• デプロイ時のバージョン混在を想定する

ここまで作り込むと、ジョブ基盤は「たまに落ちるブラックボックス」から「予測可能に運用できるインフラ」へ変わります。まずは idempotency_key と状態遷移の明確化から始めるのがおすすめです。

Redis を使っていても、ピークトラフィック時に DB が突然落ちることがあります。原因の多くはキャッシュスタンピードです。人気キーの TTL が同時に切れると、大量リクエストが一斉に DB へ流れ、接続プールが飽和します。

「Redis を入れたのに遅い」「ピーク時だけ 500 が増える」という現象は、このパターンで説明できることが非常に多いです。

本記事では、キャッシュスタンピードを実運用で防ぐために、設計原則・実装パターン・監視方法を順に解説します。

1. キャッシュスタンピードとは何か

典型シナリオ:

1. 商品ランキング API が ranking:daily を Redis に 300 秒で保存
2. 300 秒後、人気時間帯にキー期限切れ
3. 同時に 1000 リクエストが miss
4. 1000 回 DB 集計が走ってレイテンシ急増

このとき Redis 自体は正常でも、背後の DB が壊れます。つまり、問題はキャッシュ障害ではなく「再生成の同時実行制御」です。

2. 防御の基本は三層構え

スタンピード対策は単一施策では不十分です。次の三層を組み合わせると安定します。

1. 同時再生成の抑制（singleflight / 分散ロック）
2. 期限切れの分散（TTL ジッター）
3. 期限切れ後の挙動制御（stale-while-revalidate）

3. パターン1: singleflight で同時再生成を止める

同一キーの miss が同時発生しても、1 リクエストだけ再生成し、他は待つ設計です。

TypeScript 例:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

const inflight = new Map<string, Promise<string>>();

async function getOrCompute(key: string, ttlSec: number, compute: () => Promise<string>) {
  const cached = await redis.get(key);
  if (cached) return cached;

  if (!inflight.has(key)) {
    const p = (async () => {
      try {
        const value = await compute();
        await redis.set(key, value, { EX: ttlSec });
        return value;
      } finally {
        inflight.delete(key);
      }
    })();
    inflight.set(key, p);
  }

  return await inflight.get(key)!;
}

単一プロセスではこれで十分ですが、複数インスタンス構成では分散ロックも必要です。

4. パターン2: 分散ロック（SET NX EX）

複数 Pod で同時 miss が起きる場合、Redis ロックで再生成担当を 1 つに制限します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

const lockKey = `lock:${key}`;
const lock = await redis.set(lockKey, instanceId, { NX: true, EX: 10 });

if (lock) {
  // ロック獲得: 再生成担当
  const value = await compute();
  await redis.set(key, value, { EX: ttlSec });
  await redis.del(lockKey);
  return value;
}

// ロック未獲得: 少し待って再取得
await sleep(40);
return await redis.get(key);

注意点は、ロック TTL が短すぎると再生成中に失効し、二重計算になることです。処理時間の p99 を見て余裕を持って設定してください。

5. パターン3: TTL ジッターで期限切れを分散

同系統キーが同時に切れると負荷波形が尖ります。TTL にランダム幅を持たせるだけでかなり改善します。

1
2
3
4
5

function ttlWithJitter(baseSec: number, jitterSec: number) {
  return baseSec + Math.floor(Math.random() * jitterSec);
}

await redis.set(key, value, { EX: ttlWithJitter(300, 90) });

300 秒固定より、300〜390 秒の分布にすると、同時失効が目に見えて減ります。

6. パターン4: stale-while-revalidate

高可用性が重要な API では、期限切れ直後でも古い値を短時間返しつつ、裏で更新する手法が有効です。

データ構造例:

1
2
3
4
5

{
  "value": {"items": [...]},
  "hardExpireAt": 1700000000,
  "softExpireAt": 1699999700
}

• now < softExpireAt: 新鮮データ
• softExpireAt <= now < hardExpireAt: 古い値を返しつつ非同期更新
• hardExpireAt <= now: 同期再生成

この方式はピーク帯の体感性能を維持しやすく、DB 保護にも強いです。

7. 失敗時フォールバックを設計する

キャッシュ再生成が失敗したときの動作を明確にしておくと、障害時の揺れが減ります。

推奨順序:

1. stale データがあれば返す
2. stale もなければ軽量な代替レスポンス
3. 最後に明示エラー（再試行可能）

「毎回 DB にフォールバック」は危険です。障害時に DB をさらに追い込むため、回路遮断（circuit breaker）とセットで設計すべきです。

8. 監視で見るべき指標

対策の効果はメトリクスで評価します。

• cache hit ratio
• key 単位の miss burst（短時間 miss 件数）
• 再生成処理の同時実行数
• DB クエリ QPS と接続待ち時間

Prometheus を使う場合、以下のようなカウンタを実装すると分析しやすいです。

• cache_requests_total{key_group, result="hit|miss|stale"}
• cache_rebuild_total{key_group, result="ok|error"}
• cache_lock_contention_total{key_group}

9. 導入手順（既存システム向け）

Step 1: 熱いキーを特定

アクセス上位 20 キーを抽出し、まずそこだけ対策します。

Step 2: singleflight + ジッター導入

実装コストが低く、効果が高い組み合わせです。

Step 3: 分散ロック導入

複数インスタンス環境で必須。ロック競合率も計測する。

Step 4: stale-while-revalidate 追加

高トラフィック API へ段階適用。UX と DB 安定性が両立しやすい。

10. よくある失敗例

失敗1: TTL を長くしてごまかす

データ鮮度要件を満たせず、別の問題が出ます。期限延長は応急処置に留める。

失敗2: 分散ロックだけで安心する

ロックが取れない側の待機戦略がないと、スパイクは残ります。待機・再取得・stale 応答まで設計が必要です。

失敗3: miss 率しか見ない

miss が少なくても、特定キーへの burst が強ければ障害は起きます。キーグループ単位で観測してください。

11. 実運用チェックリスト

• 熱いキーを定義し、キーグループで計測している
• singleflight もしくは同等の同時実行制御がある
• TTL にジッターを導入している
• 分散ロックの TTL が処理時間 p99 を上回る
• stale-while-revalidate の返却条件が明確
• 障害時フォールバック（回路遮断含む）がある

まとめ

Redis キャッシュスタンピード対策は、キャッシュを置くことではなく「miss 後の世界を設計する」ことです。

• 同時再生成を止める
• 失効タイミングを分散する
• 期限切れ直後の応答を制御する

この3点を実装すれば、ピーク時の DB 崩壊リスクは大幅に下げられます。まずはアクセス上位キーから段階導入し、メトリクスで効果を確認してください。仕組みとして回り始めると、トラフィック増加に対する耐性が目に見えて改善します。

12. キャッシュキー設計の実務ポイント

スタンピード対策では、アルゴリズム以前にキー設計が重要です。user:123:timeline のような粒度が粗すぎるキーは、人気ユーザーにアクセスが集中したとき一気にホットスポットになります。可能なら page や segment を分割し、巨大レスポンスを小さく分けると miss 時の再生成コストを抑えられます。

また、キーの命名規約をチームで統一しておくと観測しやすくなります。service:domain:resource:variant 形式で揃えれば、メトリクス集計時に key_group を自動分類しやすく、どの領域で burst が起きているかを短時間で判断できます。運用性を上げるキー設計は、性能改善と同じくらい価値があります。