Fabric Apps のトラブルシューティング

Fabric Apps プロジェクトを開発またはデプロイするときの一般的な問題を診断します。 この記事では、サインイン、ローカル サービス、スキーマの変更、静的ホスティング、CLI に関する問題について説明します。

デプロイメントの問題

401 または 403 エラーでデプロイが失敗する

症状：npx rayfin upを実行すると、認証エラーが返されます。

原因： 認証セッションの有効期限が切れているか、サインインしていません。

Solution:

再認証し、デプロイを再試行します。

npx rayfin login
npx rayfin up

データベース適用レポートで破壊的変更が報告されます

症状：npx rayfin up db apply ブロックを実行し、データ損失に関する警告を表示します。

原因： CLI によって、データを削除する可能性があるスキーマの変更 (列の削除、テーブルの名前変更) が検出されました。

Solution:

一覧表示されている操作を注意深く確認します。 データ損失を受け入れる場合は、次の --forceを使用します。

npx rayfin up db apply --force

Caution

--forceを使用すると、永続的なデータ損失が発生する可能性があります。 続行する前に、操作を確認します。

静的デプロイがサイズ制限を超えています

症状： 静的コンテンツのデプロイは、サイズ制限エラーで失敗します。

原因： 圧縮アーカイブが 100 MB を超えています。

Solution:

次の方法でビルド出力サイズを小さくします。

  • 運用ビルドからのソース マップの除外
  • 大きな画像やビデオを最適化または削除する
  • バイナリ ファイルをバンドルするのではなく、ストレージに移動する
  • バンドラ構成で開発用成果物が除外されることを確認する

認証の問題

サインイン後にセッションが保持されない

症状： ユーザーは認証の直後にサインアウトされます。

原因： クライアントが正しいベース URL または発行可能なキーで構成されていません。

Solution:

RayfinClient構成がバックエンドと一致するかどうかを確認します。

const client = new RayfinClient({
  baseUrl: import.meta.env.VITE_RAYFIN_API_URL ?? 'http://localhost:5168',
  publishableKey: import.meta.env.VITE_RAYFIN_PUBLISHABLE_KEY,
});

Fabric SSO ポップアップがブロックされました

Symptom: ブラウザーは、サインイン時にFabricポータル ウィンドウをブロックします。

原因:ensureSignedInWithFabric() は、ユーザー ジェスチャ ハンドラーから呼び出されませんでした。

Solution:

同期イベント ハンドラーから関数を呼び出します。

async function handleClick() {
  await ensureSignedInWithFabric(client.auth, options);
}

// Attach to button click
<button onClick={handleClick}>Sign in</button>

データ モデルの問題

API にリレーションシップが表示されない

症状： 関連エンティティ フィールドは、クエリを実行するときに使用できません。

原因： ナビゲーション デコレーターが見つからないか、スキーマが適用されませんでした。

Solution:

  1. リレーションシップデコレーターが存在することを確認します。

    @one(() => Notebook) notebook?: Notebook;

  2. スキーマを再適用します。

承認ポリシーが機能しない

症状： ユーザーは、表示すべきではないレコードにアクセスできます。

原因： ポリシー式が正しくないか、要求名が一致しません。

Solution:

  1. ポリシーで正しい要求名 (sub、 email、 role) が使用されていることを確認します。

    policy: (claims, item) => claims.sub.eq(item.user_id)

  2. デコードされた JWT をログに記録して、要求値がコードと一致することを確認します。

古い API 応答

症状： フロントエンドは、スキーマの変更後に古いデータ図形を返します。

原因： 生成された構成がキャッシュされます。

Solution:

  1. バックエンドを停止します。

  2. .temp/でrayfin/ ディレクトリを削除します。

    rm -rf rayfin/.temp/

  3. サービスを再起動し、スキーマを再適用します。

CLI の問題

コマンドが見つからない

症状：npx rayfinを実行すると、"コマンドが見つかりません" が返されます。

原因： CLI がインストールされていないか、npm が PATH にありません。

Solution:

  1. Node.js と npm がインストールされていることを確認します。

    node --version
npm --version

  2. 依存関係を再インストールします。

    npm install

CLI バージョンの不一致

症状： CLI コマンドは、更新後に予期しないエラーで失敗します。

原因： キャッシュされた CLI のバージョンが古くなっています。

Solution:

更新して再インストールします。

npm update --save
npm install
npx rayfin --version

CLI グローバル バージョンとローカル バージョンの不一致

症状： CLI コマンドは、プロジェクト間で予期しないエラーで失敗します。

原因： CLI バージョンのグローバルインストールとローカルインストールが一致しません。

解決策: ローカル バージョンの npm list @microsoft/rayfin-cliを検証します。 現在のプロジェクトのnode_modulesのバージョンが表示されます。 グローバル バージョンの npm list -g @microsoft/rayfin-cliを確認します。 システム全体にインストールされているバージョンが表示されます。 rayfin CLI パッケージで npm uninstall -g を使用して、グローバル バージョンを削除し、ローカル バージョンを使用します。

ビルドとパッケージ化の問題

ビルド コマンドが失敗する

症状： ビルド コマンドで出力が生成されないため、静的ホスティングのデプロイは失敗します。

原因： ビルド エラーまたは正しく構成されていないビルド コマンド。

Solution:

  1. ビルド コマンドを手動で実行します。

    npm run build

  2. 報告されたエラーを修正します。

  3. 出力フォルダーにファイルが含まれていることを確認します。

空の静的フォルダー

症状： 静的デプロイが "空のフォルダー" エラーで失敗する。

原因： 構成された folder パスが正しくありません。

Solution:

folderのrayfin.yml パスがビルド出力と一致するかどうかを確認します。

services:
  staticHosting:
    folder: dist  # Verify this matches your build output
    buildCommand: npm run build

データベースの問題

接続が拒否されました

症状： データ操作は接続エラーで失敗します。

原因： データベース コンテナーが実行されていないか、正常性チェックが失敗しました。

Solution:

  1. コンテナー ログを確認します。

    docker compose logs -f

  2. サービスを再起動します。

再起動後のデータ損失

症状： サービスを停止して開始すると、データが消えます。

原因： ボリュームは --purgeで削除されました。

Solution:

データを保持するには、--downの代わりに--purgeを使用します。

既知の制限

現在の制限事項と推奨される回避策については、次を参照してください。

  • count() は fluent GraphQL クライアントでは使用できません。 results.lengthを使用します。
  • 多対多リレーションシップはサポートされていません。明示的な結合エンティティを使用します。
  • セッション オブジェクトは不透明であり、 isAuthenticated プロパティまたは user プロパティを確認します。
  • rayfin.ymlで認証を有効または無効にした後、バックエンドを再起動します。

ヘルプを取得する

問題が解決しない場合:

  1. Fabric Apps のドキュメントを確認します。
  2. GitHub リポジトリで既知の問題を確認します。
  3. 詳細なログと再現手順を含むバグ レポートを提出します。

関連するコンテンツ

  • Last updated on