トラブルシューティング

まずこれをしてください

どんな問題でも、サイトルートの runtime.log を読んでください。

runtime/log/ の中ではなく、ルート直下の runtime.log です。ほぼすべての問題の本当の原因がそこに書かれています。

DEBUG=false の場合、捕捉されなかった例外は 404 ページとして描画され HTTP 500 で返されます。画面には手がかりが何も出ません。本当の原因は runtime.log にしかありません。

インストールとアクセス

トップページだけ開けて、リンクを踏むとすべて 404 URL 書き換えが未設定です。書き換えルールを参照してください。

真っ白／500 多くは bcmath 拡張の不足です。金額計算がすべてこれに依存しており、無いと致命的エラーになります。インストール方法の選択を参照。

インストーラが「ディレクトリに書き込めません」と言うconfig、runtime、kernel/Install、assets/cache が書き込み可能である必要があります。aaPanel（宝塔パネルの国際版）なら、Files（ファイル）でサイトのルートを選び、Permission（権限）で所有者を www にしてください。

Docker コンテナは動いているのにブラウザで開けない ポートマッピングが逆です。-p 8080:80 の左がホスト側、右は常に 80 です。クラウドサーバーではセキュリティグループの開放も必要です。

Docker のアップグレード後にデータが消えた-v acg_data:/data が指定されていませんでした。Docker でインストール参照。

移行後

新サーバーで動かない場合は、この順で確認します。

1. config/database.php が旧サーバーの情報のままになっていないか
2. 旧サイトが Redis にセッションを保存していたなら、新サーバーにも導入するか、PHP のセッション保存先をファイルに戻す
3. PHP 拡張がすべて入っているか（特に bcmath）
4. ディレクトリ権限と URL 書き換えは、どちらも設定し直しが必要です

アップグレードと移行も参照してください。

アカウントとログイン

3.8.1 にアップグレードしたら会員が全員ログアウトされた 想定どおりの動作です。3.8.1 ではセキュリティのため会員のログイン情報を作り直しました。各会員がもう一度ログインすれば済みます（アカウントとログインのセキュリティ参照）。

ログイン画面に「パスキーでログイン」ボタンがない パスキーを使うには、サイトを https://ドメイン で開く必要があります（IP アドレスや http では不可）。また標準のブラウザが必要で、WeChat・QQ・Alipay のアプリ内ブラウザには対応していません。

管理画面がすぐロックされる 3.8.1 で追加された自動ロックで、既定では 15 分間操作がないとロックされます。サイト設定 → セキュリティ設定 の「管理画面の自動ロック」で時間を延ばすか、0 にして無効にしてください。

注文と決済

購入者が支払ったのに何も届かない

1. 商品注文を注文番号か連絡先で検索し、注文が存在するか確認
2. 状態を確認。「未入金」のままなら決済コールバックが届いていません
3. コールバックが届かない主な原因は、事業者側のコールバック URL の誤り、または CDN のファイアウォールによる遮断です
4. CDN が原因ならカスタム決済コールバックドメインで回避します（サイト設定参照）

在庫はあるのにストアフロントでは売り切れ表示 商品に種別や SKU がある場合、在庫は組み合わせごとに計算されます。合計は多くても、その組み合わせのカードが無ければ売り切れです。カードがロックされている可能性もあります（カード在庫管理参照）。

年額を選んだのに月額のカードが届いた カード取り込み時の種別が違っていました。

商品が 0 円と表示される 会員価格が未入力だと、ログインユーザーは無料で持って行ける場合があります。両方の価格を入力してください（決済設定参照）。

サブストア

サブドメインが開けない 必要なのは 3 つで、どれか 1 つでも欠けると動きません。管理画面での本店ドメインと DNS-CNAME の設定、DNS 事業者での * ワイルドカードレコード、そしてサーバーでの *.ドメイン の紐付けです。最後のものが最も見落とされます。

独自ドメインが開けない サーバーに既定サイトが設定されていません（サブストア参照）。

ストア連携

店舗の追加に失敗する アドレス・加盟店 ID・キーの誤り、または相手側で連携が無効になっています。

顧客の注文でエラーになり発送されない 上流での残高が尽きています。連携注文は上流店舗のあなたの残高から支払われます。

エラーが資金操作の追加認証や連携用ホワイトリストに関するものなら、メッセージに合わせて対処します。

• 「该账号已开启资金二次验证，必须先登记对接白名单 IP……」（資金操作の追加認証が有効なため、先にホワイトリストへ IP を登録する必要がある）：上流は 3.8.2 以降で、上流のアカウントで資金操作の追加認証がオンなのにホワイトリストが空です。上流の会員センターで、自分のサーバーの IP を連携用 IP ホワイトリストに追加してください
• 「调用方 IP 不在该账号的对接白名单内……」（呼び出し元の IP がこのアカウントの連携用ホワイトリストにない）：上流は 3.8.2 以降で、上流のアカウントにはホワイトリストがありますが、自分のサーバーの IP が入っていません。同じく追加してください
• 「该账号已开启资金二次验证，无法通过对接接口消费余额」（連携 API では残高を使えない）：上流は 3.8.1 で、ホワイトリストがありません。そのアカウントで資金操作の追加認証をオフにするか、上流に 3.8.2 へのアップグレードを依頼してください

ホワイトリストは、既定のテーマでは「連携用ホワイトリスト」ページ、ほかのテーマでは「2段階認証」ページにあります。拒否された IP はホワイトリストの下の「最近拒否された接続元」に表示され、ワンクリックで追加できます。

商品一覧が空で返る 相手の商品で「API 連携」が有効になっていません。

プラグインとテーマ

プラグインを入れたのに何も起きない汎用プラグインで有効化する必要があります。

新しいフックファイルを追加したのに発火しない フック登録表はコンパイル済みキャッシュです。プラグインを停止して再度有効化すると再構築されます。

テーマを変えたら表示が崩れた テンプレートキャッシュを消してください。runtime/view/compile の中身を削除します。

runtime/config は絶対に削除しないでください。 設定キャッシュであり、消すとサイトが壊れます。

質問するときのコツ

一言の説明だけで原因を言い当てられる人はいません。質問する前に次を用意してください。

1. runtime.log の内容 — エラー後にサイトルートにあります
2. 何をしたら起きたのか — 直前の操作
3. スクリーンショット — 問題に関係するもの

これらを揃えるのが結局いちばん早い解決法です。一言で書いて誰かが助けてくれるのを待つこともできますが、時間の節約にはならず、やり取りが長引くだけです。

質問できる場所

• Telegram：https://t.me/mcyofficial
• QQ グループ：868709021