> For the complete documentation index, see [llms.txt](https://docs.digitalhumans.jp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalhumans.jp/dev/miniprem/services/miniprem-monitor.md).

# MiniPrem Monitor

MiniPrem Monitor は、Docker コンテナと Kubernetes Pod のためのプロフェッショナルなモニタリングダッシュボードであり、コンテナ化されたワークロードをリアルタイムに可視化します。

{% hint style="info" %}
本ページの内容はデジタルヒューマン株式会社の正式サポート対象外です。参考情報としてご利用ください。
{% endhint %}

## クイックアクセス

**URL:** <http://localhost:3001>

**前提条件:**

* Docker Engine 20.10 以上が稼働していること
* kubectl が設定済みであること（Kubernetes モニタリング用）
* ホストマシン上でポート 3001 が利用可能であること

## 概要

MiniPrem Monitor は以下を統合的にモニタリングします。

* **Docker コンテナ**: ローカルコンテナのモニタリングとリアルタイムログ
* **Kubernetes Pod**: マルチクラスター対応の Pod モニタリングとログストリーミング
* **システムヘルス**: CPU、メモリ、ディスクのメトリクス
* **サービスステータス**: 接続のヘルスチェックと可用性

## モニターへのアクセス

### インストール後

ミニプレム（MiniPrem）をデプロイすると（デフォルト（Default Install）／フルインストール（Full Install）のいずれの種別でも）、モニターは自動的に利用可能になります。

```bash
# Start MiniPrem services
./miniprem.sh start

# Open your browser to:
http://localhost:3001
```

### スタンドアロン モニターのデプロイ

MiniPrem スタック全体をデプロイせずに Kubernetes クラスターをモニタリングしたい場合は、次のコマンドを実行してください。

```bash
cd docker
docker-compose -f docker-compose.monitor.yml up -d

# Access at:
http://localhost:3001
```

このスタンドアロン デプロイは以下の用途に最適です。

* 本番 EKS／AKS／GKE クラスターのモニタリング
* プラットフォーム運用チーム
* AI スタック全体を稼働させない DevOps モニタリング

## 主な機能

### 1. リアルタイム コンテナ モニタリング

* **ライブステータス**: ステータスインジケータ付きで稼働中のコンテナを一覧表示
* **リソース メトリクス**: コンテナごとの CPU、メモリ、ネットワーク使用量
* **ログ ストリーミング**: 任意のコンテナをクリックしてリアルタイムにログをストリーミング
* **コンテナ コントロール**: ダッシュボードから直接コンテナを起動／停止
* **自動更新**: WebSocket ベースの更新（ページのリロードは不要）

### 2. Kubernetes クラスター モニタリング

* **Pod ステータス**: 全ネームスペースにわたる Pod ヘルスをリアルタイムに表示
* **ノード モニタリング**: クラスターノードのステータスとリソース可用性
* **マルチクラスター対応**: 設定済みの kubectl コンテキストを切り替え可能
* **ライブ Pod ログ**: コンテナを選択して任意の Pod からログをストリーミング
* **ネームスペース フィルタリング**: ネームスペース単位で Pod を絞り込み

### 3. プロフェッショナル UI 機能

* **シンタックス ハイライト**: ログレベル（ERROR、WARN、INFO、DEBUG）の自動カラーコーディング
* **ダーク／ライトモード**: ユーザーの好みに合わせたテーマ切替
* **レスポンシブ デザイン**: デスクトップ、タブレット、モバイルに対応
* **ログ ダウンロード**: オフライン分析用にテキストファイルへログをエクスポート
* **検索・フィルター**: コンテナと Pod の高速フィルタリング

## アーキテクチャ

### ホストネットワーク モード

MiniPrem Monitor は最適なパフォーマンスのために Docker の**ホストネットワーク**（`network_mode: host`）を利用します。

**メリット:**

* ✅ Docker ソケットへ直接アクセス（ブリッジによるオーバーヘッドなし）
* ✅ ホストの kubeconfig を用いたシームレスな kubectl 連携
* ✅ ポートマッピングのオーバーヘッドがゼロ
* ✅ 設定がシンプル

**ポート バインディング:**

* **フロントエンド**: ポート 3001（パブリック アクセス）
* **バックエンド**: ポート 8000（内部 API、外部公開なし）

**このことが重要な理由:** ホストネットワークを利用すると、モニターはホストのポートに直接バインドされます。これによりネットワーク変換のオーバーヘッドが排除され、Docker および Kubernetes API への直接アクセスが可能になります。

### セキュリティ機能

* **読み取り専用 Docker ソケット**: 読み取り専用でマウントし、コンテナの変更を防止
* **コマンド ホワイトリスト**: 承認済みの Docker／kubectl コマンドのみ実行
* **入力バリデーション**: すべてのコンテナ／Pod 名を厳密な正規表現で検証
* **権限昇格の禁止**: `no-new-privileges:true` セキュリティオプションでコンテナを実行
* **安全なコマンドのみ**: `ps`、`logs`、`stats`、`get`、`describe` に限定

## ダッシュボードの使い方

### Docker コンテナ モニタリング

1. **コンテナの表示**: メインダッシュボードに稼働中のすべてのコンテナが表示されます
2. **ステータスの確認**: 緑 = 稼働中、赤 = 停止、黄 = 異常
3. **ログの表示**: 任意のコンテナの「View Logs」ボタンをクリック
4. **リソースのモニタリング**: CPU とメモリ使用量をリアルタイムに確認
5. **コンテナの制御**: 起動／停止ボタンを使用（権限がある場合）

### Kubernetes Pod モニタリング

1. **コンテキスト切替**: クラスタードロップダウンで kubectl コンテキストを選択
2. **ネームスペース選択**: ネームスペースで Pod を絞り込む（または全表示）
3. **Pod ヘルスの確認**: ステータスインジケータで Pod のヘルスを確認
4. **ログの表示**: 「View Logs」をクリックし、複数コンテナがある場合は対象コンテナを選択
5. **ノードのモニタリング**: ノードのステータスとリソース可用性を確認

### ログ ストリーミング

**機能:**

* **リアルタイム ストリーミング**: ログが継続的に更新されます
* **シンタックス ハイライト**: ログレベルに応じた自動カラーコーディング
* **ダウンロード**: テキストファイルへログをエクスポート
* **自動スクロール**: フォロー モードで最新ログを常に表示
* **検索**: ログ内のテキストを高速検索

**ログ コントロール:**

* **一時停止／再開**: ログストリーミングを停止／再開
* **クリア**: 現在のログビューをクリア
* **ダウンロード**: ログを `.txt` ファイルとして保存
* **閉じる**: ダッシュボードへ戻る

## トラブルシューティング

### モニターにアクセスできない

**問題**: <http://localhost:3001> にアクセスできない

**解決策:**

```bash
# Check if container is running
docker ps | grep miniprem-monitor

# Check container logs
docker logs miniprem-monitor

# Verify port 3001 is not in use
lsof -i :3001

# Restart the monitor
cd docker
docker-compose restart miniprem-monitor
```

### コンテナが表示されない

**問題**: ダッシュボードに Docker コンテナが表示されない

**解決策:**

```bash
# Verify Docker socket access
docker exec miniprem-monitor ls -l /var/run/docker.sock

# Test Docker command inside container
docker exec miniprem-monitor docker ps

# Check container logs for errors
docker logs miniprem-monitor | grep -i error
```

### Kubernetes が動作しない

**問題**: Kubernetes の Pod やコンテキストが表示されない

**解決策:**

```bash
# Verify kubectl config
docker exec miniprem-monitor kubectl config get-contexts

# Test cluster connectivity
docker exec miniprem-monitor kubectl cluster-info

# Refresh AWS credentials (for EKS)
aws sso login
aws eks update-kubeconfig --region us-east-1 --name your-cluster

# Check if kubeconfig is mounted correctly
docker exec miniprem-monitor ls -la /root/.kube/
```

### ログ ストリーミングが動作しない

**問題**: 「View Logs」をクリックしてもログが表示されない

**解決策:**

```bash
# Check WebSocket connection in browser
# Open Developer Tools → Network tab → Look for WS connection

# Verify backend health
curl http://localhost:8000/health

# Check backend logs
docker logs miniprem-monitor | grep -i websocket

# Restart the monitor
docker-compose restart miniprem-monitor
```

### ポート 3001 がすでに使用中

**問題**: 「port 3001: bind: address already in use」というエラーメッセージが出る

**解決策:**

```bash
# Find process using port 3001
lsof -i :3001

# Kill the conflicting process (if safe)
kill <PID>

# Or change monitor port (edit docker-entrypoint.sh)
# Then rebuild: docker-compose up -d --build
```

## ネットワーク設定

### ホストネットワークの解説

モニターは `network_mode: host` を使用しており、これは次のことを意味します。

1. **コンテナがホストのネットワークを共有**: 別個のネットワーク ネームスペースを持たない
2. **直接ポートバインド**: サービスがホストのポート（3001、8000）にバインド
3. **ポートマッピング不要**: docker-compose の `ports:` ディレクティブは無視される
4. **直接アクセス**: localhost のサービスや Docker ソケットへ直接アクセス可能

**比較:**

| 機能          | ホストネットワーク | ブリッジネットワーク         |
| ----------- | --------- | ------------------ |
| ポートマッピング    | 不要        | 必須（3001:3001）      |
| Docker ソケット | 直接アクセス    | 特別な設定が必要           |
| kubectl     | 直接アクセス    | ホストマウントが必要         |
| パフォーマンス     | 最適        | ネットワーク変換のオーバーヘッドあり |
| 分離性         | 低い        | 高い                 |

**モニターでホストネットワークを使う理由:**

* モニタリングツールはシステムへの直接アクセスが必要
* 頻繁な API 呼び出しでネットワークオーバーヘッドを排除
* Docker ソケットと kubectl 連携をシンプル化
* モニタリング コンテナにおける標準的なプラクティス

## 高度な設定

### 環境変数

`docker-compose.monitor.yml` を編集してモニターを設定します。

```yaml
environment:
  - MONITOR_MODE=standalone      # Deployment mode
  - LOG_LEVEL=info              # Logging level (debug/info/warn/error)
  - BACKEND_PORT=8000           # Internal backend port
  - FRONTEND_PORT=3001          # External frontend port
```

### カスタム kubeconfig の配置場所

kubeconfig が標準以外の場所にある場合は、以下のように指定します。

```yaml
volumes:
  - /path/to/your/.kube:/root/.kube:ro
```

### 複数の Kubernetes クラスター

モニターは kubeconfig 内のすべてのコンテキストを自動検出します。

```bash
# Add multiple clusters to kubeconfig
kubectl config use-context cluster1
kubectl config use-context cluster2

# Monitor will show all contexts in dropdown
```

### リソース制限

モニターがリソースを消費しすぎるのを防ぐため、リソース制限を追加します。

```yaml
deploy:
  resources:
    limits:
      cpus: '1.0'
      memory: 1G
    reservations:
      cpus: '0.5'
      memory: 512M
```

## MiniPrem との統合

### フルインストール（Full Install）でのデプロイ

MiniPrem のフルインストール（Full Install）を使用すると、モニターは以下を追跡できます。

* レンダラー（開発コード：Renny）のデジタルヒューマンコンテナ
* vLLM 推論コンテナ
* Flowise ワークフロー エンジン
* Redis キュー システム
* Prometheus メトリクス収集
* Grafana モニタリング

### 他ツールとの補完的なモニタリング

MiniPrem Monitor は他のモニタリングツールを補完します。

| ツール                  | 用途                 | ポート  |
| -------------------- | ------------------ | ---- |
| **MiniPrem Monitor** | コンテナ／Pod モニタリングとログ | 3001 |
| Grafana              | メトリクス可視化           | 3002 |
| Prometheus           | メトリクス収集            | 9090 |

**MiniPrem Monitor** はリアルタイムの運用モニタリングとログストリーミングに利用してください。 **Grafana／Prometheus** は履歴メトリクスとトレンドの確認に利用してください。

## 開発

モニターのコードを修正するコントリビューター向けの情報です。

### ローカル開発

**バックエンド:**

```bash
cd miniprem-monitor/backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python run.py  # Port 8000
```

**フロントエンド:**

```bash
cd miniprem-monitor/frontend
npm install
npm run dev  # Port 3500
```

### テスト

**Playwright テスト:**

```bash
cd miniprem-monitor/frontend
npm run test          # All tests
npm run test:headed   # Visual mode
npm run test:ui       # Interactive UI
```

### Docker ビルド

```bash
cd miniprem-monitor
docker build -t miniprem-monitor:dev .
```

## 関連リソース

* **詳細ドキュメント**: MiniPrem Monitor README
* **メインプロジェクト README**: MiniPrem Platform
* **Kubernetes デプロイ**: Kubernetes ガイド
* **トラブルシューティング**: [トラブルシューティング ガイド](/dev/miniprem/troubleshooting.md)

## サポート

問題や質問がある場合は、次の手順に従ってください。

1. 上記のトラブルシューティング セクションを確認する
2. コンテナのログを確認する: `docker logs miniprem-monitor`
3. 詳細なトラブルシューティングについては MiniPrem Monitor README を参照する
4. ログとエラーメッセージを添えて[サポート窓口](https://support.digitalhumans.jp/)に連絡する

***

## ライセンス

MiniPrem のドキュメントとインストール スクリプトは MIT ライセンスの下でオープンソースとして提供されています。詳細は LICENSE ファイルを参照してください。なお、Renny デジタルヒューマンアプリケーション自体は UneeQ による商用ライセンスのもとで提供されており、本ライセンスの対象外です。

***

## 著作権

**© 2025 UneeQ. All rights reserved.**

[サポート窓口](https://support.digitalhumans.jp/)