CLI から Confluence のスペースをエクスポートしてバックアップする

atlassian-cli はコミュニティによる独立したオープンソースプロジェクトです。Atlassian と提携・関連しておらず、Atlassian による承認、推奨、後援のいずれも受けておらず、Atlassian が提供する公式 CLI（acli）でもありません。製品名は互換性を示す目的でのみ使用しています。

コマンドラインからの confluence space export とは、1 つのコマンドにスペースキーを指定して、そのスペース内のすべてのページ、ブログ記事、コメントを機械可読な 1 つのファイルとして受け取ることです。atlassian-cli を使えば、スペース全体が JSON アーカイブになり、git にコミットしたり、オブジェクトストレージに置いたり、先週のコピーと差分を取ったりできます。対話を伴わない 1 つのコマンドなので、同じエクスポートがそのままスケジュール実行のバックアップにもなります。スクリプトに包んで cron の行を 1 つ追加すれば、ブラウザを開かずにナレッジベースの Confluence 外コピーが手に入ります。

このガイドはスペース単位のエクスポートとバックアップのループに絞って解説します。スペース全体のダンプ、適切な形式の選択、JSON では取得できない部分（添付ファイルと権限）の取得、そしてスケジュール実行です。復元の方針や保持期間を含む広い視点は、Confluence バックアップランブックをご覧ください。

Confluence のスペースエクスポートで取得できるもの

エクスポートの前に、スペースに実際に何が含まれ、JSON のエクスポートがどの部分を保持するのかを知っておくと役立ちます。Confluence のスペースは、コンテンツと設定を収める入れ物です。

• コンテンツ。ページ、ブログ記事、そこに付いたコメントです。残したいものの大半がこれで、一括エクスポートが JSON に書き出すのもまさにこの部分です。
• 添付ファイル。ページに埋め込まれた画像、PDF、その他のバイナリです。これらは別のファイルなので、別途ダウンロードする手順が必要です（後述します）。
• 設定。スペースの名前、説明、権限の付与です。これらはページ本文ではなくスペースのオブジェクトにあるため、明示的にスナップショットを取ります。

まずはエクスポートしたいスペースのキーを調べます。スペースキーは、ページの URL に現れる短い大文字の識別子（DOCS や ENG など）です。

# List every space you can see, with its key
atlassian-cli confluence space list --limit 50

# Inspect one space before backing it up
atlassian-cli confluence space get DOCS

space get の出力で、対象のスペースが正しいことを確認でき、名前と種類も分かります。キーが分かれば、エクスポート自体は 1 つのコマンドで済みます。

スペース全体を 1 つのコマンドでエクスポートする

主役は confluence bulk export です。ページ ID の代わりに CQL クエリを渡すと、スペース全体に一致するクエリならそのスペースをまるごと一度にエクスポートします。どれだけのコンテンツが動くのかを把握するため、まず --dry-run で確認してください。

# Preview: how many items match, nothing is written
atlassian-cli confluence bulk export \
  --cql "space = DOCS" \
  --output docs-backup.json \
  --format json \
  --dry-run

# Run the real export of the whole space
atlassian-cli confluence bulk export \
  --cql "space = DOCS" \
  --output docs-backup.json \
  --format json

CLI は結果全体を自動でページ送りするため、2,000 ページあるスペースでもページトークンに触れることなく 1 つの docs-backup.json にまとまります。大きなスペースは並列で処理されます。レート制限のあるインスタンスでは並列度を下げられます。

# Gentler on rate limits for very large spaces
atlassian-cli confluence bulk export \
  --cql "space = DOCS" \
  --output docs-backup.json \
  --format json \
  --concurrency 2

スペース全体が必要とは限りません。CQL を使えば、必要な範囲だけにエクスポートを絞れます。変更があった分だけを取得する差分バックアップに便利です。

# Pages only (skip blog posts and comments)
atlassian-cli confluence bulk export \
  --cql "space = DOCS and type = page" \
  --output docs-pages.json \
  --format json

# Only content modified in the last 7 days: a delta backup
atlassian-cli confluence bulk export \
  --cql "space = DOCS and lastmodified > now(\"-7d\")" \
  --output docs-delta.json \
  --format json

すべてが CQL で駆動されるため、同じ仕組みが 1 つのスペースから、複数のスペースにまたがる厳選したページ群まで対応します。Confluence のサブコマンドとグローバルフラグの一覧はコマンドリファレンスをご覧ください。

アーカイブの形式を選ぶ

atlassian-cli はどのコマンドでも --format を受け付けます。バックアップでは、選ぶ形式によってアーカイブの忠実さと再利用のしやすさが決まります。スペースのエクスポートに絞って各選択肢を比較します。

長期保存のバックアップには JSON を使い続けてください。スペースの中身を素早く一覧できる平たいインデックスもほしい場合は、CQL 検索を実行してアーカイブと並べて CSV を書き出します。

# Flat inventory of every page: title, id, and more
atlassian-cli confluence search cql "space = DOCS and type = page" \
  --format csv \
  --limit 500 > docs-inventory.csv

構造的なバックアップではなく、各ページを持ち運べる読みやすい形で残したいのなら、それは別の作業です。Confluence を Markdown にエクスポートするガイドと markdown 同期ランブックが、docs-as-code のワークフロー向けにページ本文を .md ファイルへ変換する方法を扱っています。この記事は、復元元となる JSON アーカイブに絞って解説します。

添付ファイルと権限をバックアップする

JSON のエクスポートはページの内容と構造を取得しますが、ページ本文の外にあるものが 2 つあります。バイナリの添付ファイルと、スペースの権限の付与です。完全なバックアップでは両方を取得します。

添付ファイル

添付ファイルは別のファイルなので、ループでバックアップします。スペース内のページを一覧表示し、各ページの添付ファイルを一覧表示し、すべてダウンロードします。ここでは confluence attachment list と confluence attachment download を使います。

# Download every attachment in a space to ./attachments/
mkdir -p attachments
atlassian-cli confluence search cql "space = DOCS and type = page" \
  --format json --limit 500 \
| jq -r '.[].id' \
| while read -r PAGE; do
    atlassian-cli confluence attachment list "$PAGE" --format json \
    | jq -r '.[].id' \
    | while read -r ATT; do
        atlassian-cli confluence attachment download "$ATT" \
          --output "attachments/$ATT"
      done
  done

スペースの設定と権限

スペースのオブジェクトと権限の付与を JSON でスナップショットしておくと、バックアップ時点で誰がアクセスできたかを正確に確認できます。スペースを作り直す場合や、アクセス権の変更を監査する場合にとても役立ちます。

# Space metadata (name, description, type)
atlassian-cli confluence space get DOCS --format json > docs-space.json

# Permission grants at the time of backup
atlassian-cli confluence space permissions DOCS --format json > docs-permissions.json

コンテンツの JSON、添付ファイルのディレクトリ、そしてこの 2 つのメタデータファイルを合わせると、スペースの自己完結したスナップショットになります。バックアップの頻度を決める材料として規模と活動状況を継続的に把握したい場合は、スペースレポートランブックがスペースごとのページ数と分析値を取得します。

スペースのバックアップを自動実行する

CLI でエクスポートする本当の利点は、無人で実行できることです。対話的なプロンプトがないため、バックアップ全体をシェルスクリプトにまとめて cron に渡せます。以下を backup-space.sh として保存してください。

#!/usr/bin/env bash
# Usage: backup-space.sh SPACEKEY
set -euo pipefail

SPACE="${1:?usage: backup-space.sh SPACEKEY}"
PROFILE="prod"
STAMP="$(date +%Y-%m-%d)"
DEST="$HOME/confluence-backups/$SPACE/$STAMP"
mkdir -p "$DEST"

# 1. Space metadata and permissions
atlassian-cli confluence space get "$SPACE" --profile "$PROFILE" \
  --format json > "$DEST/space.json"
atlassian-cli confluence space permissions "$SPACE" --profile "$PROFILE" \
  --format json > "$DEST/permissions.json"

# 2. All pages, blog posts, and comments
atlassian-cli confluence bulk export \
  --cql "space = $SPACE" \
  --output "$DEST/content.json" \
  --format json \
  --profile "$PROFILE"

echo "Backup of $SPACE written to $DEST"

実行権限を付けて cron のエントリーを追加します。次の例は毎晩 2 時に実行し、実行を確認できるよう出力をログファイルに追記します。

# chmod +x backup-space.sh, then: crontab -e
0 2 * * * /home/you/backup-space.sh DOCS >> /home/you/conf-backup.log 2>&1

スケジュール実行にあたっての実務的な注意点です。

• 専用のプロファイルを使う。このスクリプトは --profile prod を対象にしています。auth login で一度設定しておけば、cron ジョブは保存された API トークンで非対話的に認証します。
• 出力に日付を付ける。$STAMP のディレクトリが毎晩のスナップショットを分けて保持するので、昨日のコピーを上書きせずに履歴が積み上がります。
• 古いスナップショットを整理する。保持期間の処理（たとえば 30 日より古いバックアップのディレクトリを削除する）と組み合わせて、アーカイブが際限なく増えないようにします。
• 同じスクリプトは CI でも動く。サーバーで cron を動かしたくない場合は、エクスポートをスケジュール実行のパイプラインに入れてください。Confluence 自動化ガイドが、CI ランナーからこれらのコマンドを実行する方法を扱っています。

バックアップの検証と復元

一度も開いたことのないバックアップは、あるつもりでしかありません。エクスポートのたびに、アーカイブに実際に中身があるかを手軽に確認してください。JSON なので jq を使えば 1 行で済みます。

# How many items did we capture?
jq 'length' docs-backup.json

# List the titles so you can eyeball them
jq -r '.[].title' docs-backup.json | head -20

その件数を、スペースが実際に持っている件数と比べます。space get と検索の件数を確認すれば、黙って切り捨てられていないことが分かります。

# Count pages currently in the space
atlassian-cli confluence search cql "space = DOCS and type = page" \
  --format json --limit 500 | jq 'length'

復元は 1 つのインポートコマンドではなく、意図的に手順を踏む形です。これは利点でもあり、何をどこに戻すかを自分で決められます。JSON アーカイブは各ページのタイトルと本文を忠実に記録しているので、confluence page create でページを作り直せます。ループの書き方は、添付ファイルのバックアップで ID をループしたのと同じです。

# Recreate a page from a saved title and body
atlassian-cli confluence page create \
  --space DOCS \
  --title "Runbook: Incident Response" \
  --body "<p>Restored from backup</p>"

一部だけ復元する場合は、jq で JSON を必要なページに絞り込み、1 件ずつ page create に渡します。エクスポートの実行頻度や保存先を含む、復元と保持の方針の全体像はConfluence バックアップランブックに従ってください。

よくある質問

関連リソース