管理コンソールのセットアップとアクセス

独立した管理アプリの実行とデプロイ、運用担当者の昇格、MFA の必須化、専用オリジンの設定を説明します。

スターターのコミット 2a1a04a と同期しています。

顧客向けアプリの外から、顧客、請求、運用障害を調べる担当者が必要な場合に使います。管理コンソール自体は含まれていますが、デプロイするか、誰にアクセス権を与えるか、専用オリジンをどう保護するかは自分で決めます。

推奨の出発点： 専用のホスト名へデプロイし、日常調査には admin_ro を使います。意図した変更を行う少人数のグループだけに admin_rw を与え、全員に MFA を必須とします。小規模チームは、運用上の制御が整うまで管理コンソールをデプロイしない選択もできます。顧客向けアプリは管理コンソールに依存しません。

完了後は、認可された運用担当者が別アプリへログインでき、一般ユーザーと読み取り専用の運用担当者は書き込めない状態になります。

スターターには、apps/admin に運用用の管理コンソールが含まれています。これは顧客向けアプリ内の /admin ルートではなく、二つ目の Next.js アプリです。この境界により、認証、データベーススキーマ、モデル、サービスを共有しながら、コンソールを保護された専用オリジンに配置し、独立してリリースできます。

ローカルで実行する

先に通常のスターターのセットアップを完了し、顧客向けアプリからユーザーを作成してから管理アプリを起動します。

pnpm dev:admin

http://localhost:3001 で待ち受けます。関連コマンドは次のとおりです。

pnpm build:admin
pnpm start:admin

.env にローカル管理オリジンを設定します。

NEXT_PUBLIC_ADMIN_WEB_URL=http://localhost:3001

この値がある場合、シェルまたはデプロイ環境が BETTER_AUTH_URL や NEXT_PUBLIC_AUTH_BASE_URL を明示的に指定しない限り、管理ビルドはこの値を Better Auth のオリジンとして使います。NEXT_PUBLIC_ADMIN_WEB_URL はビルド時に埋め込まれるため、本番環境で変更した後は再デプロイが必要です。

運用担当者を昇格する

プラットフォーム管理権限は users.role に保存され、組織の owner、admin、member ロールとは別です。

admin_ro はコンソールを開き、運用データを閲覧できます。
admin_rw はさらにコンソールの書き込み操作を実行できます。

リポジトリのルートから既存アカウントを昇格します。

pnpm admin:promote operator@example.com admin_rw

このコマンドは既定で admin_rw を使い、--dry-run に対応します。同じメールアドレスが複数の認証事業者のアカウントに属する場合、コマンドは推測せず停止します。その場合は、たとえば次のように --provider で正確なアカウントを選びます。

pnpm admin:promote operator@example.com --role admin_ro --provider google

認可処理がメールアドレスからロールを解決することはありません。サーバーはセッション固有の ID または UUID に一致するデータベースユーザーを読み込み、保護されたすべてのページと API ルートで保存済みロールを検査します。

MFA は必須

管理ロールだけではアクセスできません。すべての運用担当者は公開側のアカウント UI で Better Auth の二要素認証を有効にする必要があります。管理ロールがあっても MFA が未設定なら /mfa-required に移動し、有効化後に管理アプリ固有の /two-factor チャレンジを完了します。

Google のみでログインするアカウントは、Better Auth で二要素認証を有効にする前にパスワードが必要です。この場合、公開側のアカウント UI に パスワードを設定 が表示されます。設定後も Google ログインは引き続き利用できます。

管理コンソールへのログインは、顧客向けアプリと同じ、確認処理付きのメールログインエンドポイントを使います。そのため CAPTCHA 保護を有効にしている場合は、管理アプリのデプロイにも NEXT_PUBLIC_TURNSTILE_SITE_KEY と TURNSTILE_SECRET_KEY が必要です。

別アプリとしてデプロイする

同じリポジトリから 2 つ目のホスティングプロジェクトを作成し、pnpm build:admin を実行します。https://admin.example.com のような専用オリジンを割り当てます。

管理アプリはスターター共通の本番環境検証を読み込むため、管理画面が各外部サービスを直接使わない場合でも、現時点では本番で必須の環境変数一式が必要です。まず顧客向けアプリの本番環境変数を複製し、.env.example とデプロイとセキュリティを確認してください。そのうえで管理アプリ固有の値を調整します。

顧客向けアプリと同じ DATABASE_URL と BETTER_AUTH_SECRET を使う
NEXT_PUBLIC_ADMIN_WEB_URL を管理オリジンに設定する（明示的に上書きしない限り、管理ビルドは Better Auth の URL にもこの値を使います）
管理ホスト名で有効な Turnstile のサイトキーとシークレットキーの組を設定する（顧客向けアプリのキー設定がそのホスト名を許可する場合に限り再利用する）
製品に適した ADMIN_MAX_CREDIT_GRANT の上限を選ぶ（既定値は 100000）

Web と管理のオリジンは分離してください。管理アプリは noindex、nofollow、noarchive、no-store のレスポンスヘッダーに加えて、厳格なフレーム、リファラー、コンテンツセキュリティポリシーを適用します。ただし、これらは露出を抑えるためのもので認可の代わりではありません。サーバーレイアウトと各管理 API がロールと MFA を検査します。

リリース前チェックリスト

pnpm build:admin でコンソールをビルドします。
管理オリジンと認証ベース URL が同じデプロイ先を指すことを確認します。
admin_ro でログインし、データは見える一方で書き込み操作が使えないことを確認します。
admin_rw でログインして MFA を完了し、元に戻せる書き込みを 1 つ試します。
その操作が /audit に表示されることを確認します。
一般ユーザーが管理ページを開けず、管理 API も呼べないことを確認します。

現在提供されている画面と各操作の使い分けは、管理コンソールのページと運用を参照してください。公開前のネットワーク、シークレット、ヘルスチェックはデプロイとセキュリティで最終確認します。