SiteOps 導入ガイド

1. 事前準備

導入を始める前に、次のものを用意します。

手元に揃えておく情報

ディレクトリ構成

SiteOps専用フォルダは任意の場所に作成できます。既存サイトのフォルダとは完全に独立しており、位置関係の制約は「既存サイトのプロジェクト内には作らないこと」の1つです。配布ファイルは次の配置を前提にコマンドを記載します。

work/                    ← 任意の作業フォルダ(場所は自由)
├─ vendor/
│   └─ siteops.tgz       ← 受け取った配布ファイルをこの名前で配置
└─ company-siteops/      ← これから作成するSiteOps専用フォルダ

2. セットアップ

SiteOps専用プロジェクトを作成します。実行場所は配布ファイル(vendor/)を置いた作業フォルダで、既存サイトのフォルダとは無関係です。

配布ファイルの検証

リリースに記載されたSHA-512値と、次のコマンドの出力を照合します。

shasum -a 512 vendor/siteops.tgz
# Windows (PowerShell) — リリースノートの値を貼り付けると True/False で判定できます:
(Get-FileHash vendor\siteops.tgz -Algorithm SHA512).Hash -eq "<リリースノートのSHA-512>"

セットアップの実行

mkdir company-siteops
cd company-siteops
npm init -y
npm install ../vendor/siteops.tgz
npx siteops setup .

# 対話できない環境では2項目を引数で渡します
npx siteops setup . --yes --name "株式会社サンプル" --admin-email admin@example.com

SiteOps専用プロジェクトに作成されるもの

3. デプロイ

SiteOps本体(Worker、D1、R2、管理画面)を会社のCloudflareアカウントへ配置します。実行場所はSiteOps専用フォルダ(company-siteops/)です。

# 実行場所: company-siteops/
npm run siteops:deploy

成功すると SiteOps deployed、管理画面URL(Administration URL)、サイトデータの初期化確認が表示されます。初期化まで完了すると公開APIをすぐに利用できます。表示されたURL(SiteOps URLの /login)を開き、保存した管理者トークンでログインできることを確認します。

途中で止まった場合は npm run siteops:status が現在の進捗と次に実行するコマンドを表示します。

4. 既存サイトへの接続

SiteOpsと既存サイトの間に共有コードはなく、公開APIで接続します。接続情報の取得、公開URLの登録、既存サイト側の実装、の順に進めます。

1. 接続情報を取得npx siteops website manifest --json がSiteOps URL、SiteOps ID(APIパスの {siteKey})、記事・画像・フォームAPIのURLを返します。ブラウザへ渡るのは公開情報に限られます。
2. 公開URLと反映方式を登録npx siteops connect live --origin で登録し、もう一度 npm run siteops:deploy で反映します。方式は3つ: リクエスト時に表示するSSR・動的サイトは live、ビルド時にHTMLを生成する静的サイトは webhook、承認工程を挟む運用は manual(反映方式の詳細)。ビルドフックを用意できない検証環境や移行中は manual で開始し、後から connect webhook の再実行と再デプロイで切り替えられます。検証環境では http://127.0.0.1:8788 のようなURLも登録できます。成功すると反映方式と許可オリジン(Allowed origins)が表示されます。
3. 既存サイトへ実装下記の公開APIを既存サイトのデータ取得処理とフォームへ組み込みます。実装を終えたら既存サイトを普段の手順でデプロイし、「5. 動作確認」へ進みます。

# 実行場所: company-siteops/
npx siteops website manifest --json                             # 手順1
npx siteops connect live --origin "https://www.example.com"     # 手順2
npx siteops doctor                                              # 設定の点検(任意)
npm run siteops:deploy                                          # 手順2の反映
# 手順3: 下記の実装 → 既存サイトを普段の手順でデプロイ
npm run siteops:verify

https://www.example.com は実際の公開URLへ置き換えます。静的サイトの反映方式は記事の反映方式、メールを使う場合はメール接続を参照してください。

公開APIエンドポイント

website manifest --json が実際のURLへ展開した一覧を返します。管理トークンを使わず、公開済みデータとフォーム受付に接続できます。

セットアップ直後から使える既定リソース

コンテンツタイプとフォームは、次のものが最初から用意されています。管理画面で項目の追加・変更ができます。

記事エントリの構造

一覧は {entries: [...]} 、詳細は {entry: {...}} を返します。既定の編集画面では本文(body)はプレーンテキスト(段落は空行区切り)で保存されるため、HTMLへの変換はサイト側で行います。

{
  "entries": [
    {
      "slug": "sakura-no-ie-open-house",
      "publishedAt": "2026-07-17T03:25:00.000Z",
      "updatedAt": "2026-07-17T03:25:00.000Z",
      "data": {
        "title": "新モデルハウス完成見学会",
        "displayDate": "2026-07-20",
        "category": "イベント",
        "excerpt": "一覧や検索結果に見せる概要",
        "body": "本文はプレーンテキストで返ります。\n\n段落は空行で区切られます。",
        "seoTitle": "SEOタイトル(任意)",
        "seoDescription": "SEO説明(任意)"
      }
    }
  ]
}

記事一覧と記事詳細の実装

サーバー側(SSR、ビルド処理)で公開APIを取得し、title、meta description、canonical、構造化データを既存サイトのHTMLへ出力します。"news"はコンテンツタイプ(記事の種類を表すID)で、管理画面の記事設定と一致させます。

const SITEOPS_URL = "https://siteops-xxxxx.workers.dev"; // manifestのSITEOPS_URL
const SITE_KEY = "main";                                  // manifestのSITEOPS_SITE_KEY
const api = SITEOPS_URL + "/api/public/sites/" + SITE_KEY;

const list = await fetch(api + "/content/news/entries");
const { entries } = await list.json();

const detail = await fetch(api + "/content/news/entries/" + slug);
if (detail.status === 404) {
  // 既存サイトの404処理へ接続
}
const { entry } = await detail.json();

問い合わせフォームの実装

フォームはブラウザから公開APIへ直接送信します。許可オリジンの検証、レート制限、サイズ上限、Turnstileの検証はSiteOps側で実行されます。contactは管理画面で作成したフォームID、JSONの各キーは受付項目のキーと一致させます。Turnstileのウィジェット作成と秘密キーの登録は、フォーム保護の設定を参照してください。

const response = await fetch(api + "/forms/contact/submissions", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    name,
    email,
    message,
    turnstileToken // フォーム保護がTurnstileの場合。未設定(none)なら省略できます
  })
});

const result = await response.json();
if (!response.ok || result.accepted !== true) {
  throw new Error(result.error || "inquiry_submission_failed");
}

1. フォーム保護設定を読むGET .../forms/security からTurnstileの公開キーとactionを取得し、ウィジェットへ渡します。
2. 公開APIへ直接送信するSiteOpsが許可オリジン、サイズ、Turnstileを検証して問い合わせ一覧へ保存します。
3. 保存結果で完了表示を出すaccepted: trueを受付完了として扱います。メール通知の結果はレスポンスのdeliveryフィールドへ分かれて返ります。

許可オリジンの検証は、ブラウザからの送信(Originヘッダー付き)に適用されます。Originヘッダーを送らないサーバー間リクエストはこの検証の対象外で、ボット対策の実体はTurnstileです。

5. 動作確認

公開前に、SiteOps本体、既存サイト、フォーム、メール(設定した場合)を確認します。

npx siteops doctor --remote
npm run siteops:verify
npx siteops backup create
npx siteops backup verify backups/<作成されたディレクトリ>

backup createが保存先(既定はbackups/日時)を表示し、その値をbackup verifyへ渡します。

チェックリストの確認コマンド例

# 下書きが公開APIへ出ないこと(公開前のslugは404)
curl -i {SITEOPS_URL}/api/public/sites/{siteKey}/content/news/entries/下書きのslug

# 許可していないオリジンからのブラウザ送信が拒否されること(403)
curl -i -H "Origin: https://evil.example.com" {SITEOPS_URL}/api/public/sites/{siteKey}/forms/security

siteops verify 成功時の表示

PASS  runtime          SiteOps本体へ接続できました (312 ms)。
PASS  website          公開APIが https://www.example.com からの接続を許可しています(フォーム保護: turnstile)。ページ表示とフォームは既存サイト側で確認します。

FAILが1件でもあると終了コード1で停止し、原因の場所と次の対処を表示します。

メール接続

基本セットアップでフォームの問い合わせを管理画面へ保存できます。社内通知、受付メール、管理画面からの返信を使う段階で送信サービスを接続します。

npx siteops mail setup disabled
npx siteops deploy

npx siteops cloudflare connect \
  --from-email no-reply@example.com \
  --from-name "Example Company" \
  --reply-to contact@example.com \
  --notification-emails team@example.com \
  --forms-only

npx siteops cloudflare connect \
  --from-email no-reply@example.com \
  --from-name "Example Company" \
  --reply-to contact@example.com \
  --notification-emails team@example.com \
  --addresses contact@example.com,support@example.com

npx siteops mail setup sendgrid \
  --from-email no-reply@example.com \
  --from-name "Example Company" \
  --reply-to contact@example.com
npx siteops secret set SITEOPS_SENDGRID_API_KEY
npx siteops deploy

npx siteops mail setup ses \
  --from-email no-reply@example.com \
  --from-name "Example Company" \
  --reply-to contact@example.com \
  --region ap-northeast-1
npx siteops secret set SITEOPS_AWS_ACCESS_KEY_ID
npx siteops secret set SITEOPS_AWS_SECRET_ACCESS_KEY
npx siteops deploy

npx siteops mail setup agentic-inbox \
  --from-email support@example.com \
  --from-name "Example Company" \
  --base-url https://inbox.example.com \
  --mailbox support@example.com
npx siteops secret set SITEOPS_AGENTIC_INBOX_ACCESS_CLIENT_ID
npx siteops secret set SITEOPS_AGENTIC_INBOX_ACCESS_CLIENT_SECRET
npx siteops deploy

トラブルシューティング

導入はどの段階からでも再開できます。