このシリーズは何か
自己ホスト型の業務 OSS（PHP + SPA）を、Docker の本番ではなく共有レンタルサーバー（HETEML など CGI／suEXEC 系）へ ZIP で設置して運用していると、ローカルの Docker では絶対に再現しない壊れ方に次々ぶつかります。プロセスがリクエストごとに生き死にする、前段プロキシがヘッダを削る、ホストの既定タイムゾーンが効いてくる——どれも「開発環境が単一プロセス・単一構成だから隠れていた」前提のズレです。
このハブは、共有ホスティング特有の壊れ方を症状から引ける索引として束ねます。各記事は「実行モデルから原因を特定 → 実コードで修正 → 回帰テストで封じる」までを記録したものです。本番ログで実証したもの（②③）と、設置リハーサルやコンテナ再現で本番投入前に潰したもの（①④⑤）が混在します（いずれも解決済み）。共有ホスティングで同じ壁に当たった人が、症状で自分の状況に近い1本へ飛べることを狙っています。新しい罠を踏むたびに追記します。
症状別インデックス
| # | 症状（この構成で起きること） | 原因 | 対策 | 記事 |
|---|---|---|---|---|
| ① | InMemory カウンタは CGI／suEXEC では状態が保てず、そのまま載せても 429 が発動しようがない（本番投入前に設計で回避） | カウンタをプロセス内メモリに置くと、CGI ではリクエスト毎にプロセスが死んで状態が消える | ファイル退避の fixed window（flock 排他・fail-open） |
①レート制限が発動しない（公開済） |
| ② | Bearer 認証が 401。Authorization ヘッダだけ届かない |
前段プロキシ／CGI が Authorization ヘッダを剥ぐ |
独自ヘッダへミラー＋.htaccess で復元する三段構え |
②Authorization ヘッダが消える（公開済） |
| ③ | 作成1秒のデモ org まで即「期限切れ」で消える | UTC の created_at を TZ 無指定で素パース。ホスト既定が Asia/Tokyo で9時間ズレ |
タイムゾーンを明示する修正＋JST/UTC 両ホストで回る回帰テスト | ③JST×UTC で sweep が全滅（公開済） |
| ④ | 派生画像が軒並み 500、ページの画像が全部壊れる | 「ブラウザが AVIF を要求」と「サーバが AVIF を生成できる」を同一視（エンコーダ不在） | エンコーダの実在まで条件に入れた形式交渉 | ④AVIF 交渉で派生画像が全滅（公開済） |
| ⑤ |
.env の一部設定だけ既定値に落ちる（APP_BASE_PATH 等） |
phpdotenv を v4→v5 に上げ、環境変数を載せる場所が変わり putenv されない |
getenv() が拾う場所へ、未載せキーだけ putenv でブリッジ |
⑤phpdotenv v5 は putenv しない（公開済） |
このハブの使い方
- 症状から引く。上の表で自分の状況に一番近い行の記事へ飛んでください。各記事は単体で完結します。
- 各子記事の冒頭に「シリーズ内の位置（#N／全5本）」とこのハブへの逆リンクを順次整備しています。
- 共通する教訓は一つ——共有ホスティングでは「状態はプロセス外」「ヘッダは削られうる」「時刻とエンコーダはホスト依存」を最初から前提に置く。ローカルで緑でも、それは単一プロセス・単一構成で正しいことしか保証しません。
一次資料・関連
- 対象プロダクト：NeNe Invoice（①②）／NeNe Clear（③）／NeNe Records（④）ほか、自己ホスト業務 OSS 群。
- 各記事の末尾に、該当する実コード・PR・テストの一次資料を個別に挙げています。
── 筆者: 森 秀之（彩音インターナショナル）— 自己ホストの業務ツール群を実運用中。
中小企業向けの業務システムを料金公開・固定価格で開発しています。
🔗 ayane.co.jp