五、本地跑通 web-pay

这一章先认清 web-pay 的脚本入口,再把配置写到正确文件里,最后在本机启动收银台前端、运营平台前端、支付网关后端、运营平台后端。

重要

🚀 本章目标: 让 web-pay 在你的电脑上真正跑起来,并能登录运营平台。商户、应用、支付参数和支付通道放到第 6 章集中配置。

5.1 web-pay 脚本速读

web-pay 的脚本都在仓库根目录的 env-scripts/:

小技巧

🧰 先认脚本,再跑服务。 这一章不要求你手工启动每个前后端模块,主要靠下面几个脚本完成配置、启动和停止。

脚本 作用 什么时候用
rename-saas-service.sh 把第 3 章准备好的域名、RDS、ActiveMQ、SSH 信息写入 web-pay 配置和上传脚本 第一次配置或域名、数据库、服务器信息变化时
start-local-test-backend.sh 「本地测试时使用」检查 pay 库并在空库时通过 Flyway 初始化,构建并启动支付网关后端和运营后端,创建 cloudflared 隧道,生成 tmp/local-test-backend.tunnel.yml 本地跑 web-pay 后端
start-local-test-frontend.sh 「本地测试时使用」安装必要前端依赖并启动收银台、运营平台前端 本地跑 web-pay 前端
stop.sh 「本地测试时使用」停止 web-pay 本地前端、后端和 cloudflared 隧道,清理临时隧道文件 本地联调结束或端口冲突时
build-prod-backend.sh 「CI/CD自动构建上线」生产方式构建支付网关和运营后端 Jar 线上部署前构建后端
build-prod-frontend.sh 「CI/CD自动构建上线」生产方式构建收银台和运营平台前端 dist 线上部署前构建前端
upload-zhcpay-backend-jars.sh 「CI/CD自动构建上线」上传支付网关和运营后端 Jar 到云服务器目录 后端 Jar 构建完成后部署到服务器

web-pay 本地脚本入口关系

本章本地联调只需要 start-local-test-backend.sh、start-local-test-frontend.sh 和 stop.sh。生产构建和上传脚本在后面线上部署章节再用。

警告

📌 先不要跑生产脚本。 本地测试阶段只关心 start-local-test-* 和 stop.sh,生产构建、上传、CI/CD 等脚本等本地支付闭环跑通后再处理。

5.2 执行 web-pay 配置脚本

web-pay 的配置脚本在仓库根目录:

env-scripts/rename-saas-service.sh

运行前先准备好第 3 章记录的这些信息:

小技巧

📌 照着第 3 章的本地记录表填。 这里不是让你临时去翻云控制台,而是把已经准备好的域名、RDS、ActiveMQ 和 SSH 信息一次性写入配置。

脚本会询问 应该填写
支付网关后端 API 地址 线上规划的 pay-api 后端域名,例如 https://pay-api.example.com
运营平台后端 API 地址 线上规划的 paymanager-api 后端域名
统一收银台前端页面地址 线上规划的收银台前端域名,例如 https://pay.example.com
PostgreSQL 内网连接地址 RDS 内网地址,不带端口
PostgreSQL 公网连接地址 RDS 公网地址,不带端口
PostgreSQL 数据库名称 pay
数据库用户名 你的 RDS 业务用户
数据库密码 你的 RDS 业务用户密码
ActiveMQ 密码 第 3 章云服务器 ActiveMQ 密码
SSH 账户地址 云服务器公网 IP
SSH 账户 通常是 root 或你自己的服务器用户
SSH 密码 云服务器 SSH 密码

web-pay 配置脚本写入关系

在 web-pay 仓库根目录执行:

chmod +x ./env-scripts/rename-saas-service.sh
./env-scripts/rename-saas-service.sh

脚本会更新这些文件:

zhcpay-ui/zhcpay-ui-cashier/.env
zhcpay-ui/zhcpay-ui-manager/.env
zhcpay/zhcpay-payment/src/main/resources/application.yml
zhcpay/zhcpay-manager/src/main/resources/application.yml
zhcpay/zhcpay-payment/src/main/resources/application-local.yml
zhcpay/zhcpay-manager/src/main/resources/application-local.yml
env-scripts/upload-zhcpay-backend-jars.sh

危险

🔐 脚本会写入敏感配置。 数据库密码、ActiveMQ 密码、SSH 信息只应该保存在你控制的本地环境或私有仓库中,不要把改好的配置文件公开传播。

5.3 启动前检查

先把 cloudflared 的作用讲清楚:本地 web-pay 跑在你自己的电脑上,支付网关后端地址通常是 http://localhost:9216。这个地址只有本机能访问,微信 / 支付宝在公网,支付成功后无法直接回调到你的 localhost。

重要

🌐 cloudflared 是本地支付回调的临时公网入口。 没有它,你可以打开本地页面,但微信 / 支付宝无法从公网回调到你的电脑。

cloudflared 解决的就是这个问题。它会给本机服务创建一个临时的公网 HTTPS 地址,并把公网请求转发到本机 9216 端口。这样支付平台访问的是类似 https://xxxx.trycloudflare.com 的公网地址,但请求最终会进入你电脑上的 web-pay 支付网关。

所以安装 cloudflared 的核心目的不是生产部署,而是让你在本地就能测试完整支付流程:

  • 本地就能获得可被微信 / 支付宝访问的公网 HTTPS 回调地址。

  • 可以验证支付平台是否真的回调到 web-pay。

  • 可以检查回调验签、订单状态更新、支付流水和回调日志是否正常。

  • 可以继续验证 web-pay 是否把支付结果通知给 SaaS 业务后端。

  • 不用等后端上线、域名解析、HTTPS 证书和 Nginx 都配置完成后,才开始排查支付问题。

也就是说,有了 cloudflared,本地测试就不再只能测到”打开收银台”这一步,而是可以继续测到”支付成功后回调进来、订单变成已支付、业务系统收到支付结果”这一整条闭环。

cloudflared 本地回调入口与启动前检查

警告

本章后面的 ./env-scripts/start-local-test-backend.sh 会自动创建 web-pay 的 cloudflared 隧道,并把隧道地址写入运行时覆盖配置。每次启动生成的公网地址可能不同,测试支付回调时要使用脚本本次输出的最新地址。

确认第 4 章和本章配置脚本已经完成:

警告

✅ 这些项都通过后再启动后端。 少一项都可能导致后端启动失败,或者支付回调只能走到一半。

  • 本机 Redis 正在运行。

  • 本机 ActiveMQ 正在运行。

  • 云数据库 RDS pay 库已创建;新库可以保持空库,首次启动后端会自动初始化。

  • cloudflared 已安装。

  • psql 已安装,并且本机能连接 RDS 公网地址。

  • 已执行 ./env-scripts/rename-saas-service.sh。

  • zhcpay/zhcpay-payment/src/main/resources/application-local.yml 能连接 RDS 公网地址。

  • zhcpay/zhcpay-manager/src/main/resources/application-local.yml 能连接 RDS 公网地址。

5.4 启动后端

在仓库根目录执行:

./env-scripts/start-local-test-backend.sh

脚本会做这些事:

重要

🚀 这一步会同时启动两个后端。 第一次启动可能会慢一点,因为空库初始化和 Maven 构建都需要时间。

动作 说明
Maven 构建 构建支付网关和运营后端
Flyway 空库初始化 如果 pay 库为空,先由运营后端自动创建表结构和基础数据
启动支付网关 默认 http://localhost:9216
启动运营后端 默认 http://localhost:9217
创建 cloudflared 隧道 把本机 9216 暴露为公网回调地址
写入运行时覆盖配置 生成 tmp/local-test-backend.tunnel.yml

web-pay 本地后端启动流程

启动脚本会先用 psql 检查 pay 库的 public schema:

小技巧

💡 Flyway 行为不用手工干预。 脚本会根据数据库状态决定初始化、迁移或跳过,目的是尽量保护已有数据。

  • 空库:临时启用 Flyway,先启动运营后端完成初始化,再启动支付网关。

  • 已经有 flyway_schema_history:继续执行 Flyway 校验和后续迁移。

  • 已有业务表但没有 Flyway 历史:跳过 Flyway,保护旧库已有数据。

第一次空库初始化会比普通启动多花一点时间。如果脚本提示跳过 Flyway,通常说明这个库以前已经手工导入过初始化 SQL,可以继续按旧库方式运行。

5.5 启动前端

另开一个终端,在仓库根目录执行:

./env-scripts/start-local-test-frontend.sh

默认访问地址:

警告

📌 前端和后端端口不要混。 浏览器直接操作主要看 8002 运营平台;9216、9217 是接口服务,通常不会显示页面。

服务 地址
收银台前端 http://localhost:8080
运营平台前端 http://localhost:8002
支付网关后端 http://localhost:9216
运营平台后端 http://localhost:9217

web-pay 本地前端和后端端口关系

这 4 个地址不是都能看到前端页面:

  • http://localhost:8002 是运营平台前端,可以直接打开登录,进入后可以查看商户、应用、订单和支付配置。

  • http://localhost:8080 是收银台前端,但它不是给你直接从根路径进入的页面。收银台必须由其他服务携带 zhcpayToken 生成支付链接后进入,类似 http://localhost:8080/#/hub/{zhcpayToken}。没有 token 直接打开根路径,看不到正常收银台画面是预期行为。

  • http://localhost:9216 是支付网关后端接口服务,主要给收银台、SaaS 后端和支付平台回调调用,没有前端操作画面。

  • http://localhost:9217 是运营平台后端接口服务,主要给运营平台前端调用,也没有前端操作画面。

所以本地启动后,真正可以直接进入并操作的前端页面是运营平台:

http://localhost:8002

备注

🎯 收银台不是从首页直接打开的。 后面 SaaS 创建订单后会生成带 zhcpayToken 的支付链接,那时才会进入正常收银台流程。

5.6 登录运营平台

浏览器打开运营平台前端:

http://localhost:8002

登录页出现后,使用初始化账号登录:

字段 填写
账号 zhcpay
密码 zhcpay666

运营平台登录成功代表的基础链路

ZHCPAY

能进入运营平台首页,就说明这 3 件事已经跑通:

  • 运营平台前端能打开。

  • 运营平台后端能响应登录请求。

  • 后端已经能连接 pay 数据库并读取初始化账号。

ZHCPAY

重要

✅ 登录成功就是本地 web-pay 基础链路通过。 商户、应用、支付参数和通道开关下一章再配,这里先不要混在启动验收里。

参见

下一步先进入第 6 章,在运营平台创建商户、应用并整理支付身份。第 7 章再把这些值写入 saas-starter 并启动 SaaS 前后端。

5.7 常用日志和排查入口

小技巧

本地联调时不要只盯浏览器页面。web-pay 出问题时,优先看这些文件:

文件或目录 看什么
tmp/zhcpay-payment.local-test.log 支付网关后端启动、统一下单、支付平台回调、通知商户结果
tmp/zhcpay-manager.local-test.log 运营后端启动、登录、商户 / 应用 / 支付配置保存、证书上传
tmp/cloudflared-local-test.log cloudflared 是否生成公网地址、隧道是否连接成功
tmp/zhcpay-cashier-ui.log 收银台前端启动和编译错误
tmp/zhcpay-manager-ui.log 运营平台前端启动和编译错误
tmp/local-test-backend.tunnel.yml 后端本次启动使用的 web-pay.public-base-url 覆盖配置
tmp/local-test/upload/private/cert 本地上传后的微信证书和私钥文件

web-pay 本地联调日志排查入口

常见排查顺序:

  1. 运营平台打不开:先看 tmp/zhcpay-manager-ui.log,再看 tmp/zhcpay-manager.local-test.log。

  2. 登录失败:优先看运营后端日志和 RDS pay 库初始化是否成功。

  3. 运营平台页面能打开但接口报错:看 tmp/zhcpay-manager.local-test.log 和浏览器 Network。

  4. 收银台根路径看不到正常页面:这是预期行为,后面 SaaS 创建订单后才会生成带 zhcpayToken 的链接。

  5. 支付平台回调不到本机:后面支付联调时再看 tmp/cloudflared-local-test.log,确认本次公网地址仍然可用。

  6. 回调进了 web-pay 但订单没变:后面支付联调时看 tmp/zhcpay-payment.local-test.log,重点查验签、订单号、通道配置。

警告

脚本每次启动 cloudflared 都可能得到新的公网地址。不要拿上一次终端里的 trycloudflare.com 地址继续测本次支付。

5.8 停止和重启 web-pay

本地联调结束,或者端口被占用时,在仓库根目录执行:

./env-scripts/stop.sh

这个脚本会停止:

  • 支付网关后端 zhcpay-payment。

  • 运营平台后端 zhcpay-manager。

  • 收银台前端 zhcpay-ui-cashier。

  • 运营平台前端 zhcpay-ui-manager。

  • 本地 9216 对应的 cloudflared 隧道。

web-pay 停止和重启清理关系

它也会清理这些临时文件:

tmp/cloudflared-local-test.log
tmp/local-test-public-url.env
tmp/local-test-backend.tunnel.yml

小技巧

如果只是改了运营平台里的数据类配置,通常不需要重启服务;刷新页面或重新发起订单即可。只有改了本地配置文件、端口、数据库连接、Redis、ActiveMQ、cloudflared 隧道或前端 .env 后,才需要按影响范围重启。

常见重启方式:

场景 建议操作
只改支付参数或支付通道 不重启,保存后重新发起一笔新订单测试
改了后端 Spring 配置 先执行 ./env-scripts/stop.sh,再执行 ./env-scripts/start-local-test-backend.sh
改了前端 .env.development 重新执行 ./env-scripts/start-local-test-frontend.sh
cloudflared 地址失效 重启后端脚本,使用本次新生成的公网地址
端口被占用或服务状态混乱 先执行 ./env-scripts/stop.sh,确认端口释放后再重新启动前后端

警告

重启后如果 cloudflared 生成了新的 trycloudflare.com 地址,支付平台回调和本地覆盖配置也要以本次启动为准。旧地址不要继续用于新的支付测试。

5.9 本章完成标准

  • ./env-scripts/start-local-test-backend.sh 可以启动支付网关后端和运营平台后端。

  • ./env-scripts/start-local-test-frontend.sh 可以启动收银台前端和运营平台前端。

  • 浏览器可以打开 http://localhost:8002。

  • 可以使用 zhcpay / zhcpay666 登录运营平台。

  • 已知道 http://localhost:8080 是收银台入口,需要后续订单生成 zhcpayToken 后才能正常进入。

  • 已知道优先查看 tmp/zhcpay-manager.local-test.log、tmp/zhcpay-payment.local-test.log 和前端日志排查本地启动问题。

重要

只要可以登录运营平台,第 5 章就算完成。商户、应用、mchNo、appId、AppSecret、支付宝 / 微信参数和支付通道全部放到第 6 章处理。

参见

下一步进入第 6 章,先配置 saas-starter 调用 web-pay 所需的支付身份。第 7 章再启动 saas-starter 本地前端和后端。