主题
常见问题
汇总 DaxPay Plus 使用、部署、通道对接与二次开发中高频出现的疑问,按主题分组。多数条目附带指向专题排查页或相关章节的链接,深入细节请跳转阅读。
基础概念
DaxPay Plus 是什么
DaxPay Plus 是 DaxPay 开源版的商业增强版,将支付宝、微信、银联等多种支付通道封装为统一的 HTTP 接口,提供支付、退款、分账、查询、回调等支付核心能力;并在开源核心之上补齐代理商体系、商户进件、全量风控、商户限额四块商用能力。详见项目介绍。
和开源版是什么关系
fork 自 DaxPay 开源版,技术栈同源。开源版提供完整支付核心与运营/商户两端;Plus 在此基础上增加代理商端、进件审核、四层风控、限额与费率体系等商用增强,并配套全端管理界面。差异对比见项目介绍 - 与开源版的关系。
支持哪些数据库
仅支持 PostgreSQL 14+,不支持 MySQL / Oracle 等。时间字段统一 timestamp(6)(无时区),实体使用 LocalDateTime,全系统按东八区口径处理时间。
部署运行
后端编译必须用 mvnd 吗
项目约定使用 mvnd(Maven Daemon)加速编译。普通 mvn 也能编译,但 mvnd 自带守护进程,增量编译速度显著更快,推荐使用。详见项目构建。
PowerShell 下 mvnd 编译参数报错
PowerShell 下含 = 的 -D 参数会被空格拆分,必须加引号:
powershell
# 错误 — 会被拆分
mvnd compile -Dmaven.test.skip=true
# 正确 — 加引号
mvnd compile "-Dmaven.test.skip=true"Apache Artemis 能否替换为其他消息队列
当前版本强依赖 Artemis(用于支付延时通知等 JMS 场景),不支持直接替换为 RabbitMQ / Kafka。如需替换需自行改造消息中间件适配层。
延时消息提前或延后投递怎么办
现象:延时消息设置 10 秒,约 6 秒就被消费;或设置 5 秒,过了 8 秒才收到。 原因:应用与 Artemis broker 跨机器部署且两机时钟不一致,延时消息按绝对时间戳投递,实际延时被平移两机时钟差。 修复:两台机器均开启 NTP 对时,详见延时消息时钟偏差。
套了 CDN 后登录报「请求验证已失效」或「请求时间戳已过期」怎么办
现象:本地直连后端一切正常,套上 CDN(腾讯 EdgeOne、CloudFlare 等)后登录必报「请求验证已失效,请重试」或「请求时间戳已过期,请重试」。
原因:登录防重放机制要求每次登录先取一个一次性 nonce,CDN 把这类接口的响应缓存后,所有用户拿到同一份旧 nonce;图形验证码接口被缓存同理(所有人看到同一张图)。
修复:在 CDN 给所有 API 路径(/api/* 及网关域名的 /unipay/*、/client/*、/epay/*)配置不缓存规则,详见CDN 部署注意事项。
套了 CDN 后站内通知一直断开重连怎么办
现象:浏览器控制台反复报 ERR_HTTP2_PROTOCOL_ERROR 200 (OK) 之类的连接中断错误,通知消息要刷新页面才能看到,该请求按固定间隔断开重连。
原因:站内通知走 SSE 长连接,靠服务端周期性心跳维持;链路中间任何一层(CDN 回源超时、代理超时)等不到数据时,会在浏览器已收到 200 之后把连接掐断,前端随即自动重连。
修复:在 CDN 给 /api/notify/* 配置回源超时 ≥ 60 秒(须大于 10 秒的心跳间隔);EdgeOne 注意规则要配到站点实际所在的「中国大陆 / 全球」环境才生效。详见站内通知(SSE)断开重连排查。
上传文件报跨域(CORS)错误怎么办
现象:「测试连接」通过,但上传文件时报跨域错误(No 'Access-Control-Allow-Origin' header ...)或直接失败。 原因:预签名直传是浏览器直连对象存储的跨域请求,桶上未放行跨域规则;后端「测试连接」不经过浏览器,测不出这个问题。 修复:在桶上配置跨域规则——来源填三端 Web 与 H5 收银台的地址(联调可用 *)、方法必须含 PUT、暴露响应头加 ETag;Cloudflare R2 的 * 只能写在 AllowedOrigins。详见存储跨域(CORS)配置与上传排查。
容器化部署最低配置
纯后端全家桶(含 PostgreSQL / Redis / Artemis / 主应用 / 两个通道子应用)容器化跑通联调,2 核 4G 可用;生产建议 4 核 8G 起步,并按交易量增长评估资源。使用运维面板一键部署的,生产服务器建议 8 GB 内存起步,详见面板安装 - 安装前提。
一键部署与运维面板
使用一键部署或运维面板时的高频问题,完整的分阶段排查步骤见运维面板故障排查。
在线安装下载失败或校验不通过
常见原因是下载源异常或网络受限。重新执行安装命令再试;仍失败改用离线安装。注意 SHA256 校验失败时安装会直接终止,不会跳过校验强行安装。
离线安装没反应、提示在线下载
install.sh 与 .xz 安装包必须在同一个目录(脚本只探测自身所在目录,不探测当前工作目录),且两个文件须来自同一版本,用 bash install.sh 执行。
安装完成访问 IP:端口返回 404
面板默认开启安全入口:访问地址是 IP:端口/随机入口路径 的完整形式,直接访问 IP 和端口返回 404 属正常防护。忘记入口时执行 daxpay-plus entrance show 查看完整地址,详见面板安装。
忘记面板初始密码或登录被锁定
daxpay-plus info 查看首次启动生成的初始管理员凭据;改过又忘了用 daxpay-plus reset-password 重置(会吊销全部已登录会话);连续输错被锁定用 daxpay-plus unlock 解锁。详见命令行用法与面板安全。
端口冲突(18060 / 80 / 443)
面板默认占用 18060,统一网关监听 80/443(HTTPS 由外层 CDN / 网关终结)。停掉占用进程,或用 --port 换面板端口;总览页也会列出端口冲突提示。
业务后端容器 unhealthy 反复重启
常见根因是数据库密码为空,或业务侧与中间件侧密码不一致,导致认证失败。在基础环境服务卡片「查看密码」确认密码非空,用「配置」抽屉的「修改密码」对齐后重启业务容器。
页面出现 drift(漂移)横幅
提示「重新部署 <某服务>」= 该服务的端口/内存/暴露模式改了未生效,点击只重建这一个容器;提示整栈「重新部署」= 版本/JVM/内存档位等栈级变更未生效,需重建所有已启用容器;提示「应用网关配置」= 网关配置改动未应用,点击应用即可,无需重建容器。
明明部署了,面板却显示「未部署」
「已部署」判定基于运行时容器探测 + 部署快照。手动用 docker compose 拉起的容器,面板会自动补齐快照自愈;仍未识别就到对应页面点一次「部署」让面板接管。
支付通道对接
已支持哪些支付通道
共 16 个通道,分两组承载:
- 直连通道(子应用1,
daxpay-plus-channel-one)— 支付宝、微信、抖音、银联(云闪付)、银联商务 - 聚合通道(子应用2,
daxpay-plus-channel-two)— 拉卡拉、乐刷、富友、海科融通、盛付通、随行付、易宝、河马付、Adapay(汇付)、斗拱(汇付)与易支付协议通道
通道明细与配置结构见支付通道总览。
channel-one / channel-two 有什么区别
两个通道子应用架构完全相同(无状态、不连中间件、报文 AES-GCM 加密传输),区别只在承载的通道集合与端口:子应用1(端口 10100)承载官方 SDK 直连通道,子应用2(端口 10200)承载聚合通道 SDK。主应用通过 daxpay.channel.one/two.base-url 路由,子应用编号固定不可改名。
通道子应用必须独立部署吗
是的。通道子应用独立部署是 DaxPay 的核心设计——将第三方 SDK 隔离到子应用,避免 SDK 依赖污染主应用,支持独立升级与维护;主应用经声明式 HTTP 客户端调用,链路全程加密。一键部署已将两个子应用纳入统一编排,自建部署时需单独拉起。架构说明见架构总览。
支付报「通道服务不可用」或回调不推进怎么办
现象:发起支付/退款报「通道服务不可用,连接未建立」「通道子应用返回明文错误响应」等错误,或通道回调已收到但订单一直不推进。 原因:主应用与通道子应用(10100/10200)之间的 HTTP + AES-GCM 链路不通——子应用未启动、端口不可达,或两侧传输密钥(transport-encrypt.key / CHANNEL_TRANSPORT_KEY)不一致。 排查:按「进程在不在 → 端口通不通 → 两侧密钥/路由配置是否一致」的顺序排查,详见通道子应用通信失败排查。
微信服务商支付报「受理机构必须传入sub_mch_id」怎么办
现象:服务商模式发起支付时报「受理机构必须传入sub_mch_id」,但请求参数里的 sub_mchid 明明有值。 原因:这条报错文案有误导性——它真正的含义是微信对「服务商 ↔ 特约商户」绑定关系的校验失败,不是字段缺失。最常见的触发是服务商自己的商户号被填进了特约商户号位置。 修复:普通商户改配微信直连;服务商的特约商户号必须填进件绑定的真实二级商户号。详见微信服务商支付报错。
进件申请单创建后还能换服务商吗
不能。申请单创建即锁定归属服务商,后续流程都在该服务商名下推进;对外锚点始终是商户号与通道商户号,不暴露服务商细节。确实需要换服务商的,将原申请单作废后重新发起。详见进件体系总览与进件申请流程。
如何新增一个支付通道
- 在对应通道子应用仓(直连走
daxpay-plus-channel-one,聚合走daxpay-plus-channel-two)的daxpay-channel-impl下实现 SDK 调用与签名/验签 - 在主应用
daxpay-channel模块注册通道策略与配置数据 CRUD - 在
ChannelEnum补充通道枚举
新增通道只需实现 SDK 调用并注册策略,不影响主链路。
功能边界
是否支持分账
支持支付宝、微信、抖音等通道的分账。使用流程:统一下单时声明 allocation=true 创建分账订单 → 通过开放接口发起分账、查询或同步;分账接收方需提前完成绑定,操作说明见支付分账。
是否支持国际支付(PayPal / Stripe)
当前版本未接入国际通道(Stripe、PayPal 等),境外卡支付暂不可用,属后续规划方向。
沙箱环境怎么用
DaxPay 采用部署级沙箱隔离:
- 测试 / 开发环境配置
sandbox-enabled=true,允许沙箱联调 - 生产环境必须配置
sandbox-enabled=false,启动时会强制将所有activeEnv=sandbox的产品重置为prod,保证生产数据纯净
生产环境隔离
沙箱联调请走独立的测试环境部署,生产数据库严禁从测试环境导入数据。详见配置说明 - 部署模式与生产校验。
是否支持多商户 / 多商户隔离
支持,而且是三级运营结构:运营端 + 代理商端 + 商户端,商户数据按商户编号行级隔离,代理商只见名下商户(见代理商体系总览);单商户可配置多个支付应用,独立凭证与回调地址。
是否支持预授权 / 支付分
支持(plus 独有实装):支付宝预授权(授权/请款/转支付/退款)与微信支付分(独立域、需确认模式)分开建模,入口在运营端「交易管理」下。能力边界详见预授权与支付分。
配套工具
模拟联调通道是什么, 怎么接入
独立部署的模拟通道子应用,扮演三方支付平台,用于真实通道未下号时的全链路联调、POC 演示与异常演练。接入分五步:建模拟通道商户 → 纳入通道路由 → 配回调地址 → 对齐传输密钥 → 重启验证。完整步骤与失败对照见模拟联调通道 - 接入配置,工具定位与安全边界见工具概览。
压测验收工具、收款播报 APP 的文档在哪
统一收在配套工具总览。其中运维面板与模拟联调通道文档已可用;压测验收工具与收款播报 APP 的正文在编写中,当前请先看交付包内 README 与管理台内文档,补齐后总览页会更新入口。
二次开发
能否修改源码用于自己的项目
商业版按授权协议交付源码。你可以在授权范围内修改源码、用于自有业务;具体权利与义务以你所签署的授权协议为准。业务系统通过 HTTP 接口对接时,自身代码不涉及平台源码分发问题。
前端如何对接后端接口
前端通过 RESTful HTTP 接口对接主应用(dev 端口 19999),接口请求 / 响应支持 RSA 签名防篡改,认证基于 Sa-Token(token name: Accesstoken)。详细接入方式见接口总览与签名机制。
数据库表结构在哪?如何初始化
SQL 脚本位于主应用仓库 _config/sql/ 目录,全新安装顺序为 table.sql(建表)→ data.sql(初始数据)→ iam_perm_menu.sql(菜单种子,第三步为菜单权威)。仓内另提供升级脚本 update-tables.sql → update-datas.sql(不能跨版本)。详见项目构建 - 数据库准备。
为什么缓存会出现「只读 L1、不读写 Redis」的情况
这不是普通缓存的常规形态,而是敏感缓存的安全降级保护:缓存名命中敏感名单(secure: 前缀等)、且平台数据加密未启用时,敏感数据被禁止明文写入 Redis,仅写 L1 本机内存、读侧直接穿透。启用数据加密后自动恢复 L1+L2 双层。完整行为矩阵见缓存只读 L1 降级说明。