Jeepay开源聚合支付系统实战：Java工程师部署与二次开发指南

简介：一套基于Java的开源聚合支付系统Jeepay，面向需要整合微信、支付宝、云闪付等多渠道支付能力的开发者与企业。系统内置支付网关自动路由，已对接微信服务商及普通商户（V2/V3）、支付宝服务商及普通商户（RSA/RSA2）、云闪付服务商，并采用签名机制保障交易安全，适合作为电商、SaaS平台或金融机构的支付中台。资源包共387个文件，以322个Java源码为主，辅以XML配置、SQL初始化脚本、YML环境配置及Shell部署脚本，压缩包仅7.05MB，结构紧凑便于本地搭建。管理端包含运营平台与商户系统，界面简洁，前后端分离，权限基于Spring Security，订单通知通过MQ实现高可用，渠道参数配置可自动化生成。已有95人学习下载，附带的开发文档和搭建说明能大幅降低二次开发门槛，适合有Java基础并希望深入支付领域的开发者。

1. Jeepay是什么：为什么一个开源的Java支付系统值得你亲自部署一遍

一个支付系统真正吃功夫的从来不是“收钱”那一下，而是收完钱之后的账怎么算、渠道怎么切、订单怎么对。Jeepay就是这样一套用Java写成的开源聚合支付系统，它把多商户进件、多渠道聚合、统一收银台、结算分账和对账报表全部做成了可以部署的工程代码，省掉了从零攒轮子的过程。这篇按一条真实的落地路径，把Jeepay从部署到二次开发的关键步骤和参数讲清楚，适合学过Spring Boot的Java工程师、给多商户做增值服务的小团队，以及想自建支付中台的技术负责人。

2. 拆解Jeepay的技术骨架：聚合支付与四方支付的核心设计思路

2.1 聚合支付与四方支付：先搞清楚Jeepay到底做了什么

Jeepay的定位经常被人一句话说成“一个支付后台”，但这个说法太容易让人低估它的设计范围。先理清几个概念：所谓聚合支付，指的是把微信、支付宝、云闪付这些不同渠道的收款能力，封装成一套统一接口，商户不需要分别对接每一个渠道的文档，只要调一个接口就能发起一笔收款。而四方支付，是在三方支付和银行渠道之上做聚合、路由、分账、对账的技术服务方，本身不直接触碰资金，也不持有支付牌照，但承担了商户接入、渠道管理、订单匹配这些脏活累活。

Jeepay做的正是四方支付模式的项目落地。它把“聚合支付”的通用能力拆成了运营、商户、支付核心三条链路：运营侧管商户进件和费率，商户侧管应用和订单查询，支付核心管渠道调用和回调转译。这个分层不是拍脑袋设计的，它直接对应了四方支付平台在业务上的三个角色——平台运营方、入驻商户、底层渠道。理解了这个模型，后边看数据库表结构和接口设计都会顺很多。

有一点容易被忽略：四方支付系统里，资金流和信息流是分离的。用户付钱，钱直接进的是渠道侧的三方支付账户，Jeepay能做的只是记录订单状态、计算分账金额、定时对账。这意味着所有金额字段都不能用浮点型，所有状态变更都要留操作日志，渠道回调与本地订单的金额不一致时必须按差异单处理。这些约束在后边的开发中会反复出现，先把模型立住，再动手写代码，才不会越改越乱。

2.2 六大核心模块：从商户进件到资金结算的完整闭环

把Jeepay代码仓库打开，会发现它的后端工程是按业务域拆分的，大体可以分成六个核心模块，它们合起来才构成从商户进件到资金结算的完整闭环。

商户系统是入口。一个商户进来之后，平台要给他创建商户号，然后再创建应用，每个应用对应一套独立的API密钥和回调配置。真实业务里一个商户可能有好几个应用，App、小程序、H5各一个，每个应用可以单独配置允许使用哪些渠道，也可以设定不同的费率。这一步管不好，后边对账和结算全都会乱。

渠道系统是Jeepay最值得借鉴的一层设计。它把“微信下单”和“支付宝下单”这类动作，抽象成了统一的渠道接口，每个渠道自己实现下单、查单、回调解析、验签这几个方法。新增一个渠道时，核心代码改动被限制在渠道实现类里，不需要碰业务层。这其实就是策略模式在支付系统里的标准应用，但很多自研支付系统做到后面会把渠道判断散落在Service层里，改一个渠道要牵连好几个文件，Jeepay这种收敛方式值得直接抄。

支付核心是整个系统的发动机。它接收商户的下单请求，根据路由规则选中一个可用渠道，生成渠道侧的交易参数，再返回给商户端一个收银台地址。用户支付完成之后，渠道系统异步回调到Jeepay，支付核心解析回调内容、验签、更新本地订单状态，再通过商户通知接口把结果推给商户。这条链路上最怕的不是渠道挂掉，而是回调丢或重复，所以Jeepay在状态更新时做了防重和幂等，后边章节细聊。

结算和对账是四方支付里真正体现价值的部分。渠道侧的钱经过一段时间才能结算到平台账户，平台再按分账规则把钱结算给商户。这个过程需要把渠道账单、本地订单、结算记录三份数据拉到一起比，出现差异后生成差异单，人工介入处理。很多小团队做支付系统，收单功能上线很快，但结算跑批和对账脚本能拖上一个月，就是低估了这三方数据对齐的工作量。

2.3 支付流程设计：下单、渠道路由与回调通知的关键设计

一次标准支付在Jeepay里的时序可以压缩成五个步骤：

1. 商户后端调用下单接口，传入商户号、应用ID、订单号、金额、回调地址。
2. 支付核心校验参数和签名，生成支付订单，按路由规则选中渠道。
3. 返回渠道收银台地址或支付参数，商户端把用户引导到对应页面。
4. 用户在渠道侧完成支付，渠道回调Jeepay的支付结果的地址。
5. 支付核心验签后更新订单状态，调用商户回调接口通知商户。

这五步看起来简单，真正写起来每一步都有边界情况。比如第二步的路由规则，不能只看渠道开通没开通，还要看当前渠道是否在维护窗口、单笔限额是否满足、商户是否被限制使用该渠道。有些实现会把路由做成可配置的权重轮询，比如微信和支付宝各占50%流量，某个渠道连续失败就自动摘除。Jeepay里这种路由配置和渠道参数是分开存储的，做二次开发时可以直接在路由表上做文章。

第五步的回调通知是埋坑最多的地方。渠道侧回调同一个订单可能重复触发，商户回调接口可能超时或返回异常，这两件事叠加起来就会导致订单状态不一致。常见的处理方式是引入补单任务：定时扫描处于“支付中”状态且超过一定时间的订单，主动向渠道侧发起查单，根据查单结果修正本地订单状态，再触发商户通知。补单任务本身要支持手动触发，因为有些渠道查单接口也有延迟，人工触发是为了在联调阶段快速验证，不用干等定时器跑完。

在写补单逻辑时，最直接的做法是给订单状态加一个版本号字段，更新时用带条件的UPDATE语句，比如“SET status = 新状态 WHERE order_id = ? AND status = 旧状态”，这样并发回调时只有一个请求能成功更新状态，不会出现订单状态被后到的回调覆盖成旧值的情况。Jeepay这类支付系统的状态机，本质是用数据库的行锁来解决回调乱序，不要试图在Java代码里用同步锁来处理跨进程的问题。

3. 本地部署：从拉取代码到跑通一笔测试支付的完整步骤

3.1 环境准备：JDK、MySQL、Redis的版本选择

Jeepay后端是标准的Spring Boot工程，Java版本用8就够了，不需要上17之类的新版本，反而新版本JDK在运行时可能出现反射相关的兼容问题。构建工具用Maven 3.6以上，IDE用IDEA可以直接打开根目录的pom.xml，等待依赖下载完即可。先给出我实际验证过的一套组合，避免在环境上反复折腾。

MySQL的版本是最容易翻车的地方。Jeepay的初始化脚本里如果包含utf8mb4_0900_ai_ci这样的排序规则，放到MySQL 5.7上执行会直接报错。要么把脚本里的字符集和排序规则统一改成utf8mb4和utf8mb4_unicode_ci，要么直接用MySQL 8.0初始化，然后连接配置里加上characterEncoding=utf8mb4。数据库的时区也要注意，连接串里建议加上serverTimezone=Asia/Shanghai，避免Java服务本地时区和数据库时区不一致导致时间字段偏移。

Redis的作用容易被新手低估。支付订单的短暂状态、渠道访问令牌、分布式锁、延迟队列都依赖Redis，如果只把它当成缓存来用，启动时不配密码可能没事，但生产环境Redis宕机会直接影响支付链路。因为Jeepay回调和补单逻辑里大量依赖Redis的原子操作来防重，Redis不可用时订单状态就没办法可靠更新。本地部署时Redis不用开持久化，但生产环境至少开AOF，并且设置appendfsync everysec。

3.2 初始化数据库与启动服务：三个Java进程怎么配合

Jeepay的源码拉下来之后，先不要急着用IDEA点启动按钮，按顺序来。先把数据库初始化和配置改好，再逐一把服务跑起来。以下是我常用的命令序列，在项目根目录下执行。

# 拉取代码 git clone https://gitee.com/jeequan/jeepay.git cd jeepay # 初始化数据库，执行根目录下的init脚本 mysql -uroot -p < jeepay-db/init.sql # 进入支付核心工程，修改数据库和Redis配置 vim jeepay-payment-boot/src/main/resources/application.yml # 重点修改这几项： # spring.datasource.url、username、password # spring.redis.host、port、password # 打包并启动支付核心 mvn -pl jeepay-payment-boot clean package -DskipTests java -jar jeepay-payment-boot/target/jeepay-payment-boot.jar &

先启动支付核心的理由很直接：商户平台和运营平台在登录之后会有大量查询支付订单的操作，如果支付核心没起来，后端的Feign调用会报连接失败，控制台刷错误日志。三个工程的依赖关系是支付核心在最底，运营和商户平台在中间，前端页面在最上。很多人第一次跑项目时习惯一次性把所有服务全启动，结果日志混在一起看不出问题，建议逐个启动，等前一个的端口能访问了再起下一个。

支付核心的application.yml里还有一个容易被忽略的参数is_dev，开发环境下设为true会打印更多调试日志，也会跳过一些签名校验，方便本地联调。但要注意，这个参数在生产环境一定要关掉，否则回调接口会存在严重安全隐患。另外渠道的证书文件路径要确认存在，有些渠道在初始化时会加载证书，路径配错了启动都不会报错，但真正发起支付时会直接抛异常。

3.3 配置支付渠道：接入一个测试支付参数的参数说明

初始化脚本执行完之后，运营平台和商户平台里是没有任何可用渠道的。要在测试环境跑通一笔支付，需要先在运营平台里配置一个支付渠道。打开运营平台的“支付渠道”菜单，选择渠道类型，会看到一串待填写的参数。我把关键的几项列出来并说明它的实际作用。

回调地址是本地联调里第一个坎。如果用内网穿透工具把本地服务暴露出去，回调地址必须填穿透工具生成的公网HTTPS地址；如果是在服务器上部署，填真实域名并配好HTTPS证书。很多渠道要求回调地址必须是HTTPS且非局域网IP，直接用IP地址会被拒绝。首次联调时最容易遇到“支付成功但本地收不到回调”，十有八九是回调地址填错。

4. 二次开发与定制：接口签名、分账与商户系统的对接要点

4.1 接口规范：统一签名算法与应用令牌的传递方式

Jeepay给商户提供了统一的下单、退款、查单接口，这些接口共享一套签名规则。签名的作用不是为了加密，而是让服务端能够确认请求来自合法的调用方，同时防止请求参数被中途篡改。接口约定一般是这样：商户应用创建时生成一个API密钥，调用接口时把所有参数按字典序拼接，加上密钥后做MD5，得到的字符串作为sign字段传过来。

// 签名工具示例：基于TreeMap自动按key排序 public static String generateSign(Map<String, String> params, String apiKey) { TreeMap<String, String> sorted = new TreeMap<>(params); StringBuilder sb = new StringBuilder(); for (Map.Entry<String, String> entry : sorted.entrySet()) { String key = entry.getKey(); String value = entry.getValue(); // 签名参数本身不参与计算，空值也要剔除 if ("sign".equals(key) || value == null || value.isEmpty()) { continue; } sb.append(key).append("=").append(value).append("&"); } // 拼接密钥后做MD5 sb.append("key=").append(apiKey); return DigestUtils.md5Hex(sb.toString()); }

这段实现里有三个细节值得注意。TreeMap保证了参数按字典序排序，省去了手动排序的代码；过滤空值的逻辑必须写，否则渠道侧多传一个空参数就会导致签名结果不同；最后拼接的密钥不带value空串，因为apiKey是平台固定的，不需要参与排序。

登录和鉴权环节除了签名，还依赖应用令牌。商户调用接口时在请求头里带上token，token由商户应用ID和密钥动态生成。Jeepay的服务端会维护一份token到应用信息的映射，缓存到Redis里，过期后要求重新获取。做二次开发时，如果要新增一个商户自定义接口，记得先鉴权再处理业务逻辑，不要因为内部系统就跳过签名校验。

4.2 扩展一个新支付渠道：从渠道配置到回调适配的改动范围

接入一个新的支付渠道，比如某些地区的本地支付App，是Jeepay二次开发里最典型的任务。改动点可以收敛到三个地方：渠道配置表加一条渠道类型、实现一个渠道服务类、在路由规则里允许该渠道参与选择。核心的渠道服务类通常长这样：

public interface IChannelService { // 返回渠道类型标识，例如 LOCAL_PAY String getChannelId(); // 构建渠道侧下单参数并返回支付链接 PayOrderModel createOrder(PayOrderReq req); // 解析渠道回调请求，拿到原始参数 String parseCallback(HttpServletRequest request); // 校验渠道回调的签名 boolean verifyCallback(Map<String, String> params); }

实现这个接口时，createOrder是最复杂的一步。它需要把Jeepay的支付订单转换成渠道侧要求的参数格式，包括金额、商户号、回调地址、过期时间等。这里最容易踩的坑是金额单位不一致：Jeepay内部通常是分，但有些渠道接口要求元，或者反过来。转换错误会导致用户看到的价格和实际扣款不一致，这种问题在联调阶段就很难发现，需要在下单和回调两端都把金额打印出来对照。

新增渠道类型后，渠道侧的配置文件、数据字典、页面下拉选项这些都要跟着补。核心逻辑编译通过不代表功能完整，还要回到商户平台里确认这个新渠道能在创建支付订单时被路由到。一个稳妥的做法是：先走通一个新渠道的最小支付链路，再去补查单、退款、对账这些周边功能，不要一开始就追求能力一步到位。

4.3 接入商户系统的三个关键点：分账、对账与回调幂等

商户系统接入Jeepay时，最容易出问题的不是下单，而是资金相关的三个点。分账配置的粒度要到“商户应用+渠道”的层级，不同渠道的手续费率不同，分账比例自然也不同。Jeepay里分账配置通常是在运营平台上维护，商户侧只能查询，做定制时要注意权限边界，不要让商户自己把分账比例改成100%。

对账则是每天固定时间拉取渠道账单，和本地订单流水比对。差异单产生的原因一般是这三类：本地订单存在但渠道账单没有，渠道账单存在但本地订单状态不是成功，两边金额不一致。处理差异单的正确姿势不是直接改数据库，而是先跟踪渠道侧订单状态，再决定本地订单是做补单还是做退款。项目中我一般会保留所有对账差异记录至少半年，方便后续排查历史问题。

回调幂等前面提过一次，这里再强调一遍它在对接时的具体做法。商户侧接收Jeepay回调时，不能先查订单再更新，要直接用订单号加状态条件做更新，并且要保证回调处理逻辑本身可以重复执行。换句话说，商户自己的回调接口也要做幂等设计，否则Jeepay因为网络超时重发回调时，商户侧就可能把同一笔订单处理两次。

5. 部署避坑：Jeepay环境配置与支付联调的常见问题排查

5.1 部署阶段：数据库初始化失败、Redis连接异常与端口占用

现象一条接一条说。初始化数据库时执行到一半报错，日志里出现Unknown collation: utf8mb4_0900_ai_ci。原因是MySQL 8.0默认的排序规则在5.7里不存在，脚本是给8.0环境写的。解决方法是把脚本里所有utf8mb4_0900_ai_ci替换成utf8mb4_unicode_ci，或者直接换MySQL 8.0初始化，两种路都行，但要注意替换之后的脚本要在5.7和8.0上都能跑通，建议用sed批量替换后再导入。

服务启动时控制台刷Unable to connect to Redis，但本地Redis明明能连。这个现象多数不是Redis服务挂了，而是配置文件和实际运行环境不匹配。比如配置文件里写了Redis密码，但本地Redis没设置密码，连接就是会被拒绝。还有种情况是Redis只绑定了127.0.0.1，而Java服务跑在容器里，网络隔离导致连不上。解决办法是把application.yml里的Redis配置改成实际环境的值，容器部署时推荐用环境变量覆盖配置，不要把密码硬编码在代码仓库里。

端口占用问题在同时启动多个Jeepay工程时特别常见。支付核心、运营平台、商户平台默认端口不同，但8080端口经常被本地的其他服务占掉。启动报Port 8080 was already in use时，直接用lsof -i:8080查占用进程，把端口改了就行。改端口时注意不仅要改application.yml里的server.port，还要检查后台管理系统里有没有硬编码回链地址，否则登录成功之后跳转的地址还是旧端口。

5.2 联调阶段：回调接收不到、验签失败与订单状态卡住

本地联调最让人头疼的是回调链路。用户在沙箱环境支付成功，Jeepay这边订单状态却一直是等待支付，商户后台也收不到通知。先用最简单的方式验证：打开支付核心的后台日志，搜索订单号，看有没有渠道回调的记录。如果日志里根本没有回调，说明回调没有到达Jeepay；如果日志里有回调但处理失败，说明问题出在回调解析或验签。

回调到不了，绝大多数原因是回调地址配置错误。渠道侧回调时无法访问内网地址，比如http://127.0.0.1或http://192.168.x.x，需要配置成公网可访问的地址。本地开发时用内网穿透工具，服务器部署时用真实的HTTPS域名。还有少部分是渠道侧的回调地址是支付下单时动态传的，不是商户后台全局配置的，这种就检查下单参数里有没有把回调地址覆盖掉。

验签失败是第二高频问题。现象是回调到了，但日志提示验签不通过。原因往往不是密钥错了，而是签名计算时参数处理不一致。渠道回调里包含的空值字段、sign字段本身、参数名大小写，任何一处不一致都会导致验签失败。解决的唯一可靠办法是打开渠道侧的回调日志，和Jeepay接收到的原始参数逐个字段对比，写一个独立的调试接口把接收到的参数原样打印出来，眼过一遍比反复猜快得多。

订单卡住长时间不更新，可能不是回调问题而是补单任务没跑起来。有些版本的补单定时任务默认间隔较长，比如30分钟，测试时等不起。处理办法是把补单任务的时间阈值临时调短，比如改成3分钟，联调完再恢复。如果连补单任务都没有触发，检查是不是用了分布式任务调度框架但没有配置执行器，本地单机部署时这部分很容易漏配。

5.3 生产阶段：密钥泄露、订单并发与日志追踪的注意点

生产环境遇到的坑和测试环境完全是两回事。最常见的是API密钥泄露导致被刷单。Jeepay这类系统里密钥就是商户调用接口的通行证，一旦泄露，别人就可以用它下单、查单、甚至发起退款。密钥管理的基本要求是：不允许明文出现在数据库表里，存储时加密；日志打印参数时把sign和apiKey打码；定期更换密钥时保证新旧密钥有一段并行期，避免切换瞬间商户全部调用失败。

订单并发问题在生产环境会暴露得很明显。同一个订单号被渠道侧重复回调，或者商户侧因为没有做幂等，把支付中的订单重复更新成已关闭状态。Jeepay里对订单状态更新做了条件限制，但如果你在二次开发时加了自己的更新逻辑，必须加上状态条件。数据库层面用UPDATE ... WHERE status = 'pending'，返回影响行数为0就说明状态已经被其他请求修改，这时候直接返回失败，不要做任何覆盖操作。

日志追踪是生产排查的基础设施。支付系统每天几万笔订单，只靠搜订单号定位问题效率极低。最实用的做法是全链路透传一个traceId，从商户调用进来时生成，贯穿下单、回调、补单任务、对账记录，日志框架里把traceId输出到单独一个字段，方便用日志平台按traceId聚合。曾经有一次线上订单状态对不上，靠这个traceId把这笔订单在三台机器上的所有日志捞出来，十分钟就定位到了是回调重复导致的，没有这个字段的话，估计要捞一下午。

6. 进阶玩法：用Jeepay沉淀一套通用的支付中台能力

6.1 从单体到微服务：支付网关独立化的演进路径

Jeepay按业务域拆分工程，已经是微服务的雏形，但真正要支撑多条业务线时，还需要把支付能力进一步独立成平台。常见做法是把支付核心单独拆出来做成一个支付网关服务，所有业务方都通过它下单、查单、接收回调，业务侧不再直接感知底层渠道。这样做的好处是支付相关的路由规则、渠道切换、故障降级都收口在网关层，业务系统只需要关心自己的业务订单。

6.2 对账文件自动化核对：差异订单的收集与重试

对账任务跑批时，可以把差异结果输出到一个统一的差异单表，再配合可视化的后台页面人工处理。脚本触发的时机最好是渠道侧出账单之后，避开白天交易高峰。以下是一段简化版的差异核对SQL逻辑：

-- 找出本地订单成功但渠道账单缺失的记录 SELECT o.order_id, o.amount, o.pay_time FROM pay_order o LEFT JOIN channel_bill c ON o.order_id = c.order_id WHERE o.status = 'success' AND c.bill_date = #{reportDate} AND c.order_id IS NULL;

把这类查询固化到对账模块里，配合消息通知把差异单推给财务处理，比每天人工捞数高效得多。注意保留渠道账单的原始明细，因为渠道侧补传数据或者人工修复时，要能回溯是哪一笔账单出了问题。

6.3 压测、故障演练与灰度发布的落地方法

上生产之前，要至少做两轮验证。第一轮是常规压测，重点看下单接口的TPS和响应时间，方法是用压测工具模拟100个并发用户连续下单，同时观察数据库连接池和Redis的负载。第二轮是模拟渠道故障，比如把某个渠道的配置改成错误参数，看路由规则能否快速切换到其他渠道，以及回调失败后的补单任务能否在预期时间内完成状态修正。

在灰度发布策略上，支付网关的切换适合用“按商户灰度”而不是按流量百分比。挑几个测试商户先切到新网关，观察两三天的对账差异率，确认没有问题后再逐步放量。支付系统出问题的代价比普通业务系统高，回滚方案要在发布前准备好，确保切换后短时间内可以切回旧链路，否则一旦线上问题持续十几分钟，对商户的影响就是真金白银。

我吃过一次亏，当时赶着上线新渠道，压测只测了下单链路，没测回调吞吐。结果活动当天渠道侧集中回调，接收回调的线程池被打满，大量订单状态更新延迟，补单任务又因为重复触发造成数据库锁等待。后来在回调入口加了消息队列削峰，再用版本号做状态更新的乐观锁，类似的故障再没出现过。Jeepay能帮你把支付主链路搭起来，但真正让它稳定扛住业务的，是对账、限流、幂等这些细节的打磨。希望帮到你。

本文还有配套的精品资源，点击获取