# インフラ設計書

## 概要

本ドキュメントは、Laravel Framework 12.x のインフラストラクチャ設計について記載する。Laravel はPHP製のWebアプリケーションフレームワークであり、本プロジェクトはフレームワーク本体のソースコードである。フレームワークとして提供されるインフラ関連の設定・機能について記述する。

**注記**: 本プロジェクトはフレームワークライブラリであり、Docker Compose、Kubernetes、Terraform等の具体的なインフラ構成ファイルは含まれていない。本設計書では、フレームワークが提供するインフラ関連の設定オプションおよび推奨構成について記載する。

## システム構成

### 全体構成

Laravel Framework は以下のコンポーネントで構成されるWebアプリケーションをサポートする:

1. **Webサーバー層**: HTTPリクエストの受付
2. **アプリケーション層**: PHPによるビジネスロジック処理
3. **データ永続化層**: データベース、キャッシュ、ファイルストレージ
4. **非同期処理層**: キューワーカーによるバックグラウンドジョブ処理
5. **外部サービス層**: メール送信、ブロードキャスト、クラウドサービス連携

### サーバー構成

| サーバー種別 | 役割 | 推奨スペック | 備考 |
| --- | --- | --- | --- |
| Webサーバー | HTTPリクエスト処理、静的ファイル配信 | PHP 8.2以上 | Nginx / Apache推奨 |
| APサーバー | PHPアプリケーション実行 | PHP 8.2以上、必須拡張機能あり | PHP-FPM推奨 |
| DBサーバー | データ永続化 | - | SQLite / MySQL / MariaDB / PostgreSQL / SQL Server対応 |
| キャッシュサーバー | セッション・キャッシュ管理 | - | Redis / Memcached対応 |
| キューワーカー | バックグラウンドジョブ処理 | PHP 8.2以上、ext-pcntl | 専用プロセス推奨 |

### ネットワーク構成

標準的なLaravelアプリケーションのネットワーク構成:

- フロントエンド: HTTPS (443)
- アプリケーションサーバー: 内部ネットワーク
- データベース: 内部ネットワーク (MySQL: 3306 / PostgreSQL: 5432 / SQL Server: 1433)
- Redis: 内部ネットワーク (6379)
- Memcached: 内部ネットワーク (11211)

## ミドルウェア

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| PHP | ^8.2 | アプリケーション実行環境 |
| Nginx / Apache | - | Webサーバー |
| MySQL | - | リレーショナルデータベース (オプション) |
| MariaDB | - | リレーショナルデータベース (オプション) |
| PostgreSQL | - | リレーショナルデータベース (オプション) |
| SQLite | - | リレーショナルデータベース (デフォルト) |
| SQL Server | - | リレーショナルデータベース (オプション) |
| Redis | - | キャッシュ・セッション・キュー (オプション) |
| Memcached | - | キャッシュ (オプション) |
| Monolog | ^3.0 | ログ管理 |

### 必須PHP拡張機能

| 拡張機能 | 用途 |
| --- | --- |
| ext-ctype | 文字タイプチェック |
| ext-filter | データフィルタリング |
| ext-hash | ハッシュ関数 |
| ext-mbstring | マルチバイト文字列処理 |
| ext-openssl | 暗号化処理 |
| ext-session | セッション管理 |
| ext-tokenizer | PHPトークン解析 |

### 推奨PHP拡張機能

| 拡張機能 | 用途 |
| --- | --- |
| ext-pdo | データベース接続 |
| ext-redis | Redis接続 (phpredisクライアント使用時) |
| ext-memcached | Memcached接続 |
| ext-pcntl | プロセス制御 (キューワーカー) |
| ext-posix | POSIXアクセス (キューワーカー) |
| ext-gd | 画像処理 |
| ext-fileinfo | ファイルタイプ判定 |
| ext-ftp | FTPストレージ接続 |
| ext-apcu | APCキャッシュ |
| ext-gmp | 大きな整数演算 |

## 外部サービス連携

| サービス名 | 用途 | 接続方式 |
| --- | --- | --- |
| AWS SES | メール送信 | SDK / API |
| AWS S3 | ファイルストレージ | SDK (league/flysystem-aws-s3-v3) |
| AWS SQS | メッセージキュー | SDK |
| AWS DynamoDB | キャッシュ・失敗ジョブ保存 | SDK |
| Pusher | リアルタイム通信 | WebSocket / API |
| Ably | リアルタイム通信 | WebSocket / API |
| Laravel Reverb | リアルタイム通信 (自前ホスト) | WebSocket |
| Postmark | メール送信 | API |
| Resend | メール送信 | API |
| Mailgun | メール送信 | API (symfony/mailgun-mailer) |
| Slack | 通知・ログ | Webhook / Bot API |
| Papertrail | ログ集約 | Syslog UDP |

## データベース設計

### 対応データベース

| データベース | ドライバー | デフォルトポート | 接続設定 |
| --- | --- | --- | --- |
| SQLite | sqlite | - | DB_DATABASE (ファイルパス) |
| MySQL | mysql | 3306 | DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD |
| MariaDB | mariadb | 3306 | DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD |
| PostgreSQL | pgsql | 5432 | DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD |
| SQL Server | sqlsrv | 1433 | DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD |

### Redis設定

| 設定項目 | 環境変数 | デフォルト値 |
| --- | --- | --- |
| クライアント | REDIS_CLIENT | phpredis |
| クラスタモード | REDIS_CLUSTER | redis |
| ホスト | REDIS_HOST | 127.0.0.1 |
| ポート | REDIS_PORT | 6379 |
| パスワード | REDIS_PASSWORD | - |
| データベース番号 | REDIS_DB | 0 |
| キャッシュ用DB | REDIS_CACHE_DB | 1 |
| 最大リトライ | REDIS_MAX_RETRIES | 3 |
| パーシステント接続 | REDIS_PERSISTENT | false |

## キャッシュ設計

### 対応キャッシュストア

| ストア | ドライバー | 用途 | 備考 |
| --- | --- | --- | --- |
| array | array | テスト用 | メモリ内、リクエスト間で永続化しない |
| session | session | セッションキャッシュ | セッションデータ内に保存 |
| database | database | 汎用 | データベーステーブルに保存 |
| file | file | 汎用 | ファイルシステムに保存 |
| memcached | memcached | 高速キャッシュ | 分散キャッシュサーバー |
| redis | redis | 高速キャッシュ | 分散キャッシュサーバー |
| dynamodb | dynamodb | AWSネイティブ | DynamoDBテーブルに保存 |
| octane | octane | 高パフォーマンス | Laravel Octane使用時 |
| failover | failover | 高可用性 | 複数ストアのフェイルオーバー |

### デフォルト設定

- デフォルトキャッシュストア: database (CACHE_STORE環境変数で変更可能)
- キャッシュテーブル: cache
- キャッシュプレフィックス: {APP_NAME}_cache_

## キュー設計

### 対応キュードライバー

| ドライバー | 用途 | 特徴 |
| --- | --- | --- |
| sync | 開発用 | 同期実行、即時処理 |
| database | 汎用 | データベーステーブルに保存 |
| beanstalkd | 専用キューサーバー | Beanstalkdサーバー使用 |
| sqs | AWSネイティブ | Amazon SQS使用 |
| redis | 高速キュー | Redisサーバー使用 |
| deferred | 遅延実行 | リクエスト終了時に実行 |
| failover | 高可用性 | 複数ドライバーのフェイルオーバー |

### デフォルト設定

- デフォルトキュードライバー: database (QUEUE_CONNECTION環境変数で変更可能)
- ジョブテーブル: jobs
- バッチテーブル: job_batches
- 失敗ジョブテーブル: failed_jobs
- リトライ間隔: 90秒

## セッション設計

### 対応セッションドライバー

| ドライバー | 用途 | 特徴 |
| --- | --- | --- |
| file | ファイルベース | ファイルシステムに保存 |
| cookie | クッキーベース | 暗号化してクライアントに保存 |
| database | データベース | データベーステーブルに保存 |
| memcached | Memcached | 分散セッションサーバー |
| redis | Redis | 分散セッションサーバー |
| dynamodb | DynamoDB | AWSネイティブ |
| array | テスト用 | メモリ内、永続化しない |

### デフォルト設定

- デフォルトセッションドライバー: database (SESSION_DRIVER環境変数で変更可能)
- セッションテーブル: sessions
- セッション有効期間: 120分
- HTTPS専用Cookie: SESSION_SECURE_COOKIE環境変数
- HTTPOnly: true
- SameSite: lax

## ファイルストレージ設計

### 対応ストレージドライバー

| ドライバー | 用途 | 特徴 |
| --- | --- | --- |
| local | ローカルファイル | サーバーファイルシステム |
| public | 公開ファイル | Webアクセス可能なストレージ |
| s3 | AWS S3 | オブジェクトストレージ |
| ftp | FTP | FTPサーバー (league/flysystem-ftp) |
| sftp | SFTP | SFTPサーバー (league/flysystem-sftp-v3) |

### デフォルト設定

- デフォルトディスク: local (FILESYSTEM_DISK環境変数で変更可能)
- ローカルストレージパス: storage/app/private
- パブリックストレージパス: storage/app/public

## スケーリング設計

### 水平スケーリング対応

Laravelは以下の構成で水平スケーリングをサポート:

1. **ステートレスアプリケーション**: セッションを外部ストア (Redis/Database) に保存することで、複数APサーバーでの運用が可能
2. **キャッシュ共有**: Redis/Memcached を使用することで、複数サーバー間でキャッシュを共有
3. **キュー分散**: 複数のキューワーカーでジョブを分散処理
4. **メンテナンスモード**: キャッシュドライバーを使用することで、複数サーバー間でメンテナンス状態を同期

### Laravel Octane

高パフォーマンスが必要な場合、Laravel Octane の使用を推奨:

- Swoole / RoadRunner ベースの常駐プロセス
- リクエスト間でアプリケーション状態を保持
- 大幅なパフォーマンス向上

## 可用性設計

### フェイルオーバー構成

1. **キャッシュフェイルオーバー**: failover ドライバーで複数ストアを設定可能
2. **キューフェイルオーバー**: failover ドライバーで複数接続を設定可能
3. **メールフェイルオーバー**: failover / roundrobin トランスポートで複数メーラーを設定可能

### 冗長構成

| コンポーネント | 冗長化方式 |
| --- | --- |
| APサーバー | ロードバランサー配下に複数台配置 |
| データベース | リードレプリカ、マスター/スレーブ構成 |
| Redis | Redis Cluster / Sentinel |
| キューワーカー | 複数プロセス、Supervisor管理 |

## バックアップ設計

| 対象 | 方式 | 頻度 | 保持期間 |
| --- | --- | --- | --- |
| データベース | ダンプ / スナップショット | 日次推奨 | 運用ポリシーに依存 |
| ファイルストレージ | S3バージョニング / rsync | 日次推奨 | 運用ポリシーに依存 |
| 設定ファイル | バージョン管理 (Git) | 変更時 | 無期限 |

## 監視設計

### ログ設計

| チャンネル | ドライバー | 用途 |
| --- | --- | --- |
| stack | stack | 複数チャンネル出力 |
| single | single | 単一ログファイル |
| daily | daily | 日次ローテーション |
| slack | slack | Slack通知 (critical以上) |
| papertrail | monolog | 外部ログサービス |
| stderr | monolog | 標準エラー出力 |
| syslog | syslog | システムログ |
| errorlog | errorlog | PHPエラーログ |

### デフォルト設定

- デフォルトログチャンネル: stack (LOG_CHANNEL環境変数で変更可能)
- ログパス: storage/logs/laravel.log
- 日次ログ保持日数: 14日 (LOG_DAILY_DAYS環境変数で変更可能)
- デフォルトログレベル: debug (LOG_LEVEL環境変数で変更可能)

### 推奨監視項目

1. **アプリケーション監視**
   - レスポンスタイム
   - エラー率
   - キュージョブ処理状況
   - 失敗ジョブ数

2. **インフラ監視**
   - CPU/メモリ使用率
   - ディスク使用量
   - データベース接続数
   - Redis/Memcached メモリ使用量

3. **外部サービス監視**
   - API応答時間
   - メール送信成功率

## セキュリティ設計

### 暗号化

- 暗号化方式: AES-256-CBC
- アプリケーションキー: APP_KEY環境変数 (32文字のランダム文字列)
- 以前のキーサポート: APP_PREVIOUS_KEYS環境変数でキーローテーション対応

### セッションセキュリティ

- セッション暗号化: SESSION_ENCRYPT環境変数で有効化
- HTTPS専用Cookie: SESSION_SECURE_COOKIE環境変数
- HTTPOnly Cookie: デフォルトで有効
- SameSite属性: lax (CSRF対策)
- Partitioned Cookie: SESSION_PARTITIONED_COOKIE環境変数

### データベースセキュリティ

- SSL接続: MYSQL_ATTR_SSL_CA / DB_SSLMODE環境変数
- 外部キー制約: DB_FOREIGN_KEYS環境変数

## 環境変数一覧

### アプリケーション設定

| 環境変数 | 説明 | デフォルト値 |
| --- | --- | --- |
| APP_NAME | アプリケーション名 | Laravel |
| APP_ENV | 実行環境 | production |
| APP_DEBUG | デバッグモード | false |
| APP_URL | アプリケーションURL | http://localhost |
| APP_KEY | 暗号化キー | - |
| APP_TIMEZONE | タイムゾーン | UTC |
| APP_LOCALE | ロケール | en |

### データベース設定

| 環境変数 | 説明 | デフォルト値 |
| --- | --- | --- |
| DB_CONNECTION | デフォルト接続 | sqlite |
| DB_HOST | ホスト | 127.0.0.1 |
| DB_PORT | ポート | 3306 (MySQL) |
| DB_DATABASE | データベース名 | laravel |
| DB_USERNAME | ユーザー名 | root |
| DB_PASSWORD | パスワード | - |

### キャッシュ・セッション設定

| 環境変数 | 説明 | デフォルト値 |
| --- | --- | --- |
| CACHE_STORE | キャッシュストア | database |
| SESSION_DRIVER | セッションドライバー | database |
| SESSION_LIFETIME | セッション有効期間 (分) | 120 |

### キュー設定

| 環境変数 | 説明 | デフォルト値 |
| --- | --- | --- |
| QUEUE_CONNECTION | キュー接続 | database |
| QUEUE_FAILED_DRIVER | 失敗ジョブドライバー | database-uuids |

### メール設定

| 環境変数 | 説明 | デフォルト値 |
| --- | --- | --- |
| MAIL_MAILER | メーラー | log |
| MAIL_HOST | SMTPホスト | 127.0.0.1 |
| MAIL_PORT | SMTPポート | 2525 |

### ログ設定

| 環境変数 | 説明 | デフォルト値 |
| --- | --- | --- |
| LOG_CHANNEL | ログチャンネル | stack |
| LOG_LEVEL | ログレベル | debug |
| LOG_DAILY_DAYS | 日次ログ保持日数 | 14 |

## 備考

### フレームワーク固有の注意事項

1. **本プロジェクトはフレームワークライブラリ**: アプリケーション固有のインフラ構成ファイル (Docker Compose、Kubernetes マニフェスト等) は含まれていない
2. **設定ファイルはスタブ**: `config/` ディレクトリの設定ファイルは、アプリケーション作成時にコピーされるデフォルト設定
3. **環境変数による設定**: すべての環境依存設定は環境変数で外部化されている

### 推奨デプロイ環境

1. **開発環境**: Laravel Sail (Docker Compose ベース)
2. **ステージング/本番環境**: Laravel Forge / Vapor / 自前構築
3. **サーバーレス**: Laravel Vapor (AWS Lambda)

### 関連ドキュメント

- [Laravel 公式ドキュメント](https://laravel.com/docs)
- [Laravel Sail](https://laravel.com/docs/sail)
- [Laravel Forge](https://forge.laravel.com)
- [Laravel Vapor](https://vapor.laravel.com)
