AWSの設定・運用リファレンス

この手順では、さくらVPSの静的サイトとAWS上の送信処理を別々に配置する。AWSリソースの作成、AWS版での実メール送信、本番サイトへの反映は行っていない。自前版については試験環境での送信・受信が利用者から報告されているが、AWS版の確認を代替するものではない。

初めてAWSへ構築する場合は、AWSセットアップ手順から始める。認証、環境の分離、送信無効での初回デプロイ、設定確認後の有効化を順に記載している。

APIの要求・応答と再試行は両方式共通のAPI仕様に従う。自前版の配置は自前サーバーのセットアップを参照する。以下はAWS版の手順である。

フロント設定の読み込み、ビルド成果物の取り違え、APIの502とSMTP失敗の判別は試験環境のトラブルシューティングも参照する。systemd・内部IPなどの項目は自前版だけに適用する。

1. ファイルと必要なツール

場所 内容
src/pages/contact/、src/scripts/contact*.ts 入力・確認・送信画面
backend/contact-form/ Lambdaの実装、専用の依存関係、単体テスト
infra/contact-form/template.yaml AWS SAMによる構築定義
.env.example ブラウザーへ公開する設定の記入例

Webサイトの開発とバックエンド全体のテストにはNode.js 24系を使用する。Lambdaの実行環境はNode.js 22系を維持する。AWSの構築には、別途AWS CLIとAWS SAM CLI、および対象AWSアカウントの認証設定が必要になる。コマンドはリポジトリのルートから実行する。

npm ci
npm ci --prefix backend/contact-form
npm test --prefix backend/contact-form
npm run check
npm run build

AWSの認証情報をリポジトリへ保存しない。SAMは実行者のAWS認証設定を利用する。検証環境と本番環境はスタック名、Lambda関数名、秘密情報、Turnstileキーを分ける。

2. Secrets Managerへの登録

東京リージョンのSecrets Managerへ、次のJSONをそれぞれ別のシークレットとして登録する。下記は書式の例で、実際に接続できる値ではない。実値をGit、コマンド引数、公開環境変数へ保存しない。

SMTP用:

{
  "host": "SMTP接続先のホスト名",
  "port": 587,
  "user": "SMTPユーザー名",
  "password": "SMTPパスワード",
  "idempotencyKey": "64桁の16進数"
}

portは数値の587または465にする。587ではSTARTTLS、465では接続開始時からTLSを使用する。SMTPアカウントにはFromとして送信できるアドレスを設定し、可能ならフォーム専用にする。

idempotencyKeyは、入力値をそのまま保存せずに同じ要求かを照合するための秘密値である。暗号学的乱数32バイトを16進数に変換した64桁の値を使用する。SMTPパスワードを更新するときも、この値は維持する。変更すると過去の要求と照合できなくなり、同じ受付IDへの確認要求は競合として扱われる。

Turnstile用:

{
  "secret": "Turnstileの秘密鍵"
}

SAMテンプレートにはシークレットのARNだけを渡す。テンプレートはシークレット自体を作成しない。既定のSecrets Manager管理キーを使用する前提で、独自のKMSキーを使う場合は、そのキーへの復号権限も確認する。

Lambdaは取得した秘密情報を最大5分キャッシュする。更新を即時に反映する必要がある場合は、秘密情報の更新後にLambdaの実行環境を更新する。手順と権限は本番運用前に確認する。

3. AWSの構築

sam validate --lint --template-file infra/contact-form/template.yaml --region ap-northeast-1
sam build --template-file infra/contact-form/template.yaml --build-dir .aws-sam/contact-form

デプロイではビルド済みの.aws-sam/contact-form/template.yamlを指定する。プロファイル、設定ファイル、環境別パラメーターを含めたコマンドは初回デプロイの手順に従う。sam deployでIAM権限の作成を承認する必要があり、AWSリソースと課金対象が作成される。

パラメーター 内容・初期値
FunctionName 関数名。初期値はtectas-contact。別環境では別名を指定
AllowedOrigin 本番サイトのオリジン。初期値はhttps://www.tectas.co.jp。末尾の/は付けない
MailFrom 固定の差出人アドレス。1アドレスのみ
MailTo 固定のTo宛先。複数の場合はoffice@example.com,sales@example.comのようにカンマ区切り
SmtpSecretArn SMTP用シークレットのARN
TurnstileSecretArn Turnstile用シークレットのARN
HourlyLimit JSTの毎時区切りの試行上限。初期値10
DailyLimit JSTの0時区切りの試行上限。初期値30
IpHourlyLimit / IpDailyLimit IP別の送信試行上限。初期値3件/時・10件/日
SendingEnabled 送信の許可。初期値false。準備が終わるまで無効にする
NotificationEmail 管理者通知先。空欄ならメール購読を作成しない

時間・日単位の上限は運用開始時の設定例であり、月100件という利用想定から算出した上限ではない。許容する集中投稿数を確認して調整する。APIの初期レートは毎秒1要求、バースト3、Lambdaの同時実行数は2、タイムアウトは45秒に設定している。

SNSの通知先を指定した場合、管理者は届いた購読確認メールから登録を完了する。確認前には通知メールが届かない。通知は運用担当者向けであり、投稿者へは送らない。

4. Turnstileと静的サイトの設定

Turnstileの本番ウィジェットにはサイトのホスト名を許可する。LambdaはAllowedOriginのホスト名とaction: contactの組み合わせでトークンを検証する。サイトキーと秘密鍵は同じウィジェットのものを使う。

.env.exampleを参考に、ローカルの.envへ次を設定する。ここに指定する値はブラウザーへ公開される。

PUBLIC_CONTACT_API_URL=https://API-ID.execute-api.ap-northeast-1.amazonaws.com/contact
PUBLIC_TURNSTILE_SITE_KEY=Turnstileのサイトキー

APIのURLはSAMの出力ContactApiUrlを使う。SMTPの認証情報とTurnstileの秘密鍵は、PUBLIC_変数へ入れない。本番では、これらの値をGitLabのCI/CD変数(環境スコープproduction)へ登録し、タグを作成して再ビルド・配置する。手順は静的サイトの自動デプロイに従う。

npm run build

設定が空の場合も画面は表示できるが、送信操作時に電話での問い合わせを案内し、通信しない。開発環境でHTTPを使う場合、APIのURLはlocalhostまたは127.0.0.1に限る。本番成果物ではHTTPSを要求する。

Turnstileのスクリプトは送信操作時に読み込む。CSPなどで外部接続を制限している環境では、CloudflareのTurnstile公式手順に従ってchallenges.cloudflare.comのスクリプト・フレームと、APIへの接続を許可する。認証だけのテストキーを本番で使用しない。

5. APIと重複送信

要求・応答、状態、保存期間、再試行はAPI共通仕様を参照する。AWS版はDynamoDBに受付ID、入力値のHMAC、処理状態、削除期限を保存し、本文・氏名・メールアドレスは保存しない。

6. 公開前の確認

検証環境のSMTPアカウントと受信先を使い、正常送信、認証エラー、上限到達、成否不明時の動作を確認する。実メール送信は本番と分離し、受信先担当者と調整する。

リポジトリ内の自動確認では、以下のコマンドを使う。画面テストは既存のローカルサーバーを利用し、Turnstileと送信APIを代替応答へ差し替える。実メールやアクセス解析は送信しない。

npm test --prefix backend/contact-form
npm run check
npm run build
# 別ターミナルで npm run dev を起動してから実行
npm run qa:contact

このうちバックエンドのテスト、npm run check、npm run buildは、GitLab CIでも自動で実行する。CIではLambdaの実行環境に合わせ、Lambda経路のテストをNode.js 22系でも実行する。SAMテンプレートもcfn-lintで検査する。npm run qa:contactはWindows版Chromeを前提とするためCIの対象外で、作業端末で実行する。詳細はCI/CD運用手順を参照する。

単体テストでは入力、Turnstile、DynamoDBトランザクションの要求、SMTP失敗分類、同時要求を検証する。実際のDynamoDBやSMTPを使用する結合試験は別途必要になる。

7. 監視・停止・保存期間

CloudWatchのログは30日保持する。SMTP送信失敗・成否不明・依存サービスの障害をメトリクスフィルターで数え、5分間に1件以上で通知する。Lambdaのエラー、5分間に5件以上のスロットリング、APIの5xxについてもアラームを設定する。

全体送信枠を超えた要求はglobal_quota_exceededで記録し、5分間に1件以上で通知する。APIの4xxも5分間に10件以上で通知する。4xxにはAPI Gatewayの429と、アプリの入力・認証エラー等が含まれる。個別の原因はアプリの結果分類と照合する。IP別上限の拒否はip_quota_exceededとして記録する。

メトリクスフィルターでカスタムメトリクスを2種類作るため、基本のログ料金やアラーム料金に加えて料金が発生する。過去の概算には追加カスタムメトリクスを含めていないため、実際の見積もりではこの分を加える。

現行のHTTP APIはWAFの直接関連付けに対応していない。今回の変更ではAPI構成・毎秒1要求・同時実行2件を維持するため、偽トークンによる処理枠の占有への入口対策は未完了である。WAFを導入する構成の選択と必要な検証は受付制限と停止攻撃への対策を参照する。

ログには受付時に発行したreceiptId、結果分類、処理時間を記録する。本文、氏名、メールアドレス、秘密情報、SMTPの生の応答を出力しない。受信メールの保存期間とアクセス権限は、メール運用側で管理する。

通常の停止はSendingEnabled=falseへのスタック更新で行う。緊急時はLambdaの予約済み同時実行数を0にし、新しい実行を止める。どちらも開始済みの送信を取り消すものではない。設定をコンソールで変更した場合は、後でSAM定義と実環境を一致させる。

スタック削除時もDynamoDBテーブルは保持する。記録を含めて廃止する場合は、保持の必要性を確認してからテーブルを別途削除する。既存シークレットは本スタックの管理外なので、スタック削除では消えない。