RabbitMQ の手動 backup と restore

プラットフォームの backup は 2026年9月15日に RabbitMQ から削除されたため、cluster の設定を守るのはお客様自身の運用になりました。このページでは Management HTTP API で definitions を export し、ファイルが完全かを確認したうえで、新しい cluster へ import します。

警告

この方法で backup されるのは definitions だけ です。vhost、user、permission、exchange、queue、binding、policy が対象で、queue に残っているメッセージは含まれず、この方法では復旧できません。

対象は Erlang 26.x 上の RabbitMQ 3.13.x です。

definitions に含まれるもの

構成要素	内容
vhost	仮想ホスト
user と permission	アカウントとアクセス権
exchange	direct、topic、fanout、headers
queue	queue の宣言と argument
binding	exchange と queue の結びつき
policy	TTL、HA、max-length、dead-letter など

仕組み

すべての操作は backup server から行います。これはお客様が管理する VM で、RabbitMQ の cluster へ port 15672 で到達できるものです。Management HTTP API を直接呼ぶため、cluster 側には何もインストールせず、ノードを停止することもありません。

フェーズ	処理内容
Backup	backup server が元の cluster の `GET /api/definitions` を呼び、JSON を保存します
Restore	backup server が保存済みファイルを対象 cluster の `POST /api/definitions` へ送ります

restore の間、元の cluster にはまったくアクセスしません。

前提条件

項目	要件
ネットワーク	backup server から cluster へ port 15672 で到達できること
アカウント	`administrator` タグを持つ user
対象バージョン	restore 時、対象 cluster の RabbitMQ バージョンが元の cluster 以上であること
Erlang バージョン	元の cluster と揃えることを推奨します

以下のコマンドで使う placeholder は次のとおりです。<HOST> は元の cluster のアドレス、<TARGET_HOST> は対象 cluster、<USERNAME> と <PASSWORD> は administrator の認証情報、<VHOST_NAME> は vhost 名、<TIMESTAMP> は保存したファイル名に入る時刻、<RABBITMQ_HOST> はスケジュール実行するスクリプトが読み込むアドレスです。

definitions を backup する

cluster 全体を export する

curl -s \
  -u '<USERNAME>:<PASSWORD>' \
  http://<HOST>:15672/api/definitions \
  -o /backup/rabbitmq/rabbitmq_definitions_$(date +%Y%m%d_%H%M%S).json

例:

curl -s \
  -u 'admin:your_password' \
  http://10.0.1.10:15672/api/definitions \
  -o /backup/rabbitmq/rabbitmq_definitions_$(date +%Y%m%d_%H%M%S).json

vhost 単位で export する

curl -s \
  -u '<USERNAME>:<PASSWORD>' \
  'http://<HOST>:15672/api/definitions/<VHOST_NAME>' \
  -o /backup/rabbitmq/rabbitmq_vhost_<VHOST_NAME>_$(date +%Y%m%d_%H%M%S).json

例 — vhost app_production を backup する場合:

curl -s \
  -u 'admin:your_password' \
  'http://10.0.1.10:15672/api/definitions/app_production' \
  -o /backup/rabbitmq/rabbitmq_vhost_production_$(date +%Y%m%d_%H%M%S).json

警告

vhost 単位の export には user と global parameter が含まれません。移行用のファイルとして使う場合は、cluster 全体の export を使ってください。

使う前にファイルを検証する

エラーページが返ってきた場合もファイルとしてはディスクに残るため、中身の件数を数えて確認します。

python3 << 'EOF'
import json

with open("/backup/rabbitmq/rabbitmq_definitions_<TIMESTAMP>.json") as f:
    d = json.load(f)

print(f"Vhosts:      {len(d.get('vhosts', []))}")
print(f"Users:       {len(d.get('users', []))}")
print(f"Exchanges:   {len(d.get('exchanges', []))}")
print(f"Queues:      {len(d.get('queues', []))}")
print(f"Bindings:    {len(d.get('bindings', []))}")
print(f"Policies:    {len(d.get('policies', []))}")
EOF

件数が元の cluster と一致していることを確認します。

Vhosts:      4
Users:       5
Exchanges:   5
Queues:      8
Bindings:    8
Policies:    3

新しい cluster へ restore する

ファイルを import する

curl -s -X POST \
  -u '<USERNAME>:<PASSWORD>' \
  -H "Content-Type: application/json" \
  -d @/backup/rabbitmq/rabbitmq_definitions_<TIMESTAMP>.json \
  http://<TARGET_HOST>:15672/api/definitions

例:

curl -s -X POST \
  -u 'admin:your_password' \
  -H "Content-Type: application/json" \
  -d @/backup/rabbitmq/rabbitmq_definitions_20260519_020001.json \
  http://10.0.2.10:15672/api/definitions

レスポンスコードを確認する

import が成功すると何も出力されないため、ステータスコードを明示的に取得します。

curl -s -o /dev/null -w "%{http_code}\n" -X POST \
  -u 'admin:your_password' \
  -H "Content-Type: application/json" \
  -d @/backup/rabbitmq/rabbitmq_definitions_20260519_020001.json \
  http://10.0.2.10:15672/api/definitions

コード	意味
200	import 成功
400	JSON ファイルが不正
401	ユーザー名またはパスワードが誤り
403	user に `administrator` タグがない

2 つの cluster を突き合わせる

import が完全に終わったと決めつけず、両側の件数を比較します。

python3 << 'EOF'
import json, urllib.request, base64

def get_definitions(host, user, password):
    url = f"http://{host}:15672/api/definitions"
    req = urllib.request.Request(url)
    token = base64.b64encode(f"{user}:{password}".encode()).decode()
    req.add_header("Authorization", f"Basic {token}")
    with urllib.request.urlopen(req) as r:
        return json.load(r)

SOURCE = get_definitions("10.0.1.10", "admin", "your_password")
DEST   = get_definitions("10.0.2.10",  "admin", "your_password")

keys = ["vhosts", "users", "exchanges", "queues", "bindings", "policies"]

print(f"{'Thành phần':<15} {'Nguồn':>8} {'Đích':>8} {'Khớp':>8}")
print("-" * 45)
for k in keys:
    src = len(SOURCE.get(k, []))
    dst = len(DEST.get(k, []))
    match = "OK" if src == dst else "LỆCH"
    print(f"{k:<15} {src:>8} {dst:>8} {match:>8}")
EOF

期待される結果:

Thành phần      Nguồn     Đích     Khớp
---------------------------------------------
vhosts               4        4       OK
users                5        5       OK
exchanges            5        5       OK
queues               8        8       OK
bindings             8        8       OK
policies             3        3       OK

import で押さえておくこと

パスワードはそのまま引き継がれます。 definitions ファイルは平文ではなくハッシュを保持しており、そのハッシュがそのまま import されます。対象 cluster でも user は従来のパスワードのまま使えます。

HA policy はノード数が揃って初めて効きます。 ha-mode: all の policy はどの cluster にも import できますが、実際に効くのはノードが 3 つ以上ある場合です。対象 cluster には元と同等の構成を用意してください。

2 回 import しても安全です。 この操作は冪等です。すでに存在する resource は更新されるか、そのまま残るだけで、削除されることはありません。失敗した import をやり直しても問題ありません。

cluster 名は上書きされません。 ファイル内の cluster_name は参考情報にすぎません。対象 cluster は自身の名前を保持します。

自動化する

backup スクリプト

/opt/backup/rabbitmq_backup.sh を作成します。

#!/bin/bash

# ---- Configuration ----
HOST="<RABBITMQ_HOST>"
USER="admin"
PASS='your_password'
BACKUP_DIR="/backup/rabbitmq"
RETENTION_DAYS=30
# ------------------

mkdir -p "$BACKUP_DIR"

FILENAME="rabbitmq_definitions_$(date +%Y%m%d_%H%M%S).json"
FILEPATH="${BACKUP_DIR}/${FILENAME}"

curl -s \
  -u "${USER}:${PASS}" \
  "http://${HOST}:15672/api/definitions" \
  -o "$FILEPATH"

if [ $? -eq 0 ] && [ -s "$FILEPATH" ]; then
    echo "[OK] Backup thành công: ${FILENAME}"
    find "$BACKUP_DIR" -name "rabbitmq_definitions_*.json" \
      -mtime +${RETENTION_DAYS} -delete
else
    echo "[FAIL] Backup thất bại!"
    rm -f "$FILEPATH"
    exit 1
fi

実行権限を付与します。

chmod +x /opt/backup/rabbitmq_backup.sh

ヒント

PASS はシングルクォートで囲んでください。! を含むパスワードをダブルクォートで囲むと bash の history 展開が働き、スクリプトが誤った認証情報を送信します。

スケジュール設定と確認

crontab -e

毎日 02:00 に実行する行を追加します。

0 2 * * * /opt/backup/rabbitmq_backup.sh >> /var/log/rabbitmq_backup.log 2>&1

最初のスケジュール実行のあとにログを確認します。

tail -f /var/log/rabbitmq_backup.log

成功した実行ごとの出力:

[OK] Backup thành công: rabbitmq_definitions_20260519_020001.json

次のステップ

Backup と restore の概要。プラットフォームの backup が残っている engine を確認できます
database の作成。import 先となる対象 cluster を用意するときに参照します
Kafka の手動 backup と restore。Kafka も運用している場合、そちらはメッセージ自体も保全できます

definitions に含まれるもの​

仕組み​

前提条件​

definitions を backup する​

cluster 全体を export する​

vhost 単位で export する​

使う前にファイルを検証する​

新しい cluster へ restore する​

ファイルを import する​

レスポンスコードを確認する​

2 つの cluster を突き合わせる​

import で押さえておくこと​

自動化する​

backup スクリプト​

スケジュール設定と確認​

次のステップ​