待たせるAPIをやめる — メッセージキューとRabbitMQ

メッセージキューとRabbitMQ。順番に並んだメッセージの封筒と処理装置、受付の画面。

重い処理を要求の中でやると、利用者が待たされます。あとでやる仕組みに組み替えて、応答をすぐ返せるようにします。

前回: OAuthはログインの仕組みではない — 認可とOIDC 作業場所はVMの中(Ubuntu)です。ここまでで作った ~/server(Express + MySQL + Redis)と、Docker Composeの書き方|複数コンテナをまとめて起動する をそのまま使います。

前回は「遅いものを測って、速くする」をやりました。索引を張れば直る遅さは、それで直ります。

ですが、どうやっても速くならない処理があります。

画像を変換する。PDFを作る。メールを送る。外部のAPIを呼ぶ。

これらは5秒かかるものは、何をしても5秒かかります。 索引もキャッシュも効きません。そして、それをリクエストの中でやっている限り、利用者はその5秒を画面の前で待ちます。

この回でやるのは、速くすることではありません。

「いまやる」を「あとでやる」に変えます。

受け取ったら即座に返す。処理は別のプロセスがやる。 その間に立つのがメッセージキューです。

そして、この記事の本番は導入ではありません。「あとでやる」に変えた瞬間に生まれる新しい事故——同じ処理が2回走る——のほうです。

対象レベル: 初級〜中級 / 区分: 必修

目次

この記事でわかること

  • 速くできない処理があること。そこで打つ手は「速くする」ではなく「待たせない」だということ
  • キューは Redis でもできること。それでも専用のものがあるのは、失敗したときの面倒を見てくれるから
  • ack を返さないと、同じメッセージがもう一度配られること。つまり同じ処理が2回走りうること
  • 「送った」は「届いた」ではないこと。キューを durable にしただけでは、メッセージは消えること
  • 監視すべき数値は「キューの長さ」1つだということ。溜まり続けたら、いつか送る側が止まること
  • 個人のサービスなら、たいていキューは要らないこと

この記事でやること

  1. 5秒かかるAPIを実際に作って、curl で測って、待たされることを確かめる
  2. RabbitMQ を Docker Compose で立てる(管理画面は外に出しません)
  3. producer(送る側)と consumer(処理する側)を書いて、APIを202で即返しに変える
  4. worker を止めてメッセージを溜めて、管理画面で数が増えるのを見る
  5. 処理の途中で worker を殺して、同じ仕事が2回走ることを目で見て、冪等に直す
  6. 後片づけする(RabbitMQ はメモリを食います)

先に知る言葉

この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。

言葉意味
メッセージキュー「あとでやる仕事」を順番に並べておく置き場。 入れる人と、取り出してやる人が別々に動く
メッセージキューに1件入れる、仕事の依頼書。 実体はただのバイト列。中身は自分で決める(この記事ではJSON)
ブローカーキューそのものを持っているソフト。 今回は RabbitMQ がこれ
プロデューサー / コンシューマー入れる側 / 取り出して処理する側。 この記事では API が producer、worker.js が consumer
ワーカーコンシューマーとして動かす、裏方のプロセス。 画面を持たず、キューだけを見ている
ack(確認応答)「この仕事、確かに終わりました」とブローカーに返す返事。 これが返るまで、ブローカーはその仕事を消さない
再配送(redelivery)ack が返らなかった仕事を、ブローカーがもう一度誰かに配ること
冪等(べきとう)同じ操作を何回やっても、結果の状態が同じという性質。RESTの回で出てきたあれです
デッドレターキュー(DLQ)何回やっても失敗する仕事を、隔離して捨てておく別のキュー
プリフェッチ(prefetch)1つのワーカーが、同時に何件まで手元に抱えるかの上限
202 Accepted「受け取りました。まだ終わっていません」を表すHTTPのステータス。200 OK(終わった)とは別物

「入れる人と、やる人を切り離す」が、この記事の全部です。 Redisの回は「同じ答えを二度作らない」ための道具でした。今回は「答えを作るのを、あとに回す」ための道具です。目的がまったく違います。

① まず、待たされる状態を作る

「遅いから非同期にしました」を、測らずに言わないでください。 前回と同じで、先に数字を作ります。

5秒かかるAPIを足す

~/server/app.js の、app.listen の上に足します。

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

// 「重い処理」のつもり。本物なら画像変換・PDF生成・メール送信
app.post("/api/tasks/:id/report", requireLogin, async (req, res) => {
  const started = Date.now();
  await sleep(5000);
  console.log(`[同期] task=${req.params.id} ${Date.now() - started}ms かかりました`);
  res.status(200).json({ ok: true, mode: "sync" });
});

await sleep(5000) は「5秒じっと待つ」だけのニセモノです。 本物の画像変換はCPUを使います。 ここが正直に言っておくべきところで、この2つは挙動が違います。

– sleep は待っているだけなので、その間もサーバーは他のリクエストをさばけます – 本物のCPUを使う処理は、他のリクエストまで巻き込んで遅くします(Node.js は1本の流れで動いているため)

つまり今回再現できるのは「その人が待たされる」ところまでです。 それでも十分です。待たされること自体が問題なので。

測る

サーバーを立て直します。

bash
$ cd ~/server
$ node --env-file=.env app.js

別のターミナルで、ログインしてから測ります。

bash
$ cd ~/server
$ curl -s -c cookie.txt -X POST http://localhost:3000/api/login \
    -H "Content-Type: application/json" \
    -d '{"email":"me@example.com","password":"pass12345"}' > /dev/null

$ curl -o /dev/null -s -b cookie.txt -X POST \
    -w "最初の1バイト:%{time_starttransfer}s  合計:%{time_total}s\n" \
    http://localhost:3000/api/tasks/1/report
最初の1バイト:5.008431s  合計:5.008502s

5秒です。 前回覚えたとおり、time_starttransfer(TTFB)が長い=サーバーが考えている状態です。

そして、ここが今回の分かれ道です。

この5秒は、EXPLAIN を見ても、索引を張っても、Redisを入れても、1ミリ秒も縮みません。 画像の変換に5秒かかるなら、5秒かかります。

打つ手は1つしかありません。

利用者を、その5秒に付き合わせないこと。

② 「あとでやる」に組み替える、という発想

やることは、たった2つです。

いまこれから
受け取る → 5秒処理する → 200 OK を返す受け取る → 依頼書をキューに入れる → すぐ 202 Accepted を返す
(終わり)別のプロセスが、キューから取り出して5秒処理する

返す番号が変わることに注意してください。

200 OK は「終わりました」です。 終わっていないのに 200 を返すと、嘘になります。 202 Accepted は「受け取りました。まだ終わっていません」です。RESTの回で番号は「サーバーの気持ち」だと書きました。気持ちが変わったので、番号も変えます。

そして、代わりに何かを失います。

利用者は「終わったかどうか」を、その場では知れなくなります。 だから jobId(受付番号)を返します。 あとで「あれ、どうなった?」と聞けるようにするためです。 宅配便の伝票番号と同じ発想です。 受け付けた時点では、まだ届いていません。

③ キューとは何か —— Redis でもできるのに、なぜ専用のものがあるか

「あとでやる」ためだけなら、キューは要りません。 配列に入れておけばいいはずです。

const jobs = [];              // ← これでもキューではある
jobs.push({ taskId: 1 });

これが駄目な理由は1つです。

サーバーを再起動した瞬間、溜まっていた仕事が全部消えます。

では、Redis ならどうか。Redis にはリスト型があって、こう書けます。

LPUSH jobs '{"taskId":1}'     ← 入れる
BRPOP jobs 0                  ← 取り出す(無ければ待つ)

これは、ちゃんと動きます。 プロセスをまたげますし、再起動しても残ります(設定によります)。小さな用途なら、これで十分です。

では、なぜ RabbitMQ のような専用のものがあるのか。 答えは1つに絞れます。

BRPOP は、取り出した瞬間にリストから消えます。 取り出した直後にワーカーが落ちたら、その仕事は誰も知らないまま消えます。

「消えても構わない」なら Redis でいいのです。Redisの回で書いたとおり、Redis は「消えてもいいものを置く場所」でした。キャッシュなら消えても作り直せます。 ですが——

「決済の完了メールを送る」が消えたら、作り直せません。 誰も、消えたことに気づけません。

専用のブローカーが引き受けてくれるのは、そこです。

欲しいものRedis のリストRabbitMQ
入れる・取り出すできるできる
確認応答(ack)無い。 取り出した瞬間に消えるある。 ack が返るまで消さない
再配送自分で書く(処理中リストへ退避するなど)ある。 接続が切れたら自動でキューに戻る
再試行の回数を数える自分で書くメッセージのヘッダで持てる
失敗し続けるものの隔離自分で書くデッドレターキューがある
順序入れた順(ただし複数ワーカーなら追い越す)入れた順(同じく、複数ワーカーなら追い越す)
溜まっている数を見るLLEN で数えるだけ管理画面がある。 秒間の流入・流出まで見える
入っているものを覗くできるできる(管理画面から)
重さ軽い(すでに入っている)重い。 数百MBのメモリを持っていく

表の一番下を見てください。 RabbitMQ は重いです。 これは欠点で、「Redis がもう動いているのに、もう1つミドルウェアを増やすのか」は毎回考える価値があります。 なお Redis にも Streams という、ack と再配送を持つ仕組みがあります。 「Redis では絶対にできない」ではありません。この記事では、その機能が最初から主役になっている RabbitMQ で、仕組みのほうを覚えます。

要するに、専用のブローカーが売っているのは速さではありません。

「失敗したときに、なかったことにならない」という保証です。

④ RabbitMQ を Docker Compose で立てる

Composeの回でやったとおり、ファイル1枚にします。

bash
$ mkdir -p ~/queue
$ cd ~/queue
$ nano compose.yaml
services:
  rabbitmq:
    image: rabbitmq:4-management
    hostname: rabbit-1
    restart: unless-stopped
    ports:
      - "127.0.0.1:5672:5672"
      - "127.0.0.1:15672:15672"
    environment:
      RABBITMQ_DEFAULT_USER: appuser
      RABBITMQ_DEFAULT_PASS: ここに自分で決めた文字列
    volumes:
      - rabbit-data:/var/lib/rabbitmq

volumes:
  rabbit-data:

1行ずつ

書いたものなぜ
rabbitmq:4-management-management 付きのイメージ。管理画面が最初から入っています。無印だと画面はありません。4 系を使います(3 系の最後の 3.13 は、コミュニティ向けのサポートが 2024年9月30日で終わっています)
hostname: rabbit-1RabbitMQ はホスト名でデータの置き場所を決めます。 書かないとコンテナIDになり、作り直すたびに中身が空になります
"127.0.0.1:5672:5672"アプリが繋ぐ口。VMの中からしか繋げません(重要。下記)
"127.0.0.1:15672:15672"管理画面。同上
RABBITMQ_DEFAULT_USER / _PASS初期ユーザー。 書かないと guest / guest で作られます
rabbit-data(名前付きボリューム)溜まったメッセージの実体。 コンテナを作り直しても残ります

管理画面を外に出さない

ここが、この記事で一番事故りやすいところです。

ports: を、こう書きたくなります。

    ports:
      - "15672:15672"        # ← これは駄目

これは「どこからでも繋いでいい」という意味です。 管理画面はブローカーの中身を全部見られて、キューを消せて、ユーザーを作れる画面です。インターネットに出ている機械でこれをやると、その日のうちに見つかります。

そして、もっと厄介な話があります。

Docker の ports: は、ufw を素通りします。

ufw で閉じてあるから大丈夫、は成り立ちません。 Docker は自分でパケットの通り道を書き換えるので、ufw status に出てこない穴が開きます。

確かめられます。

bash
$ sudo ufw status

15672 は、どこにも出てきません。 それでも "15672:15672" と書けば、外から繋がります。

だから、ufw に頼らず、ports: の左側に 127.0.0.1: を書きます。 これは「VMの中からしか繋げない」という意味で、Redisの回で bind 127.0.0.1 を確認したのとまったく同じ話です。

起動する

bash
$ cd ~/queue
$ docker compose up -d
[+] Running 3/3
 ✔ Network queue_default        Created
 ✔ Volume "queue_rabbit-data"   Created
 ✔ Container queue-rabbitmq-1   Started

起動しただけでは、まだ使えません。 RabbitMQ は立ち上がるのに10〜20秒かかります。待ってから確かめます。

bash
$ docker compose exec rabbitmq rabbitmq-diagnostics -q ping
Ping succeeded

Error: unable to perform an operation on node が返るなら、まだ起動中です。 20秒ほど置いて、もう一度打ってください。 docker compose logs -f rabbitmq で Server startup complete が出るのを見てもいいです(Ctrl+C で抜けます)。

外に出ていないことを確かめる

「閉じたつもり」を、必ず目で確かめます。

bash
$ ss -tlnp | grep -E '5672|15672'
LISTEN 0  4096  127.0.0.1:5672   0.0.0.0:*
LISTEN 0  4096  127.0.0.1:15672  0.0.0.0:*

左側が 127.0.0.1 になっていれば正解です。 ここが 0.0.0.0 なら、外に出ています。 compose.yaml を直して docker compose up -d をやり直してください。

⑤ 管理画面を、安全に見る

画面はVMの中でしか開きません。 ですが、VMにはブラウザが入っていません。では、どうやって見るか。

SSH のトンネルを通します。

VS Code の Remote SSH で使ったのと同じ ssh コマンドに、オプションを1つ足すだけです。

Windows の PowerShell で打ちます(VMの中ではありません)。

PowerShell
PS> ssh -L 15672:127.0.0.1:15672 ユーザー名@VMのIPアドレス
部分意味
-LLocal forward。 手元のポートを、向こう側のポートに繋ぐ
15672:(左)Windows 側の 15672番
127.0.0.1:15672(右)VMから見た 127.0.0.1 の 15672番

この ssh を繋いだまま、Windows のブラウザで開きます。

http://localhost:15672

compose.yaml に書いたユーザー名とパスワードでログインします。

[スクリーンショット: 01_管理画面のログイン後.png] RabbitMQ の管理画面にログインした直後の Overview 画面を撮ってください。

これが、外に出さずに画面を見るときの定番です。 覚えておくと、この先ずっと使えます(データベースの管理画面、Grafana、Kubernetes のダッシュボード、全部同じやり方で見られます)。 ssh の窓を閉じると、トンネルも閉じます。 ブラウザが「繋がりません」になったら、まずそれを疑ってください。

⑥ producer を書く —— APIを即返しに変える

bash
$ cd ~/server
$ npm install amqplib

.env に足します。

bash
$ nano ~/server/.env
DB_USER=appuser
DB_PASSWORD=(これまでのもの)
DB_NAME=appdb
SESSION_SECRET=(これまでのもの)
REDIS_URL=(これまでのもの)
AMQP_URL=amqp://appuser:compose.yamlに書いた文字列@127.0.0.1:5672

.env は MySQLの回で .gitignore に入れてあります。 ここでも同じ扱いです。コミットしません。

繋ぐ部分

app.js の上のほう(redis を作ったあたり)に足します。

const amqp = require("amqplib");
const crypto = require("crypto");

const QUEUE = "report";
let channel = null;

async function connectQueue() {
  const conn = await amqp.connect(process.env.AMQP_URL);

  conn.on("error", (err) => console.error("[amqp]", err.message));
  conn.on("close", () => {
    channel = null;
    console.error("[amqp] 切れました。5秒後に繋ぎ直します");
    setTimeout(() => connectQueue().catch(() => {}), 5000);
  });

  const ch = await conn.createChannel();
  await ch.assertQueue(QUEUE, { durable: true });

  channel = ch;
  console.log("[amqp] 繋がりました");
}

connectQueue().catch((err) => console.error("[amqp] 繋がりません:", err.message));
書いたものなぜ
assertQueue「このキューが無ければ作る」。 送る側でも受ける側でも呼びます。先に立ち上がったほうが作るので、順番を気にしなくて済みます
durable: trueRabbitMQ を再起動してもキューの定義が残る。 これが false だと、キューごと消えます
channel を変数に持つ繋ぎ直しのたびに使い回すため。 リクエストごとに接続すると、あっという間に上限に当たります
conn.on("close") で繋ぎ直す書かないと、RabbitMQ を再起動した瞬間、APIは二度と送れなくなります(落ちはしないので、気づきません)

ルートを書き換える

さっき作った5秒のルートを、丸ごと差し替えます。

app.post("/api/tasks/:id/report", requireLogin, async (req, res) => {
  if (!channel) {
    return res.status(503).json({ error: "いま受け付けられません" });
  }

  const jobId = crypto.randomUUID();
  const job = {
    jobId,
    taskId: Number(req.params.id),
    userId: req.session.userId,
  };

  channel.sendToQueue(QUEUE, Buffer.from(JSON.stringify(job)), {
    persistent: true,
    messageId: jobId,
    contentType: "application/json",
  });

  res.status(202).json({ jobId, status: "queued" });
});

3つ、意味のある選択をしています。

選択理由
channel が無ければ 503黙って捨てない。 キューに入れられていないのに 202 を返したら、「受け付けた」という嘘になります
persistent: trueメッセージをディスクに書く。 これが最重要(下記)
messageId: jobId受け取った側が「この仕事はどれか」を言えるようにする。 後半の冪等の話で使います

durable と persistent は別物

ここは、必ず両方要ります。

設定何が残るか
durable: true(キューに付ける)キューという「箱」が残る
persistent: true(メッセージに付ける)箱の中身が残る

箱だけ残しても、中身が消えたら意味がありません。 片方だけ書いて「永続化した」と思い込むのが、定番の事故です。 そして、この2つを揃えてもまだ100%ではありません(ディスクに書き終える前に電源が落ちれば消えます)。「絶対に消えない」は存在しません。

動かして測る

bash
$ cd ~/server
$ node --env-file=.env app.js
[amqp] 繋がりました

別のターミナルで、もう一度測ります。

bash
$ curl -o /dev/null -s -b cookie.txt -X POST \
    -w "最初の1バイト:%{time_starttransfer}s  合計:%{time_total}s\n" \
    http://localhost:3000/api/tasks/1/report
最初の1バイト:0.005712s  合計:0.005780s

5.008秒 → 0.005秒。 約1000分の1です。 ただし、はっきりさせておきます。処理は1ミリ秒も速くなっていません。 まだ誰もやっていないだけです。「速くした」ではなく「待たせなくした」。ここを混同すると、次の節の事故が理解できません。

中身も見ておきます。

bash
$ curl -s -b cookie.txt -X POST http://localhost:3000/api/tasks/1/report | jq
{
  "jobId": "6f0c1f5e-1c2a-4a2b-9a77-0f7b2b4c1d33",
  "status": "queued"
}

⑦ キューに溜まる様子を見る

まだ consumer を書いていません。 つまり、誰も取り出していません。

さっき開いた管理画面の Queues タブを開いてください。report というキューがあり、Ready が増えているはずです。

もっと溜めます。

bash
$ for i in $(seq 1 20); do
$   curl -s -b cookie.txt -X POST http://localhost:3000/api/tasks/1/report > /dev/null
$ done

コマンドラインからも数えられます。

bash
$ cd ~/queue
$ docker compose exec rabbitmq rabbitmqctl list_queues name messages_ready messages_unacknowledged consumers
Timeout: 60.0 seconds ...
Listing queues for vhost / ...
name    messages_ready  messages_unacknowledged consumers
report  21              0                       0
列意味
messages_ready配られるのを待っている数。 これが監視すべき数値です
messages_unacknowledged誰かが処理中で、まだ ack が返っていない数
consumers繋がっているワーカーの数。 0 は「誰も働いていない」

[スクリーンショット: 02_溜まったメッセージ.png] 管理画面の Queues タブで、report キューの Ready が 21 になっている行を撮ってください。

consumers が 0 なのに Ready が増えている。 これが、本番で一番よく見る壊れ方です。 APIは200番台を返し続けます。 ログにもエラーは出ません。利用者は「送信できました」と言われます。 そして何も起きていません。 キューを入れると、「静かに壊れる」経路が1本増えます。 これが代償です。

⑧ consumer を書く

新しいファイルです。 APIとは別のプロセスとして動きます。

bash
$ nano ~/server/worker.js
const amqp = require("amqplib");

const QUEUE = "report";
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function handle(job) {
  console.log(`[worker] 処理を始めます job=${job.jobId} task=${job.taskId}`);
  await sleep(5000);                      // ここが本来の重い処理
  console.log(`[worker] 終わりました   job=${job.jobId}`);
}

async function main() {
  const conn = await amqp.connect(process.env.AMQP_URL);
  const ch = await conn.createChannel();

  await ch.assertQueue(QUEUE, { durable: true });
  await ch.prefetch(1);

  console.log("[worker] 待っています");

  await ch.consume(QUEUE, async (msg) => {
    if (msg === null) return;

    const job = JSON.parse(msg.content.toString());
    console.log(`[worker] 受け取りました job=${job.jobId} 再配送=${msg.fields.redelivered}`);

    try {
      await handle(job);
      ch.ack(msg);
    } catch (err) {
      console.error(`[worker] 失敗 job=${job.jobId}: ${err.message}`);
      ch.nack(msg, false, false);          // いまは捨てる。あとで直します
    }
  });

  process.on("SIGINT", async () => {
    console.log("\n[worker] 止めます");
    try { await ch.close(); await conn.close(); } catch {}
    process.exit(0);
  });
}

main().catch((err) => {
  console.error("[worker] 繋がりません:", err.message);
  process.exit(1);
});
書いたものなぜ
prefetch(1)「1件やり終わるまで、次を受け取らない」。 書かないと溜まっている全部が1台に配られ、ワーカーを増やしても暇なままになります
ch.ack(msg) を成功したときだけこれが ack の全部です。 返して初めて、ブローカーはその仕事を消します
msg.fields.redelivered「これは2回目以降ですか」 をブローカーが教えてくれる旗。次の節の主役です
ch.nack(msg, false, false)3つ目の false が「キューに戻さない」。 いまは捨てます(あとで直します)

別のターミナルで動かします。

bash
$ cd ~/server
$ node --env-file=.env worker.js
[worker] 待っています
[worker] 受け取りました job=6f0c1f5e-... 再配送=false
[worker] 処理を始めます job=6f0c1f5e-... task=1
[worker] 終わりました   job=6f0c1f5e-...
[worker] 受け取りました job=8b3d... 再配送=false

5秒に1件ずつ、溜まっていた21件が減っていきます。 管理画面の Ready が減り、consumers が 1 になっているのが見えるはずです。

ワーカーを増やす

さらに別のターミナルで、もう1本立ち上げてください。

bash
$ cd ~/server
$ node --env-file=.env worker.js

2つのターミナルに、交互にログが出ます。 処理速度が2倍になりました。

これが「切り離した」ことの見返りです。 APIを増やさずに、重い処理だけを増やせます。 そして別のマシンに移すこともできます(キューが間に立っているので、お互いの場所を知らなくていい)。 prefetch(1) を書かなかったら、これは起きません。 1台目が全部抱えて、2台目はずっと暇です。

⑨ 失敗したらどうなるか —— 同じ処理が2回走る

ここからが本題です。

わざと起こす

  1. ワーカーは1本だけにします(片方は Ctrl+C で止める)
  2. 1件送ります
bash
$ curl -s -b cookie.txt -X POST http://localhost:3000/api/tasks/1/report | jq -r .jobId
  1. ワーカーのログに 「処理を始めます」が出た直後、5秒経つ前にそのターミナルで Ctrl+C
[worker] 受け取りました job=aa11... 再配送=false
[worker] 処理を始めます job=aa11... task=1
^C
[worker] 止めます
  1. もう一度ワーカーを起動します
bash
$ node --env-file=.env worker.js
[worker] 待っています
[worker] 受け取りました job=aa11... 再配送=true
[worker] 処理を始めます job=aa11... task=1
[worker] 終わりました   job=aa11...

再配送=true。同じ jobId が、もう一度来ました。

何が起きたのか

ack を返す前にワーカーが消えたからです。

ブローカーから見ると、「配ったが、終わったという返事が来ていない」状態です。 返事が来ていない仕事を消すわけにはいきません。 だからもう一度配ります。 これは正しい動作です。

そして、これが意味することは1つです。

handle() の中身は、2回走りうる。

もし handle() がメール送信なら、利用者にメールが2通届きます。 課金なら2回引かれます。「途中で落ちる」は、めったに起きない特別なことではありません。 デプロイのたびにワーカーは止まります。普通に起きます。

なぜ「1回だけ」にできないのか

できないからです。

ワーカーが「処理を終えて、ack を送る」の間に落ちたとき、 ブローカーには「終わったのに ack が来ていない」と「終わっていない」の区別がつきません。

区別できない以上、選べるのは2つだけです。

方針起きること
ack が来なければ、もう一度配る(at-least-once)2回走ることがある
配ったら、返事を待たずに消す(at-most-once)1回も走らないことがある

RabbitMQ の既定は上です。 そして、ほとんどの現場も上を選びます。「2回やる」ほうが「消える」より、たいてい取り返しがつくからです。

だから、責任は受け取る側に移ります。 2回走っても壊れないように書く。 これが冪等です。 RESTの回で「POST は冪等でないから再送してはいけない」と書きました。キューは、その再送を機械が勝手にやる仕組みです。 だから、冪等性は「知っておくとよい性質」から「必須の条件」に変わります。

冪等にする

やることは1つです。

「この jobId は、もうやったか」を記録して、やっていたら何もしない。

記録する場所は、MySQL です。 Redis ではありません。消えては困る記録だからです。

bash
$ sudo mysql
CREATE TABLE appdb.processed_jobs (
  job_id      VARCHAR(36) NOT NULL PRIMARY KEY,
  finished_at DATETIME    NOT NULL DEFAULT CURRENT_TIMESTAMP
);

exit で抜けます。

PRIMARY KEY が主役です。 「同じ job_id は2行入らない」を、アプリではなくデータベースに保証させます。 SELECT して無ければ INSERT では駄目です。 2台のワーカーが同時に SELECT したら、両方とも「無い」と答えます。

worker.js を書き換えます。

const amqp = require("amqplib");
const mysql = require("mysql2/promise");

const QUEUE = "report";
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

const db = mysql.createPool({
  host: "127.0.0.1",
  user: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
  database: process.env.DB_NAME,
  connectionLimit: 5,
});

// すでにやった仕事なら false を返す
async function claim(jobId) {
  try {
    await db.execute("INSERT INTO processed_jobs (job_id) VALUES (?)", [jobId]);
    return true;
  } catch (err) {
    if (err.code === "ER_DUP_ENTRY") return false;
    throw err;
  }
}

async function handle(job) {
  console.log(`[worker] 処理を始めます job=${job.jobId} task=${job.taskId}`);
  await sleep(5000);
  console.log(`[worker] 終わりました   job=${job.jobId}`);
}

async function main() {
  const conn = await amqp.connect(process.env.AMQP_URL);
  const ch = await conn.createChannel();

  await ch.assertQueue(QUEUE, { durable: true });
  await ch.prefetch(1);

  console.log("[worker] 待っています");

  await ch.consume(QUEUE, async (msg) => {
    if (msg === null) return;

    const job = JSON.parse(msg.content.toString());
    console.log(`[worker] 受け取りました job=${job.jobId} 再配送=${msg.fields.redelivered}`);

    try {
      if (!(await claim(job.jobId))) {
        console.log(`[worker] すでに処理済みです。何もしません job=${job.jobId}`);
        ch.ack(msg);
        return;
      }
      await handle(job);
      ch.ack(msg);
    } catch (err) {
      console.error(`[worker] 失敗 job=${job.jobId}: ${err.message}`);
      ch.nack(msg, false, false);
    }
  });

  process.on("SIGINT", async () => {
    console.log("\n[worker] 止めます");
    try { await ch.close(); await conn.close(); await db.end(); } catch {}
    process.exit(0);
  });
}

main().catch((err) => {
  console.error("[worker] 繋がりません:", err.message);
  process.exit(1);
});

さっきと同じ実験を、もう一度やります。 送って、「処理を始めます」が出たら Ctrl+C、再起動。

[worker] 受け取りました job=bb22... 再配送=true
[worker] すでに処理済みです。何もしません job=bb22...

2回目は、何もしませんでした。

この直し方は完璧ではない

正直に書いておきます。

INSERT は通ったが、handle() の途中で落ちた——このとき、再配送されても「処理済み」と判定され、仕事は永遠に実行されません。

「先に印を付ける」と2回やらない代わりに、0回になる穴が残ります。 「後で印を付ける」と、その逆になります。

これを完全に閉じる方法は、原理的には1つだけです。

仕事の結果と、済んだ印を、同じデータベースの同じトランザクションで書く。

仕事が「MySQLに書くこと」なら、これは成立します。 ですがメールの送信は、データベースのトランザクションには入りません。 送ってしまったものは取り消せません。

だから現実の答えはこうなります。 「2回来る前提で書く」。 印だけに頼らず、処理そのものを、2回やっても同じ結果になる形にする。 例:「送信済みフラグを立てて、立っていたら送らない」ではなく、「送信記録テーブルに、この jobId で1行入れられたときだけ送る」。

完璧な保証を買おうとせず、被害を小さくする。 セキュリティの回と同じ考え方です。

何回もやり直す仕事と、絶対に成功しない仕事

いまの worker.js は、失敗したら捨てています。 それは乱暴です。かといって、無条件にキューへ戻すと、もっと悪いことが起きます。

必ず失敗するメッセージ(中身が壊れているなど)を戻し続けると、 失敗 → 戻す → 即配られる → 失敗、が秒間何千回まわります。CPUが張り付き、ログが埋まります。 これを毒メッセージ(poison message)と言います。

答えは「回数を数えて、上限で隔離する」です。 隔離先がデッドレターキューです。

まず、キューを作り直します。

bash
$ cd ~/queue
$ docker compose exec rabbitmq rabbitmqctl delete_queue report

ここで、必ずぶつかる壁があります。 すでにあるキューと違う設定で assertQueue を呼ぶと、こう言われます。

PRECONDITION_FAILED - inequivalent arg 'x-dead-letter-exchange' for queue 'report'

RabbitMQ は、キューの設定を後から変えさせてくれません。 消して作り直すしかありません。 消すと、中に残っていたメッセージも消えます。 本番では、新しい名前のキューを作って切り替えるのが定石です。

worker.js の assertQueue を差し替えます。

  await ch.assertQueue("report.dead", { durable: true });
  await ch.assertQueue(QUEUE, {
    durable: true,
    deadLetterExchange: "",
    deadLetterRoutingKey: "report.dead",
  });
書いたもの意味
deadLetterExchange: ""既定の経路を使うという指定(空文字が既定の名前です)
deadLetterRoutingKey捨てられたメッセージの行き先のキュー名

app.js 側の assertQueue も、同じ設定に揃えてください。 揃っていないと、先に立ち上がったほうと食い違って PRECONDITION_FAILED になります。

そして、失敗したときの分岐を書き換えます。

    } catch (err) {
      const attempts = (msg.properties.headers?.attempts ?? 0) + 1;
      console.error(`[worker] 失敗(${attempts}回目) job=${job.jobId}: ${err.message}`);

      // claim() で付けた「処理済み」の印を消す。消さないと、再投入したメッセージが
      // 「すでに処理済み」で ack され、再試行も DLQ 行きも起きない
      await db.execute("DELETE FROM processed_jobs WHERE job_id = ?", [job.jobId]);

      if (attempts < 3) {
        ch.sendToQueue(QUEUE, msg.content, {
          persistent: true,
          messageId: msg.properties.messageId,
          headers: { attempts },
        });
        ch.ack(msg);                       // 元のほうは片づける
      } else {
        ch.nack(msg, false, false);        // 3回失敗 → デッドレターキューへ
      }
    }

nack の3つ目の引数 false(キューに戻さない)が、DLQ行きの引き金です。 「捨てる」と言っておいて、捨て場所を用意したのが今回の変更です。 なお、この書き方は失敗するとすぐ再投入します。 相手のサービスが落ちているときは、少し待ってからやり直したいところです(指数バックオフと言います)。RabbitMQ 単体では素直に書けず、遅延用のプラグインを入れるか、x-message-ttl を付けた待機用キューを1本経由させます。 ここでは名前だけ覚えてください。

溜まった毒メッセージは、管理画面の Queues に report.dead として並びます。

[スクリーンショット: 03_デッドレターキュー.png] 管理画面の Queues タブに report と report.dead の2つが並んでいるところを撮ってください。

「送った」は「届いた」ではない

もう1つ、送る側にも穴があります。

channel.sendToQueue(QUEUE, buf, { persistent: true });
res.status(202).json({ jobId, status: "queued" });

sendToQueue は、ブローカーに届いたかを待ちません。 ネットワークに流し込んだ時点で戻ってきます。

つまり、202 を返した直後にブローカーが落ちていたら、その仕事は消えます。 API側は何も知りません。

これを埋める仕組みが「パブリッシャー確認(publisher confirms)」です。 チャンネルの作り方を変えるだけです。

  const ch = await conn.createConfirmChannel();   // createChannel から変える

送るときに、返事を待てるようになります。

  await new Promise((resolve, reject) => {
    channel.sendToQueue(QUEUE, Buffer.from(JSON.stringify(job)),
      { persistent: true, messageId: jobId },
      (err) => (err ? reject(err) : resolve()));
  });
  res.status(202).json({ jobId, status: "queued" });

返事を待つぶん、APIは少し遅くなります(数ミリ秒)。5秒に比べれば、無視できます。

「消えると困る仕事」なら、必ず入れてください。 消えても構わない仕事にまで入れる必要はありません。

⑩ 溜まりすぎたらどうなるか

キューは、無限に溜められる魔法の箱ではありません。

監視すべき数値は1つ

messages_ready(配られるのを待っている数)。

この数字の意味は、たった1行です。

見え方意味
0付近を上下する正常。 入る速さと出る速さが釣り合っている
じわじわ増え続ける処理が追いついていない。 ワーカーを増やすか、処理を速くする
一気に増えて減らないワーカーが死んでいる。 consumers を見る

絶対値では判断できません。 1000件溜まっていても、秒間500件さばけるなら2秒で消えます。 見るべきは「増え続けているか」です。傾きです。

監視の回でやったとおり、これは手で数えるものではありません。 RabbitMQ には Prometheus 用の出口が最初から入っていて、15692 番で数字を出せます(rabbitmq_prometheus プラグインを有効にします)。「取りに行く」側の設定は、あの回と同じです。

詰まると、送る側が止まる

ここが、キューの一番意地悪なところです。

RabbitMQ は、メモリが規定の割合(既定は検出したメモリの60%。旧3系では40%)を超えると、こうします。

送る側を止めます。

エラーを返すのではありません。 黙って、受け付けなくなります。 producer 側から見ると——

sendToQueue を呼んでも、何も起きない。落ちない。エラーも出ない。 リクエストがただ固まります。

同じことがディスクの空きでも起きます。 これを「フロー制御」と言います。

気づけるようにしておきます。

  conn.on("blocked", (reason) => console.error("[amqp] 止められました:", reason));
  conn.on("unblocked", () => console.error("[amqp] 再開しました"));

いまの状態は、こう見ます。

bash
$ cd ~/queue
$ docker compose exec rabbitmq rabbitmqctl status | grep -A 4 "Memory"

溜まりすぎを「防ぐ」設定もあります。 キューに x-max-length を付けると、上限を超えたぶんは古いほうから捨てられます(DLQを設定していればそちらへ回ります)。 「捨てる」が正しいこともあります。 通知のように、古くなったらもう意味がない仕事なら、溜め続けるより捨てるほうがましです。

メモリを実際に見る

bash
$ docker stats --no-stream
CONTAINER ID   NAME               CPU %   MEM USAGE / LIMIT     MEM %
a1b2c3d4e5f6   queue-rabbitmq-1   0.9%    132.4MiB / 3.82GiB    3.39%

何もしていない状態で130MB前後です。 Redis の10倍近くあります。学習用のVMでは、これは無視できない重さです。 使い終わったら必ず止めてください(後片づけの節)。

⑪ やりすぎない —— たいてい、要りません

ここまで書いてきて、最後にひっくり返します。

個人が作るサービスに、メッセージキューは、たいてい要りません。

入れた瞬間に、こうなります。

増えるもの具体的に
プロセスが1つworker が止まっていても、画面上は正常に見える。 気づく仕組みを別に作る必要がある
ミドルウェアが1つ130MBのメモリ。 起動順、認証情報、バージョン更新
ログが2箇所APIのログを見ても、失敗が書いていない
「終わったか」を返す口jobId を渡した以上、状態を聞ける口が要る。 作らないと利用者は何も分からない
冪等性という宿題全部の仕事について、2回走っても平気か考える

入れる前に、この順で考えてください。

問い答えがこうなら
測ったか測っていないなら、まず測る。 遅い原因が別のところにあることは、本当によくあります
索引やキャッシュで直らないか直るなら、そちらが先。 Redisの回の判断表を通します
本当に利用者を待たせているか夜間にまとめてやればいい仕事なら、cron で足ります。 キューは要りません
失敗したらやり直したいかやり直さなくていいなら、res.json() を返したあとに処理を続けるだけでも成立します(プロセスが落ちたら消えますが)
1日に何件か数十件なら、MySQLに jobs テーブルを1枚作って、1分おきに見に行くので十分です

最後の行が、実は一番使える答えです。 すでにあるデータベースを、キューとして使う。 「未処理の行を1件取って、印を付けて、処理する」。 MySQL 8 なら SELECT ... FOR UPDATE SKIP LOCKED で、複数のワーカーが同じ行を掴まないようにも書けます。 ミドルウェアが増えません。 バックアップも監視も、いまあるものがそのまま効きます。規模が小さいうちは、ほぼこれが正解です。

では、いつ RabbitMQ が要るのか。

  • 1日に何万件も流れる(データベースをキューにすると、そのポーリングが本業を圧迫する)
  • 仕事の種類が増えてきて、送る側が「誰がやるか」を知りたくない
  • 処理する側を、別のマシン・別の言語で書きたい
  • 再試行・隔離・順序を、自分で書きたくない

この4つのどれにも当てはまらないなら、入れないでください。

つまずいたところ

症状原因
[worker] 繋がりません: connect ECONNREFUSED 127.0.0.1:5672RabbitMQ が起動中か、落ちている。 docker compose ps と rabbitmq-diagnostics -q ping
Handshake terminated by server: 403 ACCESS_REFUSEDAMQP_URL のユーザー名かパスワード違い。 compose.yaml に書いた値と突き合わせる
パスワードに @ や / を入れたら繋がらないURLとして壊れています。 記号を使うなら書き換えが要るので、英数字で作り直すのが早い
Socket closed abruptly during opening handshake5672 ではなく 15672(管理画面)に繋いでいる。 ポート番号を見直す
PRECONDITION_FAILED - inequivalent arg ...既存のキューと違う設定で assertQueue した。 app.js と worker.js で設定を揃える。 それでも駄目なら delete_queue
docker compose up したのに管理画面が出ないrabbitmq:3 を使っている。 管理画面は rabbitmq:3-management に入っています
Windows のブラウザで localhost:15672 が繋がらないssh -L の窓を閉じた。 もう一度繋ぐ
docker compose down して上げ直したら、ユーザーが消えたhostname: を書いていない。 RabbitMQ はホスト名でデータの置き場所を決めます
consumers が 0 のままworker を起動していない、または main() が例外で落ちている。ワーカーのログを見る
ワーカーを2本立てたのに、1本しか働かないprefetch を書いていない。 1本目が全部抱えています
同じ仕事が2回走った正常です。 ack の前に落ちたから。冪等に書きます(⑨)
ワーカーが同じメッセージで無限に失敗し続けるnack の3つ目を true(キューに戻す)にした。 回数を数えて DLQ へ回す
ER_DUP_ENTRY がそのまま500になるclaim() で拾い損ねている。 err.code の綴りを確認する
APIが固まって返ってこないフロー制御。 キューが溜まりすぎてメモリの上限に当たっています。rabbitmqctl status
VMが重くなったRabbitMQ が130MB以上使っています。 使わないときは docker compose stop
rabbitmqctl が Timeout と出る起動しきっていないか、ノード名が違う。 まず rabbitmq-diagnostics -q ping

後片づけ

RabbitMQ は動かしっぱなしにしないでください。 学習用のVMでは、メモリの数%を常に持っていきます。

1. ワーカーとAPIを止めます。 それぞれのターミナルで Ctrl+C。

2. しばらく使わないだけなら、止めるだけ。

bash
$ cd ~/queue
$ docker compose stop

次に使うときは docker compose start です。 データも設定も残ります。

3. 完全に消すとき。

bash
$ cd ~/queue
$ docker compose down -v

-v は「ボリュームも消す」。 溜まっていたメッセージも、作ったユーザーも、全部消えます。 Composeの回で書いたとおり、down と down -v は別物です。

4. イメージも消して、容量を戻します。

bash
$ docker image rm rabbitmq:4-management
$ docker system df

5. アプリ側を元に戻す場合。

bash
$ sudo mysql -e "DROP TABLE appdb.processed_jobs;"
$ cd ~/server
$ npm uninstall amqplib

app.js に足した amqp の3ブロック(require・connectQueue・/report のルート)と、worker.js を消せば元通りです。

~/server/ と appdb は残してください。 ここまでで、測って・速くして・待たせないところまで来ました。

まとめ

  • 速くできない処理がある。 索引もキャッシュも効かない。打つ手は「速くする」ではなく「待たせない」
  • 「あとでやる」に変えると、返す番号が変わる。 200 OK(終わった)ではなく 202 Accepted(受け取った)
  • 受付番号(jobId)を返す。 返さないと、利用者は結果を知る手段を失う
  • キューは Redis でもできる。 専用のものが売っているのは速さではなく、「失敗したときになかったことにならない」保証
  • durable(箱が残る)と persistent(中身が残る)は別物。 両方書く
  • 管理画面を外に出さない。 ports: の左に 127.0.0.1: を書く。Docker の ports: は ufw を素通りする
  • 画面はSSHのトンネル(ssh -L)で見る。 この方法はこの先ずっと使える
  • prefetch(1) を書く。 書かないと、ワーカーを増やしても1台が全部抱える
  • ack は「終わった」の返事。 返す前に落ちたら、もう一度配られる
  • 同じ処理は2回走りうる。 これは異常ではなく仕様。冪等に書くのは受け取る側の責任
  • 「1回だけ」は原理的に作れない。 選べるのは 2回走るか、0回になるかだけ
  • 済んだ印は PRIMARY KEY に守らせる。 SELECT して無ければ INSERT は同時に走ると破れる
  • 失敗を無条件にキューへ戻さない。 回数を数えて、デッドレターキューへ隔離する
  • sendToQueue は「届いた」を待たない。 消えると困るなら createConfirmChannel
  • 監視すべき数値は messages_ready。 絶対値ではなく増え続けているかを見る
  • 溜まりすぎると、エラーではなく「送る側が黙って止まる」。 blocked を拾っておく
  • RabbitMQ は130MB以上を常に使う。 使わないときは止める
  • そして、個人のサービスならたいてい要らない。 まずデータベースを1枚のキューとして使うことを考える

参考リンク


次に読む

この記事は 【第5段階】バックエンドとデータベース の 22 / 29 本目です。

記事
← 前の記事OAuthはログインの仕組みではない — 認可とOIDC
→ 次の記事1画面のために3回叩く — GraphQLとRESTの違い

上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。

全体の順路は はじめに にあります。

roadmap.sh のどこをやっているか

Backend›Message Brokers
  • Message Brokers(RabbitMQ)
  • 非同期処理と再配送
  • 冪等性

この記事は、上の項目を実際に手を動かして確かめる回です。

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

コメント

コメントする

目次