's'

README.md

@@ -82,6 +82,16 @@ PAYMENT_PROVIDER=zpay
 # 其他 ZPAY、PocketBase、Memos 配置见 .env.example
 ```
 
+## 线上「支付失败」排查
+
+本地正常、Ubuntu 部署后显示支付失败，常见原因：
+
+1. **BASE_URL 配置错误**：必须为 ZPAY 可公网访问的地址。错误示例：`http://127.0.0.1:8700`、`http://localhost`。正确：`https://api.hackrobot.cn`（域名需解析到本机，nginx 反向代理 8700 端口）。
+
+2. **服务器无法访问 zpayz.cn**：防火墙、DNS 或网络限制。访问 `https://你的域名/health?check_zpay=1` 自检，若 `zpayz_reachable: false` 则需开放出站或检查网络。
+
+3. **启动时控制台有 BASE_URL 警告**：说明配置了内网地址，需修改 `.env` 中的 `BASE_URL` 为公网地址后重启。
+
 ## Getting started
 
 To make it easy for you to get started with GitLab, here's a list of recommended next steps.