排错指南

第一步：看日志

部署方式	查看后端日志
systemd（Nginx / Caddy 部署）	journalctl -u zebra-store -n 200 或 journalctl -u zebra-store -f（实时）
宝塔	进程守护管理器 → zebra-store → 日志
Docker Compose	docker compose logs --tail 200 zebra

需要更详细的日志时，临时设置 log.level: debug（或环境变量 ZS__LOG__LEVEL=debug）后重启，排查完改回 info。 加上 log.json: true 可以输出 JSON 格式，方便用 jq 过滤。

每个请求都有请求 ID（响应头 X-Request-ID），后台权限审计等页面也会显示，可以用它在日志里搜索。

第二步：检查后端是否正常

curl -s http://127.0.0.1:8081/api/v1/public/config | head -c 200

• 返回以 {"status_code":0 开头的 JSON：后端正常，问题在 Web 服务器或浏览器；
• Connection refused：后端没启动，看日志；
• 超时：端口或 server.host 配置不对。

网页打不开

现象	原因
502 Bad Gateway	后端没运行，或反向代理的地址端口写错
404（首页）	网页文件没放对位置：网站根目录下应该直接是 index.html
刷新子页面 404	缺少“找不到文件时返回 index.html”的配置（try_files）
后台 /admin/ 空白	后台打包没加 --base=/admin/
页面打开但提示网络错误	/api/ 没有转发到后端
图片不显示	/uploads/ 没有转发；或上传目录权限不对

买家付款后订单没有变成已支付

1. 支付管理 → 支付记录 按订单号找到这笔支付，看状态和“原始通知”：
   • 没有任何通知：支付平台没有访问到本站。检查平台后台的通知地址是否正确、是否是 HTTPS、服务器防火墙是否放行； 如果在 回调路由 改过路径，平台那边也要改；
   • 有通知但失败：看日志里的错误。常见原因：签名错误（密钥填错）、金额不一致（买家少付）；
   • 状态是“已被取代”：买家换过支付方式，付的是旧链接。需要人工核实后处理；
2. 订单已经超时取消后才收到付款通知：订单不会自动变回已支付，日志里会记录，需要人工核实后给买家退款或补单；
3. 买家少付：订单不会变成已支付，少付的金额进入买家钱包余额，买家补足后可以完成订单。

邮件发不出去

1. 站点设置 → 邮件配置 点“发送测试邮件”，看提示；
2. 端口和加密方式：465 用 SSL，587 用 TLS；
3. QQ 邮箱、163 邮箱等要用授权码，不是登录密码；
4. 很多云服务器封锁了 25 端口，不要用 25；
5. 通知中心 → 发送日志 里能看到每封邮件的失败原因。

登录问题

现象	处理
提示登录尝试过多	等 15 分钟（security.login_rate_limit），或重启后端清除（内存计数）
买家说收不到注册验证码	同上“邮件发不出去”；或临时关闭邮箱验证
管理员两步验证丢失	zebra-store admin reset-2fa --username 用户名
所有人都突然被登出	修改过 jwt.secret / user_jwt.secret，属正常现象

对接问题

现象	处理
测试连接超时	上游地址从服务器访问不到：在服务器上 curl -I 上游地址 试试
提示不允许访问内网地址	上游地址解析到了内网 IP。生产环境不要这样用；内网测试时设置 integration.allow_private_addresses: true
签名错误 / 401	Key、Secret 填错；或两台服务器时间差超过 5 分钟（执行 timedatectl 检查，开启 NTP）
采购单“已拒绝：余额不足”	在上游充值后点重试
采购单“待人工核对”	见 采购单与故障处理

数据库问题

现象	处理
unable to open database file	数据目录不存在或运行用户没有写权限
database is locked	有别的程序（例如你打开的 sqlite3）长时间占着数据库，关掉它
MySQL 连接失败	数据库需要事先创建；密码里的特殊字符要 URL 编码；用户要有建表权限

还是解决不了

提供这些信息去提问：版本号（后台右上角）、部署方式、数据库类型、出错时间点前后的后端日志、浏览器 F12 控制台和网络面板截图。