> ## Documentation Index
> Fetch the complete documentation index at: https://ai-kb.automationanywhere.com/llms.txt
> Use this file to discover all available pages before exploring further.

# オンプレミスのトラブルシューティング

> オンプレミス EKB 導入のトラブルシューティングのための L1 診断手順

このガイドでは、オンプレミス EKB 導入における問題のトラブルシューティングのためのレベル 1 (L1) 診断手順を説明します。これらの手順は、コンテナー、データベース、サービス、システム リソースに関する一般的な問題を特定するのに役立ちます。

<Warning>
  **Prerequisites**: You need SSH access to the customer's VM/server where EKB is deployed, and appropriate permissions to run Docker commands and access container logs.
</Warning>

## コンテナのステータスチェック

### すべてのコンテナのステータスを確認する

まず、実行中のコンテナとその健全性ステータスを確認します。

```bash theme={null}
# Check all containers status
docker ps -a

# Check containers with health status
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Health}}"

# Check specific container status
docker ps -a | grep <container_name>
```

**予想されるコンテナ:**

* `web` - フロントエンド アプリケーション
* `api` または `fastapi_backend` - バックエンド API サーバー
* `worker` または `celery_worker` - セロリワーカー
* `redis` - Redis キャッシュ
* `rabbitmq` - RabbitMQ メッセージ キュー
* `supabase-studio` - Supabase スタジオ
* `supabase-kong` - Kong API ゲートウェイ
* `supabase-auth` - 認証サービス
* `supabase-db` または `postgres` - PostgreSQL データベース
* その他の Supabase サービス (ストレージ、メタなど)

**確認事項:**

* すべてのコンテナが「稼働中」ステータスである必要があります
* コンテナは「再起動中」または「終了」状態であってはなりません
* ヘルスチェックでは、該当する場合は「正常」と表示される必要があります

### 失敗したコンテナを再起動する

コンテナが停止または再起動している場合:

```bash theme={null}
# Restart a specific container
docker restart <container_name>

# Restart all containers
docker compose restart

# Restart specific service
docker compose restart <service_name>
```

## バックエンドコンテナログ

### API コンテナのログを確認する

バックエンド API コンテナーのログには、エラー、データベース接続、サービスの問題に関する重要な情報が含まれています。

```bash theme={null}
# View recent logs (last 100 lines)
docker logs --tail 100 api

# Or for fastapi_backend
docker logs --tail 100 fastapi_backend

# Follow logs in real-time
docker logs -f api

# View logs with timestamps
docker logs -t api

# View logs from specific time
docker logs --since 30m api

# View logs between timestamps
docker logs --since "2024-01-01T00:00:00" --until "2024-01-01T23:59:59" api
```

**注意すべき点:**

* データベース接続エラー
* Redis 接続の失敗
* RabbitMQ 接続の問題
* 認証エラー
* API エンドポイント エラー (500、503 など)
* インポート/エクスポートのエラー
* ナレッジベースの処理エラー
* ワーカータスクの失敗

### ワーカー コンテナのログを確認する

ワーカー コンテナはバックグラウンド タスク (KB 処理、埋め込みなど) を処理します。

```bash theme={null}
# Check worker logs
docker logs --tail 100 worker

# Or for celery_worker
docker logs --tail 100 celery_worker

# Check all worker instances
docker ps | grep worker
docker logs <worker_container_name>
```

**注意すべき点:**

* タスク実行エラー
* メモリの問題
* タイムアウトエラー
* ワーカーでのデータベース接続エラー
* ナレッジベースの同期エラー
* 埋め込み生成エラー

### Web コンテナのログを確認する

フロントエンド コンテナーのログにより、UI と API の接続の問題が明らかになる場合があります。

```bash theme={null}
# Check web container logs
docker logs --tail 100 web

# Follow logs
docker logs -f web
```

**注意すべき点:**

* ビルドエラー
* API接続の失敗
* 環境変数の問題
* ポートバインディングエラー

## データベースのステータス

### PostgreSQL/Supabase データベースのステータスを確認する

```bash theme={null}
# Check database container status
docker ps | grep -E "(db|postgres|supabase-db)"

# Check database container logs
docker logs --tail 100 supabase-db

# Or for postgres container
docker logs --tail 100 postgres

# Connect to database (if psql is available)
docker exec -it supabase-db psql -U postgres

# Check database connections
docker exec supabase-db psql -U postgres -c "SELECT count(*) FROM pg_stat_activity;"

# Check database size
docker exec supabase-db psql -U postgres -c "SELECT pg_size_pretty(pg_database_size('postgres'));"
```

**確認事項:**

* データベースコンテナが実行中である
* 接続エラーがログに記録されない
* データベースがいっぱいではありません (ディスク容量を確認してください)
* アクティブな接続は制限内です
* 操作をブロックする長時間実行クエリなし

### API からデータベース接続を確認する

```bash theme={null}
# Test database connection from API container
docker exec api python -c "
import os
from sqlalchemy import create_engine
try:
    engine = create_engine(os.environ.get('DATABASE_URL'))
    conn = engine.connect()
    print('Database connection successful')
    conn.close()
except Exception as e:
    print(f'Database connection failed: {e}')
"
```

### データベースの移行を確認する

```bash theme={null}
# Check if migrations are up to date
docker exec api alembic current

# Check migration history
docker exec api alembic history

# View pending migrations
docker exec api alembic heads
```

## Redis ステータス

### Redis コンテナを確認する

```bash theme={null}
# Check Redis container status
docker ps | grep redis

# Check Redis logs
docker logs --tail 100 redis

# Test Redis connection
docker exec redis redis-cli ping

# Should return: PONG

# Check Redis info
docker exec redis redis-cli info

# Check Redis memory usage
docker exec redis redis-cli info memory

# Check connected clients
docker exec redis redis-cli info clients
```

**確認事項:**

* Redis が ping に応答しています
* メモリ使用量が制限内にある
* 接続エラーなし
* エビクション エラーなし (メモリがいっぱい)

### API コンテナから Redis をテストする

```bash theme={null}
# Test Redis connection from API
docker exec api python -c "
import redis
import os
try:
    r = redis.Redis(host='redis', port=6379, decode_responses=True)
    r.ping()
    print('Redis connection successful')
except Exception as e:
    print(f'Redis connection failed: {e}')
"
```

## RabbitMQ ステータス

### RabbitMQ コンテナを確認する

```bash theme={null}
# Check RabbitMQ container status
docker ps | grep rabbitmq

# Check RabbitMQ logs
docker logs --tail 100 rabbitmq

# Check RabbitMQ management (if accessible)
# Access: http://<server-ip>:15672
# Default credentials: user/password
```

**確認事項:**

* コンテナは実行中です
* 接続エラーなし
* キューがメッセージを処理中です
* メッセージのバックログがない

### API から RabbitMQ を確認する

```bash theme={null}
# Test RabbitMQ connection
docker exec api python -c "
import pika
try:
    connection = pika.BlockingConnection(
        pika.ConnectionParameters('rabbitmq', 5672, '/',
            pika.PlainCredentials('user', 'password'))
    )
    print('RabbitMQ connection successful')
    connection.close()
except Exception as e:
    print(f'RabbitMQ connection failed: {e}')
"
```

## システムリソース

### ディスク容量を確認する

ディスク容量が少ないと、データベース、ストレージ、コンテナーの問題が発生する可能性があります。

```bash theme={null}
# Check overall disk usage
df -h

# Check disk usage for Docker volumes
docker system df

# Check specific volume usage
docker volume inspect <volume_name>

# Check directory sizes
du -sh /var/lib/docker/volumes/*
du -sh ./supabase/docker/volumes/*

# Check in-container disk usage (for database)
docker exec supabase-db df -h
```

**確認事項:**

* ルート パーティションに十分なスペースがある (20% 以上の空きを推奨)
* Docker ボリュームがいっぱいではない
* データベース データ ディレクトリに空きがある
* Superbase ストレージにスペースがある

### メモリ使用量を確認する

```bash theme={null}
# Check system memory
free -h

# Check container memory usage
docker stats --no-stream

# Check specific container memory
docker stats <container_name> --no-stream
```

**確認事項:**

* システムに使用可能なメモリがある
* コンテナがメモリ制限に達していない
* ログに OOM (メモリ不足) による強制終了はありません

### CPU 使用率を確認する

```bash theme={null}
# Check CPU usage
top
# or
htop

# Check container CPU usage
docker stats --no-stream
```

## ネットワーク接続

### コンテナネットワークを確認する

```bash theme={null}
# Check Docker network
docker network ls

# Inspect network configuration
docker network inspect <network_name>

# Check if containers can communicate
docker exec api ping -c 3 redis
docker exec api ping -c 3 rabbitmq
docker exec api ping -c 3 supabase-db
```

### ポートの可用性を確認する

```bash theme={null}
# Check if ports are in use
netstat -tulpn | grep -E "(3001|8001|6379|5672|5432|8000)"

# Or using ss
ss -tulpn | grep -E "(3001|8001|6379|5672|5432|8000)"

# Check port from container
docker exec api curl -I http://localhost:8001/health
```

## 環境変数

### 環境構成を確認する

```bash theme={null}
# Check environment variables for a container
docker exec api env | grep -E "(DATABASE|REDIS|RABBITMQ|API)"

# Check .env files (if accessible)
cat ./env/.env.server | grep -v "PASSWORD\|SECRET\|KEY"  # Exclude sensitive data
cat ./env/.env.web | grep -v "PASSWORD\|SECRET\|KEY"

# Check environment from docker-compose
docker compose config
```

**確認事項:**

* データベース接続文字列が正しい
* Redis および RabbitMQ のホスト名が正しい
* API URLが適切に構成されている
* 必要な環境変数が設定されている
* 変数名のタイプミスがないこと

## ファイルのアクセス許可

### ファイルとディレクトリのアクセス許可を確認する

```bash theme={null}
# Check permissions on key directories
ls -la ./alignment-project-server
ls -la ./ai-content-creator
ls -la ./supabase/docker/volumes

# Check Docker socket permissions
ls -la /var/run/docker.sock

# Check certificate files (if using HTTPS)
ls -la ./certs/
```

**確認事項:**

* アプリケーションディレクトリは読み取り可能です
* Docker ソケットに正しい権限がある
* ボリュームマウントには適切な権限が必要です
* 証明書ファイルにアクセス可能

## サービス固有のチェック

### ナレッジベースの問題

ナレッジベースが更新または処理されていない場合:

```bash theme={null}
# Check worker logs for KB processing
docker logs --tail 200 worker | grep -i "knowledge\|kb\|embedding"

# Check for embedding model issues
docker logs api | grep -i "embedding\|model"

# Check Supabase storage
docker logs supabase-storage

# Check file upload limits
docker exec supabase-db psql -U postgres -c "
SELECT name, file_size_limit 
FROM storage.buckets;
"
```

### チャット/エージェントの問題

```bash theme={null}
# Check API logs for agent errors
docker logs --tail 200 api | grep -i "agent\|chat\|llm"

# Check worker logs for agent tasks
docker logs --tail 200 worker | grep -i "agent\|chat"
```

### 認証の問題

```bash theme={null}
# Check auth service logs
docker logs --tail 100 supabase-auth

# Check database for auth issues
docker exec supabase-db psql -U postgres -c "
SELECT * FROM auth.users LIMIT 5;
"
```

## 一般的なエラー パターン

### データベース接続エラー

**症状:**

* 「接続が拒否されました」エラー
* 「接続が多すぎます」エラー
* タイムアウトエラー

**診断手順:**

1. データベース コンテナーが実行されていることを確認します: `docker ps | grep db`
2. データベース ログを確認します: `docker logs supabase-db`
3. 接続制限を確認します: `docker exec supabase-db psql -U postgres -c "SHOW max_connections;"`
4. アクティブな接続を確認します: `docker exec supabase-db psql -U postgres -c "SELECT count(*) FROM pg_stat_activity;"`
5. 環境変数の DATABASE\_URL を確認します。

### Redis 接続エラー

**症状:**

* Redis への「接続が拒否されました」
* キャッシュミス
* セッションの問題

**診断手順:**

1. Redis コンテナーを確認します: `docker ps | grep redis`
2. Redis をテストします: `docker exec redis redis-cli ping`
3. Redis ログを確認します: `docker logs redis`
4. 環境変数で Redis ホスト名を確認する

### ワーカータスクの失敗

**症状:**

* タスクが完了しない
* ナレッジベースが同期しない
* バックグラウンドジョブが失敗する

**診断手順:**

1. ワーカーのログを確認します: `docker logs worker`
2. ワーカーコンテナのステータスを確認します: `docker ps | grep worker`
3. RabbitMQ キューを確認する: RabbitMQ 管理 UI にアクセスします。
4. メモリの問題を確認します: `docker stats worker`

### ストレージ/ファイルのアップロードの問題

**症状:**

* ファイルのアップロードに失敗する
* 「ファイルが大きすぎます」エラー
* ストレージ割り当てを超過しました

**診断手順:**

1. ディスク容量を確認します: `df -h`
2. Supabase ストレージ ログを確認します: `docker logs supabase-storage`
3. Supabase 設定でファイル サイズ制限を確認する
4. ストレージバケット構成を確認する

## クイック診断スクリプト

すべてのチェックを一度に実行する診断スクリプトを作成します。

```bash theme={null}
#!/bin/bash
echo "=== EKB On-Premise Diagnostics ==="
echo ""
echo "1. Container Status:"
docker ps --format "table {{.Names}}\t{{.Status}}"
echo ""
echo "2. Disk Space:"
df -h | grep -E "(Filesystem|/dev/)"
echo ""
echo "3. Memory:"
free -h
echo ""
echo "4. Redis:"
docker exec redis redis-cli ping 2>/dev/null || echo "Redis not responding"
echo ""
echo "5. Database:"
docker exec supabase-db psql -U postgres -c "SELECT version();" 2>/dev/null || echo "Database not responding"
echo ""
echo "6. Recent API Errors (last 20 lines):"
docker logs --tail 20 api 2>/dev/null | grep -i error || echo "No recent errors"
echo ""
echo "=== Diagnostics Complete ==="
```

`diagnostics.sh` として保存し、実行可能ファイルを作成: `chmod +x diagnostics.sh`、実行: `./diagnostics.sh`

## エスカレーション情報

L2 サポートにエスカレーションする場合は、以下を提供します。

1. **コンテナステータス**: `docker ps -a` の出力
2. **最近のログ**: 関連するコンテナからの最後の 100 ～ 200 行
3. **システム リソース**: `df -h` および `free -h` の出力
4. **エラー メッセージ**: ログからの特定のエラー メッセージ
5. **設定**: 設定される環境変数名 (値ではありません)
6. **タイムライン**: 問題の開始時期
7. **影響**: どの機能が影響を受けますか

**サポートへのお問い合わせ**: [support@automationanywhere.com](mailto:support@automationanywhere.com)

## 追加のリソース

* **リンク\_7**
* **リンク\_8**