# インフラ設計書

## 概要

本ドキュメントは、InvenTree（オープンソース在庫管理システム）のインフラストラクチャ設計について記載する。InvenTreeはDockerコンテナベースのアーキテクチャを採用し、PostgreSQLデータベース、Redis キャッシュ、Caddy/Nginx リバースプロキシ、およびGunicorn WSGIサーバーで構成される。

## システム構成

### 全体構成

InvenTreeは以下の主要コンポーネントで構成されるマイクロサービスアーキテクチャを採用している：

1. **リバースプロキシ層**: Caddy または Nginx によるHTTP/HTTPS終端、静的ファイル配信、認証制御
2. **アプリケーション層**: Django + Gunicorn による Web アプリケーションサーバー
3. **バックグラウンドワーカー層**: django-q によるバックグラウンドタスク処理
4. **キャッシュ層**: Redis によるセッション・データキャッシュ
5. **データベース層**: PostgreSQL によるデータ永続化

### サーバー構成

| サーバー種別 | 役割 | スペック | 台数 |
| --- | --- | --- | --- |
| inventree-proxy (Caddy/Nginx) | リバースプロキシ、静的ファイル配信、SSL終端 | caddy:alpine または nginx | 1 |
| inventree-server (Gunicorn) | Django Webアプリケーションサーバー | Python 3.11-slim-trixie, Gunicorn 23.0.0 | 1 |
| inventree-worker | バックグラウンドタスクワーカー | Python 3.11-slim-trixie | 1 |
| inventree-cache (Redis) | キャッシュサーバー | redis:7-alpine | 1 |
| inventree-db (PostgreSQL) | データベースサーバー | postgres:17 | 1 |

### ネットワーク構成

- **外部公開ポート**:
  - HTTP: 80 (デフォルト、環境変数 `INVENTREE_HTTP_PORT` で変更可能)
  - HTTPS: 443 (デフォルト、環境変数 `INVENTREE_HTTPS_PORT` で変更可能)
- **内部通信ポート**:
  - inventree-server: 8000/tcp (Gunicorn)
  - inventree-db: 5432/tcp (PostgreSQL)
  - inventree-cache: 6379/tcp (Redis)
- **ネットワークモード**: Docker Compose によるブリッジネットワーク
- **コンテナ間通信**: サービス名による名前解決（inventree-server, inventree-db, inventree-cache）

### ストレージ構成

| ボリューム | マウント先 | 用途 |
| --- | --- | --- |
| INVENTREE_EXT_VOLUME | /home/inventree/data | アプリケーションデータ（設定、メディア、バックアップ） |
| INVENTREE_EXT_VOLUME | /var/lib/postgresql/data | PostgreSQLデータファイル |
| INVENTREE_EXT_VOLUME/redis | /data | Redisデータ永続化 |
| INVENTREE_EXT_VOLUME/static | /var/www/static | 静的ファイル |
| INVENTREE_EXT_VOLUME/media | /var/www/media | ユーザーアップロードメディア |

## ミドルウェア

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| Python | 3.11 | アプリケーション実行環境 |
| Django | 5.2.10 | Webアプリケーションフレームワーク |
| Gunicorn | 23.0.0 | WSGI HTTPサーバー |
| PostgreSQL | 17 | リレーショナルデータベース |
| Redis | 7-alpine | キャッシュサーバー |
| Caddy | alpine | リバースプロキシ（本番環境デフォルト） |
| Nginx | - | リバースプロキシ（代替オプション） |
| psycopg | 3.3.2 | PostgreSQL接続ドライバ（Python） |
| django-auth-ldap | 5.3.0 | LDAP認証連携 |
| Weasyprint | - | PDF生成 |

## 外部サービス連携

| サービス名 | 用途 | 接続方式 |
| --- | --- | --- |
| PostgreSQL | データ永続化 | psycopg (TCP/5432) |
| Redis | セッション・データキャッシュ | TCP/6379 |
| LDAP | ユーザー認証（オプション） | LDAP/LDAPS (django-auth-ldap) |
| OIDC Provider | OpenID Connect認証（オプション） | HTTPS (OAuth 2.0/OIDC) |
| SMTP Server | メール通知（オプション） | SMTP/SMTPS |

## スケーリング設計

### 水平スケーリング

- **Gunicorn ワーカー数**: 環境変数 `INVENTREE_GUNICORN_WORKERS` で設定可能
  - デフォルト: `CPU数 * 2 + 1`
  - 各ワーカーは4スレッドで動作
- **バックグラウンドワーカー数**: 環境変数 `INVENTREE_BACKGROUND_WORKERS` で設定可能
  - デフォルト: 4

### パフォーマンス設定

| 設定項目 | デフォルト値 | 環境変数 |
| --- | --- | --- |
| Gunicorn ワーカー数 | CPU数 * 2 + 1 | INVENTREE_GUNICORN_WORKERS |
| Gunicorn スレッド数 | 4 | - |
| Gunicorn タイムアウト | 90秒 | INVENTREE_GUNICORN_TIMEOUT |
| 最大リクエスト数/ワーカー | 1000 | - |
| リクエストジッター | 50 | - |
| 最大アップロードサイズ | 100MB | - |

## 可用性設計

### コンテナ再起動ポリシー

| サービス | 再起動ポリシー |
| --- | --- |
| inventree-db | unless-stopped |
| inventree-cache | always |
| inventree-server | unless-stopped |
| inventree-worker | unless-stopped |
| inventree-proxy | always |

### 依存関係管理

- **inventree-server**: inventree-db, inventree-cache の起動後に起動
- **inventree-worker**: inventree-server の起動後に起動
- **inventree-proxy**: inventree-server の起動後に起動

### ヘルスチェック

- Caddy による `/auth/` エンドポイントへのフォワード認証
- Gunicorn のアクセスログ・エラーログによる監視

## バックアップ設計

| 対象 | 方式 | 頻度 | 保持期間 |
| --- | --- | --- | --- |
| PostgreSQLデータベース | INVENTREE_EXT_VOLUME のバックアップ | 運用ポリシーに依存 | 運用ポリシーに依存 |
| アプリケーションデータ | INVENTREE_EXT_VOLUME のバックアップ | 運用ポリシーに依存 | 運用ポリシーに依存 |
| 設定ファイル | config.yaml のバックアップ | 運用ポリシーに依存 | 運用ポリシーに依存 |

### バックアップディレクトリ

- `INVENTREE_BACKUP_DIR`: /home/inventree/data/backup

## 監視設計

### ログ出力

| コンポーネント | ログ出力先 | ログレベル |
| --- | --- | --- |
| Gunicorn | stdout/stderr | INVENTREE_LOG_LEVEL (デフォルト: WARNING) |
| Caddy | /var/log/caddy/inventree.access.log | - |
| Django | アプリケーションログ | INVENTREE_LOG_LEVEL |

### トレーシング

- OpenTelemetry によるトレーシングサポート（TRACING_ENABLED 設定で有効化）
- Gunicorn post_fork フックでの計装初期化

### 環境変数による設定

| 環境変数 | 説明 | デフォルト値 |
| --- | --- | --- |
| INVENTREE_LOG_LEVEL | ログレベル | WARNING |
| INVENTREE_DEBUG | デバッグモード | False (本番) / True (開発) |
| INVENTREE_DB_LOGGING | DBクエリログ | False |

## セキュリティ設計

### 認証・認可

- Django 組み込み認証システム
- LDAP 認証連携オプション（django-auth-ldap）
- OpenID Connect 認証オプション

### ネットワークセキュリティ

- リバースプロキシによるアクセス制御
- X-Forwarded-* ヘッダーによるプロキシ連携
- メディアファイルの認証付きアクセス（auth_request）
- 静的ファイルの30日間キャッシュ

### 機密情報管理

- シークレットキー: `INVENTREE_SECRET_KEY_FILE` (/home/inventree/data/secret_key.txt)
- OIDC秘密鍵: `INVENTREE_OIDC_PRIVATE_KEY_FILE` (/home/inventree/data/oidc.pem)
- データベース認証情報: 環境変数による注入

## 備考

### 開発環境との差異

| 項目 | 本番環境 | 開発環境 |
| --- | --- | --- |
| デバッグモード | INVENTREE_DEBUG=False | INVENTREE_DEBUG=True |
| ログレベル | WARNING | WARNING (変更可能) |
| Pythonイメージ | python:3.11-slim-trixie | mcr.microsoft.com/devcontainers/python:3.11-bookworm |
| フロントエンド | コンパイル済み静的ファイル | Vite開発サーバー (5173) |
| PostgreSQLバージョン | 17 | 15 |

### 推奨事項

1. **本番環境ではHTTPSを有効化**: Caddyの自動HTTPS機能を利用
2. **データベース認証情報の変更**: デフォルトのpguser/pgpasswordから変更
3. **外部ボリュームの定期バックアップ**: INVENTREE_EXT_VOLUME の定期バックアップ実施
4. **監視システムの導入**: PrometheusやDatadog等による監視推奨
