aurak/docs/1.0/DEPLOYMENT.md

# デプロイガイド

## 開発環境のデプロイ

### 前提条件

- Node.js 18+
- Yarn
- Docker & Docker Compose

### 1. プロジェクトのクローン

```bash
git clone <repository-url>
cd simple-kb
```

### 2. 依存関係のインストール

```bash
yarn install
```

### 3. 基本サービスの起動

```bash
# Elasticsearch と Tika を起動
docker-compose up -d elasticsearch tika
```

### 4. 環境変数の設定

```bash
# 環境変数のテンプレートをコピー
cp server/.env.sample server/.env

# 設定ファイルを編集
vim server/.env
```

### 5. 開発サービスの起動

```bash
# フロントエンドとバックエンドを同時に起動
yarn dev

# または個別に起動
yarn dev:web    # フロントエンド (ポート 5173)
yarn dev:server # バックエンド (ポート 3000)
```

## 本番環境のデプロイ

### Docker Compose を使用する場合

1. **環境変数の設定**

```bash
cp .env.sample .env
# 本番環境の設定を編集
```

1. **ビルドと起動**

```bash
# すべてのサービスを一括起動
docker-compose up -d
```

1. **サービスへのアクセス**

- HTTPS: <https://localhost> (推奨)
- HTTP: <http://localhost> (HTTPS へ自動リダイレクト)
- バックエンド API: Nginx プロキシ経由でアクセス
- Elasticsearch: <http://localhost:9200>
- Tika: <http://localhost:9998>

### サービス構成

- **nginx**: リバースプロキシ。HTTPS と CORS 処理を担当
- **web**: フロントエンド静的ファイルサービス (React)
- **server**: バックエンド API サービス (NestJS)
- **libreoffice**: LibreOffice ドキュメント変換サービス (FastAPI, ポート 8100)
- **elasticsearch**: ベクトル検索エンジン (ポート 9200)
- **tika**: ドキュメント内容抽出サービス (ポート 9998)

### アーキテクチャ図

```
ユーザー → nginx → web (React)
                ↓
              server (NestJS) → elasticsearch
                ↓                 ↓
          libreoffice        tika
          (FastAPI)       (Java)
```

### SSL 証明書の設定

#### 自己署名証明書（開発環境用）

```bash
# 自己署名証明書を生成
./nginx/generate-ssl.sh
```

#### 本番環境用証明書

正式な SSL 証明書を以下の場所に配置してください：

- 証明書ファイル: `nginx/ssl/cert.pem`
- 秘密鍵ファイル: `nginx/ssl/key.pem`

### Docker 常用コマンド

```bash
# すべてのサービスのログを表示
docker-compose logs -f

# 特定のサービスのログを表示
docker-compose logs -f nginx
docker-compose logs -f server

# サービスの再起動
docker-compose restart

# 特定のサービスの再起動
docker-compose restart nginx

# サービスの停止
docker-compose down

# 再ビルドして起動
docker-compose up -d --build
```

### データの永続化

#### SQLite データベース

- データベースファイルの場所: `./data/database.sqlite`
- コンテナ外部に自動マウントされるため、コンテナ再起動時もデータは失われません。

#### アップロードファイル

- ファイルの保存場所: `./uploads/`
- アップロードされたすべてのドキュメントと画像はホストマシンに保存されます。

#### Elasticsearch データ

- データボリューム: `elasticsearch-data`
- ベクトルインデックスデータが永続的に保存されます。

### 手動デプロイ

1. **フロントエンドのビルド**

```bash
cd web
yarn build
```

1. **バックエンドのビルド**

```bash
cd server
yarn build
```

1. **Nginx の設定**

```nginx
server {
    listen 80;
    server_name your-domain.com;
    
    # フロントエンド静的ファイル
    location / {
        root /path/to/web/dist;
        try_files $uri $uri/ /index.html;
    }
    
    # バックエンド API プロキシ
    location /api {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

## 環境変数の設定

### バックエンド環境変数 (server/.env)

```bash
# データベース
DATABASE_PATH=./data/metadata.db

# Elasticsearch
ELASTICSEARCH_HOST=http://localhost:9200
ELASTICSEARCH_INDEX=knowledge_base_chunks

# Tika サービス
TIKA_HOST=http://localhost:9998

# LibreOffice サービス
LIBREOFFICE_URL=http://localhost:8100

# Vision API
VISION_API_KEY=sk-xxx-your-key
VISION_API_BASE=https://api.openai.com/v1
VISION_MODEL=gpt-4-vision-preview

# ファイルアップロード
UPLOAD_FILE_PATH=./uploads
MAX_FILE_SIZE=50MB

# 一時ディレクトリ
TEMP_DIR=./temp

# JWT
JWT_SECRET=your-jwt-secret-key
JWT_EXPIRES_IN=7d

# サービスポート
PORT=3000
```

### フロントエンド環境変数 (web/.env)

```bash
# API アドレス
VITE_API_BASE_URL=http://localhost:3000

# アプリケーション設定
VITE_APP_TITLE=簡易ナレッジベース
VITE_MAX_FILE_SIZE=50
```

## バックアップと復元

### SQLite データベースのバックアップ

```bash
# バックアップ
cp server/data/metadata.db backup/metadata_$(date +%Y%m%d).db

# 復元
cp backup/metadata_20240101.db server/data/metadata.db
```

### Elasticsearch データのバックアップ

```bash
# スナップショット用リポジトリの作成
curl -X PUT "localhost:9200/_snapshot/backup_repo" -H 'Content-Type: application/json' -d'
{
  "type": "fs",
  "settings": {
    "location": "/backup/elasticsearch"
  }
}'

# スナップショットの作成
curl -X PUT "localhost:9200/_snapshot/backup_repo/snapshot_1"
```

## 監視とログ

### アプリケーションログ

- フロントエンドログ: ブラウザのコンソール
- バックエンドログ: `server/logs/`
- Elasticsearch ログ: Docker コンテナログ

### ヘルスチェック

```bash
# バックエンドのヘルスチェック
curl http://localhost:3000/health

# Elasticsearch のヘルスチェック
curl http://localhost:9200/_cluster/health
```

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

### よくある質問

1. **Elasticsearch への接続に失敗する**
   - Docker コンテナの状態を確認してください。
   - ポート 9200 がアクセス可能か確認してください。
   - ファイアウォールの設定を確認してください。

2. **ファイルのアップロードに失敗する**
   - uploads ディレクトリの権限を確認してください。
   - Tika サービスが正常に動作しているか確認してください。
   - ファイルサイズの制限を確認してください。

3. **モデル API の呼び出しに失敗する**
   - API キーの設定を確認してください。
   - ネットワーク接続を確認してください。
   - モデル ID が正しいか確認してください。

#### 1. Elasticsearch への接続失敗

**症状**: バックエンドログに "Connection refused" または "ECONNREFUSED" と表示される
**解決策**:

- Docker コンテナの状態確認: `docker-compose ps`
- ポート 9200 のアクセス確認: `curl http://localhost:9200`
- ファイアウォール設定の確認
- Elasticsearch の再起動: `docker-compose restart elasticsearch`

#### 2. ファイルのアップロード失敗

**症状**: アップロード時に「アップロード失敗」または「処理失敗」と表示される
**解決策**:

- uploads ディレクトリの権限確認: `ls -la server/uploads/`
- Tika サービスの状態確認: `curl http://localhost:9998/version`
- ファイルサイズ制限の確認（デフォルト 50MB）
- バックエンドログの詳細エラーを確認

#### 3. モデル API の呼び出し失敗

**症状**: チャット時に「API キーが無効」または「モデルの呼び出しに失敗」と表示される
**解決策**:

- API キーの設定が正しいか確認
- ネットワーク接続とファイアウォールの確認
- モデル ID の確認（例: gpt-4, gpt-3.5-turbo）
- API の利用残高と権限の確認
- Base URL の設定確認（OpenAI 互換インターフェースの場合）

#### 4. ユーザー認証の問題

**症状**: ログイン失敗またはトークンの期限切れ
**解決策**:

- ユーザー名とパスワードの確認
- ブラウザのキャッシュと localStorage のクリア
- JWT_SECRET の設定確認
- ユーザーアカウントの再登録

#### 5. ナレッジベースの検索結果が出ない

**症状**: 質問後に「関連する知識が見つかりません」と表示される
**解決策**:

- ファイルのインデックスが完了しているか確認（ステータスが「完了」）
- 類似度しきい値の設定を調整
- Embedding モデルの設定確認
- 別のキーワードで質問してみる

#### 6. フロントエンドページにアクセスできない

**症状**: ブラウザに「このサイトにアクセスできません」と表示される
**解決策**:

- フロントエンドサービスがポート 5173 で動作しているか確認
- ファイアウォールとプロキシの設定確認
- ブラウザのキャッシュのクリア
- シークレットモードでのアクセスを試す

### デバッグツール

#### サービス状態の確認

```bash
# すべての Docker コンテナを確認
docker-compose ps

# ポートの使用状況を確認
netstat -tulpn | grep :5173
netstat -tulpn | grep :3000
```

#### 詳細ログの表示

```bash
# バックエンドログ
docker-compose logs -f server

# Elasticsearch ログ
docker-compose logs -f elasticsearch

# フロントエンド開発ログ
cd web && yarn dev
```

#### ヘルスチェック

```bash
# バックエンド API のヘルスチェック
curl http://localhost:3000/health

# Elasticsearch のヘルスチェック
curl http://localhost:9200/_cluster/health

# LibreOffice サービスのチェック
curl http://localhost:8100/health

# LibreOffice API ドキュメントの表示
open http://localhost:8100/docs
```

### パフォーマンスの最適化

#### 1. Elasticsearch のチューニング

```bash
# JVM ヒープメモリの増量
export ES_JAVA_OPTS="-Xms2g -Xmx2g"

# インデックス状態の確認
curl http://localhost:9200/_cat/indices?v
```

#### 2. ファイル処理の最適化

- 同時にアップロードするファイル数を制限する
- チャンクサイズを適切に調整する（推奨 512-1024 トークン）
- 不要なインデックスデータを定期的に整理する

### データの復元

#### SQLite データベースの復元

```bash
# バックアップから復元
cp backup/metadata_20240101.db server/data/metadata.db

# データベースの整合性チェック
sqlite3 server/data/metadata.db "PRAGMA integrity_check;"
```

#### Elasticsearch データの復元

```bash
# スナップショットの復元
curl -X POST "localhost:9200/_snapshot/backup_repo/snapshot_1/_restore"
```