十、排查、脚本边界与免责声明

这一章是附录。主流程已经在第 9 章完成,这里不再新增部署步骤,只负责三件事:排查问题、说明脚本边界、明确代码包和敏感信息底线。

重要

🧭 排查原则: 先判断问题发生在哪个阶段,再看对应日志。不要在同一轮里同时改支付参数、通道、SaaS 身份、前端缓存和 tunnel 地址。支付相关问题改完后,重新创建一笔新订单验证,不要拿旧订单反复测。

10.1 按阶段排查

重要

🎯 先定位阶段,再动配置。 支付链路很长,不要看到报错就同时改前端、后端、通道、密钥和 tunnel。先判断问题卡在本地基础服务、线上 web-pay、第 9 章验收,还是后续 SaaS 上线场景。

按阶段排查支付链路问题

10.1.1 本地基础服务

这一组主要对应第 4、5、7 章:本机工具、web-pay 本地启动、SaaS 本地启动和数据库初始化。

现象 优先检查 常见原因
本地后端启动失败 本机 Redis、ActiveMQ、RDS 公网地址、后端日志 本机依赖没启动、RDS 白名单没放行、数据库账号密码错误
本地前端打不开 HBuilderX / 前端终端、端口、浏览器控制台 前端依赖没安装、端口被占用、打开了错误目录
本地 web-pay 登录失败 tmp/zhcpay-manager.local-test.log、RDS pay 库 初始化数据缺失、数据库连接失败、运营后端没启动
SaaS 页面接口报错 saas-starter/logs/backend.local.log、浏览器 Network SaaS 后端没启动、前端 API 仍指向旧地址、业务库未初始化
本地后端脚本提示没有 psql 本机 PostgreSQL 客户端 未安装 psql 或 PATH 没生效
空 pay 库首次启动失败 tmp/zhcpay-manager.local-test.log Flyway 迁移 SQL 报错或数据库用户没有建表权限
脚本提示非空库且无 Flyway 历史 RDS pay 库表清单 旧库已经手工初始化,脚本会跳过 Flyway 保护数据
Flyway 校验失败 flyway_schema_history、迁移文件版本 已执行过的迁移文件被修改或历史版本不一致

Flyway 只在本地后端启动脚本确认安全时启用。新建空库会自动初始化;已有业务表但没有 flyway_schema_history 时不会自动补建迁移历史,需要继续按旧库运行或人工评估后再迁移。

警告

不要为了让脚本“重新初始化”就随手删除业务表或 flyway_schema_history。数据库迁移问题先备份、再判断库是不是教程测试库;线上库或已有数据的库必须人工评估后再处理。

10.1.2 web-pay 线上部署

这一组主要对应第 8 章:收银台、运营平台、支付网关、运营 API 和 CodeArts。

现象 优先检查 常见原因
线上前端能打开但接口错 前端 .env、CDN 缓存、浏览器 Network 前端构建时打进了旧 API 地址,或 CDN 仍命中旧包
线上运营平台登录失败 paymanager-api、运营后端日志、浏览器 Network 运营后端没启动、反向代理错误、生产 API 域名不对
收银台域名只有空白或旧页面 OBS 上传目录、CDN 刷新、控制台 404 dist 上传路径不对、CDN 未刷新、静态资源缺失
线上后端启动失败 服务器 Java 日志、RDS 内网地址、ActiveMQ 生产配置错误、JDK 版本不对、端口被占用
支付平台回调不到 web-pay pay-api 域名、Nginx、支付网关日志 支付平台回调地址不是线上 API 域名,或 HTTPS / 反代异常
CodeArts 成功但线上没变 OBS 上传路径、CDN 刷新、Java 进程 上传了旧目录、未刷新 CDN、Jar 已上传但未重启

小技巧

💡 第 8 章验收只要求 web-pay 线上环境就绪。没有订单 token 时,直接打开收银台根域名看不到完整付款页是正常现象。

重要

CodeArts 任务成功只说明“构建和上传”成功。前端是否生效还要看 CDN 是否刷新;后端是否生效还要看 Java 进程是否重启、宝塔反代是否指到 9216 / 9217。

10.1.3 第 9 章支付验收

这一组对应当前主线的最后一段:本地 saas-starter 调用线上 web-pay,再由线上 web-pay 通知本机 SaaS tunnel。

现象 优先检查 常见原因
SaaS 不能创建订单 saas-starter/logs/backend.local.log、mchNo / appId / AppSecret、线上 pay-api SaaS 身份不匹配、线上支付网关不可达、签名失败
创建订单后没有跳收银台 zhcpay.cashier-base-url、统一下单响应、前端 Network 收银台域名仍是旧配置、payUrl 为空、前端没有重新运行
收银台没有支付宝或微信 第 6 章支付参数和通道、官方产品权限 通道未启用、支付参数未保存、官方产品权限未开通
支付成功但 web-pay 订单没成功 线上 pay-api、支付网关日志、支付平台回调记录 支付平台第一段回调没有进入线上 web-pay
web-pay 订单成功但 SaaS 没更新 application-local-tunnel.yml、backend.local.tunnel.log、backend.local.log SaaS tunnel 失效、通知地址不是本次生成、SaaS 验签失败
SaaS 收到通知但业务状态没变 t_saas_pay_order、t_vip_subscription、SaaS 后端日志 订单号不匹配、订单已终态、业务入账逻辑未执行
SaaS 前端仍显示未支付 前端轮询接口、浏览器缓存、业务订单状态 后端已成功但前端没刷新,或仍请求旧本地 API

警告

⚠️ 第 9 章还没有上线 SaaS 独立站时,不要优先查 saas-starter-api.example.com。当前主线里,线上 web-pay 通知的是 saas-starter 后端脚本生成的 cloudflared 地址。

10.1.4 后续 SaaS 上线场景

这一组只适用于你未来把 saas-starter 或自己的 SaaS 也按第 8 章方法放到线上之后。还停留在第 9 章本地验收时,可以先跳过。

备注

第 9 章完成后,基础教程主线已经结束。下面这些问题属于“把 SaaS 产品也放到线上”的后续运维场景,不是当前支付底座验收的必做项。

现象 优先检查 常见原因
SaaS 线上前端接口错 SaaS 前端 .env、CDN 缓存、浏览器 Network 前端仍指向本机 API 或旧 API
SaaS 线上后端启动失败 SaaS 服务器日志、RDS 内网地址、环境变量 生产数据库连接或密钥配置错误
web-pay 成功但线上 SaaS 没更新 saas-starter-api 域名、Nginx、线上 SaaS 日志 SaaS API 域名不可达、反代错误、通知地址配置错误
SaaS 上线后支付返回异常 site-base-url、returnUrl、浏览器跳转地址 生产前端域名配置错误或缓存未刷新

10.2 日志和 Network 优先级

重要

📌 先看最靠近失败点的日志。 创建订单失败先看 SaaS 后端;收银台展示异常先看浏览器 Network;支付成功但业务没更新先看 SaaS tunnel 和通知日志。

按失败点选择日志和 Network 入口

第 9 章最常用

saas-starter/logs/backend.local.log
saas-starter/logs/backend.local.tunnel.log
saas-starter/logs/application-local-tunnel.yml

  • backend.local.log:看 SaaS 是否成功创建订单、验签、更新业务状态。

  • backend.local.tunnel.log:看 cloudflared tunnel 是否连通、是否生成本次公网地址。

  • application-local-tunnel.yml:核对本次 zhcpay.notify-url 是否为最新 /api/pay/notify 地址。

浏览器 Network 里重点看这些方向:

页面 应该请求哪里 如果不对说明什么
本地 SaaS H5 http://localhost:9220/api/v1 前端 .env.development 或 HBuilderX 缓存没刷新
SaaS 后端创建支付 线上 https://pay-api.example.com zhcpay.api-base-url 配错
线上收银台 线上 https://pay-api.example.com 收银台生产 .env、CDN 缓存或 API 域名异常
线上运营平台 线上 https://paymanager-api.example.com 运营平台生产 .env、CDN 缓存或运营 API 异常

本地 web-pay 准备阶段

tmp/zhcpay-payment.local-test.log
tmp/zhcpay-manager.local-test.log
tmp/cloudflared-local-test.log
tmp/local-test-backend.tunnel.yml

这些日志主要用于第 5、6 章。第 9 章支付验收已经改为调用线上 web-pay,通常不需要再看本地 web-pay tunnel。

备注

如果你已经进入第 9 章,本地 web-pay 日志通常不是第一入口。除非你临时回到第 5、6 章复核本地 web-pay,否则优先看线上 web-pay 日志和 saas-starter/logs/。

线上 web-pay 阶段

/www/wwwroot/pay/payment/payment.log
/www/wwwroot/pay/manager/manager.log

如果你通过宝塔 Java 项目管理启动服务,日志路径以宝塔界面实际配置为准。线上问题优先确认:Java 进程是否在跑、Nginx 是否反代到 127.0.0.1:9216 / 127.0.0.1:9217、HTTPS 证书是否有效。

警告

公网排查不要靠直接开放 9216 / 9217。这两个端口应只在服务器本机被 Nginx 反代访问;外部统一访问 https://pay-api... 和 https://paymanager-api...。

后续 SaaS 上线阶段

/www/wwwroot/saas-starter/backend/saas-starter.log

这只适用于未来你把 SaaS 后端也部署到云服务器之后。第 9 章本地验收时,SaaS 日志仍然看本机 saas-starter/logs/ 目录。

10.3 脚本边界

web-pay 和 SaaS 脚本边界

web-pay 脚本

脚本 负责什么
env-scripts/rename-saas-service.sh 写入 web-pay 域名、数据库、ActiveMQ、服务器上传等配置
env-scripts/start-local-test-backend.sh 本地启动支付网关和运营后端,初始化空 pay 库,创建本地 web-pay tunnel
env-scripts/start-local-test-frontend.sh 本地启动收银台和运营平台前端
env-scripts/build-prod-backend.sh 构建 web-pay 支付网关和运营后端生产 Jar
env-scripts/build-prod-frontend.sh 构建 web-pay 收银台和运营平台前端 dist
env-scripts/upload-zhcpay-backend-jars.sh 上传 web-pay 后端 Jar 到云服务器
env-scripts/stop.sh 停止本地 web-pay 前后端和本地 tunnel

SaaS 脚本

脚本 负责什么
saas-starter/env-scripts/rename-saas-service.sh 写入 SaaS 前后端配置、支付身份和部署默认值
saas-starter/env-scripts/start-local-test-backend.sh 本地启动 SaaS 后端,初始化 SaaS 业务库,创建 SaaS tunnel
saas-starter/env-scripts/build-prod-backend.sh 构建 SaaS 后端 Jar,供未来上线时使用
saas-starter/env-scripts/build-prod-frontend.sh 构建 SaaS H5 前端 dist,供未来上线时使用
saas-starter/env-scripts/stop.sh 停止本地 SaaS 后端和 SaaS tunnel

SaaS 前端是 UniApp H5 项目,本地优先用 HBuilderX 运行到浏览器。命令行调试可在 saas-starter/frontend 执行 npm run dev:h5,但教程主流程以 HBuilderX 为准。

小技巧

脚本适合做重复、确定的动作:写配置、构建、启动本地服务、上传产物。遇到云资源购买、支付资质审核、证书续期、生产事故和安全策略时,仍需要你自己做判断。

✅ 脚本可以帮你:

  • 写入配置文件。

  • 启动本地服务。

  • 构建前后端产物。

  • 上传 web-pay 后端 Jar。

  • 创建本地 cloudflared 隧道。

⚠️ 脚本不会替你:

  • 购买域名、服务器、RDS、OBS/CDN。

  • 申请微信支付或支付宝商户。

  • 判断真实支付资质是否已经通过官方审核。

  • 保管密钥、证书、密码。

  • 刷新 CDN、重启线上 Java 进程或长期运维服务器。

  • 保证业务一定上线成功或一定产生收益。

小技巧

💡 后续如果要上线 saas-starter 或自己的 SaaS,复用第 8 章的部署思路:前端构建后上传 OBS/CDN,后端 Jar 上传云服务器并用 Nginx 反代,再接入 CodeArts 或其他 CI/CD。第 10 章不再单独展开 SaaS 上线步骤。

10.4 代码包边界

源码购买说明以第 3 章为准,本章不重复购买入口。

重要

代码包是工程底座,不是代运营或代部署服务。它提供可运行的示例、脚本和排查路径,但真实业务设计、支付资质、线上运维和安全责任仍由你掌握。

代码包与个人责任边界

代码包提供的是一套可复用的支付底座、SaaS 示例、启动脚本、构建脚本和排查路径。它的价值是减少你从 0 整理工程、配置和联调脚本的时间。

代码包能节省:

  • 初始工程整理时间。

  • 本地启动脚本整理时间。

  • 生产构建脚本整理时间。

  • web-pay 与 SaaS 示例联调时间。

  • 常见配置和排查路径整理时间。

代码包不等于:

  • 不等于代部署服务。

  • 不等于代运维服务。

  • 不等于代申请微信 / 支付宝商户。

  • 不等于代写完整业务系统。

  • 不承诺收益。

  • 不承诺一定上线成功。

  • 不提供长期一对一陪跑。

  • 不公开传播或代管你的真实密钥、证书和密码。

警告

不要把购买后的源码、配置包、密钥文件或部署脚本二次公开传播。公开传播不仅会暴露你的真实环境信息,也会让后续排查和安全责任变得不可控。

10.5 敏感信息底线

危险

🔐 敏感信息只放在你控制的私有环境里。 下面列出的密码、密钥和证书不要进入公开仓库、前端构建产物、公开截图或聊天记录;一旦泄露,先重置密钥,再重新部署。

敏感信息只留在私有环境

这些内容默认敏感:

  • 数据库密码。

  • ActiveMQ 密码。

  • SSH 密码或私钥。

  • web-pay 应用 AppSecret。

  • 微信支付 API 密钥、私钥、证书文件。

  • 支付宝应用私钥、支付宝公钥、AES 密钥。

  • OBS / CDN / CodeArts / 云厂商 Access Key。

  • 真实 .env、application.yml、上传脚本里的服务器账号。

这些内容不能进入:

  • Public 仓库。

  • 前端目录和前端构建产物。

  • 公开截图、教程截图、聊天群、网盘公开链接。

  • 发给 AI 或第三方工具的上下文。

可以放在你自己的私有仓库、密码管理器、云服务器私有目录或运营平台后台中。即使是私有仓库,也建议尽量使用环境变量或凭据管理,不要把长期密钥散落在多个文件里。

如果已经泄露:

  1. 立即把仓库改回私有或删除公开文件。

  2. 到对应平台重置或吊销密钥。

  3. 重新运行配置脚本或手工替换新配置。

  4. 重新构建并部署新配置。

  5. 检查是否存在异常订单、异常登录或异常云资源消耗。

警告

泄露后的优先级是“先吊销,再排查”。不要只删除公开文件就结束;被搜索引擎、缓存、第三方工具或聊天记录保存过的密钥,都应该视为已经失效。