一 · データソースの接続
API、データベース、CSV、クローラーを課金可能なツールに切る——ここが最も地雷を埋めやすい工程です。
01コレクターで gzip を切り忘れ、相手が圧縮を有効にした瞬間に解析が壊れた
- 当時
- 相手の API を叩くと gzip のバイト列が返ってきましたが、そのままテキストとして解析し、文字化けのエラーが大量に出ました。
- 解決方法
- 収集レイヤーは常に
Accept-Encoding: identityを送り、相手の既定動作には依存しません。タイムアウトとリトライも入れます。
02オンチェーンログを 0 からスキャンすると必ず失敗する
- 当時
- オンチェーンデータをジェネシスブロックからスキャンし、タイムアウトしても結果が出ませんでした。
- 解決方法
- チェーンヘッドから固定ブロック数だけ遡って増分スキャンし、カーソルを DB に保存すれば、再実行時に続きから再開できます。
03402 のレスポンスヘッダを送ったのに、ブラウザから読めない
- 当時
- パケットキャプチャでは payment 関連のヘッダが見えるのに、フロントエンドの JS では undefined でした。
- 解決方法
- 独自のレスポンスヘッダは明示的に
Access-Control-Expose-Headersに追加しないと、ブラウザのセキュリティポリシーで遮断されます。
04金額の単位を間違え、facilitator に即座に拒否された
- 当時
- 0.01 USDC を 1e16 と書いたところ、facilitator は「amount mismatch」としか返さず、単位の問題だとは分かりませんでした。
- 解決方法
- USDC は 6 桁の小数です。0.01 = 10000。価格は共通の換算関数を通して生成し、手書きはしません。
二 · 公開とルーティング
構文チェックが通っても、サイトが開けるとは限りません。この節の落とし穴はすべて構文の外側にあります。
05nginx -t はすべて緑なのに、リダイレクトループでサイトが開かない
- 当時
- 完全一致 location の 301 と try_files の内部リダイレクトが入れ子になり、ブラウザは「リダイレクトが多すぎます」と表示しました。
- 解決方法
- 変更後は実際にリクエストを送り、ステータスコードとホップ数を確認します。検証には
--max-redirs でリダイレクト回数を制限して検証し、構文を見るだけで済ませません。
06管理画面の URL が 301 → スラッシュ付き → 403 で真っ白
- 当時
/admin は 301 で /admin/に飛びました。実在するディレクトリで index ファイルが無いため、そのまま 403。入れるのは /admin.html だけです。- 解決方法
- 内部 rewrite でファイルへ直接届けます：
rewrite ^/admin/?$ /admin.html last;。ログイン保護の層はそのままです。
07location 内で if による正規表現判定を使い、キャプチャグループを上書きした
- 当時
- クリーン URL のルールに if の正規表現判定を足したところ、
$1 がリセットされ、/pricing.html はトップページへ 301 されました。
- 解決方法
- if の判定をその location の外へ出すか、map に切り替えます。location 内で if とキャプチャグループを混在させないこと。
08MCP エンドポイントのリバースプロキシがバッファリングし、SSE が固まった
- 当時
- streamable-http は SSE を使いますが、nginx のデフォルトバッファリングがストリームを止め、クライアントは応答を待ち続けました。
- 解決方法
proxy_buffering off; + proxy_cache off; + 延長 proxy_read_timeout。
三 · キャッシュとバージョン
最も厄介な種類：サーバーは正常なのに、ページだけがエラーを出し続ける。
09CSS / JS を直したのに、本番で「効いていないように見える」（3 回連続で発生）
- 当時
- nginx が静的アセットに
expires 7dを設定したのに、ページ側の参照にはバージョン番号がありませんでした。
- 解決方法
- 長期キャッシュを設定するならバージョン刻印が必須です。リソースを変えるたびにバージョンを上げ、リリースチェックリストに書きます。
10サーバーログはすべて 200 なのに、ページは「データが読めない」と表示する
- 当時
- ブラウザが 7 日間キャッシュされた古いスクリプトを実行し、新しいデータ形式を描画する際にクラッシュしました。しかも catch が一律「サーバーが読めない」と報告しました。
- 解決方法
- 管理用スクリプトは個別に no-cache。取得と描画は 2 つの try に分け、完全な失敗時は localStorage でフォールバックします。
11新しいページと古いページが混在する
- 当時
- 同じ CSS を複数ページが参照しているのに、一部のページだけバージョン番号を上げていました。
- 解決方法
- サイト全体でそのリソース名を検索し、まとめてバージョンを上げます。ページを手で選んで直さないこと。
12エラー文言に引っ張られて方向を誤る
- 当時
- 描画クラッシュ、ネットワーク障害、キー失効、タイムアウトがすべて一つの catch で同じ文言になり、サーバー側を 2 日間調べることになりました。
- 解決方法
- 4 つの失敗に 4 つの文言を。401/403 はリトライせず再ログインを促し、失敗時はまずキャッシュデータを表示します。
四 · 監視と運用
定期実行ジョブと死活監視スクリプトは、書き間違えると静かにデータを壊します。
13手で直した 876 ページが、定期ジョブ 1 回で全上書きされた
- 当時
- 静的生成サイトは cron で再生成されるため、成果物を手で直せば必ず上書きされます。
- 解決方法
- 生成テンプレートだけを直す → 再生成 → 公開。成果物の mtime を監視するガードスクリプトを追加します。
14JSON クライアントで MCP エンドポイントを監視し、SSE を「死亡」と判定した
- 当時
- 死活監視スクリプトがレスポンスボディを解析していましたが、MCP は SSE ストリームを返すため、解析失敗がそのまま「死亡」判定になっていました。
- 解決方法
- HTTP ステータスコードだけで判定します。200 も 402 も生存とみなし、レスポンスボディは絶対に解析しません。
15監視のフィールド名を書き間違え、全項目が常に「変動」判定になった
- 当時
- 書いていたのは
p.ok なのに実際のフィールドは p.lastOkで、判定ロジックは常に異常系に入っていました。
- 解決方法
- フィールド名は記憶ではなく、DB へ書き込むコードと突き合わせて確認します。公開前に既知のデータ 2 件で判定ロジックを検証してください。
16日次集計を増分加算で行うと、PV が 1 日で倍になる
- 当時
- 「昨日の値 + 今日の増分」は、再実行するたびに倍になります。
- 解決方法
- 日単位で再計算して上書きし、冪等性を保ちます。時刻の文字列化は必ずすべての集計の後に行います。
五 · GEO と引用可能性
AI から見えなければ、どんなに良いデータも売れません。
17デフォルトの robots.txt が AI クローラーを全てブロックし、GEO がゼロになる
- 当時
- フレームワークのデフォルトテンプレートを使ったため、主要な AI クローラーが締め出されていました。
- 解決方法
- 40 以上の AI クローラーを 1 件ずつ明示的に許可し、管理画面などのプライベートパスは別途 Disallow します。
18llms.txt をマーケティング文にすると、どの AI も引用しない
- 当時
- 紹介文と形容詞を並べましたが、AI は検証できないため、書いていないのと同じでした。
- 解決方法
- 検証可能な事実だけを書きます。価格、ネットワーク、エンドポイント、絶対パス、明確な決済ルールです。
19外部 AI が言及してくれたが、ルールを間違えて伝えていた
- 当時
- AI が手数料を 15%、決済を T+7 と説明していたのに、「言及率」の指標は緑でした。
- 解決方法
- 監視では「内容の正確さ」を別指標として持つ必要があります。言及されていても間違っていれば、言及なしと同じです。
六 · 価格と決済
お金の話は、一度間違えると信頼を取り戻すのが難しい。
20価格が安すぎて、1 年経っても出金しきい値に届かない
- 当時
- 単価を下げすぎて月間売上が $50 の出金ラインを越えず、資金はずっと帳簿上に留まっていました。
- 解決方法
- 出品前に計算します。呼び出し量 × 単価 × 分配率から最低成立価格を逆算し、回収期間を確認します。
21実行中にデータファイルを編集したら、メモリ上の旧値に書き戻された
- 当時
- サービス稼働中にデータファイルを直接編集しましたが、再起動前に旧値が書き戻されました。
- 解決方法
- データを触る前にサービスを停止します。照合はオンチェーンの Transfer イベントのみを根拠とし、許容誤差は ±$0.02 です。
22無料枠を IP 単位で制限しても、分散した Agent には全く効かない
- 当時
- Agent は毎回送信元 IP が変わるため、IP 単位の制限は制限になっていません。
- 解決方法
- 枠は Agent / キーの軸に紐づけ、日次サーキットブレーカーを追加します。無料枠は獲得コストとして ROI を計算します。
この 22 件を、私たちは 20 個の無料ツールにしました
各項目の下にあるツールはすべて無料で、ログイン不要、入力内容はブラウザ内だけで計算されます。自分で回せるならツールを使い、回せないときは私たちが代理出品・代理販促・代理決済を行います。