試験環境のトラブルシューティング¶
2026年11月10日のセットアップで発生した問題と、実装に沿った切り分け方法をまとめる。試験環境はNGINXが192.168.15.20、アプリが192.168.15.19:3001である。以下のIPは環境に合わせて置き換える。
利用者からは、SMTPホスト名を修正した後にブラウザーからの送信と受信が成功したと報告されている。Turnstileを省略した試験であり、実TurnstileやAWS版の動作確認とは区別する。
最初に見る場所¶
ブラウザーの開発者ツールでNetworkを開き、送信時の/api/contactのURL、HTTPステータス、Responseを確認する。HTTPステータスだけで判断せず、APIのJSONがあるかを確認すると、調べる場所を絞れる。
| 症状・応答 | 確認する場所 |
|---|---|
| 「現在フォームからのお問い合わせを受け付けできません。」 | フロントに埋め込まれたAPI URL・Turnstile設定。APIへの要求前に表示するメッセージ |
| curlの証明書エラー | NGINXの証明書とURLのIP・ホスト名。HTTP要求を送る前のエラー |
403・origin_rejected |
アプリのALLOWED_ORIGINと要求のOrigin |
400・invalid_input |
入力項目。空のJSONによる疎通確認では想定結果になる |
404・not_found |
NGINXの転送先パス。内部APIは/contact |
| 502でnginxのHTML | APIの起動、待受IP・ポート、通信許可、NGINXのログ |
502でdelivery_failedのJSON |
API内のSMTP送信処理 |
503・dependency_error |
停止設定、処理数超過、DB・秘密情報・外部サービスの障害など |
processing・delivery_unknown |
処理中・成否不明。受信側とログで確認し、安易に新規投稿しない |
429・rate_limited |
件数制限。失敗したSMTP送信も送信枠を消費する |
画面で受付できないと表示される¶
今回、表示中のHTMLはapi: ""、turnstile: "true"だった。.env.exampleを編集しても、そのファイルは設定として読み込まれない。リポジトリ直下の.env.preview.localに次を設定する。
PUBLIC_CONTACT_API_URL=https://192.168.15.20/api/contact
PUBLIC_CONTACT_TURNSTILE_ENABLED=false
PUBLIC_TURNSTILE_SITE_KEY=
npm run build:preview
dist-preview/の中身をNGINXの公開ディレクトリへ配置し、強制再読み込みする。npm run buildとdist/の組み合わせでは、.env.preview.localの設定は反映されない。
ブラウザーのConsoleで、実際に読み込まれたHTMLを確認する。
const contact = document.querySelector('.contact-layout');
({
api: contact?.dataset.contactApi,
turnstile: contact?.dataset.turnstileEnabled
});
今回の試験設定なら、apiがhttps://192.168.15.20/api/contact、turnstileが文字列の"false"になればよい。値が古い場合はビルドモード、配置したフォルダ、NGINXのroot、ブラウザーのキャッシュを確認する。
Originが拒否される¶
APIとNGINXのどちらのサーバーでcurlを実行しても、-Hで同じOriginを送れば判定は同じになる。比較対象は接続元IPではなく、要求ヘッダーのOriginである。
アプリサーバーで次を確認する。
sudo grep '^ALLOWED_ORIGIN=' /etc/tectas-contact/contact.env
sudo systemctl cat tectas-contact
設定値はALLOWED_ORIGIN=https://192.168.15.20とする。末尾の/や/contact/を含めず、HTTPSとHTTPを取り違えない。443以外のポートで開く場合は、そのポートも一致させる。
systemdのEnvironmentFileが編集したファイルを指していることを確認し、sudo systemctl restart tectas-contactを実行する。今回の試験では、この修正後に空のJSONへの応答が403から400・invalid_inputに変わり、入力検証まで到達した。
証明書の対象名とIPが一致しない¶
no alternative certificate subject name matches target host nameは、URLのIPまたはホスト名が証明書のSANに含まれない場合のエラーである。NGINXからAPIへの接続失敗とは異なる。
IP直で利用するならそのIPをSANに含む証明書、ホスト名で利用するならそのホスト名の証明書を設定する。テスト用CAを使う場合はクライアントで信頼させる。--cacertによるCAの指定だけでは、対象名の不一致は解消しない。
転送処理だけを一時的に確認する場合は、curlの-kで証明書検証を省略できる。今回の切り分けでも次のコマンドでAPIの400応答を確認した。-kはこのcurlだけに作用し、ブラウザーの証明書問題を解消するものではない。公開環境では検証を省略しない。curl公式資料
curl -k -i https://192.168.15.20/api/contact \
-H 'Origin: https://192.168.15.20' \
-H 'Content-Type: application/json' \
--data '{}'
ホスト名へ変更する場合はクライアントのhostsまたはDNS、NGINXのserver_nameと証明書、ALLOWED_ORIGIN、フロントのAPI URLをそろえる。hostsはアクセスするPCに設定する。Ubuntuでは/etc/hosts、WindowsではC:\Windows\System32\drivers\etc\hostsである。
Bad Gatewayが表示される¶
今回の502はAPIが返したdelivery_failedであり、原因はSMTPホスト名の設定ミスだった。NGINXの接続障害だけを調べても解決しないため、Responseとアプリログを照合する。
NGINXサーバーでは次を確認する。既存のNGINX設定でログの出力先を変えている場合は、そのパスを使う。
sudo tail -f /var/log/nginx/error.log
アプリサーバーでは次を確認する。
sudo systemctl status tectas-contact --no-pager
sudo journalctl -u tectas-contact -n 50 --no-pager
delivery_failedがあればSMTP設定を確認する。secrets.jsonのhostは実際のSMTP接続先、portは数値の587または465、userとpasswordはSMTP認証用の値にする。MAIL_FROMも、そのアカウントで送信できるアドレスにする。Webサイトのホスト名とSMTPホスト名を混同しない。
秘密情報は最大5分キャッシュされるため、修正後に即座に試す場合はsudo systemctl restart tectas-contactを実行する。ログは秘密情報を出さない設計なので、delivery_failedだけでは認証失敗・TLSエラーなどを区別できない。設定全体やパスワードを調査用に貼り付けない。
TLS接続の切り分けが必要なら、接続先を実値に置き換えて次を実行する。これはSMTP認証・メール送信の試験ではなく、接続と証明書の確認である。
# 587番:STARTTLS
sudo -u tectas-contact openssl s_client \
-starttls smtp -connect smtp.example.com:587 \
-servername smtp.example.com -verify_return_error -brief
# 465番:接続開始時からTLS
sudo -u tectas-contact openssl s_client \
-connect smtp.example.com:465 \
-servername smtp.example.com -verify_return_error -brief
終了はCtrl+C。修正後は画面の完了メッセージ、APIのsent、実際の受信メールを確認する。繰り返し失敗した場合は件数上限にも注意し、成否不明な投稿を新しいIDで再送しない。
複数To宛先で一部だけ受け付けられた場合は、delivery_failedではなくdelivery_unknownになる。全宛先へまとめて再送すると重複するため、管理者が各受信先とSMTP側を確認する。宛先の修正だけで、過去の同じ受付IDの投稿が自動的に再送されることはない。
Turnstileを省略して試す¶
フロントのPUBLIC_CONTACT_TURNSTILE_ENABLED=falseと、自前APIのTURNSTILE_ENABLED=falseを両方設定する。前者は再ビルド・再配置、後者はAPI再起動で反映する。フロントだけを無効にするとAPIがトークン不足を拒否し、APIだけを無効にすると画面側の認証が残る。省略中もHTTPS、Origin照合、入力検証、件数制限は有効である。
実Turnstileへ戻す場合はテスト環境用の通常のウィジェットを作り、許可ホスト名とキーを設定して両方をtrueへ戻す。現在のAPIはhostnameとactionも照合するため、ダミーキーを通常のキーと置き換えるだけでは成功しない。ダミーキーの成功応答はhostnameがexample.com固定で、actionを含まない。Cloudflare公式資料
TurnstileはCloudflareでDNSを管理していないドメインでも利用できる。ネームサーバーの移管やCloudflareのプロキシ経由への変更は不要である。Cloudflareの導入資料
設定を変更した後の反映方法¶
| 変更したもの | 必要な操作 |
|---|---|
.env.preview.local、画面・CSS・ブラウザー用JS |
npm run build:preview、dist-preview/の中身の再配置、ブラウザー再読込 |
アプリのcontact.env、secrets.json |
sudo systemctl restart tectas-contact |
| アプリのソース・依存関係 | 手動更新・切り戻し手順で新版を準備し、旧版を残して切り替え。稼働中の依存関係を直接更新しない |
tectas-contact.service |
sudo systemctl daemon-reload、API再起動 |
| NGINXの転送先・証明書 | sudo nginx -t、sudo systemctl reload nginx |
通常の構築は自前サーバーのセットアップ、APIの応答はAPI共通仕様を参照する。