文档中心开发者技术手册常见疑难异常与生产排查手册

疑难排查与常见故障处理手册 (Troubleshooting)

针对本地开发、容器构建及生产服务器部署过程中最常遇到的技术问题，提供直截了当的排错方案与排查指南。

1. 在 Strapi 保存发布的内容未在前台商城中显示

请检查 Strapi 中的 Webhook 配置，务必确保请求头中的 x-strapi-secret 与根目录 .env 文件中的 REVALIDATE_SECRET 完全一致。

.env

env

STORE_CORS=http://localhost:8000,https://store.yourdomain.com
ADMIN_CORS=http://localhost:9000,https://api.yourdomain.com
AUTH_CORS=http://localhost:8000,http://localhost:9000,https://store.yourdomain.com

2. Medusa 连接失败或前台无法检索到已上架商品

检查 Publishable API Key 与销售渠道

请核对 .env 中的公钥是否正确配置，并在 Medusa Admin 后台中确认商品已明确勾选关联至对应的 Sales Channel 销售渠道。

3. Caddy 自动申请或签发 SSL 证书遇到异常

请确保域名的 DNS A 记录已准确解析至您的 VPS 公网 IP，并且服务器安全组与防火墙的 80 和 443 端口已对外放行。

4. PostgreSQL 或 Redis 提示 Connection Refused 拒绝连接

检查所有容器是否均加入了相同的 Docker 桥接网络，并核实服务器磁盘空间是否已耗尽。

容器健康状态检测命令

bash

sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

5. 实时监控诊断与集中式日志检索

实时日志监控命令

bash

docker compose logs -f storefront
docker compose logs -f medusa
docker compose logs -f strapi

6. 无需停止整套集群，单独重新编译单个服务容器

当您仅对前端或后端代码进行了局部升级时，可单独对其执行重新编译并热替换启动：

单独重构单个容器命令

bash

docker compose up -d --build storefront

7. 彻底重置数据库并重新灌入初始演示数据

在开发测试阶段如需将商品目录与配置恢复至初始样例状态：

初始化测试数据灌入命令

env

docker compose exec medusa yarn seed

8. HTTP 403 Forbidden during Translation Sync from Strapi

If clicking Sync Translations from Strapi yields an HTTP 403 Forbidden error, the Public role lacks permission to read storefront settings. Go to Settings > Users & Permissions > Roles > Public, enable the find permission for both Storefront-setting and Media Library, and save.

9. 搜索框卡死 / 无法在弹窗中输入字符

原因：前台搜索栏采用 React InstantSearch，在客户端浏览器中直接向 Meilisearch 发送查询请求。若未在 Cloudflare DNS 中配置 search.yourdomain.com 子域名记录，或浏览器因 DNS、SSL、CORS 无法连通搜索服务，输入框状态将冻结且无法输入任何文字。

解决方案：
1. 在 Cloudflare 控制面板（DNS > Records）中，添加一条指向服务器 IP 的 A 记录，名称为 search。
2. 验证 Meilisearch 公开接口连通性：
curl -I https://search.yourdomain.com/health
3. 确保 Storefront Docker 镜像构建时已正确注入 NEXT_PUBLIC_MEILISEARCH_HOST 与 NEXT_PUBLIC_MEILISEARCH_SEARCH_KEY。

测试 Meilisearch 运行状态

bash

curl -I https://search.yourdomain.com/health
# 预期响应：HTTP 200 OK