自前アプリサーバーのセットアップ

公開側のリバースプロキシから内部アプリサーバーへ問い合わせAPIの要求を転送する。アプリサーバーはRedmineと分けたユーザー・プロセスでAPIを動かし、SQLiteで送信枠と重複を管理する。外部へのHTTPS・SMTPは既存のNAT・ゲートウェイを利用する。

2026年11月10日、利用者から試験環境でのブラウザー送信とメール受信の成功が報告された。Turnstileは省略した状態であり、実Turnstileの検証、AWS版での送信、本番配置まで確認したものではない。今回のつまずきと切り分け方法はトラブルシューティングにまとめる。

本書は初回構築の手順である。稼働後はフロントだけをCI/CDで自動配置し、バックエンドはCIで検証した版を必要時に手動更新する。手動更新・切り戻し手順に従い、SQLite・設定・秘密情報は維持する。

作業場所と進め方

本書のコマンドはUbuntu 24.04・Bashを対象とする。既存のRedmineやNGINXを再インストールする手順ではない。管理者権限を持つ作業用ユーザーで実行し、各コマンドの成功を確認してから次へ進む。

順序 作業場所 作業と完了条件
1 アプリサーバー Node.js 24系を導入し、対象版のソースを取得する
2 アプリサーバー 専用ユーザー、プログラム、設定・秘密情報、DB用ディレクトリを用意する
3 アプリサーバー systemdへ登録し、送信停止状態でAPIが起動する
4 NGINXサーバー 内部APIへの転送を設定し、公開パスからJSON応答を確認する
5 ビルド端末 フロント設定を記入してビルドし、NGINXへ成果物を配置する
6 各サーバー・ブラウザー テスト宛先で送信を有効にし、画面の完了表示とメール受信を確認する

初回構築では第1節から順に実施する。稼働済み環境に初回配置コマンドを繰り返さず、手動更新手順を使う。バックアップ・監視は第5・6節に従って設定し、運用記録に担当者と確認結果を残す。

試験環境の接続先を整理する

以下は今回使用した内部IPの例である。実環境へ適用するときは置き換える。ブラウザーとAPIの間にNGINXがあるため、アプリの待受先と、利用者が開くURLを混同しない。

設定・接続 今回の試験環境の例
アプリサーバー 192.168.15.19
NGINXサーバー 192.168.15.20
ブラウザーで開くページ https://192.168.15.20/contact/
フロントのPUBLIC_CONTACT_API_URL https://192.168.15.20/api/contact
アプリのALLOWED_ORIGIN https://192.168.15.20。アプリ側の.19を指定しない
アプリのHOST / PORT 192.168.15.19 / 3001
NGINXのproxy_pass http://192.168.15.19:3001/contact

ALLOWED_ORIGINに末尾の/やパスを付けない。ブラウザー側で443以外のポートを使う場合は、オリジンにもそのポートを含める。HOST=127.0.0.1では別サーバーのNGINXから接続できない。IP直のHTTPSには、そのIPをSANに含み、クライアントから信頼される証明書が必要になる。

1. 配置するファイルと実行環境

自前版はNode.js 24系を使用する。SQLiteにはNode.js組み込みのnode:sqliteを使い、DBサーバーは追加しない。AWS版の実行環境は従来どおりNode.js 22系であり、自前版のモジュールを読み込まない。

Ubuntu 24.04でNode.js 24系を用意する

Ubuntu標準リポジトリの候補が18系の場合は、そのままインストールしても自前APIを起動できない。今回のsystemd設定ではシステム全体で利用できるNode.jsを使用する。次はNodeSourceの手順に従う導入例で、Ubuntu標準とは別のAPTリポジトリを追加する。

sudo apt update
sudo apt install -y ca-certificates curl git openssl sqlite3
curl -fsSL https://deb.nodesource.com/setup_24.x -o nodesource_setup.sh
sudo bash nodesource_setup.sh
apt-cache policy nodejs
sudo apt install --simulate nodejs
sudo apt install nodejs
/usr/bin/node --version
npm --version

候補が24系であることと、シミュレーションで削除・更新されるパッケージを確認してからインストールする。事前に既存のnodejsを削除する必要は通常ない。競合が起きた場合は該当パッケージを確認して対応し、先に一括でpurgeやautoremoveを実行しない。他のアプリがシステムのNode.jsを使っている場合は更新の影響も確認する。

ソースを取得して対象版を確認する

以降はアプリサーバーで実行する。リポジトリを取得済みなら、その作業コピーへ移動する。初回取得の場合は次の例のURLとタグを実際の値へ置き換える。GitLabの取得権限は作業用ユーザーに用意し、サービス用ユーザーへSSH鍵を持たせない。アプリサーバーからGitLabへ接続できない場合は、作業端末で対象版を取得して転送し、コミットSHAを併せて記録する。

git clone '取得先のリポジトリURL' website-renewal
cd website-renewal
git switch --detach v1.0.0
git status --short
git rev-parse HEAD
/usr/bin/node --version
npm ci --prefix backend/contact-form
npm test --prefix backend/contact-form

以降のリポジトリ相対パスを使うコマンドは、このルートディレクトリから実行する。Node.jsが24系で、作業コピーに変更がなく、テストが成功したことを確認する。本番へ配置する版は、保護タグのパイプラインで検証済みのものを選ぶ。試験用ブランチを配置する場合も、コミットSHAとテスト結果を記録する。

専用ユーザーと配置先を作成する

まずユーザー・グループの有無を確認する。両方が存在しない場合だけuseraddを実行する。既存の場合はgetent passwd tectas-contactとid tectas-contactで用途と所属グループを確認し、別用途のユーザーを流用しない。

getent passwd tectas-contact
getent group tectas-contact
sudo useradd --system --user-group --no-create-home --shell /usr/sbin/nologin tectas-contact

SQLiteはローカルディスクへ置く。ネットワーク共有や複数サーバー間でのDB共有は対象外とする。

sudo install -d -o root -g root -m 755 /opt
sudo install -d -o tectas-contact -g tectas-contact -m 700 /etc/tectas-contact
sudo install -d -o tectas-contact -g tectas-contact -m 700 /var/lib/tectas-contact

APIを初回配置する

次のブロックは、アプリサーバーのリポジトリ直下から実行する。/opt/tectas-contactが既にある場合は停止し、上書きしない。依存関係は作業用ユーザーで準備してから、プログラムをroot所有で配置する。

(
  set -eu
  if sudo test -e /opt/tectas-contact || sudo test -L /opt/tectas-contact; then
    echo '既存の配置先があるため停止します。手動更新手順を使用してください。' >&2
    exit 1
  fi
  contact_stage=$(mktemp -d /tmp/tectas-contact.XXXXXX)
  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"
  git rev-parse HEAD > "$contact_stage/DEPLOYED_COMMIT"
  sudo install -d -o root -g root -m 755 /opt/tectas-contact
  sudo cp -a "$contact_stage/." /opt/tectas-contact/
  sudo chown -R root:root /opt/tectas-contact
  sudo chmod -R u=rwX,go=rX /opt/tectas-contact
  sudo -u tectas-contact test -r /opt/tectas-contact/src/server.mjs
  sudo -u tectas-contact test -r /opt/tectas-contact/node_modules/nodemailer/package.json
)

コピー後は上記のchmodでプログラム一式の権限を整える。mktemp -dで作成した一時ディレクトリは通常0700であり、cp -a "$contact_stage/."はその権限を配置先にも引き継ぐ。先にinstall -m 755を実行するだけでは、コピー後に実行ユーザーがアクセスできなくなる。u=rwX,go=rXは所有者に書き込みを許可し、他のユーザーには読み取りと、ディレクトリ・実行可能ファイルへの実行権限を設定する。この指定はプログラムの配置先だけに適用し、/etc/tectas-contactやDBのディレクトリには適用しない。

実行ユーザーにはプログラムの読み取り・実行を認め、書き換えは認めない。src/と依存関係を同じ版で配置し、Webサイトのpublic/やdist/へコピーしない。依存関係にはAWS SDKも含まれるが、自前版はAWSへ接続しない。サービス起動前に次節の設定・秘密情報を用意する。

2. 設定と秘密情報

backend/contact-form/.env.exampleを参考に、/etc/tectas-contact/contact.envを作成する。初回はSENDING_ENABLED=falseで起動する。systemdが環境変数を読み込むため、アプリ自身は.envファイルを自動読込しない。

アプリサーバーのリポジトリ直下で次を実行する。既存設定を上書きしないよう、ファイルが存在する場合は停止する。

(
  set -eu
  if sudo test -e /etc/tectas-contact/contact.env; then
    echo 'contact.envが既に存在します。内容を確認して個別に編集してください。' >&2
    exit 1
  fi
  sudo install -o root -g root -m 600 backend/contact-form/.env.example /etc/tectas-contact/contact.env
)
sudoedit /etc/tectas-contact/contact.env

次は今回の試験環境でTurnstileを省略し、まだ送信を許可しない設定例である。FromとToは実際に使用するテスト用アドレスへ置き換える。保存先はアプリサーバーの/etc/tectas-contact/contact.envとし、フロントの.envへ記入しない。

ALLOWED_ORIGIN=https://192.168.15.20
MAIL_FROM=web@example.com
MAIL_TO=office@example.com
SENDING_ENABLED=false
TURNSTILE_ENABLED=false
HOURLY_LIMIT=10
DAILY_LIMIT=30
IP_HOURLY_LIMIT=3
IP_DAILY_LIMIT=10
TRUSTED_PROXY_IPS=192.168.15.20
DATABASE_PATH=/var/lib/tectas-contact/contact.sqlite
SECRET_FILE=/etc/tectas-contact/secrets.json
HOST=192.168.15.19
PORT=3001

本番ではTURNSTILE_ENABLED=trueとし、公開ドメインのオリジン、実際の内部IP、送受信アドレスへ置き換える。環境変数ファイルはrootが読み込んでプロセスに渡すため、root所有・0600でよい。秘密情報JSONは実行ユーザーが直接読むため、後述の所有者・権限にする。

設定 内容
ALLOWED_ORIGIN サイトのHTTPSオリジン。末尾の/は付けない
MAIL_FROM 固定の送信元。1アドレス
MAIL_TO 固定のTo宛先。複数の場合はカンマ区切り。全受信者に宛先一覧が見える
SENDING_ENABLED trueまたはfalse。停止中は新規送信を受け付けない
TURNSTILE_ENABLED 既定はtrue。ローカル検証でのみfalseを指定し、Turnstile検証を省略可能
HOURLY_LIMIT / DAILY_LIMIT 初期値10件・30件
IP_HOURLY_LIMIT / IP_DAILY_LIMIT IP別の送信試行上限。省略時3件/時・10件/日
TRUSTED_PROXY_IPS X-Real-IPを信用するNGINXの接続元IP。カンマ区切りのIP完全一致。別サーバー構成では必ず指定する
DATABASE_PATH SQLiteファイルの絶対パス。親ディレクトリを事前に用意する
SECRET_FILE 非公開JSONファイルの絶対パス
HOST / PORT 既定は127.0.0.1:3001。別ホストのプロキシから接続する場合は内部IPを指定

複数宛先はcontact.envに次のように指定する。1件だけの指定も使える。各アドレスの前後の空白は除去し、完全一致する重複は1件にまとめる。空の項目、セミコロン区切り、表示名付きの指定、不正なアドレス、改行は拒否する。

MAIL_TO=office@example.com,sales@example.com

APIプログラムを今回の複数宛先対応版に更新したうえで、設定変更後にsudo systemctl restart tectas-contactを実行する。フロントの再ビルドは不要である。更新した宛先は新しい投稿に適用され、成功済みの同じ受付IDを再確認しても新しい宛先へ再送しない。

/etc/tectas-contact/secrets.jsonには次の構造で実値を設定する。portは数値とし、587または465に限定する。

{
  "smtp": {
    "host": "smtp.example.com",
    "port": 587,
    "user": "SMTPユーザー名",
    "password": "SMTPパスワード",
    "idempotencyKey": "暗号学的乱数32バイトを表す64桁の16進数"
  },
  "turnstile": { "secret": "Turnstile秘密鍵" }
}

秘密情報ファイルを作成する

アプリサーバーで次を実行する。最初のブロックは、ファイルを新規作成する場合だけ使う。空のファイルを専用ユーザー所有・0600で用意してから、管理者がエディターで上記JSONを記入する。

(
  set -eu
  if sudo test -e /etc/tectas-contact/secrets.json; then
    echo 'secrets.jsonが既に存在します。上書きせず既存の秘密情報を維持してください。' >&2
    exit 1
  fi
  sudo install -o tectas-contact -g tectas-contact -m 600 /dev/null /etc/tectas-contact/secrets.json
)
sudoedit /etc/tectas-contact/secrets.json

idempotencyKeyは次のコマンドで生成した64桁の値を記入する。端末への出力は秘密情報として扱い、画面共有やセッション記録のない環境で実行する。稼働後に作り直さず、秘密情報のバックアップにも含める。

openssl rand -hex 32

TURNSTILE_ENABLED=falseの試験ではJSONのturnstile項目を省略できる。SMTPのhostは、さくらレンタルサーバーが案内するメール接続先のホスト名を指定し、Webサイトのホスト名や内部IPで代用しない。587ではSTARTTLS、465では接続開始時からTLSを使う。JSONの文字列内に引用符やバックスラッシュがある場合はJSONとしてエスケープする。

保存後、所有者・権限とJSONの書式を確認する。次のコマンドは秘密値を出力しない。SMTP接続や認証の成功は、後の送信試験で確認する。

sudo chown tectas-contact:tectas-contact /etc/tectas-contact/secrets.json
sudo chmod 600 /etc/tectas-contact/secrets.json
sudo -u tectas-contact /usr/bin/node --input-type=module -e 'import { readFileSync } from "node:fs"; import { validateSecrets } from "/opt/tectas-contact/src/secrets.mjs"; const data = JSON.parse(readFileSync("/etc/tectas-contact/secrets.json", "utf8")); validateSecrets(data.smtp, data.turnstile, { turnstileEnabled: false }); console.log("SMTP設定の形式: OK");'

上の検査はTurnstileを省略した試験用である。Turnstileを使う場合はturnstileEnabled: trueにして、秘密鍵の設定も検査する。

秘密情報は専用ユーザーを所有者とし、ファイルの権限を0600、親ディレクトリを0700にする。Linuxではグループ・その他のアクセス権がある秘密情報ファイルを起動時に拒否する。値をGit・コマンド引数・公開環境変数へ入れない。設定例の値は認証に利用できない。

SMTPとTurnstileの秘密情報は最大5分キャッシュする。即時反映にはサービスを再起動する。SMTPパスワードを変える際もHMAC用のidempotencyKeyは維持する。

ローカル検証でTurnstileを省略する場合

アプリサーバーのcontact.envにTURNSTILE_ENABLED=falseを指定し、サービスを再起動する。送信も試す場合はSENDING_ENABLED=trueとする。この場合、秘密情報JSONのturnstile項目は省略できる。SMTP認証情報とidempotencyKeyは引き続き必要になる。

フロント側はリポジトリ直下の.env.preview.localにPUBLIC_CONTACT_TURNSTILE_ENABLED=falseとAPIのURLを設定し、npm run build:previewで再ビルドして配置する。サイトキーは空欄でよい。両方を無効にすると、ブラウザーのウィジェット読込・トークン取得と、自前APIのSiteverify通信を省略する。フロントだけを無効にするとAPIに拒否され、APIだけを無効にするとブラウザー側の認証処理が残る。

# フロントの.env.preview.local
PUBLIC_CONTACT_API_URL=https://テスト用のホスト名またはIP/api/contact
PUBLIC_CONTACT_TURNSTILE_ENABLED=false
PUBLIC_TURNSTILE_SITE_KEY=

省略中も入力検証、Origin照合、件数制限、重複送信防止は行う。HTTPS必須の条件も維持するため、IP直で試す場合はそのIPに対応した証明書を用意する。実メールは送信されるので、宛先はテスト用に設定する。

公開環境では両設定をtrueに戻し、秘密鍵とサイトキーを設定して再起動・再ビルドする。設定を省略した場合も有効になる。AWS版には無効化設定を追加せず、引き続きTurnstileを必須とする。

3. 起動と通信の制限

systemd設定例を/etc/systemd/system/tectas-contact.serviceへ配置する。Node.jsの実パスに合わせてExecStartを修正し、サービスを有効化する。

設定例のExecStartは/usr/bin/node /opt/tectas-contact/src/server.mjsである。対話シェルのnode --versionだけでなく、指定先の/usr/bin/node --versionが24系であることを確認する。設定例はProtectHome=trueのため、ホームディレクトリ内のnvmで導入したNode.jsはそのままでは利用できない。

アプリサーバーのリポジトリ直下で設定例を配置する。既に登録済みの環境では上書きせず、現在の設定との差分を確認する。

(
  set -eu
  if sudo test -e /etc/systemd/system/tectas-contact.service; then
    echo 'サービス設定が既に存在します。差分を確認してから更新してください。' >&2
    exit 1
  fi
  sudo install -o root -g root -m 644 infra/contact-form/self-hosted/tectas-contact.service /etc/systemd/system/tectas-contact.service
)
sudo systemd-analyze verify /etc/systemd/system/tectas-contact.service
sudo systemctl daemon-reload
sudo systemctl enable --now tectas-contact
sudo systemctl status tectas-contact --no-pager
sudo journalctl -u tectas-contact -n 50 --no-pager
sudo ss -ltnp 'sport = :3001'

読み込まれている設定は、アプリサーバーで次のコマンドにより確認できる。

sudo systemctl cat tectas-contact
sudo grep '^ALLOWED_ORIGIN=' /etc/tectas-contact/contact.env
/usr/bin/node --version

EnvironmentFile=/etc/tectas-contact/contact.envとExecStartを確認する。環境設定や秘密情報の変更後はsudo systemctl restart tectas-contactを実行する。.serviceファイル自体を変更した場合は、その前にsudo systemctl daemon-reloadも実行する。設定ファイル全体をログやチャットへ貼り付けない。

設定例では専用ユーザー、DBディレクトリの自動作成、再起動、書き込み先の限定、CPU・メモリ上限を指定している。Redmineと設定・DB・認証情報を共用しない。APIの同時処理数は1プロセスあたり2件に制限し、超過時は503を返す。最初は1プロセスで運用し、複数起動する場合はSMTPへの同時接続総数も調整する。

APIへのTCP 3001番の接続は、ホストのファイアウォールでプロキシの内部IPからだけ許可する。既存のファイアウォール方式に合わせて設定し、RedmineやSSHへの接続を維持する。UFWなど別の方式を無条件に有効化しない。内部ネットワークが信頼できない区間を通る場合は、VPNやTLSで通信を保護する。外向きにはCloudflare SiteverifyへのHTTPS 443番、SMTP接続先への587番または465番と、名前解決を許可する。

4. 公開プロキシとフロントの接続

既にサイトとAPI転送が動いている場合は、稼働済みNGINXの差分更新を使う。httpとHTTPS用serverの違い、今回追加する設定、検査・疎通確認を順に記載している。サイトの公開ファイルはCI/CDで配置する。

nginx設定例を公開側HTTPSサーバーの設定に組み込む。転送先の10.0.0.10は実際の内部IPへ置き換える。/api/contactだけを内部の/contactへ転送し、APIのポート全体を公開しない。

NGINXサーバーでsudo nginx -Tを実行し、ブラウザーで開くホスト名を扱うHTTPS用serverブロックと、その設定ファイルを特定する。設定ファイルをバックアップしてから管理者権限で編集する。nginx.conf.exampleにはhttp内へ入れる定義と、HTTPS用server内へ入れるlocationがある。ファイル全体をserver内へ貼り付けず、既存サイト設定全体の置き換えにも使わない。

最初にnginx設定例のlimit_req_zone、limit_conn_zone、log_formatをhttpブロックへ一度だけ追加する。今回のIPを使う場合、HTTPS用serverブロック内へ次を追加する。同じlocation = /api/contactが既にある場合は重複追加せず、その内容を更新する。

location = /api/contact {
    limit_req zone=contact_rate burst=2 nodelay;
    limit_req_status 429;
    limit_conn contact_connections 1;
    limit_conn_status 429;
    client_max_body_size 32k;
    client_body_timeout 15s;
    proxy_pass http://192.168.15.19:3001/contact;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header Origin $http_origin;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header Connection "";
    proxy_connect_timeout 5s;
    proxy_send_timeout 15s;
    proxy_read_timeout 60s;
    proxy_next_upstream off;
    proxy_intercept_errors off;
    access_log /var/log/nginx/contact-access.log contact_safe;
    error_log /var/log/nginx/contact-error.log crit;
}

既存の静的サイトのroot・証明書・Redmine等の転送設定は維持する。HTTPSサイト自体がない場合は、先にサイト用のserverブロックと信頼できる証明書を用意し、ブラウザーで警告なくサイトを開けることを確認する。静的サイトの本番配置先と初期保存版の準備は本番デプロイの初回セットアップに従う。

設定例はIP別に平均6要求/分(バースト2)、同時処理1件を許可し、超過を429で拒否する。1つのIPがAPIの2つの処理枠を占有することを抑える。共有IPの誤制限と通常の再試行を確認して値を調整する。TRUSTED_PROXY_IPSに実際のNGINXの接続元IPを設定し、NGINXがX-Real-IPを上書きする変更と合わせて反映する。未設定では全利用者がNGINXのIPとして集計される。CDNを挟む場合は、信頼するCDNのアドレス範囲だけを対象に実IPを復元する。詳細と受入確認は受付制限と停止攻撃への対策を参照する。

proxy_next_upstream offでプロキシによる自動再試行を止め、APIのJSONエラーを独自HTMLへ置き換えない。APIの上限は32 KiB、同時処理は2件。プロキシの読み取り待ちは60秒、画面側は55秒で結果確認へ切り替わる。

sudo nginx -t && sudo systemctl reload nginx

サイトのビルド設定に次を指定し、再ビルド・配置する。公開APIは絶対HTTPS URLを指定する。

フロントの.env.exampleは記入例であり、自動では読み込まれない。試験環境の値はリポジトリ直下の.env.preview.localへ記入する。PUBLIC_CONTACT_API_URLなどはビルド時にHTMLへ埋め込まれるため、設定変更後は必ず再ビルド・再配置する。NGINXサーバーに環境変数だけを追加しても、配置済みの静的ファイルは変わらない。

PUBLIC_CONTACT_API_URL=https://www.tectas.co.jp/api/contact
PUBLIC_TURNSTILE_SITE_KEY=対象ホストに許可されたサイトキー
設定ファイル ビルド 配置する成果物
.env.development.local npm run dev ローカル開発サーバーで確認。設定変更後は再起動
.env.preview.local npm run build:preview dist-preview/の中身
本番用の.env.production.localなど npm run build dist/の中身
GitLabのproductionスコープのCI/CD変数 CIのnpm run build dist/を自動配置。.envファイルは配置しない

.env.preview.localの値は通常のnpm run buildには使われない。ビルドは開発PCで実行してもよく、生成したフォルダの中身をNGINXのrootで指定したディレクトリへ配置する。再配置後はブラウザーを強制再読み込みし、表示中の設定をConsoleで確認する。秘密情報ファイルは成果物に含めない。

フォームを公開しない場合

フロントの.env.preview.localへPUBLIC_CONTACT_ENABLED=falseを指定して再ビルド・再配置すると、ヘッダー(PC・モバイル)、フッター、商品ページのフォームへのリンクが非表示になる。サイトマップからも除外し、/contact/への直接アクセスでは入力欄の代わりに電話番号を表示する。既定値はtrueで、再開時はtrueへ戻して再ビルド・再配置する。

APIのSENDING_ENABLED=falseは送信処理だけを止める設定であり、フロントのリンクは変わらない。フロントの公開設定もAPIへは反映されないため、両方を止める場合はそれぞれ設定する。Turnstileの省略はフォームの非公開設定とは別に扱う。

フロントをビルドして配置する

ビルド端末のリポジトリ直下で、.env.preview.localをエディターで新規作成する。既にある場合は必要な項目だけ編集し、上書きで他の設定を消さない。Turnstileを省略する試験では、前節の3つのPUBLIC_設定を記入する。実Turnstileを使う場合はウィジェットに公開サイトのホスト名を許可し、対応するサイトキー・秘密鍵をフロントとAPIへそれぞれ設定する。

npm ci
npm run check
npm run build:preview

dist-preview/contact/index.htmlが生成されたことを確認し、dist-preview/の中身一式をNGINXの試験サイトの公開ディレクトリへ転送する。src/やリポジトリ全体、バックエンド、.envを転送しない。既存の転送方法がなければ、作業端末からSCP等でNGINX上の作業ディレクトリへ送り、管理者が公開先へ配置する。公開先はsudo nginx -Tの対象サイトのrootで確認する。本番のcurrent・releasesを手動で上書きせず、本番反映はCI/CDを使う。

本番CI/CDではフロント用の.envファイルをRunnerやNGINXへ置かず、公開設定をGitLabのCI/CD変数へキーごとに登録する。作業端末の.env.*.localはRunnerへ転送されない。フロントのビルドに必要なのは公開API URLとサイトキー等だけで、SMTP認証情報やTurnstile秘密鍵を登録しない。

接続を段階的に確認する

最初はメールを送らない空のJSONで、内部API、NGINX経由の順に確認する。以下のコマンドはNGINXサーバーから実行する。Originはcurlの実行元IPではなく、ブラウザーで開くサイトのオリジンを指定する。

# 1. NGINXから内部APIへ直接接続
curl -i http://192.168.15.19:3001/contact \
  -H 'Origin: https://192.168.15.20' \
  -H 'Content-Type: application/json' \
  --data '{}'

# 2. NGINXの公開パスを経由
curl -i https://192.168.15.20/api/contact \
  -H 'Origin: https://192.168.15.20' \
  -H 'Content-Type: application/json' \
  --data '{}'

SENDING_ENABLED=falseなら503・dependency_error、trueなら入力不足の400・invalid_inputが想定結果である。後者は失敗を直すための送信ではなく、APIの検証まで届いたことの確認になる。403・origin_rejectedはオリジン設定の不一致、404・not_foundは転送パスを確認する。証明書エラーが出た場合は証明書の切り分けを参照する。

最初に停止設定のまま503が返ることを確認する。送信試験へ進む際は、アプリサーバーでテスト用のFrom・To・SMTP認証情報を確認し、次の操作を行う。

sudoedit /etc/tectas-contact/contact.env
# SENDING_ENABLED=trueへ変更して保存する。
sudo systemctl restart tectas-contact
sudo systemctl status tectas-contact --no-pager

再度空のJSONを送って400・invalid_inputになることを確認する。この要求では送信枠を消費せず、メールも送らない。その後、ブラウザーでhttps://192.168.15.20/contact/を開き、入力・確認・送信を行う。ここからは実メールが送られる。画面の完了メッセージとTo宛先すべてへの受信、From・Reply-To、自動返信がないことを確認する。アプリサーバーのjournalにはoutcome: sentが記録される。

sudo journalctl -u tectas-contact -n 50 --no-pager

Turnstileを省略していた場合は、公開前にAPIのTURNSTILE_ENABLED=trueと秘密鍵、フロントのPUBLIC_CONTACT_TURNSTILE_ENABLED=trueとサイトキーを設定し、サービスの再起動・再ビルド・再配置を行う。実Turnstileによる送信、件数制限、入力不正、通信断は受入確認に従って試験する。Redmineでの通信実績とは別に、APIの実行ユーザーと接続先で検証する。

5. SQLiteの保持とバックアップ

DBには受付ID、入力のHMAC、処理状態、作成日時、有効期限と、時間・日単位のカウンターだけを保存する。氏名・メールアドレス・本文は保存しない。期限は7日で、起動時と1時間ごとの処理で期限切れ記録を削除する。期間の切り替えはJSTのキーで判定し、削除のタイミングに依存しない。

バックアップはSQLite CLIの.backupなど、一貫したスナップショットを作る方法で取得する。稼働中にDBファイルだけをコピーしない。WALを利用するため、未反映の変更が別ファイルに存在する場合がある。取得例は次のとおり。出力先は事前に作成し、専用ユーザーだけがアクセスできるようにする。

sudo install -d -o tectas-contact -g tectas-contact -m 700 /var/backups/tectas-contact
sudo -u tectas-contact sqlite3 /var/lib/tectas-contact/contact.sqlite ".backup '/var/backups/tectas-contact/contact.sqlite'"

日次・7世代を初期案とし、バックアップを暗号化して別サーバーへ保管する。実際のスケジュール、世代管理、転送、暗号化は既存のバックアップ基盤へ設定する。秘密情報ファイル、HMAC秘密鍵、起動・プロキシ設定、配置したコミットも復旧できるように管理する。バックアップのコピーには削除済みの記録が残るため、世代保持期間も個人情報・管理情報の保持方針に含める。

復元はAPIを停止し、DB・WAL・SHMを一式退避してから行う。復元したDBの所有者と権限を整え、対応するHMAC秘密鍵を維持する。古いDBではバックアップ後の件数・重複判定が失われるため、その間の送信記録を確認し、上限を調整して再開する。DBから本文を復元することはできない。受信メールのバックアップはメール運用側で行う。

6. 監視と停止

ログはjournalへ出し、本文・氏名・メールアドレス・秘密情報・SMTPの生の応答を記録しない。自前版のSlack通知に従い、APIとは別のsystemd timerでログとサービス状態を確認する。全体上限超過・503・メール送信障害は5分に1件以上、IP別上限超過とNGINXの429は5分に10件以上で通知し、サービス停止とプロキシの5xxも通知する。既存の監視基盤は不要だが、Webhookの準備と監視プログラム・timerの配置が必要である。

NGINXの専用アクセスログは時刻・ステータス・メソッド・処理時間・頻度制限の結果だけを記録する。ログは30日保持を方針とし、journalと専用ログの容量・保持設定、ローテーションをサーバー側で追加する。同じサーバーで動く監視ではホスト停止やネットワーク全断を通知できない。ディスク容量とホスト外からの死活監視は別途設定する。

送信だけを止める場合はSENDING_ENABLED=falseとして再起動する。プロセス自体を止める場合はsystemctl stop tectas-contactを使う。SIGTERMでは新規接続を止め、最大60秒間、開始済みの処理を待つ。強制終了や障害で残ったPENDINGは自動再送しない。受信側・ログで確認し、結果を確認できないものは再送しない。

バックエンドを切り替える場合はAPI共通仕様の手順に従う。AWSへの自動切り替え、DB間の自動同期、記録の移行機能は含めない。

参考資料