# 五、本地跑通 web-pay 这一章先认清 web-pay 的脚本入口,再把配置写到正确文件里,最后在本机启动收银台前端、运营平台前端、支付网关后端、运营平台后端。 ```{important} 🚀 **本章目标:** 让 web-pay 在你的电脑上真正跑起来,并能登录运营平台。商户、应用、支付参数和支付通道放到第 6 章集中配置。 ``` ## 5.1 web-pay 脚本速读 web-pay 的脚本都在仓库根目录的 `env-scripts/`: ```{tip} 🧰 **先认脚本,再跑服务。** 这一章不要求你手工启动每个前后端模块,主要靠下面几个脚本完成配置、启动和停止。 ``` | 脚本 | 作用 | 什么时候用 | | ------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | | `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 本地脚本入口关系](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/index-06-051-script-map.png) 本章本地联调只需要 `start-local-test-backend.sh`、`start-local-test-frontend.sh` 和 `stop.sh`。生产构建和上传脚本在后面线上部署章节再用。 ```{warning} 📌 **先不要跑生产脚本。** 本地测试阶段只关心 `start-local-test-*` 和 `stop.sh`,生产构建、上传、CI/CD 等脚本等本地支付闭环跑通后再处理。 ``` ## 5.2 执行 web-pay 配置脚本 `web-pay` 的配置脚本在仓库根目录: ```text env-scripts/rename-saas-service.sh ``` 运行前先准备好第 3 章记录的这些信息: ```{tip} 📌 **照着第 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 配置脚本写入关系](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/index-07-052-config-write.png) 在 `web-pay` 仓库根目录执行: ```bash chmod +x ./env-scripts/rename-saas-service.sh ./env-scripts/rename-saas-service.sh ``` 脚本会更新这些文件: ```text 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 ``` ```{danger} 🔐 **脚本会写入敏感配置。** 数据库密码、ActiveMQ 密码、SSH 信息只应该保存在你控制的本地环境或私有仓库中,不要把改好的配置文件公开传播。 ``` ## 5.3 启动前检查 先把 `cloudflared` 的作用讲清楚:本地 web-pay 跑在你自己的电脑上,支付网关后端地址通常是 `http://localhost:9216`。这个地址只有本机能访问,微信 / 支付宝在公网,支付成功后无法直接回调到你的 `localhost`。 ```{important} 🌐 **cloudflared 是本地支付回调的临时公网入口。** 没有它,你可以打开本地页面,但微信 / 支付宝无法从公网回调到你的电脑。 ``` `cloudflared` 解决的就是这个问题。它会给本机服务创建一个临时的公网 HTTPS 地址,并把公网请求转发到本机 `9216` 端口。这样支付平台访问的是类似 `https://xxxx.trycloudflare.com` 的公网地址,但请求最终会进入你电脑上的 web-pay 支付网关。 所以安装 `cloudflared` 的核心目的不是生产部署,而是让你在本地就能测试完整支付流程: - 本地就能获得可被微信 / 支付宝访问的公网 HTTPS 回调地址。 - 可以验证支付平台是否真的回调到 web-pay。 - 可以检查回调验签、订单状态更新、支付流水和回调日志是否正常。 - 可以继续验证 web-pay 是否把支付结果通知给 SaaS 业务后端。 - 不用等后端上线、域名解析、HTTPS 证书和 Nginx 都配置完成后,才开始排查支付问题。 也就是说,有了 `cloudflared`,本地测试就不再只能测到"打开收银台"这一步,而是可以继续测到"支付成功后回调进来、订单变成已支付、业务系统收到支付结果"这一整条闭环。 ![cloudflared 本地回调入口与启动前检查](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/index-08-053-cloudflared-check.png) ```{warning} 本章后面的 `./env-scripts/start-local-test-backend.sh` 会自动创建 web-pay 的 `cloudflared` 隧道,并把隧道地址写入运行时覆盖配置。每次启动生成的公网地址可能不同,测试支付回调时要使用脚本本次输出的最新地址。 ``` 确认第 4 章和本章配置脚本已经完成: ```{warning} ✅ **这些项都通过后再启动后端。** 少一项都可能导致后端启动失败,或者支付回调只能走到一半。 ``` - 本机 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 启动后端 在仓库根目录执行: ```bash ./env-scripts/start-local-test-backend.sh ``` 脚本会做这些事: ```{important} 🚀 **这一步会同时启动两个后端。** 第一次启动可能会慢一点,因为空库初始化和 Maven 构建都需要时间。 ``` | 动作 | 说明 | | --------------------- | ---------------------------------------- | | Maven 构建 | 构建支付网关和运营后端 | | Flyway 空库初始化 | 如果 `pay` 库为空,先由运营后端自动创建表结构和基础数据 | | 启动支付网关 | 默认 `http://localhost:9216` | | 启动运营后端 | 默认 `http://localhost:9217` | | 创建 cloudflared 隧道 | 把本机 `9216` 暴露为公网回调地址 | | 写入运行时覆盖配置 | 生成 `tmp/local-test-backend.tunnel.yml` | ![web-pay 本地后端启动流程](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/index-09-054-backend-flow.png) 启动脚本会先用 `psql` 检查 `pay` 库的 `public` schema: ```{tip} 💡 **Flyway 行为不用手工干预。** 脚本会根据数据库状态决定初始化、迁移或跳过,目的是尽量保护已有数据。 ``` - 空库:临时启用 Flyway,先启动运营后端完成初始化,再启动支付网关。 - 已经有 `flyway_schema_history`:继续执行 Flyway 校验和后续迁移。 - 已有业务表但没有 Flyway 历史:跳过 Flyway,保护旧库已有数据。 第一次空库初始化会比普通启动多花一点时间。如果脚本提示跳过 Flyway,通常说明这个库以前已经手工导入过初始化 SQL,可以继续按旧库方式运行。 ## 5.5 启动前端 另开一个终端,在仓库根目录执行: ```bash ./env-scripts/start-local-test-frontend.sh ``` 默认访问地址: ```{warning} 📌 **前端和后端端口不要混。** 浏览器直接操作主要看 `8002` 运营平台;`9216`、`9217` 是接口服务,通常不会显示页面。 ``` | 服务 | 地址 | | ------------ | ----------------------- | | 收银台前端 | `http://localhost:8080` | | 运营平台前端 | `http://localhost:8002` | | 支付网关后端 | `http://localhost:9216` | | 运营平台后端 | `http://localhost:9217` | ![web-pay 本地前端和后端端口关系](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/index-10-055-frontend-ports.png) 这 4 个地址不是都能看到前端页面: - `http://localhost:8002` 是运营平台前端,可以直接打开登录,进入后可以查看商户、应用、订单和支付配置。 - `http://localhost:8080` 是收银台前端,但它不是给你直接从根路径进入的页面。收银台必须由其他服务携带 `zhcpayToken` 生成支付链接后进入,类似 `http://localhost:8080/#/hub/{zhcpayToken}`。没有 token 直接打开根路径,看不到正常收银台画面是预期行为。 - `http://localhost:9216` 是支付网关后端接口服务,主要给收银台、SaaS 后端和支付平台回调调用,没有前端操作画面。 - `http://localhost:9217` 是运营平台后端接口服务,主要给运营平台前端调用,也没有前端操作画面。 所以本地启动后,真正可以直接进入并操作的前端页面是运营平台: ```text http://localhost:8002 ``` ```{note} 🎯 **收银台不是从首页直接打开的。** 后面 SaaS 创建订单后会生成带 `zhcpayToken` 的支付链接,那时才会进入正常收银台流程。 ``` ## 5.6 登录运营平台 浏览器打开运营平台前端: ```text http://localhost:8002 ``` 登录页出现后,使用初始化账号登录: | 字段 | 填写 | | ---- | ---- | | 账号 | `zhcpay` | | 密码 | `zhcpay666` | ![运营平台登录成功代表的基础链路](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/index-11-056-manager-login.png) ![ZHCPAY](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/PAY-01.png) 能进入运营平台首页,就说明这 3 件事已经跑通: - 运营平台前端能打开。 - 运营平台后端能响应登录请求。 - 后端已经能连接 `pay` 数据库并读取初始化账号。 ![ZHCPAY](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/PAY-02.png) ```{important} ✅ **登录成功就是本地 web-pay 基础链路通过。** 商户、应用、支付参数和通道开关下一章再配,这里先不要混在启动验收里。 ``` ```{seealso} 下一步先进入第 6 章,在运营平台创建商户、应用并整理支付身份。第 7 章再把这些值写入 `saas-starter` 并启动 SaaS 前后端。 ``` ## 5.7 常用日志和排查入口 ```{tip} 本地联调时不要只盯浏览器页面。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 本地联调日志排查入口](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/index-16-0511-log-routing.png) 常见排查顺序: 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`,重点查验签、订单号、通道配置。 ```{warning} 脚本每次启动 cloudflared 都可能得到新的公网地址。不要拿上一次终端里的 `trycloudflare.com` 地址继续测本次支付。 ``` ## 5.8 停止和重启 web-pay 本地联调结束,或者端口被占用时,在仓库根目录执行: ```bash ./env-scripts/stop.sh ``` 这个脚本会停止: - 支付网关后端 `zhcpay-payment`。 - 运营平台后端 `zhcpay-manager`。 - 收银台前端 `zhcpay-ui-cashier`。 - 运营平台前端 `zhcpay-ui-manager`。 - 本地 `9216` 对应的 cloudflared 隧道。 ![web-pay 停止和重启清理关系](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/index-17-0512-stop-restart.png) 它也会清理这些临时文件: ```text tmp/cloudflared-local-test.log tmp/local-test-public-url.env tmp/local-test-backend.tunnel.yml ``` ```{tip} 如果只是改了运营平台里的数据类配置,通常不需要重启服务;刷新页面或重新发起订单即可。只有改了本地配置文件、端口、数据库连接、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`,确认端口释放后再重新启动前后端 | ```{warning} 重启后如果 `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` 和前端日志排查本地启动问题。 ```{important} 只要可以登录运营平台,第 5 章就算完成。商户、应用、`mchNo`、`appId`、`AppSecret`、支付宝 / 微信参数和支付通道全部放到第 6 章处理。 ``` ```{seealso} 下一步进入第 6 章,先配置 `saas-starter` 调用 web-pay 所需的支付身份。第 7 章再启动 `saas-starter` 本地前端和后端。 ```