Jeepay开源聚合支付系统部署与通道配置实战指南

简介：这是一套全开源的Java聚合支付系统Jeepay，面向中高级Java开发者与支付平台架构师，解决多渠道统一接入、安全路由与高并发支付场景下的系统搭建难题。资源包含387个文件，主体为322个Java业务与配置类、28个XML配置及7个YML环境配置文件，辅以SQL建表脚本、FTL模板页和Shell部署脚本，整体压缩包仅6.8MB，轻量易部署。已有816人学习下载，适合二次开发、教学演示或中小型企业快速构建自有支付中台。读者可直接获取完整前后端分离架构源码，涵盖微信/支付宝/云闪付全渠道V2/V3、RSA/RSA2签名实现，以及基于Spring Security的权限体系、RocketMQ订单通知机制、自动化参数配置界面等生产级能力，代码结构清晰，模块职责分明，便于理解支付网关设计逻辑与分布式安全实践。

1. Jeepay 是什么：一个能跑通、能改、能上线的全开源 Java 聚合支付系统，不是 Demo，也不是玩具

Jeepay 这个名字在 Java 支付开发圈里，已经不是“听说有这么个东西”，而是“上线前我先拉下来跑一遍再决定要不要自己重写”的真实存在。它不是 Spring Boot + MyBatis-Plus 的教学示例，也不是只支持微信扫码的单通道玩具——它原生支持微信（JSAPI/APP/NATIVE/小程序）、支付宝（当面付/手机网站/APP/小程序）、云闪付、银联商务、PayPal（社区扩展）、连连支付、宝付等十余家主流通道，并通过「通道抽象层 + 策略路由 + 异步回调分发」实现真正的四方支付架构：商户 → Jeepay 系统 → 第三方支付通道 → 银行/清算机构。你不需要对接 10 家 SDK，只需配置 JSON 或数据库字段，就能把一笔订单自动路由到成本最低、成功率最高的通道；失败时自动降级、重试、补偿；所有交易状态变更都走幂等事件总线，避免“支付成功但未记账”这类线上事故。它面向的是中小支付服务商、SaaS 平台、自营电商中台——需要快速具备多通道收单能力，又不愿被商业支付 SaaS 锁死、不接受按笔抽佣、必须掌控资金流与数据主权的团队。如果你正在评估自建支付中台，Jeepay 不是唯一选项，但它是目前 GitHub 上唯一一个代码可读、结构清晰、数据库设计合理、无硬编码通道逻辑、且生产环境有真实案例验证的 Java 开源聚合支付系统。

2. 从 ZIP 解压到后台可登录：Jeepay 的最小可运行部署路径（含 MySQL 初始化与 Nginx 反向代理）

Jeepay 的官方发布包jeepay-aggregation-pay-system.zip是一个典型的 Spring Boot 多模块 Maven 工程压缩包，解压后目录结构清晰：jeepay-admin（管理后台）、jeepay-merchant（商户门户）、jeepay-gateway（网关服务）、jeepay-core（核心业务逻辑）、jeepay-common（通用工具）。它不依赖 Docker Compose 编排或 Kubernetes 部署脚本，但正因如此，新手容易卡在“解压完不知道下一步该动哪个文件”。下面这条路径是我在线上灰度环境反复验证过的最小闭环流程——不跳过任何一步，不假设你已装好 JDK 17 或 MySQL 8.0。

2.1 环境准备：JDK 17 + MySQL 8.0.33 + Redis 7.0（三者缺一不可）

Jeepay 自 v2.5.0 起强制要求 JDK 17（因使用了sealed class和switch pattern matching），MySQL 必须为 8.0+（依赖JSON类型字段存储通道配置和回调日志），Redis 用于分布式锁、缓存商户密钥、限流计数。不要用 OpenJDK 17 替代 Oracle JDK 17（部分国产信创环境需 Oracle JDK 的 JCE 加密策略）；MySQL 字符集必须设为utf8mb4，排序规则为utf8mb4_0900_as_cs（注意：不是_ci，大小写敏感对 API 签名验签至关重要）。

提示：application-prod.yml中spring.redis.database: 0是默认值，但 Jeepay 实际使用了database: 1存商户配置、database: 2存支付订单缓存、database: 3存风控规则。若你复用已有 Redis 实例，请提前清空对应 DB 或修改配置。

2.2 数据库初始化：执行jeepay.sql前必须手动处理的 3 处 DDL 陷阱

Jeepay 发布包根目录下的jeepay.sql是完整建库脚本，但它不是“双击运行就能用”的傻瓜式 SQL。我见过太多人直接mysql -u root -p < jeepay.sql导致后续启动报Unknown column 'pay_order_id' in 'field list'。问题出在三处隐性依赖：

1. sys_user表的user_type字段类型是TINYINT UNSIGNED，但 MySQL 8.0 默认 strict mode 下不允许INSERT INTO sys_user (...) VALUES (..., -1, ...)—— Jeepay 初始化脚本中插入超级管理员时用了-1表示系统用户，必须在执行前关闭 strict mode：

   SET GLOBAL sql_mode=(SELECT REPLACE(@@sql_mode,'STRICT_TRANS_TABLES','')); SET GLOBAL sql_mode=(SELECT REPLACE(@@sql_mode,'STRICT_ALL_TABLES',''));

2. pay_order表的notify_url字段定义为VARCHAR(512)，但部分 MySQL 8.0.33 安装包默认innodb_large_prefix=OFF，导致建表失败。需在my.cnf中显式开启：

   [mysqld] innodb_large_prefix=ON innodb_file_format=Barracuda innodb_file_per_table=ON

3. channel_info表的ext_config字段是JSON类型，但某些低版本 MySQL 客户端（如 Navicat 16）导出时会转成TEXT，再导入就丢失 JSON 校验。务必用mysql --default-character-set=utf8mb4 -u root -p < jeepay.sql命令行执行，而非 GUI 工具。

执行成功后，检查sys_user表中username='admin'的记录是否存在，password字段应为 BCrypt 加密后的字符串（如$2a$10$...），不是明文。若为明文，说明jeepay.sql中的INSERT语句未触发UserServiceImpl.initAdmin()的密码加密逻辑——此时需手动更新：

UPDATE sys_user SET password='$2a$10$XkVZQzYbGvLmNcPqRtSvUwXyZaBcDfEgHiJkLmNoPqRsTuVwXyZaBcDfEg' WHERE username='admin';

（该哈希值对应密码jeepay123，来自 Jeepay 源码UserServiceImpl.java的硬编码）

2.3 启动网关服务：jeepay-gateway模块的 JVM 参数与 profile 切换关键点

jeepay-gateway是整个系统的流量入口，它不提供 Web 页面，只暴露/api/**接口。启动前必须确认：

• application-prod.yml中spring.profiles.active: prod已启用；
• server.port: 8080未被占用（若改端口，jeepay-admin的vue.config.js中proxy配置也需同步改）；
• jeepay-gateway的pom.xml中<artifactId>spring-boot-starter-web</artifactId>版本与jeepay-core一致（常见翻车点：gateway用 3.1.0，core用 3.0.5，导致@Validated注解找不到）。

启动命令（Linux/macOS）：

cd jeepay-gateway mvn clean package -Dmaven.test.skip=true java -server -Xms512m -Xmx1024m -XX:+UseG1GC -XX:MaxGCPauseMillis=200 \ -Dfile.encoding=UTF-8 \ -Dspring.profiles.active=prod \ -jar target/jeepay-gateway-2.5.0.jar

注意：-Xms512m是底线，低于此值会导致RedisConnectionException: Unable to connect to Redis—— Jeepay 在启动时会预热 Redis 连接池并加载全部通道配置，内存不足时连接池初始化失败，但日志只打印Failed to bind properties under 'spring.redis'，极易误判为配置错误。

启动成功标志：控制台输出Started JeepayGatewayApplication in X.XXX seconds，且curl http://localhost:8080/api/v1/pay/order/create返回{"code":401,"msg":"Token is empty"}（说明网关已就绪，只是未带 token）。

2.4 Nginx 反向代理配置：让jeepay-admin前端能正确调用jeepay-gateway接口

Jeepay 前端jeepay-admin是 Vue 3 + Element Plus 构建的 SPA，它通过axios请求http://localhost:8080/api/**，但浏览器同源策略会拦截。不能靠vue.config.js的devServer.proxy解决生产环境问题——必须用 Nginx 做反向代理。以下是最简可用配置（/etc/nginx/conf.d/jeepay.conf）：

upstream jeepay_gateway { server 127.0.0.1:8080; } server { listen 80; server_name pay.yourdomain.com; # 管理后台静态资源 location / { alias /opt/jeepay/jeepay-admin/dist/; try_files $uri $uri/ /index.html; } # API 代理 location /api/ { proxy_pass http://jeepay_gateway/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; # 关键：透传原始请求头，Jeepay 签名验签依赖 X-Jeepay-Nonce 等头 proxy_pass_request_headers on; } # WebSocket 代理（用于实时订单通知） location /ws/ { proxy_pass http://jeepay_gateway/; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; } }

注意：proxy_pass_request_headers on;不可省略。Jeepay 的SignUtil.verify()方法会读取X-Jeepay-Nonce、X-Jeepay-Timestamp、X-Jeepay-Signature三个请求头做 HMAC-SHA256 签名验证。若 Nginx 默认过滤了自定义头，所有 API 请求都会返回401 Unauthorized，且日志无明确提示。

配置完成后nginx -t && nginx -s reload，访问http://pay.yourdomain.com即可看到 Jeepay 登录页。初始账号admin/jeepay123。

3. 四方支付的核心落地：如何配置微信/支付宝通道并完成一笔真实支付（含回调验签与状态同步）

Jeepay 的“聚合”价值，不在界面有多炫，而在能否把微信 JSAPI 支付、支付宝手机网站支付、云闪付 APP 支付这三类完全不同的接入协议，统一成一套商户调用接口。本节不讲理论，只拆解从“填入微信商户号”到“用户扫码付款后订单变 SUCCESS”的完整链路，每一步都对应代码中的真实函数调用。

3.1 通道配置本质：channel_info表的ext_configJSON 字段如何决定支付行为

Jeepay 不用 XML 或 properties 文件管理通道参数，所有配置存于数据库channel_info表。以微信 JSAPI 为例，ext_config字段内容如下：

{ "mchId": "165XXXXXXX", "appId": "wx1234567890abcdef", "apiKey": "your_api_key_here", "certPath": "/opt/jeepay/certs/wechat/apiclient_cert.pem", "keyPath": "/opt/jeepay/certs/wechat/apiclient_key.pem", "mchKey": "your_mch_key_here" }

注意三点：

• certPath和keyPath必须是绝对路径，且jeepay-gateway进程用户（如jeepay）对该路径有r权限；
• mchKey是微信商户平台「APIv3 密钥」，不是 APIv2 的apiKey（v2 的apiKey已废弃，但 Jeepay 仍兼容，需在channel_info.channel_code字段设为WX_JSAPI_V2）；
• ext_config是JSON类型，若你用 Navicat 手动编辑，务必点击「格式化 JSON」按钮，否则JSON_VALID(ext_config)=0导致通道加载失败。

支付宝通道同理，ext_config中app_id、private_key、alipay_public_key必须与支付宝开放平台「应用公钥」配对。Jeepay 使用AlipaySignature.rsaCheckV1()验签，若alipay_public_key是 PKCS#8 格式（以-----BEGIN PUBLIC KEY-----开头），需转换为 PKCS#1（-----BEGIN RSA PUBLIC KEY-----）——这是支付宝 SDK 的硬性要求，Jeepay 未做自动转换。

3.2 发起支付：/api/v1/pay/order/create接口的必填字段与签名生成逻辑

商户调用 Jeepay 创建支付订单，HTTP POST 请求体为：

{ "mchNo": "MCH_20240501001", "subject": "测试商品", "body": "商品描述", "amount": 100, "currency": "CNY", "channelCode": "WX_JSAPI", "clientIp": "127.0.0.1", "notifyUrl": "https://yourdomain.com/callback/wx", "returnUrl": "https://yourdomain.com/success", "param": { "openId": "oAbcDefGhIjKlMnOpQrStUvWxYz" } }

关键点：

• mchNo必须在mch_info表中存在，且state=0（启用）；
• channelCode必须与channel_info.channel_code匹配，Jeepay 内部通过ChannelContext.getStrategy(channelCode)获取对应支付策略；
• param.openId是微信用户在公众号内的唯一标识，不是 unionId，且必须通过jsapi_ticket+nonceStr+timestamp+url四元组在前端 JS SDK 中获取，Jeepay 不提供getOpenId接口；
• notifyUrl必须是公网可访问地址，且 Jeepay 会对其做HEAD请求校验连通性，失败则创建订单返回{"code":400,"msg":"Notify URL unreachable"}。

签名由商户端生成，算法为HMAC-SHA256，密钥为mch_info.api_key，待签名字符串为mchNo=xxx&subject=xxx&...&signType=HMAC-SHA256（字段按字典序拼接，不含sign字段）。Jeepay 源码中SignUtil.generateSign()方法可直接复用。

3.3 回调验签与状态同步：为什么你的notifyUrl总是 400？真相在这里

Jeepay 对微信/支付宝回调的处理流程是：接收请求 → 解析原始 body（非 form-data）→ 提取sign字段 → 用mch_info.api_key重新计算签名 → 比对 → 成功则更新pay_order.state为SUCCESS，失败则记录notify_log并返回success字符串（微信要求）。

常见 400 错误原因：

• 微信回调 body 是application/xml，但 Nginx 默认不透传Content-Type，导致 Jeepay 用@RequestBody String xml接收时乱码。解决方案：在 Nginxlocation /callback/wx块中添加proxy_set_header Content-Type application/xml;；
• 支付宝回调的charset=utf-8参数被 Tomcat 丢弃，request.getParameter("sign")返回 null。解决方案：在application-prod.yml中添加server.tomcat.relaxed-query-chars=/，允许/出现在 query string 中；
• notifyUrl域名未备案或 HTTPS 证书不被微信信任（微信回调只支持https且证书必须由权威 CA 签发，Let's Encrypt 有效）。

验签通过后，Jeepay 会触发PayOrderService.notifySuccess()，该方法内含事务边界：先更新pay_order状态，再发 MQ 消息通知商户系统，最后调用NotifyService.sendNotify()向商户notifyUrl发送 JSON 回调。若商户回调超时（默认 5 秒），Jeepay 会重试 3 次，间隔 10/30/60 秒，重试日志存于notify_log表。

4. 避坑指南：Jeepay 生产环境踩过的 5 个血泪坑（附定位命令与修复代码）

Jeepay 的文档和 Wiki 对新手不够友好，很多问题不会报错，只会静默失败。以下是我在三家客户现场部署时，花 2 小时以上才定位的真实问题，每一条都附带curl或grep命令，可直接复现。

4.1 现象：支付订单创建成功，但微信扫码后一直显示「支付失败，请稍后再试」，pay_order表state=0（待支付）始终不变

原因：微信回调地址被微信服务器拒绝，但 Jeepay 日志只记录WARN NotifyService - notify failed, mchNo: MCH_XXX，未打印 HTTP 响应体。根本原因是微信回调时携带X-WX-Nononce头，而 Jeepay 的NotifyController未将其加入签名验签白名单，导致验签失败后直接返回401，微信认为回调失败。
解决：修改jeepay-gateway/src/main/java/org/jeepay/core/controller/NotifyController.java，在@PostMapping("/wx/notify")方法中，将request.getHeader("X-WX-Nonce")加入待签名参数 Map：

// 原代码 Map<String, String> params = new HashMap<>(); params.put("mchNo", mchNo); // 新增一行 params.put("X-WX-Nonce", request.getHeader("X-WX-Nonce"));

然后重新编译jeepay-gateway模块。

4.2 现象：支付宝手机网站支付返回{"code":400,"msg":"Invalid sign"}，但用支付宝沙箱验签工具验证签名正确

原因：支付宝回调参数中sign_type=RSA2，但 Jeepay 的AlipayNotifyService.verify()方法硬编码为RSA，导致AlipaySignature.rsaCheckV1(params, sign, alipayPublicKey, "UTF-8")返回 false。
解决：在AlipayNotifyService.java的verify()方法中，根据params.get("sign_type")动态选择验签方法：

String signType = params.get("sign_type"); if ("RSA2".equals(signType)) { return AlipaySignature.rsaCheckV1(params, sign, alipayPublicKey, "UTF-8", "RSA2"); } else { return AlipaySignature.rsaCheckV1(params, sign, alipayPublicKey, "UTF-8", "RSA"); }

4.3 现象：jeepay-admin登录后点击「通道管理」页面空白，F12 查看 Network 发现/api/v1/channel/list返回500

原因：channel_info.ext_config中某个通道的 JSON 格式错误（如多了一个逗号），Jackson反序列化失败，抛出JsonMappingException，但全局异常处理器未捕获IOException子类。
解决：在jeepay-gateway/src/main/java/org/jeepay/core/exception/GlobalExceptionHandler.java中，增加对com.fasterxml.jackson.databind.JsonMappingException的捕获：

@ExceptionHandler(JsonMappingException.class) public ResponseEntity<ErrorResponse> handleJsonMappingException(JsonMappingException e, HttpServletRequest request) { log.error("JsonMappingException: {}", e.getMessage(), e); return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR) .body(new ErrorResponse("500", "Channel config JSON invalid: " + e.getMessage())); }

4.4 现象：jeepay-gateway启动后 CPU 占用 90%+，jstack发现大量redis.clients.jedis.JedisFactory.makeObject()线程阻塞

原因：Redis 连接池配置不合理。application-prod.yml中spring.redis.jedis.pool.max-active: 8过小，而 Jeepay 默认每通道初始化 2 个 Jedis 实例（主+备），10 个通道即需 20 连接，连接池耗尽后线程无限等待。
解决：将max-active改为64，max-wait改为3000（毫秒）：

spring: redis: jedis: pool: max-active: 64 max-wait: 3000 max-idle: 32 min-idle: 4

4.5 现象：商户调用/api/v1/pay/order/query查询订单，返回{"code":0,"data":{"state":"SUCCESS","amount":100}}，但pay_order表中state=0

原因：PayOrderService.queryByMchOrderNo()方法中，查询条件AND state IN (0,1,2)包含0（待支付），但state=0的订单也可能被人工改为SUCCESS（如线下补单），导致缓存穿透。Jeepay 的@Cacheable注解未设置unless条件，state=0订单也被缓存。
解决：修改PayOrderService.java的queryByMchOrderNo()方法，添加缓存条件：

@Cacheable(value = "payOrder", key = "#mchNo + ':' + #mchOrderNo", unless = "#result == null || #result.state == 0") public PayOrder queryByMchOrderNo(String mchNo, String mchOrderNo) { // ... }

5. 进阶实战：用 Jeepay 实现「通道智能路由」——基于成功率与费率的动态决策引擎

Jeepay 的ChannelContext默认是静态路由：channelCode直接映射到具体策略类。但真实业务中，你需要根据「微信近 1 小时成功率 92%、费率 0.6%」vs「支付宝成功率 98%、费率 0.55%」自动选通道。Jeepay 本身不提供此功能，但它的扩展点设计得非常干净——我们只需重写ChannelContext.getStrategy()方法，注入自己的路由逻辑。

5.1 数据采集：如何从pay_order表实时统计各通道成功率与平均耗时

Jeepay 的pay_order表有channel_code、state、create_time、update_time字段，足够计算基础指标。我们用定时任务（@Scheduled(cron = "0 */5 * * * ?")）每 5 分钟执行一次统计：

-- 成功率（近 1 小时） SELECT channel_code, COUNT(*) as total, SUM(CASE WHEN state = 2 THEN 1 ELSE 0 END) as success, ROUND(SUM(CASE WHEN state = 2 THEN 1 ELSE 0 END) * 100.0 / COUNT(*), 2) as success_rate, ROUND(AVG(TIMESTAMPDIFF(SECOND, create_time, update_time)), 0) as avg_duration_sec FROM pay_order WHERE create_time > DATE_SUB(NOW(), INTERVAL 1 HOUR) AND channel_code IS NOT NULL GROUP BY channel_code;

结果存入channel_stat表，结构为(channel_code, success_rate, avg_duration_sec, last_update)。

5.2 路由策略：编写DynamicChannelStrategy实现加权评分

新建类DynamicChannelStrategy，实现PayChannelStrategy接口：

@Component public class DynamicChannelStrategy implements PayChannelStrategy { @Autowired private ChannelStatService channelStatService; @Override public PayChannel getPayChannel(PayOrder payOrder) { List<ChannelStat> stats = channelStatService.listLastHour(); if (stats.isEmpty()) { return ChannelContext.getStrategy("WX_JSAPI"); // fallback } // 加权评分：成功率权重 0.6，耗时权重 0.3，费率权重 0.1 return stats.stream() .map(stat -> { double score = stat.getSuccessRate() * 0.6 + (100 - stat.getAvgDurationSec()) * 0.3 + (100 - getChannelFee(stat.getChannelCode())) * 0.1; return new AbstractMap.SimpleEntry<>(stat.getChannelCode(), score); }) .max(Map.Entry.comparingByValue()) .map(entry -> ChannelContext.getStrategy(entry.getKey())) .orElse(ChannelContext.getStrategy("WX_JSAPI")); } private double getChannelFee(String channelCode) { // 从 channel_info.ext_config 中解析费率，此处简化为硬编码 Map<String, Double> feeMap = Map.of("WX_JSAPI", 0.6, "ALIPAY_WAP", 0.55, "UNIONPAY_APP", 0.45); return feeMap.getOrDefault(channelCode, 0.6); } }

然后在ChannelContext.java中，将getStrategy()方法改为：

public static PayChannelStrategy getStrategy(String channelCode) { if ("DYNAMIC".equals(channelCode)) { return SpringUtil.getBean(DynamicChannelStrategy.class); } return strategyMap.get(channelCode); }

5.3 商户侧开关：如何让不同商户启用不同路由策略

Jeepay 的mch_info表有extra字段（JSON 类型），我们约定：{"channel_strategy":"DYNAMIC"}表示启用智能路由。修改PayOrderService.createOrder()方法，在获取通道策略前：

String strategyCode = "DEFAULT"; if (mchInfo.getExtra() != null) { JSONObject extra = JSON.parseObject(mchInfo.getExtra()); strategyCode = extra.getString("channel_strategy"); } PayChannelStrategy strategy = ChannelContext.getStrategy(strategyCode);

这样，只需在管理后台编辑商户信息，填入{"channel_strategy":"DYNAMIC"}，该商户所有订单就走智能路由。

我的习惯是：上线前用SELECT channel_code, COUNT(*) FROM pay_order WHERE create_time > NOW() - INTERVAL 1 DAY GROUP BY channel_code;查看当前通道分布，再对比智能路由预测结果；上线后每天晨会看channel_stat表的success_rate趋势图，如果某通道连续 3 小时低于 90%，立刻在管理后台禁用该通道。这套机制让我们把整体支付成功率从 94.2% 提升到 97.8%，同时降低费率支出 12%。希望帮到你。

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