四、本地环境与项目配置

这一章只处理三件事:

快速看懂 web-pay 仓库里每个目录负责什么。
让本机具备后续启动 web-pay 和 saas-starter 示例项目的基础环境。
在 RDS 中准备 web-pay 支付库和 SaaS 业务库。

重要

🧰 本章目标很简单: 先把本地电脑和数据库准备好,不要一上来就纠结业务代码。只要目录能找对、工具能跑、数据库能连,后面第 5 章启动 web-pay 就会顺很多。

4.1 项目目录速读

进入你自己的 web-pay 仓库根目录:

cd /你的/web-pay/仓库路径

小技巧

🎯 先建立地图感。 这一节不是让你背代码结构,而是让你知道“出问题时应该去哪个目录看”。

教程默认仓库结构如下:

web-pay/
  env-scripts/                    # web-pay 的本地启动、生产构建、上传和配置脚本
  zhcpay-ui/
    zhcpay-ui-cashier/            # 统一收银台前端
    zhcpay-ui-manager/            # 运营平台前端
  zhcpay/
    zhcpay-payment/               # 支付网关后端
    zhcpay-manager/               # 运营平台后端
    zhcpay-service/               # 业务数据访问和通用服务
    zhcpay-core/                  # 核心实体、工具和通用模型
    zhcpay-components/            # OSS、MQ 等组件
    zhcpay-sdk-java/              # Java SDK
    docs/sql/                     # web-pay 数据库 SQL 资料
  saas-starter/
    env-scripts/                  # SaaS 示例项目的配置、启动、构建脚本
    backend/                      # SaaS 后端
    frontend/                     # SaaS 前端
    logs/                         # SaaS 本地运行日志

你先记住这 4 个入口就够了:

入口	你需要知道的事
`env-scripts/`	操作 `web-pay` 的脚本都在这里。
`zhcpay-ui/`	两个 web-pay 前端:收银台和运营平台。
`zhcpay/`	两个 web-pay 后端和共享 Java 模块。
`saas-starter/`	本教程默认的业务 SaaS 示例项目。

备注

📌 第一次阅读只记入口,不用展开源码。 真正动手时,你大多数操作都会从脚本入口开始,很少需要手工钻到每个 Java 模块里改配置。

本地联调时一共有 6 个服务:

服务	路径	默认端口	作用
收银台前端	`zhcpay-ui/zhcpay-ui-cashier`	`8080`	用户付款时打开的页面
运营平台前端	`zhcpay-ui/zhcpay-ui-manager`	`8002`	你管理商户、应用、订单、支付通道的页面
支付网关后端	`zhcpay/zhcpay-payment`	`9216`	SaaS 下单、支付平台回调都会打到这里
运营平台后端	`zhcpay/zhcpay-manager`	`9217`	运营平台前端调用的后台 API
SaaS 前端	`saas-starter/frontend`	`5173`	业务用户看到的 SaaS 页面
SaaS 后端	`saas-starter/backend`	`9220`	创建业务订单、调用 web-pay、接收支付结果

web-pay 本地目录与服务端口关系

本地调用关系可以先理解成:

SaaS 前端 :5173
  -> SaaS 后端 :9220
  -> web-pay 支付网关 :9216
  -> web-pay 收银台前端 :8080

web-pay 运营平台前端 :8002
  -> web-pay 运营平台后端 :9217

小技巧

💡 排查时按端口找服务。 页面打不开先看前端端口,接口报错再看后端端口,支付回调问题优先看 9216 支付网关。

后面排查问题时,先看请求卡在哪个端口,再回到上面的表找对应目录。

4.2 本地环境清单

本项目本地联调需要下面这些环境。这里不展开解释每个工具是什么,只列出后续脚本和服务会用到的清单。

备注

🧪 这一节的目的不是安装教学,而是确认“本机能不能跑”。 如果缺工具,可以先交给本地 AI 或包管理器安装,最后按检查命令验收即可。

类别	需要具备
基础命令行	Bash 或兼容 Shell、`awk`、`sed`、`grep`、`find`、`perl`、`chmod`、`mktemp`、`pkill`、`nohup`
代码与构建	Git、Node.js、npm、JDK 17、Maven
远程与网络	OpenSSH、`scp`、`curl`、`nc`、`lsof`
本地回调	`cloudflared`
数据库客户端	PostgreSQL 客户端 `psql`
本地依赖服务	Redis、ActiveMQ
可选文档环境	Python 3、venv、pip;只在你要本机构建本教程文档时需要

建议版本:

环境	建议
JDK	17
Node.js	20 LTS 优先,18 LTS 也可以
npm	跟随 Node.js 安装
Maven	3.8+
PostgreSQL 客户端	能连接你第 3 章准备的 RDS
Redis	本机 `127.0.0.1:6379` 可访问
ActiveMQ	本机 `127.0.0.1:61616` 可访问

本地联调环境清单

复制给本地 AI 的安装提示词

如果你不想自己逐个安装工具,可以把下面这段提示词直接发送给你电脑上的本地 AI。让它先检查环境,再按你的系统安装缺失项。

警告

🔐 复制提示词前先确认: 下面这段不会要求 AI 读取或输出数据库密码、SSH 密码、支付密钥等敏感信息。安装工具和检查版本不需要这些资料。

你是我的本地开发环境安装助手。我要在这台电脑上运行 web-pay 和 saas-starter 本地联调项目。

项目根目录: <把我的 web-pay 仓库绝对路径填在这里>

请你完成以下任务:

1. 先识别当前操作系统、CPU 架构、默认 Shell、包管理器和当前用户权限。
2. 检查下面这些环境是否已安装并可用:
   - Bash 或兼容 Shell
   - awk、sed、grep、find、perl、chmod、mktemp、pkill、nohup
   - Git
   - Node.js 20 LTS 或 18 LTS
   - npm
   - JDK 17,并确保 java 和 JAVA_HOME 指向 JDK 17
   - Maven 3.8+
   - OpenSSH 和 scp
   - curl、nc、lsof
   - cloudflared
   - PostgreSQL 客户端 psql
   - Redis 服务和 redis-cli,本机 127.0.0.1:6379 可访问
   - ActiveMQ 服务,OpenWire 端口 127.0.0.1:61616 可访问
   - 可选:Python 3、venv、pip,用于构建 docs 文档
3. 对缺失项制定安装方案:
   - macOS 优先使用 Homebrew。
   - Windows 优先使用 WSL2 或 Git Bash 环境;需要说明我后续应在哪个终端里运行项目脚本。
   - Linux 按当前发行版使用 apt、dnf、yum、pacman 或官方安装方式。
4. 安装或修复缺失项。安装前请告诉我将执行哪些命令,不要修改项目源码文件。
5. Redis 安装后请启动本机服务,并确认 redis-cli ping 输出 PONG。
6. ActiveMQ 本机安装,最终必须让 127.0.0.1:61616 可访问;用户名和密码要与项目 application-local.yml 保持一致,默认按 system / manager 检查。
7. 不要读取、打印、上传或保存我的数据库密码、SSH 密码、支付密钥、AppSecret 等敏感信息。
8. 完成后输出一张检查表,逐项给出命令、输出摘要、是否通过、失败时的修复建议。

最后请运行这些检查命令:

git --version
node -v
npm -v
java -version
mvn -v
ssh -V
command -v scp
curl --version
nc -h 或 nc -z 127.0.0.1 61616
lsof -v
cloudflared --version
psql --version
redis-cli ping

安装后自己再检查一遍

本地 AI 安装完成后,你自己也在终端运行一次:

git --version
node -v
npm -v
java -version
mvn -v
ssh -V
command -v scp
curl --version
cloudflared --version
psql --version
redis-cli ping
nc -z 127.0.0.1 61616

重点看下面几项:

检查	通过标准
`java -version`	输出里能看到 17
`mvn -v`	能看到 Maven 版本,并且 Java 版本是 17
`redis-cli ping`	输出 `PONG`
`nc -z 127.0.0.1 61616`	命令退出码为 0,说明 ActiveMQ 端口可连
`cloudflared --version`	能正常输出版本
`psql --version`	能正常输出版本

重要

✅ 这些检查都通过后,本机环境就算准备好了。 后面启动失败时,就可以把注意力放到配置、端口和数据库连接上,不用反复怀疑工具没装好。

4.3 在 RDS 中新建两个数据库

本地联调仍然使用第 3 章准备好的华为云 PostgreSQL RDS。本章只要求你在同一个 RDS 实例中准备两个数据库:

重要

🎯 这里要准备的是两个库,不是两个 RDS 实例。 一个 RDS PostgreSQL 实例里放 pay 和 SaaS 业务库即可,成本更低,也更方便本地联调。

数据库	建议名称	用途
web-pay 支付库	`pay`	存放 web-pay 商户、应用、订单、支付通道等数据，即第三章配置的pay数据库
SaaS 业务库	跟随你的 SaaS 服务名,例如 `saas_starter`	存放业务用户、业务订单、订阅等数据

警告

📌 两个库的职责不要混。 pay 归 web-pay 使用,保存支付平台自己的数据;SaaS 业务库归你的业务系统使用,保存业务用户、套餐、订单等数据。

pay 库只需要先创建出来,新用户不需要手工导入 web-pay 初始化 SQL。第 5 章启动本地后端时,脚本会检测空库并通过 Flyway 自动建表和写入基础数据。SaaS 业务库仍按第 7 章的要求处理。

SaaS 业务库名要和后面 saas-starter/env-scripts/rename-saas-service.sh 里填写的「数据库名」一致。脚本默认规则是:

服务名: saas-starter
默认数据库名称: saas_starter

如果你还不准备改名,可以先使用模板默认库名:

saas_starter

RDS 双数据库准备关系

在华为云 RDS / DAS 中创建数据库

进入华为云 RDS 控制台:

打开 云数据库 RDS。
进入第 3 章创建好的 PostgreSQL 实例。
点击登录或进入 DAS 数据库管理页面。
使用 RDS 实例管理员账号登录,数据库名称通常先填 postgres。
在数据库列表里点击 新建数据库。
新建 pay（第三章已经完成新建,可保持空库）
再新建你的 SaaS 业务库,例如 saas_starter。

重要

✅ 完成标志: RDS 里能看到 pay 和你的 SaaS 业务库,并且本机 psql 可以通过 RDS 公网地址连上它们。

数据库配置

4.4 配置关系总览

先把一句话讲清楚:前端看 .env 文件,后端看 Spring 配置文件。

重要

🎯 这句话后面会反复用到。 页面里能看到的 API 地址通常来自前端 .env;数据库、Redis、ActiveMQ、支付密钥这类后端私有信息来自 Spring 配置。

.env 是前端工程的环境变量文件。它通常放在各自前端目录下,例如收银台的 zhcpay-ui/zhcpay-ui-cashier/.env.development、运营平台的 zhcpay-ui/zhcpay-ui-manager/.env.development、SaaS 前端的 saas-starter/frontend/.env.development。前端构建或本地启动时,Vite、Vue CLI、UniApp 会读取这些变量,把 API 地址、页面标题、部署基础路径等写进前端运行时配置。注意:前端配置最终会被浏览器看到,所以这里不要放数据库密码、AppSecret、证书私钥这类敏感信息。

危险

🔐 前端配置不是保密位置。 只要最终会进浏览器,就不要放数据库密码、AppSecret、证书私钥、支付密钥或 SSH 密码。

Spring 配置文件是后端工程的配置文件,通常放在 src/main/resources/ 下面,例如 application-local.yml 和 application.yml。后端启动时,Spring Boot 会读取这些文件,决定服务端口、数据库连接、Redis、ActiveMQ、web-pay 对外地址、SaaS 通知地址、支付应用身份等信息。后端配置可以引用环境变量,也可以在本地用启动脚本生成的覆盖文件临时补充。

为什么本地环境和线上环境要分开?因为它们访问的对象不一样:

对比项	本地联调	线上部署
运行位置	你的电脑	云服务器、OBS/CDN、Nginx 等线上环境
前端访问后端	访问 `localhost` 端口,例如 `9216`、`9217`、`9220`	访问正式域名,例如 `pay-api`、`paymanager-api`、SaaS API
后端访问数据库	通常用 RDS 公网地址,方便你电脑直连	通常用 RDS 内网地址,更稳定也更安全
回调和通知	通过 cloudflared 把本机临时暴露成公网地址	通过正式域名和线上 Nginx 转发
配置目标	方便调试、热更新、看日志	面向真实用户、正式支付和长期运行

所以同一个系统会有两套配置:本地配置用于“我在电脑上跑起来”,线上配置用于“服务部署到云上给用户访问”。本地配置应该尽量指向 localhost 和 RDS 公网地址;线上配置应该尽量指向正式域名、RDS 内网地址和生产环境变量。

本地与线上配置关系总览

对应关系可以这样看:

场景	前端读取	后端读取
本地联调	`.env.development`	`application-local.yml` 和启动脚本生成的覆盖配置
线上部署	`.env`	`application.yml` 或生产环境变量

小技巧

📌 后面脚本会替你写配置。 你现在只需要理解哪些信息属于前端、哪些信息属于后端,真正填写时尽量交给脚本批量处理。

本地前端配置负责把浏览器请求打到本机后端:

前端	本地文件	关键配置	指向
web-pay 收银台	`zhcpay-ui/zhcpay-ui-cashier/.env.development`	`VUE_APP_API_BASE_URL`	`http://localhost:9216`
web-pay 运营平台	`zhcpay-ui/zhcpay-ui-manager/.env.development`	`VITE_API_BASE_URL`	`http://localhost:9217`
SaaS 前端	`saas-starter/frontend/.env.development`	`VITE_API_BASE_URL`	`http://localhost:9220/api/v1`

线上前端配置负责把线上页面请求打到线上 API:

前端	线上文件	关键配置	指向
web-pay 收银台	`zhcpay-ui/zhcpay-ui-cashier/.env`	`VUE_APP_API_BASE_URL`	线上 `pay-api` 域名
web-pay 运营平台	`zhcpay-ui/zhcpay-ui-manager/.env`	`VITE_API_BASE_URL`	线上 `paymanager-api` 域名
SaaS 前端	`saas-starter/frontend/.env`	`VITE_API_BASE_URL`	线上 SaaS API 域名 `/api/v1`

本地后端配置负责让本机服务接上对应的数据库、缓存和支付入口:

后端	本地文件	重点关系
web-pay 支付网关	`zhcpay/zhcpay-payment/src/main/resources/application-local.yml`	连接 RDS 公网 `pay` 库、本机 Redis、本机 ActiveMQ;启动脚本可把 `web-pay.public-base-url` 覆盖成 cloudflared 公网地址
web-pay 运营后端	`zhcpay/zhcpay-manager/src/main/resources/application-local.yml`	连接 RDS 公网 `pay` 库、本机 Redis、本机 ActiveMQ;运营平台前端本地调用 `9217`
SaaS 后端	`saas-starter/backend/src/main/resources/application-local.yml`	连接 SaaS 业务库;本地支付验收时 `zhcpay.api-base-url` 指向线上 `pay-api`;`zhcpay.cashier-base-url` 指向线上收银台

线上后端配置负责让云服务器上的服务互相找到:

后端	线上文件	重点关系
web-pay 支付网关	`zhcpay/zhcpay-payment/src/main/resources/application.yml`	连接 RDS 内网 `pay` 库;`web-pay.public-base-url` 是线上 `pay-api`;`cashier-public-base-url` 是线上收银台
web-pay 运营后端	`zhcpay/zhcpay-manager/src/main/resources/application.yml`	连接 RDS 内网 `pay` 库;运营后台对外地址是线上 `paymanager-api`
SaaS 后端	`saas-starter/backend/src/main/resources/application.yml`	通过生产环境变量或私有配置连接生产库;调用线上 `pay-api`;跳转线上收银台;`notify-url` 是 SaaS API 的支付通知地址

一句话理解:本地前端只找本地后端;本地 SaaS 做支付验收时,后端直接调用第 8 章上线后的 web-pay;线上前端只找线上 API,线上 SaaS 后端也继续调用线上 web-pay。

这里看起来文件很多,但不用担心你要挨个去查、挨个手改。后面用到的 rename-saas-service.sh 脚本,作用就是把你在第 3 章准备好的域名、数据库、端口、SSH、支付应用信息快速写到对应位置。你只需要理解这些配置大概分工,真正填写参数时交给脚本批量处理。

4.5 本章检查清单

继续第 5 章前确认:

警告

✅ 不要跳过这张清单。 第 5 章会直接启动多个前后端服务,如果这里有一项没准备好,后面错误信息会变得很绕。

进入第 5 章前的本章检查

能进入自己的 web-pay 仓库根目录。
已经看懂 env-scripts/、zhcpay-ui/、zhcpay/、saas-starter/、docs/ 分别负责什么。
Git、Node.js、npm、JDK 17、Maven、OpenSSH、cloudflared、psql 都能输出版本。
本机 Redis 127.0.0.1:6379 可用,redis-cli ping 输出 PONG。
本机 ActiveMQ 127.0.0.1:61616 可用。
华为云 RDS 同一 PostgreSQL 实例中已经有 pay 和 SaaS 业务库,其中 pay 新库可保持空库。
本机能用 psql 连接 RDS 公网地址上的两个数据库。
已准备好第 3 章记录的域名、RDS、ActiveMQ 和 SSH 信息,下一章会写入 web-pay 配置。
已决定 SaaS 业务库名称;如果后续要改名 SaaS,第 7 章脚本输入要和这个库名一致。