> 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/first-steps.md).

# 問題診断ガイド

## MiniPrem の問題を診断する

> サポートへ連絡する前に診断情報を収集するための初心者向けガイド

### 目次

* [サポートへ連絡する前に](#before-you-contact-support)
* [ステップ 1：デプロイ種別を特定する](#step-1-identify-your-deployment-type)
* [ステップ 2：プラットフォームが稼働しているか確認する](#step-2-check-if-your-platform-is-running)
* [ステップ 3：サービスの正常性を確認する](#step-3-check-service-health)
* [ステップ 4：Renny を個別に確認する](#step-4-check-renny-specifically)
* [ステップ 5：ログを収集する](#step-5-gather-logs)
* [ステップ 6：WebRTC 接続を診断する](#step-6-diagnose-webrtc)
* [ステップ 7：動作確認チェックリスト](#step-7-functional-verification)
* [クイックチェックリスト](#quick-checklist)
* [ライセンス](#license)
* [著作権](#copyright)

***

### サポートへ連絡する前に

ミニプレム（MiniPrem）のインストールで何らかの問題が発生した場合、サポートへ連絡する**前に**適切な情報を収集しておくと、問題の解決がより早く進みます。本ガイドでは、5 つの基本的な診断ステップを順を追って説明します。

{% hint style="warning" %}
前提条件を満たす環境の準備はお客様の責任において実施いただきますようお願いいたします。デジタルヒューマン株式会社では前提条件を満たすための環境構築のサポート、ドライバー等の不具合に対する対応作業は提供しておりません。
{% endhint %}

{% hint style="warning" %}
2026年6月現在、デジタルヒューマン株式会社の正式サポート対象はデフォルト（Default Install）の Renny のみです。フルインストール（Full Install）に含まれる Renny 以外のサービス（vLLM、Flowise、RIME AI、NVIDIA RIVA、Whisper など）はサポート対象外です。
{% endhint %}

**本ガイドで学べること：**

* 実行中のデプロイ種別を特定する方法
* プラットフォームが実際に稼働しているかを確認する方法
* サービスが正常な状態かを確認する方法
* ログの所在と読み解き方
* WebRTC 接続の診断方法
* 動作確認（レンダリング・TTS・リップシンク・会話）チェックリスト
* サポートへ連絡する際に提供すべき情報

> **ヒント**：問題が発生していない場合でも、これらのステップを定期的に実行することで、システムをより深く理解できます。

#### 事前診断スクリプト（miniprem\_precheck）

インストール前および稼働後の初動切り分けには、デジタルヒューマン株式会社が提供する事前診断スクリプト `miniprem_precheck` を実行し、結果ファイルをサポート窓口へ送付いただくとスムーズです。OS / CPU / メモリ / ストレージ / GPU / ネットワーク到達性（Docker Hub・api.uneeq.io・hosted-experience.jp など）・Azure TTS 13 リージョンの RTT 平均・WebRTC を想定したパケットロス品質判定までを 1 コマンドで収集し、`miniprem_precheck_YYYYMMDD_HHMM.txt` として保存します。

{% hint style="info" %}
スクリプトの全コマンドと判定基準は [前提条件と事前診断](/dev/miniprem/prerequisites.md) を参照してください。\
パケットロスの 5 段階品質判定（優秀 / 良好 / 注意 / 警告 / 不適）の詳細とネットワーク要件は [ネットワーク要件](/dev/miniprem/network-requirements.md) にまとめています。
{% endhint %}

***

### ステップ 1：デプロイ種別を特定する

MiniPrem は 2 種類の環境で稼働できます。どちらの方式を使用しているかを把握することが、トラブルシューティングの第一歩です。

#### Docker デプロイ（単一マシン）

以下に該当する場合は Docker を使用しています：

* `./docker/scripts/install_miniprem.sh` を使ってインストールした
* `./miniprem.sh start|stop|status` でサービスを管理している
* すべてのコンポーネントが単一マシンで動作している

**確認方法：**

```bash
# このコマンドで "uneeq-miniprem" コンテナが表示されれば Docker 構成です
docker ps --format "table {{.Names}}\t{{.Status}}" | grep -E "(renny|miniprem)"
```

**出力例（Docker デプロイ）：**

```
NAMES               STATUS
renny               Up 2 hours (healthy)
miniprem-monitor    Up 2 hours (healthy)
```

**インストールタイプ（default / custom）の判定：**

Docker デプロイの場合、どの `docker-compose` ファイルが使われているかは `.miniprem_install_type` ファイルで判定できます。トラブル切り分け時に対象 compose ファイルを特定する際に利用してください。

```bash
cat .miniprem_install_type
```

| 値         | 使用される compose ファイル                  | 内容                              |
| --------- | ----------------------------------- | ------------------------------- |
| `default` | `docker/docker-compose.default.yml` | デフォルト（Default Install）構成        |
| `custom`  | `docker/docker-compose.yml`         | フルインストール（Full Install）またはカスタム構成 |

#### Kubernetes デプロイ（クラスター）

以下に該当する場合は Kubernetes を使用しています：

* `kubernetes/scripts/` 配下のスクリプトでデプロイした
* `kubectl` コマンドでサービスを管理している
* ワークロードがクラスター内の複数ノードにまたがって動作している

**確認方法：**

```bash
# このコマンドで Pod が表示されれば Kubernetes 構成です
kubectl get pods -n uneeq-renderer 2>/dev/null
```

**出力例（Kubernetes デプロイ）：**

```
NAME                        READY   STATUS    RESTARTS   AGE
renny-renderer-abc123-xyz   1/1     Running   0          2d
renny-renderer-def456-uvw   1/1     Running   0          2d
```

#### なぜ重要なのか

* **Docker**：問題は通常、コンテナ設定、ポート競合、ローカルリソースに関連します
* **Kubernetes**：問題はクラスターのネットワーク、ノードのスケジューリング、クラウドプロバイダー設定に関わる場合があります

***

### ステップ 2：プラットフォームが稼働しているか確認する

個別のサービスを確認する前に、基盤となるプラットフォーム（Docker または Kubernetes）が稼働していることを確認してください。

#### Docker デプロイの場合

**Docker Engine が稼働しているか確認します：**

```bash
docker info > /dev/null 2>&1 && echo "Docker is running" || echo "Docker is NOT running"
```

**正常な出力：**

```
Docker is running
```

**異常な出力：**

```
Docker is NOT running
```

**Docker が稼働していない場合は起動してください：**

```bash
# systemd を使う Linux の場合
sudo systemctl start docker

# macOS/Windows の場合
# Docker Desktop アプリを起動してください
```

#### Kubernetes デプロイの場合

**kubectl からクラスターへ到達できるか確認します：**

```bash
kubectl cluster-info
```

**正常な出力：**

```
Kubernetes control plane is running at https://your-cluster.example.com
CoreDNS is running at https://your-cluster.example.com/api/v1/...

To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.
```

**異常な出力：**

```
The connection to the server was refused - did you specify the right host or port?
```

**クラスターへ到達できない場合：**

```bash
# 現在のコンテキストを確認
kubectl config current-context

# 利用可能なコンテキストを一覧表示
kubectl config get-contexts

# EKS の場合、認証情報の更新が必要な場合があります
aws sso login --profile your-profile
aws eks update-kubeconfig --region your-region --name your-cluster
```

***

### ステップ 3：サービスの正常性を確認する

ここから、MiniPrem のサービスが稼働しており、正常な状態かを確認していきます。

#### Docker デプロイの場合

**ステータスコマンドを実行します：**

```bash
./miniprem.sh status
```

**正常な出力（すべてのサービスが正常）：**

```
=== MiniPrem Status ===
Installation type: default

Container Status:
NAME               STATUS              HEALTH
renny              Up 2 hours          healthy
miniprem-monitor   Up 2 hours          healthy

All services are running normally.
```

**実機での出力例（NAME / IMAGE / SERVICE / STATUS / PORTS フォーマット）：**

実際の MiniPrem では `docker compose ps` 相当の以下のような表形式で出力されます。`STATUS` 列に `Up <経過時間> (healthy)` が表示されていれば、Renny コンテナはヘルスチェック合格の正常稼働状態です。

```
+=================================================================+
| MiniPrem Services Status                                          |
+=================================================================+

NAME    IMAGE                                  COMMAND                  SERVICE   CREATED       STATUS                 PORTS
renny   facemeproduction/renny:0.540-40978     "/opt/renny/entrypoi…"   renny     7 hours ago   Up 7 hours (healthy)
```

**問題発生時の出力（サービスが異常）：**

```
=== MiniPrem Status ===
Installation type: default

Container Status:
NAME               STATUS              HEALTH
renny              Up 10 minutes       unhealthy
miniprem-monitor   Up 10 minutes       healthy

WARNING: Some services are unhealthy. Run './miniprem.sh logs <service>' for details.
```

**コンテナ状態の意味：**

| 状態                         | 意味                       | 対応            |
| -------------------------- | ------------------------ | ------------- |
| `Up X hours (healthy)`     | サービスが稼働しており正常に応答している     | 対応不要          |
| `Up X minutes (unhealthy)` | サービスは稼働中だがヘルスチェックに失敗している | ログでエラーを確認     |
| `Exited (1)`               | サービスがエラーでクラッシュした         | ログ確認後、再起動     |
| `Exited (0)`               | サービスが正常終了した              | 必要に応じて再起動     |
| `Restarting`               | サービスが再起動ループに入っている        | クラッシュ原因をログで確認 |

**個別コンテナのヘルスを確認します：**

```bash
docker inspect --format='{{.State.Health.Status}}' renny
```

#### Kubernetes デプロイの場合

**Pod の状態を確認します：**

```bash
kubectl get pods -n uneeq-renderer -o wide
```

**正常な出力：**

```
NAME                        READY   STATUS    RESTARTS   AGE   IP           NODE
renny-renderer-abc123-xyz   1/1     Running   0          2d    10.17.2.15   ip-10-17-2-248.ec2.internal
renny-renderer-def456-uvw   1/1     Running   0          2d    10.17.3.22   ip-10-17-3-112.ec2.internal
```

**問題発生時の出力：**

```
NAME                        READY   STATUS             RESTARTS   AGE   IP           NODE
renny-renderer-abc123-xyz   0/1     CrashLoopBackOff   5          10m   10.17.2.15   ip-10-17-2-248.ec2.internal
```

**Pod 状態の意味：**

| 状態                 | 意味                     | 対応                    |
| ------------------ | ---------------------- | --------------------- |
| `Running`          | Pod が正常に稼働している         | READY 列を確認（1/1 であること） |
| `Pending`          | Pod がスケジューリング待ち        | ノードのリソースとイベントを確認      |
| `CrashLoopBackOff` | Pod がクラッシュと再起動を繰り返している | `kubectl logs` でログを確認 |
| `ImagePullBackOff` | コンテナイメージを取得できない        | イメージ名とレジストリ認証情報を確認    |
| `Error`            | Pod の起動に失敗した           | ログとイベントを確認            |

**問題のある Pod の詳細を取得します：**

```bash
kubectl describe pod <pod-name> -n uneeq-renderer
```

***

### ステップ 4：Renny を個別に確認する

Renny はデジタルヒューマンの中核サービスです。正常に応答していることを確認しましょう。

#### ヘルスエンドポイントの確認

**Docker の場合：**

```bash
curl -s http://localhost:8081/health | head -20
```

**Kubernetes の場合（クラスターへアクセス可能なマシンから）：**

```bash
# まず Pod 名を取得します
kubectl get pods -n uneeq-renderer -o name | head -1

# 次にヘルスを確認します（取得した Pod 名に置き換えてください）
kubectl exec -n uneeq-renderer <pod-name> -- curl -s http://localhost:8081/health | head -20
```

**正常な出力（Renny が正常）：**

```json
{
  "status": "healthy",
  "version": "0.758-f9e3f",
  "uptime": "2h 15m 30s",
  "connections": {
    "platform": "connected",
    "speech": "ready"
  }
}
```

**問題発生時の出力（Renny が異常）：**

```json
{
  "status": "unhealthy",
  "version": "0.758-f9e3f",
  "uptime": "0h 5m 12s",
  "connections": {
    "platform": "disconnected",
    "speech": "error"
  },
  "errors": [
    "Failed to connect to UneeQ platform",
    "Speech service initialization failed"
  ]
}
```

**ヘルスエンドポイントが応答しない場合：**

```bash
# ポートが Listen 状態かを確認します（Docker）
docker exec renny netstat -tlnp | grep 8081

# またはコンテナが実際に稼働しているかを確認します
docker ps | grep renny
```

#### Renny の代表的なヘルス関連の問題

| 問題                       | 想定される原因                      | 解決策                          |
| ------------------------ | ---------------------------- | ---------------------------- |
| `platform: disconnected` | API キーが無効、またはネットワークの問題       | `configuration.dat` の認証情報を確認 |
| `speech: error`          | Azure Speech の認証情報が無効        | Azure のリージョンと speech key を確認 |
| まったく応答がない                | Renny がクラッシュ、またはポートが公開されていない | コンテナのログを確認                   |
| `status: starting`       | Renny がまだ初期化中                | 1〜2 分待ってから再確認                |

***

### ステップ 5：ログを収集する

ログには、サービス内部で起きていることに関する詳細な情報が含まれます。所在と読み解き方を以下に示します。

#### ログの確認

**Docker の場合：**

```bash
# 直近のログを表示
./miniprem.sh logs renny

# より詳細なオプションを指定する場合
docker logs renny --tail 100

# ログをリアルタイムで追跡（停止は Ctrl+C）
docker logs -f renny
```

**Kubernetes の場合：**

```bash
# 特定の Pod のログを表示
kubectl logs <pod-name> -n uneeq-renderer --tail 100

# ログをリアルタイムで追跡
kubectl logs -f <pod-name> -n uneeq-renderer

# すべての Renny Pod のログを表示
kubectl logs -l app=renny-renderer -n uneeq-renderer --tail 50
```

#### ログ形式の理解

Renny は JSON 形式のログを出力します。読み解き方は以下のとおりです。

**ログエントリ例：**

```json
{"timestamp":"2025-01-08T15:30:45.123Z","service":"renderer","log_level":"info","message":"Session started successfully","client_session_id":"abc123"}
```

**主なフィールド：**

* `timestamp`：イベントが発生した時刻
* `log_level`：重要度（debug、info、warn、error、fatal）
* `message`：発生した内容
* `client_session_id`：対象のユーザーセッション（該当する場合）

#### ログ内のエラーを探す

**エラー検索（Docker）：**

```bash
docker logs renny 2>&1 | grep -i "error\|fatal\|failed"
```

**エラー検索（Kubernetes）：**

```bash
kubectl logs <pod-name> -n uneeq-renderer | grep -i "error\|fatal\|failed"
```

**エラー出力の例：**

```
{"timestamp":"2025-01-08T15:30:45.123Z","log_level":"error","message":"Failed to connect to UneeQ platform: connection timeout"}
{"timestamp":"2025-01-08T15:31:00.456Z","log_level":"error","message":"Speech service unavailable: invalid credentials"}
```

#### ログをファイルに保存する

サポートへ連絡する際は、ログをファイルに保存してください。

**Docker：**

```bash
docker logs renny > renny_logs_$(date +%Y%m%d_%H%M%S).txt 2>&1
```

**Kubernetes：**

```bash
kubectl logs <pod-name> -n uneeq-renderer > renny_logs_$(date +%Y%m%d_%H%M%S).txt
```

#### ログレベルの意味

| レベル     | 意味      | 注意すべきタイミング                 |
| ------- | ------- | -------------------------- |
| `debug` | 詳細な診断情報 | 深いトラブルシューティング時のみ有用         |
| `info`  | 通常動作    | 想定どおりであり、問題ではない            |
| `warn`  | 潜在的な問題  | 記録に値し、将来的な問題の兆候の可能性        |
| `error` | 何らかの失敗  | 必ず調査するべき。何かが失敗している         |
| `fatal` | 致命的な障害  | サービスがクラッシュした可能性が高く、即時対応が必要 |

***

### ステップ 6：WebRTC 接続を診断する

デジタルヒューマンの映像が表示されない、もしくはセッション中に切断・コマ落ちが発生する場合、WebRTC レイヤーの一次切り分けを行います。

#### サーバ側ポートの到達性確認

P2P 構成では、表示端末から MiniPrem ホストの UDP 動的ポート（49152-65535）への接続性が必要です。

```bash
# 表示端末から MiniPrem ホストへの UDP 接続テスト
nc -u -v -z <MiniPremホストIP> 49152

# MiniPrem ホスト側で待ち受けポートを確認
ss -unap | grep -E "49[0-9]{3}|5[0-9]{4}|6[0-5]{4}"
```

TURN/STUN 構成では、TURN サーバーへの到達性も確認します。

```bash
# STUN サーバー（UDP 3478）への接続テスト
nc -u -v -z turn.uneeq.io 3478

# TURN サーバー（TLS / TCP 5349）への接続テスト
nc -v -z turn.uneeq.io 5349
```

#### ブラウザ側での確認（chrome://webrtc-internals/）

デジタルヒューマンを表示している端末の Google Chrome で `chrome://webrtc-internals/` を開き、ICE 接続状況と候補タイプを確認します。

```
# P2P 接続が成立している場合
"googLocalCandidateType": "host"
"googRemoteCandidateType": "host"
"iceConnectionState": "connected"

# TURN 経由で成立している場合
"googLocalCandidateType": "relay"
"googRemoteCandidateType": "relay"
"iceConnectionState": "connected"

# 使用ポートの確認例
"googLocalAddress": "192.168.200.200:49152"
"googRemoteAddress": "192.168.200.100:53872"
```

{% hint style="info" %}
ファイアウォール開放ポート（共通 / P2P / TURN）の早見表とホワイトリスト対象 FQDN は [ネットワーク要件](/dev/miniprem/network-requirements.md) を参照してください。
{% endhint %}

***

### ステップ 7：動作確認チェックリスト

サービスがすべて稼働している場合でも、エンドユーザー観点で「正常に動作している」と判断するには、実際にセッションを開始して以下の 4 項目を確認してください。

実行中のセッションに対してデジタルヒューマンへ発話指示を送信し、以下が正常に機能することを確認します。

* [ ] **レンダリング**：デジタルヒューマンが表示されるか
* [ ] **TTS（音声合成）**：指示したテキストが音声として出力されるか
* [ ] **アニメーション / リップシンク**：発話に合わせて口元・表情が動いているか
* [ ] **会話 AI（オーケストレーション）接続**：デジタルヒューマンと自然な会話のやりとりができるか

いずれかに失敗する場合は、症状に応じて [トラブルシューティングガイド](/dev/miniprem/troubleshooting.md) の該当セクションを参照してください。

***

### クイックチェックリスト

サポートに提供する情報を収集する際は、以下のチェックリストをご利用ください。

#### 必須情報

* [ ] **デプロイ種別**：Docker か Kubernetes か？
* [ ] **プラットフォーム状態**：Docker / Kubernetes は稼働しているか？
* [ ] **サービス状態**：`./miniprem.sh status` または `kubectl get pods` の出力
* [ ] **Renny のヘルス**：ヘルスエンドポイント確認の出力
* [ ] **直近のログ**：Renny ログの直近 100 行（ファイルに保存）

#### 追加コンテキスト（取得可能な場合）

* [ ] **インストール種別**：デフォルト（Default Install）かフルインストール（Full Install）か？（`cat .miniprem_install_type` の出力）
* [ ] **問題が発生し始めた時期**：アップデート後？設定変更後？
* [ ] **エラーメッセージ**：エラーメッセージの正確な文言
* [ ] **再現手順**：問題が発生したときに行っていた操作
* [ ] **事前診断スクリプトの結果**：`miniprem_precheck_YYYYMMDD_HHMM.txt`（[前提条件と事前診断](/dev/miniprem/prerequisites.md) を参照）
* [ ] **JavaScript コンソールログ**：レンダラー実行 / セッション開始時の不具合では、サーバ側ログだけでなく、表示端末側ブラウザ（Chrome）の DevTools（F12）で取得したセッションの JavaScript コンソールログも添付してください。クライアント起因の切断・無音・映像不具合の一次切り分けに必須です
* [ ] **WebRTC 接続情報**：`chrome://webrtc-internals/` のスクリーンショット、または `iceConnectionState` / `googLocalCandidateType` / `googRemoteCandidateType` の値

#### サポートチケットへ記載する情報

サポートへ連絡する際は、以下を含めてください。

```
Subject: [MiniPrem Issue] Brief description

Deployment: Docker / Kubernetes
Installation Type: Default / Full
Issue Started: Date/time or "after X"

Problem Description:
[What's happening vs what you expected]

Diagnostic Results:
- Platform running: Yes/No
- Service status: [paste output]
- Health check: [paste output]

Logs attached: renny_logs_YYYYMMDD_HHMMSS.txt

Steps to Reproduce:
1. [First step]
2. [Second step]
3. [Issue occurs]
```

***

### 次のステップ

* **問題が解決しない場合は？** サービス別の詳細な解決策については [トラブルシューティングガイド](/dev/miniprem/troubleshooting.md) を参照してください
* **セットアップで困っている場合は？** [はじめに](/dev/miniprem/getting-started.md) に戻ってください
* **アーキテクチャを理解したい場合は？** [サービス概要](/dev/miniprem/services.md) を参照してください