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

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

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

## 10.1 按阶段排查

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

![按阶段排查支付链路问题](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/index-35-101-stage-troubleshooting.png)

### 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` 时不会自动补建迁移历史,需要继续按旧库运行或人工评估后再迁移。

```{warning}
不要为了让脚本“重新初始化”就随手删除业务表或 `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 已上传但未重启 |

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

```{important}
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 |

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

### 10.1.4 后续 SaaS 上线场景

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

```{note}
第 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 优先级

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

![按失败点选择日志和 Network 入口](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/index-36-102-log-network-priority.png)

### 第 9 章最常用

```text
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 准备阶段

```text
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。

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

### 线上 web-pay 阶段

```text
/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 证书是否有效。

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

### 后续 SaaS 上线阶段

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

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

## 10.3 脚本边界

![web-pay 和 SaaS 脚本边界](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/index-37-103-script-boundary.png)

### 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 为准。

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

✅ 脚本可以帮你:

- 写入配置文件。
- 启动本地服务。
- 构建前后端产物。
- 上传 web-pay 后端 Jar。
- 创建本地 cloudflared 隧道。

⚠️ 脚本不会替你:

- 购买域名、服务器、RDS、OBS/CDN。
- 申请微信支付或支付宝商户。
- 判断真实支付资质是否已经通过官方审核。
- 保管密钥、证书、密码。
- 刷新 CDN、重启线上 Java 进程或长期运维服务器。
- 保证业务一定上线成功或一定产生收益。

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

## 10.4 代码包边界

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

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

![代码包与个人责任边界](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/index-38-104-code-package-boundary.png)

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

代码包能节省:

- 初始工程整理时间。
- 本地启动脚本整理时间。
- 生产构建脚本整理时间。
- web-pay 与 SaaS 示例联调时间。
- 常见配置和排查路径整理时间。

代码包不等于:

- 不等于代部署服务。
- 不等于代运维服务。
- 不等于代申请微信 / 支付宝商户。
- 不等于代写完整业务系统。
- 不承诺收益。
- 不承诺一定上线成功。
- 不提供长期一对一陪跑。
- 不公开传播或代管你的真实密钥、证书和密码。

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

## 10.5 敏感信息底线

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

![敏感信息只留在私有环境](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/index-39-105-secrets-boundary.png)

这些内容默认敏感:

- 数据库密码。
- ActiveMQ 密码。
- SSH 密码或私钥。
- web-pay 应用 `AppSecret`。
- 微信支付 API 密钥、私钥、证书文件。
- 支付宝应用私钥、支付宝公钥、AES 密钥。
- OBS / CDN / CodeArts / 云厂商 Access Key。
- 真实 `.env`、`application.yml`、上传脚本里的服务器账号。

这些内容不能进入:

- Public 仓库。
- 前端目录和前端构建产物。
- 公开截图、教程截图、聊天群、网盘公开链接。
- 发给 AI 或第三方工具的上下文。

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

如果已经泄露:

1. 立即把仓库改回私有或删除公开文件。
2. 到对应平台重置或吊销密钥。
3. 重新运行配置脚本或手工替换新配置。
4. 重新构建并部署新配置。
5. 检查是否存在异常订单、异常登录或异常云资源消耗。

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