自前バックエンドの手動更新・切り戻し¶
お問い合わせAPIは、GitLab CIで検証した版を担当者がアプリサーバーへ手動配置する。フロントの静的サイトは従来どおりCI/CDでNGINXへ自動配置する。APIの更新頻度が低いことを前提に、バックエンド用の自動デプロイジョブは設けない。
この手順は、初回セットアップを済ませたLinux・systemd環境を対象とする。プログラムの公開パスは/opt/tectas-contactの実ディレクトリ、サービス名はtectas-contactとする。シンボリックリンクによる別の配置方式や、DBスキーマ変更を伴う版には、そのまま適用しない。
受付制限・Slack通知を追加する今回の更新では、APIコード以外に環境設定・NGINX・フロント・監視の反映が必要になる。最初に今回の反映チェックリストで更新箇所と作業順を確認する。
1. 更新対象と保存対象¶
| 対象 | 更新時の扱い |
|---|---|
src/、package.json、package-lock.json |
同じコミットの内容でまとめて更新 |
node_modules/ |
新しい版の作業ディレクトリでnpm ci --omit=devにより用意 |
/var/lib/tectas-contact/ |
SQLiteと関連ファイルを維持。コードの配置に含めない |
/etc/tectas-contact/contact.env |
維持。必要な設定変更だけ別途行う |
/etc/tectas-contact/secrets.json |
維持。SMTP・Turnstile・HMACの秘密情報をGitや配布物へ含めない |
| systemd・NGINX設定 | 通常のコード更新では維持。変更がある版だけ別途反映 |
| Slack監視のコード・設定・状態 | APIとは別配置。Slack監視の更新手順で更新し、Webhookと通知状態は維持 |
コードを切り戻す際も、DB・秘密情報を古い版へ戻さない。古いDBに戻すと、更新後の送信件数や送信済み記録が失われ、重複判定に影響する。バックアップからの復元は通常のコード切り戻しとは別の障害復旧として扱う。
2. 対象版を決める¶
mainの履歴に含まれ、保護タグのパイプラインでバックエンドのテストとSAM検査が成功した版を選ぶ。ブランチへのpushだけではCIが動かないため、必要なら先に保護タグのパイプラインを実行する。現在のパイプラインはフロントも自動配置するので、バックエンド更新のためだけにタグを作成する場合も、公開されるフロントの内容を確認する。
API仕様を変更した版は、フロントとAPIの互換性・反映順を事前に確認する。現在の共通API仕様を維持した更新なら、フロントを再配置する必要はない。
アプリサーバーの作業用リポジトリに、対象タグを取得しておく。次はタグを選ぶ例で、v1.0.0は実際の対象タグに置き換える。未コミット変更がある作業コピーは使用しない。
git status --short
git switch --detach v1.0.0
git rev-parse HEAD
/usr/bin/node --version
サービスが使う/usr/bin/nodeが24系であることを確認する。GitLabのパイプラインURL、対象タグ、コミットSHA、更新日時、担当者を作業記録に残す。
3. 稼働中の版を残して新しい版を準備する¶
以下はアプリサーバーの作業用リポジトリ直下でBashから実行する。変数は後の切り替え・切り戻しでも使用するため、同じシェルで続ける。旧版のバックアップ先は日時で分け、既存のファイルを上書きしない。
contact_revision=$(git rev-parse HEAD)
contact_stamp=$(date -u +%Y%m%dT%H%M%SZ)
contact_stage=$(mktemp -d /tmp/tectas-contact.XXXXXX)
contact_next="/opt/tectas-contact-next-$contact_stamp"
contact_backup="/opt/tectas-contact-backup-$contact_stamp"
cp -a backend/contact-form/src "$contact_stage/"
cp backend/contact-form/package.json backend/contact-form/package-lock.json "$contact_stage/"
npm ci --omit=dev --prefix "$contact_stage"
printf '%s\n' "$contact_revision" > "$contact_stage/DEPLOYED_COMMIT"
if [ -e "$contact_next" ] || [ -L "$contact_next" ] || [ -e "$contact_backup" ] || [ -L "$contact_backup" ]; then
echo '配置先または旧版の保存先が既に存在するため停止します。' >&2
exit 1
fi
sudo install -d -o root -g root -m 755 "$contact_next"
sudo cp -a "$contact_stage/." "$contact_next/"
sudo chown -R root:root "$contact_next"
sudo chmod -R u=rwX,go=rX "$contact_next"
sudo -u tectas-contact test -r "$contact_next/src/server.mjs"
sudo -u tectas-contact test -r "$contact_next/node_modules/nodemailer/package.json"
cp -aは一時ディレクトリの権限もコピーするため、コピー後のchmodを省略しない。これにより実行ユーザーの読み取り・実行を許可し、プログラムへの書き込みはrootに限定する。秘密情報・SQLiteにはこの権限を適用しない。
各コマンドが成功したことを確認してから次へ進む。途中で失敗した場合は切り替えない。依存関係はアプリサーバー上で準備し、Windowsなど別OSのnode_modulesを転送しない。実行ユーザーにはプログラムの書き換え権限を与えない。
必要なバックアップはセットアップ手順に従って取得する。ここまでの操作では、稼働中のプログラム・SQLite・秘密情報を変更しない。
4. APIを停止して切り替える¶
停止から再起動・疎通確認が終わるまで、問い合わせAPIは短時間利用できなくなる。静的サイトは引き続き配信される。問い合わせの少ない時間帯に行い、フロントと同時に別の変更を反映しない。
最初にサービスが参照するパスを確認する。WorkingDirectory=/opt/tectas-contact、ExecStart=/usr/bin/node /opt/tectas-contact/src/server.mjsであることが前提になる。
sudo systemctl cat tectas-contact
if ! sudo test -d /opt/tectas-contact || sudo test -L /opt/tectas-contact; then
echo '/opt/tectas-contactが実ディレクトリでないため停止します。' >&2
exit 1
fi
sudo systemctl stop tectas-contact
if sudo systemctl is-active --quiet tectas-contact; then
echo 'サービスがまだ稼働しているため切り替えません。' >&2
exit 1
fi
systemctl stopが成功し、停止が完了したことを確認する。停止操作は開始済みの処理を待つが、障害や強制終了で残ったPENDINGは自動再送しない。成否不明の投稿があれば、ログ・受信側で別途確認する。
if ! sudo mv -T /opt/tectas-contact "$contact_backup"; then
echo '旧版を退避できなかったため停止します。' >&2
exit 1
fi
if ! sudo mv -T "$contact_next" /opt/tectas-contact; then
sudo mv -T "$contact_backup" /opt/tectas-contact
sudo systemctl start tectas-contact
exit 1
fi
sudo systemctl start tectas-contact
sudo systemctl status tectas-contact --no-pager
1つ目の移動に成功して2つ目に失敗した場合は、旧版をsudo mv -T "$contact_backup" /opt/tectas-contactで戻してからサービスを起動する。APIのコードだけの更新ではdaemon-reloadやNGINXの再読み込みは不要である。
5. 起動・疎通を確認する¶
アプリサーバーで、配置したコミットと起動後のログを確認する。
cat /opt/tectas-contact/DEPLOYED_COMMIT
sudo journalctl -u tectas-contact -n 50 --no-pager
次にNGINXサーバーから公開APIの疎通を確認する。IPとOriginは実環境に置き換える。証明書検証を省略せず、IP・ホスト名と証明書を合わせる。
curl -i https://192.168.15.20/api/contact \
-H 'Origin: https://192.168.15.20' \
-H 'Content-Type: application/json' \
--data '{}'
SENDING_ENABLED=trueなら400・invalid_input、停止設定のfalseなら503・dependency_errorが想定結果である。空のJSONなのでメールを送らず、送信枠も消費しない。curlを--fail付きにすると、想定した400や503でもコマンドが失敗扱いになる点に注意する。
この確認はAPIへの到達と入力検証までで、SMTP・Turnstile・DBへの書き込みの成功を確認するものではない。依存関係や送信設定を更新した場合など、必要に応じて受信先担当者と調整し、試験送信と受信も確認する。試験のために本番のTurnstileを無効化しない。
正常であれば、旧版の保存先、配置したコミット、疎通結果を作業記録へ追記する。作業ディレクトリと旧版は、確認が終わるまで残す。保存先・版を確認してから保持方針に従って整理し、最新の切り戻し用の版は残す。
6. 旧版へ切り戻す¶
起動や疎通に問題がある場合は、新しいプログラムを退避し、直前に保存した旧版を同じパスへ戻す。以下は前述と同じシェルで実行する例である。別セッションでは、作業記録から実際のバックアップ先を確認して変数を設定し直す。
contact_failed="/opt/tectas-contact-failed-$contact_stamp"
if ! sudo test -f "$contact_backup/src/server.mjs" || [ -e "$contact_failed" ] || [ -L "$contact_failed" ]; then
echo '旧版または退避先を確認できないため停止します。' >&2
exit 1
fi
sudo systemctl stop tectas-contact
if ! sudo mv -T /opt/tectas-contact "$contact_failed"; then
echo '新版を退避できなかったため停止します。' >&2
exit 1
fi
if ! sudo mv -T "$contact_backup" /opt/tectas-contact; then
sudo mv -T "$contact_failed" /opt/tectas-contact
sudo systemctl start tectas-contact
exit 1
fi
sudo systemctl start tectas-contact
sudo systemctl status tectas-contact --no-pager
旧版を戻す移動に失敗した場合は、退避した新版を元のパスに戻して復旧するか、サービスを停止したまま原因を確認する。通常のコード切り戻しでSQLite・HMAC秘密鍵・SMTP設定を戻したり、送信済み記録を削除したりしない。起動後は前節と同じ疎通確認を行う。
設定値の変更が障害原因なら、コードを戻すだけでは解決しない。変更記録に従って該当する設定だけを修正し、サービスを再起動する。Node.js自体を更新した場合も、プログラムの旧版を戻すだけでは実行環境は戻らないため、その互換性を別途確認する。
更新頻度が低い場合の保守¶
機能を変更しない期間も、Node.jsと依存ライブラリのセキュリティ情報を定期的に確認する。更新はリポジトリのロックファイルへ反映し、検証済みの版を同じ手順で配置する。稼働中のnode_modulesへ直接npm updateを実行する運用にはしない。
バックエンドの自動配置が必要になった場合は、専用の接続先・環境・切り戻し処理を別途追加する。現時点でRunnerからアプリサーバーへのSSH経路や、バックエンド用のCIデプロイ鍵を用意する必要はない。