重い処理を要求の中でやると、利用者が待たされます。あとでやる仕組みに組み替えて、応答をすぐ返せるようにします。
前回: OAuthはログインの仕組みではない — 認可とOIDC 作業場所はVMの中(Ubuntu)です。ここまでで作った
~/server(Express + MySQL + Redis)と、Docker Composeの書き方|複数コンテナをまとめて起動する をそのまま使います。
前回は「遅いものを測って、速くする」をやりました。索引を張れば直る遅さは、それで直ります。
ですが、どうやっても速くならない処理があります。
画像を変換する。PDFを作る。メールを送る。外部のAPIを呼ぶ。
これらは5秒かかるものは、何をしても5秒かかります。 索引もキャッシュも効きません。そして、それをリクエストの中でやっている限り、利用者はその5秒を画面の前で待ちます。
この回でやるのは、速くすることではありません。
「いまやる」を「あとでやる」に変えます。
受け取ったら即座に返す。処理は別のプロセスがやる。 その間に立つのがメッセージキューです。
そして、この記事の本番は導入ではありません。「あとでやる」に変えた瞬間に生まれる新しい事故——同じ処理が2回走る——のほうです。
対象レベル: 初級〜中級 / 区分: 必修
この記事でわかること
- 速くできない処理があること。そこで打つ手は「速くする」ではなく「待たせない」だということ
- キューは Redis でもできること。それでも専用のものがあるのは、失敗したときの面倒を見てくれるから
ackを返さないと、同じメッセージがもう一度配られること。つまり同じ処理が2回走りうること- 「送った」は「届いた」ではないこと。キューを durable にしただけでは、メッセージは消えること
- 監視すべき数値は「キューの長さ」1つだということ。溜まり続けたら、いつか送る側が止まること
- 個人のサービスなら、たいていキューは要らないこと
この記事でやること
- 5秒かかるAPIを実際に作って、
curlで測って、待たされることを確かめる - RabbitMQ を Docker Compose で立てる(管理画面は外に出しません)
- producer(送る側)と consumer(処理する側)を書いて、APIを202で即返しに変える
- worker を止めてメッセージを溜めて、管理画面で数が増えるのを見る
- 処理の途中で worker を殺して、同じ仕事が2回走ることを目で見て、冪等に直す
- 後片づけする(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本の流れで動いているため)つまり今回再現できるのは「その人が待たされる」ところまでです。 それでも十分です。待たされること自体が問題なので。
測る
サーバーを立て直します。
別のターミナルで、ログインしてから測ります。
最初の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枚にします。
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-1 | RabbitMQ はホスト名でデータの置き場所を決めます。 書かないとコンテナ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 に出てこない穴が開きます。
確かめられます。
15672 は、どこにも出てきません。 それでも "15672:15672" と書けば、外から繋がります。
だから、
ufwに頼らず、ports:の左側に127.0.0.1:を書きます。 これは「VMの中からしか繋げない」という意味で、Redisの回でbind 127.0.0.1を確認したのとまったく同じ話です。
起動する
[+] Running 3/3
✔ Network queue_default Created
✔ Volume "queue_rabbit-data" Created
✔ Container queue-rabbitmq-1 Started
起動しただけでは、まだ使えません。 RabbitMQ は立ち上がるのに10〜20秒かかります。待ってから確かめます。
Ping succeeded
Error: unable to perform an operation on nodeが返るなら、まだ起動中です。 20秒ほど置いて、もう一度打ってください。docker compose logs -f rabbitmqでServer startup completeが出るのを見てもいいです(Ctrl+Cで抜けます)。
外に出ていないことを確かめる
「閉じたつもり」を、必ず目で確かめます。
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の中ではありません)。
| 部分 | 意味 |
|---|---|
-L | Local 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を即返しに変える
.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: true | RabbitMQ を再起動してもキューの定義が残る。 これが 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%ではありません(ディスクに書き終える前に電源が落ちれば消えます)。「絶対に消えない」は存在しません。
動かして測る
[amqp] 繋がりました
別のターミナルで、もう一度測ります。
最初の1バイト:0.005712s 合計:0.005780s
5.008秒 → 0.005秒。 約1000分の1です。 ただし、はっきりさせておきます。処理は1ミリ秒も速くなっていません。 まだ誰もやっていないだけです。「速くした」ではなく「待たせなくした」。ここを混同すると、次の節の事故が理解できません。
中身も見ておきます。
{
"jobId": "6f0c1f5e-1c2a-4a2b-9a77-0f7b2b4c1d33",
"status": "queued"
}
⑦ キューに溜まる様子を見る
まだ consumer を書いていません。 つまり、誰も取り出していません。
さっき開いた管理画面の Queues タブを開いてください。report というキューがあり、Ready が増えているはずです。
もっと溜めます。
コマンドラインからも数えられます。
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とは別のプロセスとして動きます。
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 が「キューに戻さない」。 いまは捨てます(あとで直します) |
別のターミナルで動かします。
[worker] 待っています
[worker] 受け取りました job=6f0c1f5e-... 再配送=false
[worker] 処理を始めます job=6f0c1f5e-... task=1
[worker] 終わりました job=6f0c1f5e-...
[worker] 受け取りました job=8b3d... 再配送=false
5秒に1件ずつ、溜まっていた21件が減っていきます。 管理画面の Ready が減り、consumers が 1 になっているのが見えるはずです。
ワーカーを増やす
さらに別のターミナルで、もう1本立ち上げてください。
2つのターミナルに、交互にログが出ます。 処理速度が2倍になりました。
これが「切り離した」ことの見返りです。 APIを増やさずに、重い処理だけを増やせます。 そして別のマシンに移すこともできます(キューが間に立っているので、お互いの場所を知らなくていい)。
prefetch(1)を書かなかったら、これは起きません。 1台目が全部抱えて、2台目はずっと暇です。
⑨ 失敗したらどうなるか —— 同じ処理が2回走る
ここからが本題です。
わざと起こす
- ワーカーは1本だけにします(片方は
Ctrl+Cで止める) - 1件送ります
- ワーカーのログに 「処理を始めます」が出た直後、5秒経つ前にそのターミナルで
Ctrl+C
[worker] 受け取りました job=aa11... 再配送=false
[worker] 処理を始めます job=aa11... task=1
^C
[worker] 止めます
- もう一度ワーカーを起動します
[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 ではありません。消えては困る記録だからです。
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)と言います。
答えは「回数を数えて、上限で隔離する」です。 隔離先がデッドレターキューです。
まず、キューを作り直します。
ここで、必ずぶつかる壁があります。 すでにあるキューと違う設定で
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] 再開しました"));
いまの状態は、こう見ます。
溜まりすぎを「防ぐ」設定もあります。 キューに
x-max-lengthを付けると、上限を超えたぶんは古いほうから捨てられます(DLQを設定していればそちらへ回ります)。 「捨てる」が正しいこともあります。 通知のように、古くなったらもう意味がない仕事なら、溜め続けるより捨てるほうがましです。
メモリを実際に見る
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:5672 | RabbitMQ が起動中か、落ちている。 docker compose ps と rabbitmq-diagnostics -q ping |
Handshake terminated by server: 403 ACCESS_REFUSED | AMQP_URL のユーザー名かパスワード違い。 compose.yaml に書いた値と突き合わせる |
パスワードに @ や / を入れたら繋がらない | URLとして壊れています。 記号を使うなら書き換えが要るので、英数字で作り直すのが早い |
Socket closed abruptly during opening handshake | 5672 ではなく 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. しばらく使わないだけなら、止めるだけ。
次に使うときは docker compose start です。 データも設定も残ります。
3. 完全に消すとき。
-vは「ボリュームも消す」。 溜まっていたメッセージも、作ったユーザーも、全部消えます。 Composeの回で書いたとおり、downとdown -vは別物です。
4. イメージも消して、容量を戻します。
5. アプリ側を元に戻す場合。
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枚のキューとして使うことを考える
参考リンク
- roadmap.sh — Backend(Message Brokers の項目)
- RabbitMQ 公式チュートリアル
- RabbitMQ — Consumer Acknowledgements and Publisher Confirms
- RabbitMQ — Dead Letter Exchanges
- RabbitMQ — Memory Alarms
- RabbitMQ — Management Plugin
- RabbitMQ — Production Checklist
- Docker Hub — rabbitmq
- amqplib(npm) / amqplib チャンネルAPI
次に読む
この記事は 【第5段階】バックエンドとデータベース の 22 / 29 本目です。
上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。
全体の順路は はじめに にあります。
roadmap.sh のどこをやっているか
- Message Brokers(RabbitMQ)
- 非同期処理と再配送
- 冪等性
この記事は、上の項目を実際に手を動かして確かめる回です。

コメント