Echo Nebula Feedback ドキュメント

トラブルシューティング

対象読者：ローカル Alpha 環境、SDK payload、API call をデバッグする開発者。

失敗している境界から確認します。Godot payload 生成、ローカルキュー、public API、添付アップロード、admin API auth、または Docker Compose 依存サービスです。

最小例

cd ../echo-nebula-infra
./scripts/smoke-public-api.sh
./scripts/smoke-admin-api.sh

curl -i "http://localhost:4100/healthz"
curl -i "http://localhost:4100/readyz"
curl -i "http://localhost:4000/healthz"
curl -i "http://localhost:4000/readyz"

curl -fsS "http://localhost:4000/v1/sdk/config?locale=ja" \
  -H "X-Project-Key: enb_pk_xxx"

feedback_payload_ready は準備状態とフィールド数の確認にのみ使用します。最初のフィードバックを参照してください。このシグナルは配信完了を証明しません。ローカルでキュー件数、HTTP ステータス、安定したエラーコード、応答の関連 ID を確認し、Developer Console でレポートと添付の到着を確認してください。完全な payload、キュー JSON、本文、連絡先、ログ、Key、token、署名 URL を出力・添付しないでください。送信への同意は診断ログへのプレイヤーデータの複製を許可するものではありません。

/healthz と /readyz は区別してください。health response の成功は process が生きていることだけを示し、PostgreSQL や object storage の利用可否は示しません。Admin の 200 degraded は PostgreSQL が ready で object storage が degraded であることを意味し、text management は続行できますが attachment operation は失敗する可能性があります。Public は両 dependency を必要とし、どちらかが失敗すると 503 unavailable を返します。default Compose project に触れず再現可能な outage/recovery evidence が必要な場合は ./scripts/e2e-readiness-isolated.sh を使ってください。

よくある間違い

次のステップ

Alpha 概要に戻り、エンドツーエンドの順序を確認してください。

リソースと設定の境界

Public config と 2 つの書き込みエンドポイントは、認証前の接続元 IP ごとのプロセス内予算（既定で毎分 600 回）を共有します。未指定・無効な Project Key も対象です。認証後の書き込みは別のプロジェクト予算（既定で毎分 60 回、同じプロジェクトの Key 間で共有）を維持します。429 は common.rate_limited と Retry-After を返すため、待機して再試行してください。Forwarded/X-Forwarded-For は信頼しません。プロキシ経由の通信はその接続元 IP の予算を共有するため、入口でクライアントごとの制限を行い、サービス予算を設定してください。カウンターはレプリカ間で共有しません。各 limiter は最大 4096 個の有効な識別子を保持し、満杯では新しい識別子を拒否、期限後に容量を回復します。

添付ファイル名は有効な UTF-8、1–255 Unicode コードポイント、制御文字なしとし、basename がドット・二重ドットの場合も 400 attachment.invalid で拒否します。パス部分を除き、未対応の文字は保存名でアンダースコアに変換します。内容は契約の 10 MiB と、より小さいデプロイ設定の制限に従います。名前の拒否時はオブジェクトを作成しません。再試行にも consent、プロジェクト分離、冪等性を適用します。

Admin JSON は最大 64 KiB、認証・組織の既存 16 KiB 制限も維持します。過大、不完全、不正な JSON は既存のルート別 400 エラーです。フィードバックの search は trim 前に最大 200 Unicode コードポイントとし、不正 UTF-8 または超過は 400 admin.request.invalid です。UI もコードポイント数を検証します。

両 API は形式不正、ゼロ、負数、過大なリソース設定を起動時に拒否します。Public のヘッダー/読み取り/書き込み/アイドル/終了タイムアウトの既定値は 5s/2m/2m/2m/10s、Admin は 5s/15s/30s/1m/10s です。正の値が必要で、ヘッダー/終了は最大 1m、読み取り/書き込み/アイドルは最大 5m、readiness は最大 30s です。レート期間は正かつ最大 1h、回数は 1–1,000,000。ダウンロード TTL は正かつ最大 1h、既定 15m。Public のフィードバック本文は 1–1,048,576 バイト、添付は 1–10,485,760 バイト、ログ 1–200 件、breadcrumb 1–100 件、連絡先 1–200 文字です。任意データの無効化にはプロジェクト feature flag を使います。

APP_ENV=local 以外は DATABASE_URL、S3_ENDPOINT、S3_REGION、S3_BUCKET、非既定の S3 認証情報を明示します。DB パスワードと S3 secret は 16 バイト以上です。PostgreSQL は URI と単一の明示 sslmode を使用し、公開ホストは verify-full、プライベート IP、単一ラベルのサービス名、.internal/.localhost ホストは管理されたネットワークで disable、require、verify-ca を許可します。query で DB の識別情報、ホスト、認証情報を上書きできません。S3 の HTTP はこれらのプライベートホストのみ、その他は HTTPS です。Admin は追加で HTTPS の S3_PUBLIC_ENDPOINT、強い非既定の JWT/bootstrap 認証情報、明示 CORS allowlist の HTTPS origin を必要とします。空の CORS リストはクロスオリジンのブラウザーアクセスを許可しません。local の既定値は引き続き使用できますが、他環境へ流用しないでください。設定エラーはフィールド名だけを示し、値を出力しません。これらの検証は本番デプロイや複数レプリカ保護の完了を意味しません。