放課後リンク 開発仕様

Appearance

Cloudflare デプロイ・運用ガイド (Cloudflare Deployment Guide) ​

本ドキュメントでは、バックエンドAPIおよび各種PWAアプリを Cloudflare プラットフォームへデプロイする際に、現行の Workers / D1 / KV / R2 / Queues 構成と、本番環境のセキュリティ設定を確認する手順を解説します。PWAのホスティング設定（Pages等）は配布環境ごとに別途確定してください。

1. サーバーレスインフラの設計構成 ​

システムは Cloudflare の以下のサービスを組み合わせて構成されています。

2. インフラのプロビジョニング手順 ​

ローカルのコマンドラインから Cloudflare のリソースを作成します。

2.1 D1 データベースの作成 ​

本番環境用と検証（Staging）環境用の2つのデータベースを作成します。

bash
# 本番用データベース作成
npx wrangler d1 create houkago_link_d1

# 検証用データベース作成
npx wrangler d1 create houkago_link_d1_test

作成完了後、ターミナルに表示されるデータベースID（UUID）をメモし、wrangler.toml の database_id に設定してください。

2.2 KV ネームスペースの作成 ​

認証セッションのキャッシュや失効JTIを格納するKVを作成します。アプリ側のbinding名は KV_AUTH です。

bash
# 本番用 KV ネームスペース作成
npx wrangler kv namespace create KV_AUTH_PROD

# 検証用 KV ネームスペース作成
npx wrangler kv namespace create KV_AUTH_STAGING

出力された id を wrangler.toml の kv_namespaces に、binding = "KV_AUTH" として反映します。既存のnamespaceを再作成せず、対象環境のIDを照合してください。

2.3 Queues (非同期メッセージキュー) の作成 ​

FCMプッシュ通知の遅延送信やリトライ処理を制御するためのキューを作成します。現行の本番設定では EVENT_QUEUE producer と同一キューのconsumerを使用します。ローカル開発でbindingを省略した場合だけ、APIが ctx.waitUntil で直接処理します。

bash
# プッシュ通知配信用キュー作成
npx wrangler queues create push-notification-queue

# staging用（未作成の場合）
npx wrangler queues create push-notification-queue-staging

3. Wrangler Configuration (wrangler.toml) の構成 ​

API のルートディレクトリ（app/api）に配置する設定ファイルの構造例です。

toml
name = "houkago-link-api"
main = "src/index.ts"
compatibility_date = "2026-04-21"
compatibility_flags = ["nodejs_compat"]

# 環境変数 (非暗号化データ)
[vars]
NODE_ENV = "production"
REQUIRE_CSRF_ORIGIN_CHECK = "true"
ALLOWED_ORIGINS = "https://guardian.amga.jp,https://staff.amga.jp,https://localhost,capacitor://localhost"
# Provider の実配信Originを確定後、別途 `PROVIDER_ORIGIN` として設定する。
# 例: PROVIDER_ORIGIN = "https://provider.example.jp"
UPDATE_BASE_URL = "https://api.amga.jp/update"
DISABLE_BACKGROUND_TASKS = "false"

# Cloudflare KV ネームスペースのバインド
[[kv_namespaces]]
binding = "KV_AUTH"
id = "xxxx-xxxx-xxxx-session-prod-id"

# Cloudflare D1 データベースのバインド
[[d1_databases]]
binding = "DB"
database_name = "houkago_link_d1"
database_id = "xxxx-xxxx-xxxx-db-prod-id"

# Cloudflare Queues のバインド
[[queues.producers]]
queue = "push-notification-queue"
binding = "EVENT_QUEUE"

# キュー・コンシューマー（受信バインド）の設定
[[queues.consumers]]
queue = "push-notification-queue"
max_batch_size = 10
max_batch_timeout = 5
max_retries = 3

# Cloudflare R2（帳票・ファイル保存）
[[r2_buckets]]
binding = "REPORTS_BUCKET"
bucket_name = "houkago-link-reports"

検証環境は [env.staging] 配下に別名のD1、KV、R2、Queueを設定します。現行設定のQueue名は push-notification-queue-staging です。database_id やnamespace IDは実環境の値に置き換え、productionとstagingで共有しないでください。

4. シークレット環境変数の設定 ​

暗号キーや外部APIキーなど、バージョン管理に含めてはいけない機密情報は wrangler secret コマンドを使用して暗号化環境変数として Cloudflare に登録します。

bash
# JWT認証トークンの暗号化キー
npx wrangler secret put JWT_SECRET
# アクセストークン・リフレッシュトークンを分離する場合は両方を登録
npx wrangler secret put ACCESS_TOKEN_SECRET
npx wrangler secret put REFRESH_TOKEN_SECRET
# Provider API の機械間認証を使う場合
npx wrangler secret put PROVIDER_API_SECRET

# APIフィールド暗号化用のbase64 32バイト鍵
npx wrangler secret put ENCRYPTION_KEY

# Firebase Cloud Messaging 送信用のサービスアカウントJSON文字列
npx wrangler secret put FIREBASE_SERVICE_ACCOUNT

# LINE連携を有効にする場合
npx wrangler secret put LINE_CHANNEL_SECRET
npx wrangler secret put LINE_CHANNEL_ACCESS_TOKEN
npx wrangler secret put LINE_CHANNEL_ID

# Kiosk連携・QR受け取りを有効にする場合
npx wrangler secret put KIOSK_API_KEY
npx wrangler secret put KIOSK_QR_SECRET

# 更新マニフェスト署名検証を有効にする場合
npx wrangler secret put UPDATE_SIGNING_PUBLIC_KEY
# または鍵ローテーション用のJSONマップ
npx wrangler secret put UPDATE_SIGNING_PUBLIC_KEYS

AUDIT_LOG_SALT と FIREBASE_SERVICE_ACCOUNT_JSON は現行実装で参照していないため、設定名として使用しません。必要なSecretは機能と環境ごとに登録し、値をログやリポジトリへ出力しないでください。

Provider PortalをJWTで利用する場合は、通常のtenant adminを流用せず、Provider専用の管理組織を作成したうえで、その組織IDをWorkerの非Secret設定 PROVIDER_ADMIN_ORGANIZATION_ID に登録します。Providerの組織一覧・全体設定・端末ログはこの組織に属するadmin、または X-Provider-Token に正しい PROVIDER_API_SECRET を付けた機械間クライアントだけが利用できます。専用組織IDが未設定の場合、JWT経由のProvider APIは503でfail closedになります。

POST /v1/demo/seed はデータを全削除して再生成するため、NODE_ENV=production ではトークンが一致しても拒否されます。デモ用トークンは開発・ステージング環境だけに登録してください。

5. APIコードのデプロイ ​

設定とシークレットの登録が終わったら、本番環境へのデプロイを実行します。

bash
cd app/api
npm run deploy
# 同等の直接コマンド: npx wrangler deploy

デプロイ完了後、割り当てられたエンドポイント（例: https://api.amga.jp）に対してブラウザまたは curl でヘルスチェックを行います。

bash
curl https://api.amga.jp/health
# 応答: {"status":"ok","worker":"cloudflare"}
curl https://api.amga.jp/v1/health
# 応答: {"status":"healthy","services":{"database":"ok",...}}

6. Cloudflare Zero Trust (Access) と WAF による保護設定 ​

保護者および職員が利用する公式オンラインマニュアル Pages は、無許可の一般アクセスから防御するために Cloudflare Zero Trust を適用します。

6.1 Cloudflare Access の適用手順 ​

  1. Cloudflare ダッシュボードにログインし、[Zero Trust] ＞ [Access] ＞ [Applications] を開きます。
  2. [Add an Application] をクリックし、[Self-hosted] または [Bookmark] を選択します。
  3. アプリケーション名（例: Official Manuals）と、保護対象のドメイン（例: docs.amga.jp）を設定します。
  4. Identity Providers: ログイン認証に使用するプロバイダー（例: Google Workspace、Microsoft Entra ID、または One-Time Pin）を紐付けます。
  5. Policies: 閲覧を許可するメールアドレスのドメイン（例: @amga.jp）や、特定の保護者認証をパスしたJWTトークンによるアクセスを許可するポリシーを設定します。

AccessとWAFはこのリポジトリの wrangler.toml だけでは有効化されません。ダッシュボードまたは別のIaCで設定した内容を、本番リリース記録へ残してください。

6.2 WAF (Web Application Firewall) カスタムルールの導入 ​

API サーバーのエンドポイントに対する DOS 攻撃や SQL インジェクションを防ぐため、WAF ルールを設定します。

  • レートリミットルール: 同一IPアドレスからの API 接続を「10秒間に最大100リクエスト」に制限。
  • Geo-blocking: 海外からの不正アクセスを遮断するため、接続元国コードが「JP（日本）」以外のトラフィックに対して JS Challenge（ボット検証）を強制。
  • OWASP コアルールセット: Cloudflare マネージドルールを「High (高感度)」で有効化し、一般的な脆弱性スキャンを自動検知してブロック。

放課後リンク 開発プロジェクト

Copyright © 2026 NGS / takao-dev. All Rights Reserved.