デプロイガイド

開発環境のデプロイ

前提条件

Node.js 18+
Yarn
Docker & Docker Compose

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

git clone <repository-url>
cd lumina

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

yarn install

3. 基本サービスの起動

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

4. 環境変数の設定

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

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

5. 開発サービスの起動

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

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

本番環境のデプロイ

Docker Compose を使用する場合

環境変数の設定

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

ビルドと起動

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

サービスへのアクセス

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 証明書の設定

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

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

本番環境用証明書

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

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

Docker 常用コマンド

# すべてのサービスのログを表示
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
ベクトルインデックスデータが永続的に保存されます。

手動デプロイ

フロントエンドのビルド
```
cd web
yarn build
```
バックエンドのビルド
```
cd server
yarn build
```

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)

# データベース
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)

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

# アプリケーション設定
VITE_APP_TITLE=Lumina
VITE_MAX_FILE_SIZE=50

バックアップと復元

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

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

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

Elasticsearch データのバックアップ

# スナップショット用リポジトリの作成
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 コンテナログ

ヘルスチェック

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

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

トラブルシューティング

よくある質問

Elasticsearch への接続に失敗する
- Docker コンテナの状態を確認してください。
- ポート 9200 がアクセス可能か確認してください。
- ファイアウォールの設定を確認してください。
ファイルのアップロードに失敗する
- uploads ディレクトリの権限を確認してください。
- Tika サービスが正常に動作しているか確認してください。
- ファイルサイズの制限を確認してください。
モデル 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 で動作しているか確認
ファイアウォールとプロキシの設定確認
ブラウザのキャッシュのクリア
シークレットモードでのアクセスを試す

デバッグツール

サービス状態の確認

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

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

詳細ログの表示

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

# Elasticsearch ログ
docker-compose logs -f elasticsearch

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

ヘルスチェック

# バックエンド 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 のチューニング

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

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

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

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

データの復元

SQLite データベースの復元

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

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

Elasticsearch データの復元

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

DEPLOYMENT.md 11 KB Histórico Raw

デプロイガイド

開発環境のデプロイ

前提条件

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

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

3. 基本サービスの起動

4. 環境変数の設定

5. 開発サービスの起動

本番環境のデプロイ

Docker Compose を使用する場合

サービス構成

アーキテクチャ図

SSL 証明書の設定

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

本番環境用証明書

Docker 常用コマンド

データの永続化

SQLite データベース

アップロードファイル

Elasticsearch データ

手動デプロイ

環境変数の設定

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

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

バックアップと復元

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

Elasticsearch データのバックアップ

監視とログ

アプリケーションログ

ヘルスチェック

トラブルシューティング

よくある質問

1. Elasticsearch への接続失敗

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

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

4. ユーザー認証の問題

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

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

デバッグツール

サービス状態の確認

詳細ログの表示

ヘルスチェック

パフォーマンスの最適化

1. Elasticsearch のチューニング

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

データの復元

SQLite データベースの復元

Elasticsearch データの復元

DEPLOYMENT.md 11 KB

Histórico Raw