跳到主内容

故障排查

ShopFaaS 常见故障排查指南——登录问题、支付失败、邮件未送达、应用冲突、私有化部署故障等。

本页汇总 ShopFaaS 常见故障的排查思路与解决方案。按问题类型分类，逐步排查。

登录与账户

无法登录后台

  1. 检查邮箱与密码

    确认邮箱拼写正确，密码区分大小写。忘记密码点击「忘记密码」重置。

  2. 检查账户状态

    账户被暂停或关闭将无法登录。检查注册邮箱是否收到账户状态变更通知。

  3. 清除浏览器缓存

    清除 shopfaas.com 域名下的 Cookie 与缓存，或使用无痕模式重试。

  4. 检查浏览器扩展

    部分广告拦截或隐私扩展可能干扰登录。临时禁用扩展后重试。

  5. 检查网络

    公司网络或 VPN 可能拦截请求。切换网络环境（如手机热点）测试。

店铺切换器不显示新店铺

  • 刷新页面（新店铺创建后偶有缓存延迟）
  • 检查套餐店铺数量配额是否已满
  • 退出登录后重新登录

支付与订单

客户无法完成支付

  1. 检查支付网关配置

    在「设置 → 收款」确认支付网关已启用且配置正确（API Key、Webhook 等）。

  2. 检查支付网关账户状态

    登录支付网关后台（如 Stripe Dashboard）确认账户正常、无限制。

  3. 检查货币与地区

    部分支付方式仅支持特定货币或地区。确认店铺币种与客户所在地区匹配。

  4. 查看订单详情

    在后台订单详情查看支付失败的具体错误码与消息。

  5. 检查 Webhook

    支付网关 Webhook 未配置或失败会导致支付状态不更新。在「设置 → 应用 → Webhook」查看投递记录。

订单状态未更新

  • 支付完成但订单仍显示「待付款」：检查支付网关 Webhook 是否正确配置并投递成功
  • 发货后订单仍显示「已付款」：确认是否在订单详情页点击「标记为已发货」
  • 退款后库存未回滚：检查商品是否启用了库存跟踪

邮件与通知

客户未收到订单确认邮件

  1. 检查邮件配置

    私有化部署用户检查邮件发送相关配置（邮件发送由 suite 平台方处理，store 通过 SUITE_API_URL 调用；若 suite 不可达，邮件发送会降级 NoOp）。托管服务用户跳过此步。

  2. 检查客户邮箱

    确认客户下单时填写的邮箱正确。在订单详情查看客户邮箱。

  3. 检查垃圾邮件箱

    让客户检查垃圾邮件箱，将 noreply@shopfaas.com 加入白名单。

  4. 检查邮件模板

    在「营销 → 邮件模板」确认订单确认模板已启用且内容正确。

  5. 查看邮件投递日志

    在后台「营销 → 邮件投递记录」查看投递状态与失败原因。

弃单召回邮件未发送

  • 确认弃单召回任务已启用
  • 检查召回邮件模板是否配置
  • 确认客户未取消订阅营销邮件

商品与库存

商品图片上传失败

  • 文件过大：单文件最大 50 MB，建议压缩后上传
  • 格式不支持：支持 jpg/png/gif/webp，其他格式需转换
  • 存储空间不足：检查套餐存储配额，升级套餐或清理旧文件
  • 网络超时：大文件上传可能超时，建议在网络稳定时上传

库存数量不正确

  • 检查是否有未完成的订单占用了库存
  • 检查是否有退款未回滚库存（退款应自动回滚）
  • 查看库存调整日志（商品详情 → 库存历史）

应用与扩展

安装应用后店铺异常

  1. 禁用应用

    在「设置 → 应用」禁用最近安装的应用，确认问题是否消失。

  2. 检查应用权限

    查看应用所需权限是否合理。权限过大的应用可能影响店铺稳定性。

  3. 检查浏览器控制台

    按 F12 打开开发者工具，查看 Console 是否有错误信息。

  4. 联系应用开发者

    通过应用市场页面联系应用开发者反馈问题。

  5. 卸载应用

    若问题持续，卸载应用并提交 Bug 报告。

Webhook 投递失败

  • 检查应用 Webhook URL 是否可公开访问
  • 检查应用服务是否正常运行
  • 在后台查看 Webhook 投递历史与失败原因
  • 手动重发失败的投递

前台页面

店铺前台显示空白

  • 检查店铺状态是否为「上线」（非「密码保护」或「已暂停」）
  • 检查主题是否已激活
  • 清除浏览器缓存后重试
  • 尝试切换到默认主题排查是否为主题问题

自定义域名无法访问

  • 检查 DNS CNAME 记录是否正确指向 ShopFaaS
  • 等待 DNS 生效（最长 48 小时）
  • 检查 SSL 证书是否已签发（在「设置 → 域名」查看）
  • 确认域名未过期

页面加载缓慢

  • 检查主题是否加载了大量未优化的图片
  • 检查是否安装了过多应用（每个应用会增加前端资源）
  • 使用 PageSpeed Insights 分析性能瓶颈
  • 私有化部署用户检查服务器负载与带宽

私有化部署

服务无法启动

# 查看各服务日志
docker compose logs postgres
docker compose logs redis
docker compose logs rustfs
docker compose logs shopfaas

常见原因：

  • 端口被占用（检查 4322/5432/6379/9000 端口）
  • 环境变量配置错误
  • 卷权限问题
# 查看服务状态
sudo systemctl status shopfaas
sudo systemctl status postgresql
sudo systemctl status redis-server

# 查看应用日志
sudo journalctl -u shopfaas -f

常见原因：

  • 依赖服务未启动
  • 环境变量配置错误
  • 文件权限问题

数据库连接失败

  • 检查 DATABASE_URL 中的密码是否与 POSTGRES_PASSWORD 一致
  • 确认 PostgreSQL 服务已启动（systemctl status postgresql）
  • 确认数据库 shopfaas 与用户 shopfaas 已创建
  • 检查 PostgreSQL 是否允许本地连接（pg_hba.conf）

Redis 连接失败

  • 检查 REDIS_URL 中的密码是否与 REDIS_PASSWORD 一致
  • 确认 Redis 服务已启动（systemctl status redis-server）
  • 检查 Redis 是否配置了 requirepass

对象存储连接失败

  • 检查 S3_ACCESS_KEY 与 RUSTFS_ACCESS_KEY 是否一致
  • 检查 S3_SECRET_KEY 与 RUSTFS_SECRET_KEY 是否一致
  • 确认 RustFS 服务已启动
  • 确认 S3 兼容端点（RustFS/MinIO）已正确配置 S3_ENDPOINT / S3_ACCESS_KEY_ID / S3_SECRET_ACCESS_KEY / S3_BUCKET（path-style 访问由 boots-core/storage 自动检测）

升级后服务异常

  1. 查看迁移日志

    查看容器启动日志确认数据库迁移是否成功：

    docker compose logs shopfaas | grep -i migrate

    数据库迁移在容器启动时自动执行，无需手动运行命令。

  2. 回滚到旧版本

    # Docker
docker compose down
# 修改 docker-compose.yml 中的镜像 tag 为旧版本
docker compose up -d

  3. 恢复数据库备份

    docker compose exec -T postgres psql -U shopfaas shopfaas < backup_20260101.sql

  4. 提交 Issue

    将迁移日志与错误信息提交到 GitHub Issues。

性能问题

后台操作缓慢

  • 检查网络连接质量
  • 清除浏览器缓存
  • 检查是否加载了大量数据（如数万商品），考虑分页或筛选
  • 私有化部署用户检查服务器 CPU 与内存使用率

API 调用被限流

  • 检查是否短时间内发送了大量请求（默认 600 次/分钟）
  • 实现指数退避重试
  • 批量操作用列表 API，避免循环单条查询
  • 高频场景考虑使用 Webhook 代替轮询

仍无法解决？

GitHub Issues

提交 Bug 报告，附错误日志与复现步骤。

GitHub Discussions

社区互助问答。

邮件支持

support@shopfaas.com（付费用户优先响应）。

常见问题

非技术问题的解答。

此页面有帮助吗?

在 GitHub 上编辑此页