🍊mikanBox Cloudflare版 マニュアル v0.6.10

このマニュアルはCloudflare版の導入と、PHP版との違いを説明します。共通の操作は操作マニュアルも参照してください。

初期設定・配布について

新規インストールと公開

画像付きインストールガイドでは、AIに依頼し、Cloudflareの認可とアドレス選択から公開まで画面を見ながら進められます。

ファイルの取得やコマンド実行ができるAIを使う場合は、作業フォルダで新しい会話を開き、「https://github.com/yoshihik0/mikanBox-cloud からCloudflareにインストールしてください」と依頼します。AIがファイル取得・設定・配置を進め、利用者はCloudflare認可、アドレスの選択、普段のブラウザでの初回端末登録を行います。以下のコマンドは自分で操作する場合の詳細です。

ここでは新しいサイトを作る手順を説明します。既存サイトの更新では、D1やWorkerを新規作成せず、アップデート手順を参照してください。

最初に用意するもの

Cloud版のリリース一覧で使用する公開リリースを開き、Assetsの Source code (zip) をダウンロードして展開します。公開プレリリースを選ぶこともできます。端末のターミナルで展開したフォルダへ移動してから、以下のコマンドを実行します。npm ci はそのフォルダの package-lock.json に従って必要なツールを準備します。Cloudflareにログインするブラウザでは、設置するアカウントを選んでください。Wranglerの認可画面に「Wrangler wants to access your account」と表示されたら対象アカウントを確認し、Authorize を押します。「Authorization granted to Wrangler」と表示されたらターミナルに戻ります。

npm ci
npx wrangler login
npx wrangler whoami

whoami に表示されたアカウントを確認し、以下の手順に進みます。ログイン済みであっても対象のアカウントが違う場合は設置しないでください。管理用・公開用の名前、アカウントID、D1 ID、設定ファイルは後で更新するために控えておきます。メールアドレスやトークンは公開URLやGitには含めません。

管理用と公開用の2つのWorkerを使います。workers.dev を使う場合、例えば共通のサブドメインが mikanbox-cloud なら、管理画面を https://admin.mikanbox-cloud.workers.dev/admin、公開サイトを https://mikan.mikanbox-cloud.workers.dev/ のようにできます。admin と mikan はそれぞれ管理用・公開用に決める名前で、共通の mikanbox-cloud はCloudflareアカウントのサブドメインです。新しく登録するサブドメインは、ほかで使われていないものを選びます。サブドメインは公開URLに含まれるため、メールアドレスの一部やログインIDなどを使わず、サイトに関係する名前などを選んでください。

公開サイトには独自ドメインも使えます。まず workers.dev の仮URLで始め、あとから独自ドメインに変えることもできます。独自ドメインにはCloudflareでの準備が必要です。AIによる導入では、まず「独自ドメインを使用する」「使用しない（または、あとで設定する）」を確認します。使用する場合は、取得済みドメインの接続または新規取得の方法を案内します。既存ドメインの購入や移転が必須とは限りません。「Worker名」と尋ねるのではなく、管理画面と公開サイトのアドレスをそれぞれ改行して示し、先頭の選べる部分を平易に尋ねます。独自ドメインを使わない場合は管理用と公開用の2つの名前を別にします。独自ドメインを使う場合は公開用の workers.dev アドレスや名前を尋ねず、独自ドメインを表示します。アカウントのサブドメインなど確認できる情報はAIが調べ、URLの形式を例で説明し、名前は利用者に選んでもらって、作成前に管理・公開の両URLを確認します。AIから名前を推奨せず、候補を求められた場合にだけ答えます。メールアドレスやログイン情報から名前を推測・提案しません。設定例の名前は無断で使いません。入力フォームが使える場合は、管理用の名前と、必要な場合だけ公開用の名前・未登録のサブドメインを、別々の入力欄にまとめます。登録済みのサブドメインは確認結果として表示します。

公開URLをあとから変更する場合は、新しいドメインを公開用Workerに接続し、管理側の PUBLIC_SITE_URL を更新して管理用Workerをデプロイし直します。その後、管理画面で再構築し、新URL・ページ・画像・サイトマップ・RSSを確認します。外部リンクや検索結果の移行も必要になる場合があります。管理URLは別に選べます。管理URLの変更時は端末の再認証が必要になる場合があります。既存サイトに公開用の初期ページを再デプロイしないでください。

  1. npm ci、npx wrangler login を実行し、npx wrangler whoami で対象アカウントを確認します。npx wrangler d1 create mikanbox-cloud で新しいD1を作成し、表示されたIDを控えます。
  2. wrangler.production.example.json を wrangler.production.json に、wrangler.public.example.json を wrangler.public.json にコピーします。両ファイルの account_id に同じアカウントIDを設定します。管理側の name と vars.CLOUDFLARE_WORKER_NAME を同じ管理用の名前に、公開側の name と管理側の vars.CLOUDFLARE_PUBLIC_WORKER_NAME を同じ別の公開用の名前にします。管理側の vars.CLOUDFLARE_ACCOUNT_ID にアカウントIDを、vars.CLOUDFLARE_D1_ID と d1_databases[0].database_id に作成したD1のIDを設定します。PUBLIC_SITE_URL には実際の公開用HTTPS URLをパスなしで設定します（例 https://mikanbox-public.<サブドメイン>.workers.dev）。各設定ファイルはGitに含めません。
  3. 初回だけ npx wrangler deploy --config wrangler.public.json を実行し、公開用Workerに初期ページを配置します。既存の公開サイトにこのコマンドを再実行するとサイトが初期ページに置き換わります。 初期作成前に対象名を確認してください。

秘密ファイルをまだ作っていない新規サイトでは、例えば次のコマンドで2つの値を生成できます。既存ファイルがある場合は上書きせずエラーで止まります。登録時はファイル内の SETUP_TOKEN の値だけを自分のブラウザに入力してください。

node -e "const fs=require('node:fs'),c=require('node:crypto'); fs.writeFileSync('.env.production.secrets', 'JWT_SECRET='+c.randomBytes(32).toString('hex')+'\nSETUP_TOKEN='+c.randomBytes(32).toString('hex')+'\n', {flag:'wx',mode:0o600})"

このファイルは手順4のマイグレーションとデプロイの前に作成します。既存サイトの更新にはこの生成コマンドを使いません。

  1. インストールごとに暗号学的に安全な乱数で JWT_SECRET と一度だけ使う SETUP_TOKEN を生成し、.env.production.secrets に KEY=value 形式で保存します。AIによる導入でもローカルで生成し、値を会話やログに表示せず、初回登録に使うファイルの場所を利用者に伝えます。秘密は公開・コミットしません。npx wrangler d1 migrations apply DB --remote --config wrangler.production.json、npm run deploy:cloud の順に実行します。普段使うブラウザで管理URLの /admin を開き、初回端末を登録します。トークンを入力したブラウザが登録され、トークンは一度しか使えません。AIの内蔵ブラウザで登録すると、普段のブラウザには自動で引き継がれません。AIはローカルの秘密ファイルへのリンクを示し、普段使うブラウザで管理画面を開いてトークンを入力するよう伝えます。トークンを会話へ貼るよう求めません。公開設定とビルドの詳細は管理画面の案内に任せ、問題がある場合や尋ねられた場合に説明します。初期設定画面では「初期設定トークン（SETUP_TOKEN）」「ユーザーID」「表示名」「この端末の名前」を入力し、「この端末を登録」を押します。すでに別のブラウザで登録した場合は、登録済みブラウザの「サイト」→「端末とユーザー」から追加コードを作り、普段のブラウザを追加できます。
  2. Cloudflareで対象アカウントに限定した Workers Scripts Edit 権限のAPIトークンを作成し、管理画面の「サイト」→「Cloudflare公開設定」に保存します。Wranglerログインとは別のトークンです。D1の書き出し・復元も使う場合は別途D1編集権限が必要です。
  3. ページ一覧の「静的サイトをビルド」で公開し、公開URLを開きます。管理側の匿名アクセス、公開ページと画像、非公開ページ、更新と取り下げを確認します。ブラウザは完了まで開いておきます。

npm run deploy:cloud は管理用Workerだけを更新します。公開用Workerは管理画面のビルドで更新します。旧 npm run publish:static は分離構成では使用できません。

端末認証

パスワードはありません。管理画面に入れるのは、登録した端末（ブラウザ）だけです。 「端末とユーザー」は通常閉じており、端末の期限を変更するとその場に結果を表示します。端末のCookieには乱数のトークンを入れ、D1にはそのハッシュだけを保存します。

全体像

標準コンテンツ

初回設定時はSQLite版と同じ標準データを選択言語で取り込みます。日本語・英語それぞれページ8件（ホーム、404、検索、各見本、DB見本）とコンポーネント11件（レイアウト、ヘッダー、フッター、カード、検索、AI指示の見本など）です。

既存ページ・コンポーネントは上書きしません。今回の公開サイトでは、公開時に置いた仮トップページが未編集の場合に限り標準ホームへ置き換えます。設定・アカウント・秘密・以前のCloud版のデータはこの取り込みに含めません。

標準検索フォームの /index.php?page=search&q=... と /search?q=... に対応します。検索結果は公開ページだけを対象にし、下書き・承認待ち・DBは含めません。AI指示の DESIGN_sample.md / DESIGN.md を編集できます。AI質問の {{AI_QUESTION}} と {{AI_QUESTION:セクションID}} に対応します。外部取得の EXT_MD は未対応です。見本内の画像は同梱されていません。メディア画面から必要な画像をアップロードできます。

ページ・ページ編集

共通の操作はページとページ編集を参照してください。

現在の操作

ページと設定は取得時の内容を確認して保存し、競合した場合はエラーにして再読み込みを求めます。APIキー再発行を古い設定保存で巻き戻さないようにしています。ユーザーを削除すると、そのユーザーの端末も止まり、同じIDで作り直しても旧端末は使えません。

コンポーネントの直接JavaScript URLは /component-js/ID.js。ページ・コンポーネントのJavaScriptは管理者が記述するコードとして公開ページで実行されます。

ページIDを test/index とすると、/test/index.html、/test/index/、/test/、/test から表示できます。ビルドが必要です。test 自体のページもある場合はそちらを優先します。HTMLファイルと別名ルールを配信します。

DB状態のページは /api/ID でDATA/DATAROWを公開できます。下書き・承認待ちのページを公開ページのPOST_MD・ナビ・フィード・APIから読み出すことはできません。

管理画面のプレビューでは、配信前の画像も表示できます。プレビュー中に参照する画像だけに短時間有効なURLを発行し、プレビューの分離を維持します。

ページ一覧のプレビューは保存済みの内容を表示します。ページ編集画面のプレビューは未保存の入力内容を表示し、保存や公開は行いません。

サイト

共通の設定はサイトを参照してください。

アップデート

画像付きアップデートガイドでは、GitHubの画面を見ながら設定と更新ができます。

管理画面の「サイト」で、現在のバージョンとGitHub上の最新版を確認できます。「再確認」は最新版の情報を取り直します。管理画面のコードを更新した後は、画面自体を再読み込みして現在のバージョンを確認します。

更新方法は、ダウンロードして更新と、初回設定後にGitHubで実行する手動Actions更新の2つです。どちらも記事や画像を初期化するための操作ではありません。更新前には「データ移行・インポートツール」で必要なバックアップを保存してください。非公開データを含むため、安全に保管します。

方法1：ダウンロードして更新

AIに既存の管理画面URLとGitHubリポジトリのURLを伝え、「既存サイトを最新版に更新してください」と依頼することもできます。AIがダウンロードと設定確認を行い、Cloudflare認可が必要な場合は利用者が対象アカウントを確認して許可します。

自分でコマンドを実行する場合は、最新版のリリースページから Source code (zip) をダウンロードして展開し、そのフォルダで npm ci、npx wrangler login、npx wrangler whoami を実行します。Cloudflareのアカウントが既存サイトと一致していることを確認します。これは新規インストールではありません。既存のD1、管理Worker、公開Workerを使います。

設置時の wrangler.production.json を展開先に用意します。アカウントID、管理Worker名、D1 ID、R2を接続している場合のバインディング、ルートや独自ドメインが現在の実際の構成と一致することを確認します。設定が不明なら、Cloudflareの管理画面で既存Workerの設定とバインディングを確認し、正確な構成を復元するまで公開しないでください。新規用のサンプル値をそのまま使わないでください。

次に、次の2コマンドを順番に実行します。--keep-vars は既存の環境変数を保持します。既存のWorkerの秘密情報も保持されます。

npx wrangler d1 migrations apply DB --remote --config wrangler.production.json
npx wrangler deploy --config wrangler.production.json --keep-vars

既存サイト用に JWT_SECRET や SETUP_TOKEN を作り直さないでください。特に新しい秘密ファイルを使って npm run deploy:cloud を実行すると、登録済み端末の認証等に影響する可能性があります。公開側の初期ページ用 wrangler.public.json を既存サイトに再デプロイしないでください。公開サイトが初期ページに置き換わります。完了後は管理画面を再読み込みし、バージョン、記事、画像を確認します。

方法2：GitHub Actionsで手動更新

最初にGitHubの自分のリポジトリとCloudflareへの権限を設定します。以後は管理画面の「GitHubでアップデート」→ GitHubの Run workflow で実行します。自動実行はありません。毎回PCにダウンロードしたり、フォークに制作元のコードを同期したりする必要はありません。

初回1：自分のリポジトリを作る

  1. GitHubにログインし、制作元のリポジトリを開きます。
  2. 画面右上の Fork を押し、所有先を自分のアカウントにして Create fork を押します。すでに自分が管理するコピーがある場合はそれを使えます。制作元の所有者は同じアカウントにそのリポジトリをフォークできません。
  3. 作成した自分のリポジトリの Actions タブを開き、無効なら表示される有効化ボタンを押します。Update mikanBox Cloud が表示されることを確認します。ワークフローがない古いコピーでは、最新版の .github/workflows/update-cloud.yml を自分のリポジトリの既定ブランチに追加する必要があります。

初回2：更新先と権限を登録する

トークンを新しく作る場合は、Cloudflareダッシュボードのプロフィールから APIトークン → トークンを作成する を開き、「カスタムトークンを作成する」の 始める を押し、権限に「アカウント / Workers スクリプト / 編集」と「アカウント / D1 / 編集」を追加します。アカウントリソースで対象アカウントを指定し、概要に進む → トークンを作成する を押します。表示された値は再表示できないため、安全に控えます。トークンはGitHubのSecret欄へ直接貼り、チャットに送らないでください。

自分のリポジトリで Settings → Secrets and variables → Actions を開き、New repository secret から次の2件をそれぞれ登録します。Nameに名前、Secretに値を入れて Add secret を押します。制作元ではなく自分のリポジトリに登録してください。

初回3：実行してリンクを設定する

自分のリポジトリの Actions → Update mikanBox Cloud → Run workflow を開き、表示された Run workflow を押します。実行履歴を開き、Success になるまで待ちます。成功後、管理画面を再読み込みすると「GitHubでアップデート」が自分のリポジトリを開きます。管理画面に「手動アップデートの設定」がすでにある場合は、自分のリポジトリを 所有者/リポジトリ名 の形式で保存してリンクを設定することもできます。

v0.6.5以前でも、管理用・公開用のWorkerが分かれ、必要なアカウント・管理Worker・D1・公開Workerの設定とJWT_SECRETが存在し、D1/R2接続が一致するサイトなら、このActionsから最初の更新を実行できます。旧単一Worker構成にはそのまま使えません。

2回目から

  1. 管理画面「サイト」で新しいバージョンを確認し、GitHubでアップデートを押します。
  2. GitHubで Run workflow → 表示された Run workflow を押します。
  3. 実行履歴で Success を確認し、管理画面を再読み込みします。現在のバージョンと記事・画像を確認します。Failure の場合は失敗した工程を開いて内容を確認します。

Actionsは制作元の最新公開リリースを毎回取得します。公開プレリリースも対象です。フォーク側のワークフロー自体は自動更新されないため、その修正が公開された場合は自分のコピーにも反映する必要があります。Workers Buildsなど別の仕組みでGitHubへのpush時に自動デプロイしている場合は、手動更新とは別にその設定を確認してください。

Actionsは既存の管理WorkerとD1/R2の接続を照合し、ビルド、未適用D1マイグレーション、管理Workerの公開を行います。接続が違う場合や未対応の追加バインディングがある場合は中止します。接続やルートを変更したらGitHubに保存した設定も更新してください。DB更新とWorker公開は一つの処理ではないため、途中で失敗するとDBだけ更新済みの場合があります。失敗した工程と現在の状態を確認してから再実行してください。適用済みマイグレーションは再適用されません。

管理Workerの更新では公開用Workerは更新されません。公開ページ・画像への変更は管理画面の「静的サイトをビルド」で配信します。公開側の配信処理を変更するリリースでは、別途案内される公開側の更新が必要な場合があります。

公開用ファイルの取得はダウンロードとして扱い、管理画面の権限でコードを実行しません。公開ヘルプでは製品側のスクリプトだけを許可します。削除したページが配信先に残っている間は未反映として表示します。端末停止では、その端末が発行した未使用コードも取り消します。初期設定・復旧トークンは同時要求でも一度だけ使用できます。

管理画面はGitHubのCloud版リリース情報を確認し、現在と最新のバージョン、新版の有無を表示します。「再確認」は最新情報だけを取得します。現在のバージョンを更新後に確認するには画面を再読み込みしてください。手動更新の初回設定は下記を参照してください。CLOUD_RELEASE_MANIFEST_URL でHTTPSのCloud専用JSONを指定することもできます。

配信と取り下げ

公開ページは、静的ファイルとしてだけ配信します。閲覧でWorkerもD1も動かないため、Workerの1日あたりのリクエスト数とD1の読み出し行数を使いません。以前の「Worker配信」（WorkerがD1の生成済みHTMLや動的ページを配信する形）と、STATIC_DELIVERY の設定はなくなりました。

サイト内検索は、Googleのサイト内検索を使います。{{SEARCH_RESULTS}} は、Googleでこのサイトの中を検索するフォームになります（as_sitesearch にサイトURLを入れます）。検索ページ（ID search）も静的に公開し、標準の検索ボックス（_search_box）から index.php?page=search&q=… に送られた検索語は、検索ページからそのままGoogleへ渡します。Googleに登録されたページだけが見つかり、公開したばかりのページはしばらく出てきません。入力した言葉はGoogleに送られます。

ページの状態は、下書き・承認待ち・公開・DBの4つです。ページごとの静的・動的の選択はありません。「公開」のページは、ビルドでHTMLを作って配信します。以前の「公開(動的)」のページは、マイグレーション 0014 とバックアップの復元で「公開」になります。MCPやインポートで public_dynamic を指定しても、「公開」として保存します。

ビルド（再構築・配信更新）のボタンは、ページ一覧の下にあります。進み具合と結果はボタンの横に表示し、公開側に反映していない変更のページ数と、最後に公開した日時も表示します。

取り下げ

配信先に出したファイルはWorkerを通らないため、元データを消しても配信先に残ります。配信先から取り除くことを取り下げと呼びます。

ページの取り下げはビルドで行います。非公開にしたページと削除したページは、ビルドのときに配信先から取り除き、URL別名も取り消します。ビルドまでは読める状態が続きます。 公開をやめたら、ビルドも行ってください。

画像の削除時はメディア画面の操作が自動で取り下げます。名前変更・WebP変換時は次のビルドまで元の公開画像を維持します。「画像の静的配信」を参照してください。

公開と管理の分離

CLOUDFLARE_PUBLIC_WORKER_NAME（公開用のWorkerの名前）と PUBLIC_SITE_URL（公開サイトのURL）を設定すると、公開ページを別のWorkerに出力します。公開用のWorkerは静的ファイルだけで、プログラムは動きません。管理画面とMCPは今のWorkerに残ります。新規インストールはこの分離構成を使います。旧構成からの移行時は、公開先を確認してから設定してください。 ページ一覧のビルドボタンの近くに公開先URLを表示し、リンクから公開サイトを開けます。

管理画面操作

再構築ボタンで公開HTMLを生成し、配信も更新します。非公開・削除済みのページは同時に配信先から削除します。再構築までは以前の公開ファイルが残ります。画像はアップロード完了後に配信を更新し、削除では旧画像の取り下げも管理画面で行い、名前変更・WebP変換は次のビルドで公開側へ反映します。ブラウザから処理を小分けに進めるので、完了まで画面を開いておいてください。Workers編集権限を持つCloud版専用トークンが必要です。サイト設定の「Cloudflare公開設定」で入力し、暗号化して保存します。トークンは再表示せず、JSONバックアップにも含めません。トークンは最初に1回だけ作ります。作り直すのは、Cloudflare側でトークンを削除・失効させたとき、権限を変えたとき、サイトのJWT_SECRETを変えたとき、バックアップやTime Travelで別のDBへ戻したときだけです。トークンが未設定のときは、ページ一覧の「静的サイトをビルド」の下に案内が出ます。期限付きWranglerログインをWorkerへコピーしません。MCPの従来のbuild_ssgはHTML生成のみで、配信更新は管理画面か従来の公開コマンドが必要です。 Cloudflare APIがエラーの詳細を返した場合は、エラーコードとメッセージを表示します。 公開時は最新アップロード済みのWorkerバージョンが配信中と一致する必要があります。異なる場合は意図したバージョンを先にデプロイしてください。 分離構成では公開接続の保存時に公開用Workerへのアクセスを確認します。編集権限の実際の確認はビルド時に行われます。

画像のアップロードでは長辺2,000pxへの縮小を既定で選べます。JPEG・PNG・WebPのリサイズとWebP変換はブラウザで実行し、原本を処理後の画像に置き換えます。WebPへの名前変更ではページ・コンポーネントの参照も更新し、ページ履歴を残します。GIF・SVGのアップロードは原本のまま保存します。変換は16,000px以下かつ4,000万画素以下が対象です。

D1からR2への移行

最初はR2を有効にせずD1で利用できます。サイト画面の「メディアの保存先」で現在の保存先と使用量を確認し、「D1からR2へ移行」を実行します。これは画像の保存先の切り替えで、ページ・設定・ユーザーなどはD1に残ります。

R2の準備にはCloudflareで支払い方法を登録してR2を有効にする必要があります。無料枠内でも登録が必要です。バケットを作成し、WorkerのR2接続名を MEDIA にします。ローカルのWrangler設定にはテスト用接続がありますが、公開用設定にR2接続は追加していません。公開用 wrangler.production.json に次の設定を追加し、実際のバケット名でコードをデプロイしてください。この準備だけでは保存先は切り替わりません。

"r2_buckets": [{"binding": "MEDIA", "bucket_name": "実際のバケット名"}]

確認の画面で移行を開始します。1画像ずつコピーし、チェックサムとR2への保存結果を検証します。移行中はD1の原本を表示し、画像の追加・変更・削除を止めます。画面を閉じても、同じメニューから再開・中止できます。全件の確認が完了するとD1の画像データを除去し、R2の参照へ一括で切り替えます。未完了・失敗・中止ではD1の原本を保持します。成功後にD1へ戻すメニューはありません。移行前に完全JSONバックアップを保存してください。画像URLと本文中のファイル名は変わりません。

D1の画像上限は400 MBです。D1 Freeは1DB500 MB、Paidは1DB10 GBまでで、プラン変更は別途必要です。R2へ移行すると画像合計400 MBの制限を外し、1画像10 MB・10,000件の制限を維持します。R2 Standardの無料枠はアカウント全体で月間10 GB-month・書込み系100万回・読出し系1,000万回です。容量の上限ではなく超過分は課金されます。

サイト画面にはD1のDB使用量と、管理対象のR2容量（一時画像・保持画像を含む）を表示し、無料枠の80%程度で注意を表示します。他サイトや管理外のR2オブジェクトは含みません。実際のアカウント全体の使用量・リクエスト数・料金はCloudflareで確認してください。料金通知は利用を停止する機能ではありません。D1から画像を削除してもDBの確保済み領域がすぐ小さくなるとは限りません。

R2の書き換えは新しい一意のオブジェクトへ保存してからD1の参照を切り替えます。「不要な一時画像を整理」で、使用中・移行中・復元中の画像を除き、24時間以上保持した未使用画像を最大20件ずつ削除できます。完全JSONバックアップは画像も含み、D1・R2のどちらの保存先にも復元できます。復元先の保存先設定は維持します。D1復元は画像400 MB・現在と一時画像の合計450 MBまで、R2復元は原本と一時画像の両方を使用量に含めます。D1 Time TravelとSQL書き出しにはR2の画像実体が含まれず、古い参照先が整理済みの場合は戻せません。R2では完全JSONバックアップを使用してください。

画像は保存先にかかわらず公開URLが /media/ファイル名 です。公開済みの画像はStatic Assetsから配信し、未公開の画像はWorkerがD1/R2から配信します。生成済みのページHTMLもStatic Assetsから直接配信します。名前変更・WebP変換で更新した本文や部品を公開済みのHTMLへ反映するには、通常の再構築・配信更新が必要です。詳細は「画像の静的配信」を参照してください。

参考: D1の制限、R2の料金、R2の初期設定、料金と使用量。

JSONバックアップと復元

サイト設定の「データ移行・インポートツール」専用ページで、設定・すべてのページ・コンポーネント・履歴・静的HTML・ユーザー・画像原本を1つのJSONファイルでダウンロードし、そのファイルを選んで復元できます。SQLiteファイルではありません。画像は500KB単位で転送します。大容量では時間とブラウザのメモリを使うため、画面を閉じないでください。バックアップには非公開内容・APIキー・認証ハッシュが含まれます。安全に保管してください。設定などのメタデータは20MBまでです。

保存と復元は確認の画面だけで行います。通常の復元は現在のサイトID・APIキー・ユーザー・Cloudflare接続を維持します。「ユーザーも復元」を選ぶとユーザーも復元します。バックアップにないユーザーの端末は止まります。復元後に再構築してください。復元データを一時領域に保存し、欠損や同時編集があれば元のデータを保持して中止します。D1では現在と復元分・他の復元処理の一時画像の合計450MB以内が必要です。R2では原本と復元用の一時画像をR2に保存します。D1の実際の空き容量によっては、それより少なくても復元できません。

D1自体のバックアップ

D1のSQL書き出しと、指定時点にDB全体を戻すTime Travelは別の項目です。D1編集権限を持つ専用トークンが必要です。無料プランのTime Travelは直近7日間で、D1の画像原本・ユーザー・保存済み接続設定もその時点に戻りますが、R2の画像実体は含まれません。SQL書き出し中はD1が一時的に利用できず、動的処理が停止することがあります。完了まで画面を開いてください。Time Travelは配信中の静的ファイルを戻しません。復元後の再構築と、古い時点へ戻した場合のコード・DB構造の互換性確認が必要です。SQLファイルのアップロードによるD1復元は管理画面には実装していません。

大量の配信更新やバックアップはD1の読出し・書込みとWorkerリクエストを消費します。静的配信が無料でも更新処理は無制限ではなく、アカウント全体の無料枠を超えると中断します。最大20,000ファイルを毎日更新できるという保証ではありません。

静的HTMLのZIP出力

ビルド後、「データ移行・インポート」画面の「静的HTML（ZIP）」で「静的ZIPを保存」を選びます。ID.html と ID/index.html の構造を選べます。index はトップの index.html、末尾が /index のIDはディレクトリ構造でそのまま ディレクトリ/index.html になります。出力先が衝突する場合はエラーにします。

ビルド済みで現在も公開HTML状態のページだけを出力し、同梱ページへのリンクと画像・部品JSの参照を相対パスにします。使用画像と公開アセットを同梱します。動的ページ・検索・APIは元の公開サイトへのリンクとして残ります。APIキー・設定・ユーザー・非公開ページは入れません。ZIP内ではWebMCPを登録せず、AI質問欄はCloudヘルプへのリンクになります。

ZIP全体は20 MBまでで、画像読出し回数にも上限があります。出力画像が不足する場合はエラーにし、途中のZIPを渡しません。任意のJavaScript内の通信処理や、文字列形式のCSS @import は自動変換しません。これは静的サイトの持ち出し機能で、完全なD1バックアップではありません。

Macで作成したZIPに含まれる __MACOSX や ._ で始まる補助ファイルは自動的に無視します。

インポート画面の「ZIP内のファイルの置き方」を開くと、ページIDとフォルダ配置の例を確認できます。

更新・復元の途中で失敗した場合

JSON復元では、転送中のデータを一時領域に置き、全件の検証後に現在のデータと一括で切り替えます。画像の転送中に通信が切れた場合は、バックアップファイルを選び直して最初から復元してください。画面を開き直して転送位置から再開する機能はありません。

最後の復元操作で応答だけが届かなかった場合は、同じ操作を一度再試行し、保存済みの完了結果を確認します。完了済みの復元を再実行して、その後の編集を上書きすることはありません。完了を確認できないという表示が出た場合は、再読み込みしてページや画像の内容を確認してから再試行してください。ユーザーも復元した場合は、改めてログインが必要になることがあります。

「復元は完了しましたが、公開更新に失敗しました」と表示された場合、復元済みのデータは残っています。バックアップをもう一度取り込むのではなく、ページ一覧からサイトのビルドを再試行してください。

プログラムの更新は、ビルド、未適用DBマイグレーション、管理Workerの公開の順で行います。ビルド失敗時はDBを変更しません。DB更新後にWorkerの公開が失敗した場合、適用済みのDB更新は残ります。ログで失敗した工程を確認し、接続や権限などの原因を解消してから同じ更新手順を再実行してください。適用済みのマイグレーションを削除したり、初期設定をやり直したりする必要はありません。

データ入出力画面はSQLite版の状態カード・ZIP取込・WordPress XML取込・実行ログに合わせ、CSVとCloud固有のJSONバックアップ・復元を追加しています。ZIP/XMLは追加取込で既存IDを保持し、画像・アカウント・サイト設定は取り込みません。上限はファイル20MB、展開15MB、取込内容1MB、300件です。設定フォームとカテゴリ新規ボタンもPHP共通CSSに合わせています。

未公開の画像の変更にCloudflare公開設定は不要です。公開済み画像の削除・名前変更は取り下げのため配信更新を行うので、接続が必要です。名前変更は参照更新を選べる確認ダイアログを使います。完全バックアップ・容量・移行の仕様は「D1からR2への移行」を参照してください。

Cloud専用MCP

サイト画面でCloud専用のAPIキーを生成し、別ワークスペースから /mcp にBearerキー付きで接続します。ルートの .mcp.json は公式サーバー専用のままです。

現在のツールは get_site_info、list_pages、get_page、create_page、update_page、delete_page、list_components、get_component、create_component、update_component、delete_component、get_revisions、get_settings、get_ai_context、list_ai_docs、get_ai_doc、update_ai_doc、upload_media、build_ssg。

作成・更新はSQLite版と同じ id と各フィールドを直接渡す形式に対応し、従来の id と data も使えます。両形式で同じフィールドを重ねて指定しないでください。更新は未指定のフィールドを保持します。接続直後は get_site_info、続けて get_ai_context を呼びます。AI指示書IDの .md は省略できます。get_settings はAPIキー・認証情報・管理メモを返しません。編集操作には公開URLのディレクトリ省略ではなく正確なIDを指定します。

upload_media は filename と content_base64 を渡します。JPEG・PNG・GIF・WebP・SVGの10 MBまでです。任意の category は英数字・_・- に限り、ファイル名の接頭辞になります。同名は上書きせずエラーです。大きな画像ではBase64通信と変換処理が増えるため、通常の管理画面アップロードも使ってください。音声・動画や重複時の連番保存はPHP版と差があります。

管理用の互換URL /mikanBox/mcp と /mikanBox/mcp.php も同じキーが必要です。管理窓口と公開ヘルプ窓口は別です。

書き込み前には get_site_info のCloudサイトIDを確認してください。公式サイトIDはCloud版へ引き継ぎません。Cloud APIキーはサイトの管理操作権限を持つため公開しません。

公開ヘルプ・WebMCP

公開の /public-mcp はAPIキー不要・読み取り専用です。search_help、get_help_section、get_product_info、get_agent_instructions の4つだけを提供します。管理用 /mcp は引き続きキー必須です。/mikanBox/public-mcp.php は公開窓口の互換URLです。

公開済みの help_ja・help_en ページがあればその本文を読み、なければこのCloud専用マニュアルを使います。下書き・承認待ち・DB・管理情報・AI指示書・その他のページは公開窓口から読みません。Cloud専用マニュアルを更新したら node scripts/sync-cloud-help.mjs で同梱コピーを更新します（check/test/buildでも自動実行）。人向けヘルプは /public-help.html?language=ja または en です。

公開ページと管理画面にWebMCP用スクリプトを読み込みます。対応するブラウザ・エージェントで4つのヘルプツールを利用できます。未対応ブラウザでは登録を省略し、通常画面やAI質問欄は利用できます。ChromeのWebMCP APIに従う仕組みで、すべてのブラウザやAIクライアントで利用できるとは限りません。AI質問欄はCloudの公開ヘルプと公開MCPを参照し、APIキーや管理画面URLは外部AIへ渡しません。

デザイン

共通の操作はデザインを参照してください。

コンポーネント一覧

「AIに聞く」の右側に3版共通の絞り込みセレクタがあります。すべて、選択中のカテゴリ、ページ、パーツ、AI指示、標準コンポーネントを選べます。標準はID先頭の _ で判定します。通常の新規作成・複製では付けず、標準扱いを意図する場合は使用できます。保存は拒否しません。
「選択中のカテゴリ」は管理画面上部のカテゴリを使い、画像と同様にIDの接頭辞で判定します。例えば apps_header は apps カテゴリに含まれます。カテゴリ未選択時は絞り込みません。

ページ・コンポーネントのCSSは全版共通で自動挿入されます。で挿入位置を指定でき、複数ある場合は最初の1つにだけ出力し、残りは取り除きます。省略時は</head>直前、閉じタグがなければHTML先頭へ挿入します。コメントやscript/style/textarea/title内の文字列は挿入位置として扱いません。

デザインコンポーネントの「なし」、不足するhead情報の補完、サイト共通の計測ID・計測コード（head／body開始直後）とページ単位の除外に対応します。ページ編集の概要・本文の間隔、Raw HTMLチェック、JS欄の高さはPHP版に合わせています。詳しくは同梱の共通ヘルプを参照してください。

メディア

共通の操作はメディアを参照してください。

画像アップロードと制限

メディア欄で画像を選ぶか、画面へドラッグしてアップロードできます。ファイル名をクリックするとコピーできます。本文には ![説明](ファイル名.png) または {{IMAGE:ファイル名.png}} と書きます。「保存」リンクから個別にダウンロードできます。

ファイル名検索・カテゴリー絞り込み・ページ送りが使えます。表示件数はサイト設定の「メディア表示件数」に従います。カテゴリー絞り込みは、そのカテゴリーのページが参照する画像、またはカテゴリー名を接頭辞に持つ画像を対象にします。

D1構成の「名前変更」は本文・CSS・JavaScript・OGP画像・コンポーネントの参照先も更新します。拡張子変更と同名上書きはできません。メモと過去の履歴は書き換えません。参照更新するページの履歴を保存し、同時編集・競合があれば画像を含む操作全体を中止します。変更した静的ページは再ビルドが必要です。コンポーネントに参照があれば全静的HTMLを再ビルドしてください。参照データが大きすぎる場合は一括変更できません。外部サイトや独自JavaScriptで組み立てたURLまでは更新しません。

静的ビルドでは、ローカルの画像（JPEG / PNG / GIF / WebP。SVGは対象外）に、PHP版と同じ width・height と読み込みのヒント（最初の大きい画像は fetchpriority="high"、以降は loading="lazy"）を付けます。対象は ![説明](ファイル名) と {{IMAGE:}} で、直接書いた <img> は変えません。寸法は画像の先頭部分だけを読んで求め、保存はしません。1回のビルドで調べる画像は30枚までで、超えた分は属性なしになります。公開前のライブ表示と管理画面のプレビューでは付けません。

D1モードの400 MBはコンテンツ・履歴・DB管理領域の余地を残す画像用上限です。R2モードには適用しません。プラットフォームの容量上限に先に達すると保存できません。

D1 Freeの枠は読出し500万行/日、書込み10万行/日、DB合計5 GB。Workers Freeは1日10万リクエストです。D1の画像読出しは500 KBごとに1行を読み出します。R2配信では画像メタデータとR2オブジェクトを読み出します。これらの枠は同じアカウントの他のアプリとも共有します。Freeで日次上限に達すると処理が停止し、リセット後に再開します。アプリから契約を自動変更しません。既にPaid契約の場合はその料金体系に従います。

画像はアップロード後に公開されます。下書きのページだけで使う画像も対象です。公開してはいけない画像はアップロードしないでください。JS・CSSファイルはサイトのビルド時に公開されます。

メディア画面では画像変換の補足と最大ファイルサイズの行を省き、ページ内での利用方法を案内します。Markdownはファイル名だけ、HTMLは media/ファイル名 を標準とします。画像の従来の images/ファイル名 も利用できます。

メディアの名前変更やWebP変換では、変更先のファイルが既にある場合、元のファイルや公開中の画像を取り下げずに中止します。参照を更新するページが編集中の場合も、保存して編集を終了するまで中止します。失敗した理由は画像の操作欄に表示されます。

メディアの編集とカテゴリ

操作後も可能な範囲でメディア一覧のスクロール位置を保ちます。各画像の操作はPHP版と同じ「リサイズ▼」「名前変更▼」「WebP に変換」の順です。WebP変換はJPEG・PNGだけに表示し、ページ・コンポーネント・サイト共通OGPの参照を更新します。名前変更は拡張子を変えずに行います。上部のカテゴリ選択はファイル名の接頭辞でメディアを絞り込み、g_で始まる共通画像も表示します。アップロードには選択カテゴリの接頭辞が付与されます。

画像の静的配信

配信更新に画像を含めます。保存しているファイルは、どのページからも参照されていないものも含めて全件公開します。動的ページも静的ページと同じ /media/ファイル名 を読むためです。

公開済みの画像はStatic Assetsから配信します。管理画面のプレビューでは、配信前の画像も確認できます。メディア画面から画像をアップロードすると、その画像だけを自動で配信先へ追加し、ページのビルドは行いません。自動配信にはCloudflare公開設定と直前の配信状態が必要です。配信先が外部で変更された場合などは一度ビルドしてください。配信に失敗した画像は管理側に保存されたまま、公開未反映として通知します。MCPからのアップロードは自動配信の対象外です。

配信先の上限は1バージョンあたり20,000ファイル、1ファイル25 MiBです。画像は1ファイル10 MB・最大10,000件のため、ページとコンポーネントを合わせても上限内に収まります。

公開済み画像の名前変更・WebP変換では、公開中の元画像とHTMLは次のビルドまで維持されます。管理画面には変更後の画像と参照が保存され、次のビルドで公開側が切り替わります。元の公開ファイル名はビルドで取り除かれるまで再利用できません。画像を削除するときは、メディア画面が配信先からの取り下げを先に行います。

同じファイル名での差し替えは公開URLが変わらないため取り下げは不要です。ただし公開済みの画像は、配信更新を行うまで配信先に古い内容が残ります。

JS・CSSライブラリ

メディアでブラウザー用の .js・.css をアップロードできます。UTF-8の空でないテキスト、1ファイル10 MB以下を受け付け、元のコードをそのまま保存します。管理画面では実行せず、カードからURLや読み込みタグをコピーして、ページ本文・コンポーネントのHTMLに貼ります。アップロードだけでは自動挿入しません。信頼できる管理者・APIキーから、提供元を確認したコードをアップロードしてください。形式検査は安全性を保証しません。

カテゴリ接頭辞と画像変換は適用しません。種類による絞り込み、同じ拡張子のままの名前変更、削除に対応します。同名ファイルは上書きせず、別名でのアップロードを求めます。フォルダ階層をまとめてアップロードする機能はありません。

保存先はメディア設定のD1/R2に従い、公開URLは /media/ファイル名 です。完全JSONバックアップと復元、D1からR2への移行にも含まれます。コード欄の内容はD1に保存します。静的ページ公開では配信先の静的ファイルから配信します。「画像の静的配信」を参照してください。別サーバー向けの静的ZIPにはHTMLから参照するファイルを同梱します。

タグ

使用できないタグ

Markdown のリンク先で {{SITE_URL}} を使えます。コード例内のタグは展開しません。画像の名前変更では、サイト共通OGPだけで使っている場合も参照ありとして確認します。