メインコンテンツへスキップ

トラブルシューティング

このガイドは、AIGNE WebSmith を使用する際の一般的な問題を診断して修正するのに役立ちます。生成、公開、または設定中に問題が発生した場合は、以下のシナリオの解決策を確認してください。

設定の問題

問題 1: 設定ファイル形式の誤り

エラーメッセージ：

Error: Failed to parse config file: Implicit map keys need to be followed by map values at line 112, column 1:

lastGitHead: c4a4d3db4bf230e2c6873419e26b6654c39613a5
appUrl: https://staging.websmith.aigne.io
Error: Failed to parse config file: Map keys must be unique at line 116, column 1:

projectCover: .aigne/web-smith/cover.png
appUrl: https://staging.websmith.aigne.io
^

考えられる原因： 設定ファイルの YAML 構文に誤りがあります。よくある問題：

  • インデントにタブを使用している（スペースを使用すべき）
  • 全角コロン（：）を使用している（半角コロン（:）を使用すべき）
  • 必要な引用符が欠けている
  • 重複した設定項目がある

解決方法：

  1. エラーメッセージに記載されている行番号を確認し、問題の場所を特定
  2. その行のインデントが正しいか確認（スペースを使用、Tab は使用しない）
  3. コロンが半角（:）であることを確認（全角（：）ではない）
  4. オンライン YAML バリデーターを使用して構文を確認
  5. 修正後、aigne web publish を再実行

ヒント： 設定ファイル形式の誤りを修正する必要がある場合を除き、一部のパラメータが正しく設定されていない場合、システムは自動的にデフォルト値を使用するため、基本機能には影響しません。

生成の問題

問題 2: 生成されたコンテンツが期待通りでない

発生する可能性がある問題：

  • 生成されたコンテンツのトーンが期待と異なる
  • ページ構造が期待と一致しない
  • 重要な情報が欠けている

考えられる原因：

  1. 設定内の rules の説明が不十分または不明確
  2. targetAudienceTypes の設定が実際のターゲットオーディエンスと一致しない
  3. sourcesPath 内の参照ドキュメントが少ない、または関連性が低い

解決方法：

  1. rules を充実させる： config.yaml に詳細なガイダンスを追加： yaml rules: | ### ページ構造要件 1. ファーストビューには以下を含める必要があります： * 明確な製品見出し * 簡潔な説明 * 主要な行動喚起 ### コンテンツのトーン - 積極的で自信のある言語を使用 - 具体的なデータと例を含める - マーケティング用語を避ける
  2. オーディエンスを調整： targetAudienceTypes が実際のオーディエンスと一致することを確認： yaml targetAudienceTypes: - customers # エンドユーザー向け - developers # 技術的なオーディエンス向け
  3. より多くのソースを追加： sourcesPath に関連ドキュメントを含める： yaml sourcesPath: - ./README.md - ./docs - ./CHANGELOG.md

問題 3: 画像の品質が低い、または欠落している

発生する可能性がある問題：

  • 生成されたページの画像解像度が低い
  • 期待される画像が表示されない

原因： media.minImageWidth の設定値が高すぎて、一部の画像がフィルタリングされています。

解決方法：

  1. config.yaml ファイルを開き、media 設定項目を見つける： yaml media: minImageWidth: 800 # 現在のしきい値
  2. ニーズに応じてこの値を調整：
  • 400-600：より多くの画像が含まれるが、品質の低い画像が含まれる可能性がある
  • 600-800：品質と数量のバランスが取れている（推奨設定）
  • 800-1000：高品質な画像のみが保持され、数量は減少する
  1. ファイルを保存した後、更新コマンドを実行： bash aigne web update

公開の問題

問題 4: 公開時に URL が無効と表示される

エラーメッセージ：

Error: ⚠️  The provided URL is not a valid website on ArcBlock platform

💡 Solution: Start here to set up your own website to host pages:

原因： 設定内の appUrl が空であるか、無効なウェブサイトアドレスを指しています。

解決方法： config.yaml に正しいデプロイアドレスを設定：

yaml
# あなたのウェブサイトアドレスを入力
appUrl: https://your-site.user.aigne.io

# 一時的にウェブサイトがない場合は、この設定をクリアできます
# appUrl: ""

問題 5: 公開時に認証が期限切れと表示される

エラーメッセージ：

❌ Failed to publish pages: bundle: not authorized

原因： ログイン認証情報が期限切れで、再認証が必要です。

解決方法： 以下のコマンドを順番に実行：

bash
# まず古い認証情報をクリア
aigne web clear

# その後、再公開を実行。システムが再ログインを促します
aigne web publish

復旧方法

方法 1: Git を使用して復元

Git でコードを管理している場合、以前正常に動作していた設定に素早く復元できます：

bash
# 現在の変更を一時保存
git stash

その後、ウェブサイトを再生成：

bash
aigne web generate

ヒント： 後で一時保存した変更を復元したい場合は、git stash pop を実行できます

方法 2: クリーンアップ後に再生成

問題の原因を特定できない場合、生成されたすべてのファイルをクリアし、最初から再生成できます：

bash
# 生成されたすべてのファイルをクリアし、再生成
aigne web clear && aigne web generate

注意： これにより、生成されたすべてのコンテンツが削除されますが、設定ファイルには影響しません。実行後、システムは現在の設定に基づいてウェブサイトを再生成します。

使用のヒント

以下は、一般的な問題を避けるのに役立つ実用的なヒントです：

  1. 変更履歴を保存：

    Git を使用している場合、設定ファイルを変更した後は必ずコミットし、問題が発生したときに以前のバージョンに簡単に戻れるようにする

  2. 変更前にバックアップ：

    重要な設定を変更する前に、設定ファイルのコピーをバックアップとして作成し、万が一に備える

  3. 変更後すぐにテスト：

    設定を変更した後は、すぐに aigne web generate を実行してテストし、問題があれば早期に発見できる

  4. 形式が正しいか確認：

    YAML ファイルを変更した後、オンラインツールで形式に誤りがないか確認する

  5. シンプルから始める：

    最初は最もシンプルな設定を使用し、すべてが正常に動作することを確認してから、徐々に複雑な機能を追加する

  6. 変更を記録：

    各変更の内容と理由を簡単に記録しておくと、後で問題が発生したときに原因を見つけやすくなる

さらなるヘルプの取得

上記の方法で問題が解決しない場合、以下を試してください：

  1. 設定ドキュメントを確認：

    Config Reference を参照して、各設定項目の詳細な説明を確認

  2. コマンドドキュメントを確認：

    Command Reference を参照して、コマンドの詳細な使用方法を確認

  3. エラーログを確認：

    ターミナルに表示されるエラーメッセージを注意深く読み、通常は具体的なヒントが含まれています

  4. AIGNE Observability を使用：

    以下で紹介する AIGNE Observability ツールを使用して、詳細な実行記録を取得

  5. コミュニティのヘルプを求める：

    AIGNE コミュニティ にアクセスして質問を投稿すると、他のユーザーや開発者が助けてくれる可能性があります

AIGNE Observability を使用して問題を調査

複雑な問題を深く調査する必要がある場合、またはコミュニティに問題を報告する場合、AIGNE Observability を使用できます。各ステップの実行プロセスを詳細に記録し、あなたや技術サポートスタッフが問題を迅速に見つけられるようにします。

Observability サーバーの起動

以下のコマンドを実行してローカル Observability サーバーを起動：

Observability サーバーを起動

bash
aigne observe

出力には以下が表示されます：

  • データベースパス：トレースデータの保存場所
  • サーバーアドレス：ブラウザでこのアドレスを開くと Observability ダッシュボードを確認できます

Observability サーバー実行中

実行記録の表示

  1. ダッシュボードを開く： 出力に表示されているサーバーアドレスをクリックするか、ブラウザで開く
  2. 操作記録を確認： ダッシュボードには、以下のようなすべての WebSmith 操作が表示されます：
  • 入力と出力のデータ
  • 各ステップにかかった時間
  • 実行された操作ステップとその結果
  • 詳細なエラー情報

実行記録を表示する Observability ダッシュボード

Observability を使用した問題の報告

コミュニティに問題を報告する場合：

  1. トレースをキャプチャ： 問題が発生している操作中に Observability サーバーを実行し続ける
  2. トレースデータをエクスポート： ダッシュボードから関連する実行記録をエクスポート
  3. 問題を報告： AIGNE コミュニティ にアクセスし、以下を添付：
  • 問題の説明
  • 再現手順
  • エクスポートしたトレースファイル
  • 設定（該当する場合）

ヒント： トレース記録には、WebSmith の実行に関する完全な情報が含まれており、各ステップの操作と結果が記録されています。この情報を技術サポートやコミュニティに提供することで、問題解決の効率が大幅に向上します。