デスクトップのトラブルシューティング

変更する前にランタイムを特定する

デスクトップ セッションには個別の障害境界があります。Vite は開発中にフロントエンド アセットを提供します。 Tauri Rust プロセスはネイティブ統合を備えています。 Bun サイドカーはアプリケーションのリクエストと永続性を処理します。 SolidJS WebビューはそのAPIに接続します。空白のウィンドウ、ブート タイムアウト、401 応答、空のプロジェクト リストには、さまざまな原因が考えられます。

起動コマンドと、エンドポイントが Tauri 変数と Vite 変数のどちらから来たのかを記録します。異なるランタイムで異なるデータが表示されるという理由だけで、データベースを削除したり、依存関係を再インストールしたりしないでください。

起動タイミングを理解する

Rust シェルは起動トークンを生成し、アプリケーション データと移行ディレクトリを解決し、ターゲット サイドカーを生成します。子供が束縛する 127.0.0.1 一時的なポート上で。公開されるまで待ちます /api/health 応答すると、そのポートを使用して JSON Ready イベントを書き込みます。 WebView が呼び出すのは、 get_sidecar_endpoint そしてそのマネージド API ランタイムを作成します。

再試行すると、WebView 接続の試行が再開されます。枯渇した Rust 監視予算を補充するものではありません。起動原因を修正し、スーパーバイザが端末障害状態に達したときにアプリを再起動します。子の再起動前のポートは古くなっている可能性があります。

ポートと健全性を個別に確認する

ヴァイトの用途 localhost:1420 tauri の設定された開発 URL と一致する厳密なポート選択を使用します。別のポートに静かに移動するのではなく、失敗します。サイドカー ポートは無関係であり、起動ごとに変更されます。コンパニオン HTTPS ポートは 3 番目のリスナー (デフォルトは 8443) で、Studio はループバック 4396 を使用します。

CADCAM_URL=http://127.0.0.1:43111
CADCAM_TOKEN=local-development-token

curl --max-time 5 --fail-with-body "$CADCAM_URL/api/health"
curl --max-time 5 --fail-with-body "$CADCAM_URL/health"   -H "Authorization: Bearer $CADCAM_TOKEN"
curl --max-time 5 --fail-with-body "$CADCAM_URL/version"   -H "Authorization: Bearer $CADCAM_TOKEN"

公衆衛生ルートはステータスとタイムスタンプを返します。認証されたシステム ルートにより、準備状況とアプリケーションのバージョンが公開されます。正常なプロセスは、すべてのプロバイダー、データベース クエリ、またはネイティブ ダイアログが機能することを証明するものではありません。比較してください ヘルス API そして システムAPI プローブを選択するとき。

ポート 1420 が占有されている場合は、既存の開発サーバーを特定して意図的に停止します。記憶された API ポートが接続を拒否した場合は、隣接するポートを推測するのではなく、現在の Ready イベントを読み取るか、Tauri エンドポイントを再解決します。

独立したサイドカーで再現

ソース プロセスは、ネイティブ バンドルの問題をサーバーの動作から分離するのに役立ちます。対話型ターミナルのリポジトリ ルートからこれを実行します。新しいデータ ディレクトリを作成し、生成された移行フォルダーを明示的に使用します。

CADCAM_DIAGNOSTIC_DIR=$(mktemp -d /tmp/cadcamfun-desktop-guide.XXXXXX)
CADCAMFUN_TOKEN=local-development-token CADCAMFUN_DATA_DIR="$CADCAM_DIAGNOSTIC_DIR/data" CADCAMFUN_MIGRATIONS_DIR="$PWD/packages/db/drizzle" CADCAMFUN_AI_OFFLINE=true bun --no-env-file apps/sidecar/src/main.ts

アナウンスされたポートを 2 番目の端末のプローブ変数にコピーします。オフライン AI モードでは、基本的な起動診断のために構成されたリモート モデルに依存することを回避します。代替のローカル モデルは実行されません。サーバーは、標準入力 EOF、明示的なシャットダウン イベント、および通常のランタイム割り込みを監視します。

ソースプロセスは現在のファイルを使用します。ネイティブ プロセスは、すでにステージングされているコンパイル済み実行可能ファイルを使用します。 src-tauri/binaries。コンパイルされた実行のみが失敗した場合は、次の方法で再構築します。 bun run build:sidecar バンドル/移行リソースを検査します。 TypeScript を編集しても、すでに実行されている実行可能ファイルは置き換えられません。

実際のデータベース パスを解決する

これらのファイルはエイリアスではありません。欠落している図面を調査する前に、選択したプロセス パスを一致させてください。ブラウザ フィクスチャがこれらの SQLite ファイルを開くことはありません。サイドカーは、その構成が移行フォルダーを提供する場合にのみ移行を適用します。これを省略しても、source-tree フォルダーは自動的に検出されません。

データベース層では、WAL と外部キーが有効になります。既存のデータベースをアップグレードする前に、自動移行前バックアップが書き込まれ、一致する 5 つのバックアップが保持されます。保存、変更なしの起動、最初の作成、またはメモリ内テストのたびにこのようなバックアップが作成されるわけではありません。データベース/リカバリ手順を通じて一貫性のあるバックアップを保存します。実行中の WAL データベースのメイン ファイルのみをコピーすると、コミットされた WAL コンテンツを省略できます。

プロトコルの出力とログを読み取る

ソース サイドカー ターミナルでは、stdout は準備完了/エラー プロトコル イベント用に予約されており、JSON アプリケーション ログは stderr に保存されます。ネイティブ アプリでは、Rust ロギング プラグインは、監視された子の出力を含むシェル側のイベントをキャプチャします。シェルは、起動資格情報が含まれる可能性のある行を編集します。

ネイティブ get_logs_dir コマンドは、オペレーティング システムのアプリケーション ログ ディレクトリを解決します。システム全体に 1 つのユニバーサル パスを想定するよりも信頼性が高くなります。 Web ビュー内の開発者診断は、既存の Tauri コマンド インターフェイスを通じて呼び出すことができます。ネイティブ パスを開くことは、許可されたフォルダーに制限され、実行可能なファイル タイプは拒否されます。

再利用可能なブート画面コンポーネントは、オプションのログ表示コールバックをサポートしていますが、現在の App.tsx そのコールバックを渡しません。起動失敗時に [ログの表示] ボタンが表示されるとは想定しないでください。開発起動ターミナルを利用可能な状態にしておくか、適切な診断画面を通じてネイティブ ログ ディレクトリを使用してください。

レポートには、起動モード、非機密データ/移行パス、経過待機、現在の API バージョン、正確なエラー タグ/メッセージ、および関連する最新の起動イベントが含まれます。起動/セッション/デバイストークン、ペアリングリンク、モデルキー、署名資料を編集します。

認証と空のデータを区別する

ブラウザのリアルクライアント モードには両方が必要です VITE_SIDECAR_URL そして VITE_SIDECAR_TOKEN。トークンのない URL は偽のフォールバックをアクティブにしません。エンドポイント解決に失敗します。 Vite が起動する前に変数を指定する必要があります。親シェルを更新しても、すでに実行されているサーバーは再構成されません。

VITE_SIDECAR_URL=http://127.0.0.1:43111 VITE_SIDECAR_TOKEN=local-development-token bun run --filter @cadcamfun/desktop dev

保護された呼び出しでは、アプリケーション トークンに加えてアカウント セッション コンテキストを使用できます。コンパニオン トークンとスタンドアロン ブリッジ トークンのスコープは狭く、起動トークンの代わりにはなりません。 401 には認証情報の診断が必要です。 403 には操作/アクセスの診断が必要です。存在しないプロジェクトまたはアクセスできないプロジェクトは、404 として報告できます。

現在、プロジェクトの子リソース タブを含む一部の画面では、個々のリスト エラーが空の配列に変換されます。空白のタブは、レコードが削除されたことを示す十分な証拠ではありません。対応するものを読んでください プロジェクト, 描画、 または ツールパス 作業を再作成する前にエンドポイントを確認してください。

有効な起動トークンは 64 個の 16 進文字 (32 個のランダム バイト) であり、起動するたびに変更されます。デスクトップ シェルによって異なる形式のトークンが発行されませんでした。

プレビューとネイティブの制限を認識する

偽の API は、選択されたプロジェクト、図面、マテリアル、ツール、マシン、ツールパス、KV、およびジェネレーター パスを処理します。サポートされていないコレクションは、プレビュー固有のメッセージを含む HTTP 501 を返します。フィクスチャ データは実行中のページに属します。プレビュー アクションが成功しても、永続化された組織、プラグイン、請求、またはライブ プロバイダーの動作を実証することはできません。

ネイティブ ダイアログ、キーチェーン操作、トレイ、アップデータ、および macOS マテリアルには、Tauri ホストと適切な機能が必要です。登録されたコマンドは、その機能設定に基づいて WebView で引き続き使用できない場合があります。ファイルを開く場合、シェルはサポートされている関連付けを登録し、パスを転送します。それだけでは、特定の編集者がコンテンツをインポートしたことを証明することはできません。

グラフィックスの障害もまた境界線です。ゼロ以外のコンテナ サイズ、表示されるエンティティ/レイヤー、ロック解除された選択、およびサポートされる WebGL は、関連するビューポート インタラクションの前提条件です。レンダリングされたメッシュはレンダリングの証拠であり、保存や CAM 検証が成功したことを示すものではありません。を使用します。 ビューポート診断 ワーカーのキャパシティ、タイムアウト、および 4 ビューの動作について。

設定と表示の問題を回復する

共有 Web ビュー設定レコードは次のとおりです。 cadcamfun.settings。デフォルトには、ミリメートル、システムテーマ、小数点以下 3 桁、GRBL 設定、スナップ有効、公差 0.01 mm、ガラス有効が含まれます。保存されたフィールドは個別に検証されます。無効な値はシェルを失敗させることなくフォールバックします。ローカル ストレージがいっぱいまたはブロックされていると、永続化が妨げられる可能性があります。

表示単位を変更しても、保存されている CAD ジオメトリは再スケールされません。ドキュメントの許容差は、共有 CAD/ジェネレーター/検証設定ヘルパーを通じて伝達されます。一部のフィーチャー/ロータリー値は明示的に度を使用します。描画角度にはラジアンが使用されます。数値の不一致をジオメトリの破損と診断する前に、フィールドの契約を確認してください。

Glass の動作は Tauri/macOS のサポートに依存します。この実装では、サポートされている場合は液体ガラスが使用され、古い macOS ではプラグインを介して鮮やかさが使用され、使用できない場合または無効になっている場合は不透明なフォールバックが使用されます。テーマ/マテリアルの変更によって、ジオメトリ、プロジェクトの所有権、または加工の証拠が変更されることはありません。

すべての WebView ストレージをクリアするよりも、関連する設定または機能制御を優先します。このストレージには、セッション/エディターのハンドオフも含まれる可能性があります。ビジュアル設定のリセットはデータベース修復手順ではありません。

加工証拠から UI を個別に復元

ロードされたプロジェクト、成功した HTTP 保存、アニメーション化されたツールパス、および生成された NC は、異なる観察結果です。保存された加工結果に依存する前に、その結果の正確な NC、ソース図面/ストック、工具アセンブリ、機械エンベロープ、選択したポスト、および検証リリース/問題を検査してください。

CAM スナップショット コードは、現在の NC テキストとそのハッシュが一致する場合にのみカーネル証拠を保存します。ポータブル プログラムの書き込みはドキュメントの一貫性を検証し、キャプチャされたカーネル リクエストを再評価する場合があります。 NC を編集したりストックを変更すると、以前の証拠が無効になる可能性があります。プレーン NC を再度開くと、同じ製造プルーフを復元せずにプログラムを解析できます。

クラッシュまたは保存の中断後、まず保存された行とそのバージョンを検査します。 CAM 保存モーダルは更新前の以前のプログラムを記録し、ツールパス詳細手動保存は更新されたリビジョンを記録します。プロジェクト履歴はまた別になります。使用 歴史の比較 回復パスを選択します。

UI が回復したため、未解決のチェックを受け入れられた操作に変換しないでください。実際のリソースと NC に対して適切な検証を再実行します。アプリケーション健全性プローブには、マシンの安全性を管理する権限はありません。

一度に 1 つの失敗を優先順位付けします

1. 起動モード、プロセスのバージョン、ポート、および実際のデータ ディレクトリを記録します。
2. プローブの健全性、次に 1 つの保護された読み取り。接続を認証から分離します。
3. 何かをリセットまたは削除する前に、構造化された起動/移行エラーを検査してください。
4. コンパイル/ネイティブの問題が疑われる場合は、分離されたソース プロセスに対して再現します。
5. 特定された原因を修正し、適切なプロセスを再起動し、古いエンドポイント変数を更新します。
6. 保存したドキュメント/プログラムを再度開き、永続化された状態、バージョン、エクスポート、および現在の検証を検査します。

実装アンカーは、 app/App.tsx, app/sidecar.ts, src-tauri/src/{sidecar,commands,lib}.rs、サイドカー main.ts/config.ts/shutdown.ts、データベースのライフサイクル。 地域発展 構成の詳細を提供します。 コンパニオンペアリング 個別のネットワーク境界を処理します。

起動チェックリスト

1. このプラットフォームにサイドカー バイナリが存在しますか (src-tauri/binaries/sidecar-<target triple>)? desktop:dev それを構築します。 tauri:dev スタブを使用する場合があります。
2. 移行は段階的に行われていますか src-tauri/resources/migrations? bun run build:sidecar または bun scripts/build.ts --only=resources それらを再上演します。
3. サイドカーは印刷されましたか ready 60秒以内に?を探してください error stdout の行と、ログ ディレクトリの stderr の JSON ログ (get_logs_dir).
4. 再開したんですか？自動再起動は 1 回だけ許可されます。 2 回目の失敗ではステータスはそのままになります failed.
5. する GET /api/health 報告されたポートで応答しますか?存在するが、保護されたルートが 401 を返す場合、トークンは別の起動に属しています。
6. データ ディレクトリは書き込み可能ですか?また、互換性のない移行を行う別のプロセスによってデータベース ファイルが開かれたままになっていませんか?

ログを読む

サイドカー ログは標準エラー出力上の JSON 行であり、標準出力ハンドシェイクとは別に保持されます。認証情報が含まれる可能性のある行は次のように置き換えられます。 [redacted: line may contain credentials] したがって、ログ内の行が編集されることは予想されますが、破損することはありません。ハンドシェイク自体にそのような行が含まれていた場合、報告される起動エラーは編集マーカーになります。周囲の stderr 行を読んでコンテキストを確認してください。

ログ ディレクトリはプラットフォーム固有です。から入手してください get_logs_dir パスを推測するのではなくコマンドを実行し、次のようにして開きます open_path、アプリケーション ログ ディレクトリを受け入れます。

エラーメッセージとその意味

3Dで