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

疑难排查与常见故障处理手册 (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