Skip to content

收款播报 APP:部署与激活 ​

更新时间:2026/11/17 10:43:53

播报消息由平台经 MQTT over WebSocket(wss)长连接推送到手机。管道必须先打通,否则设备激活成功也收不到播报——九成「激活了但不播报」的问题都出在这一步。

面板部署路径 ​

运维面板 / 一键部署的用户,在「网关管理 → MQTT 接入」页完成(完整说明见网关管理 - MQTT 接入):

  1. 一键应用配置:在「Artemis MQTT 接入」状态卡点「一键应用配置」,面板自动完成接入配置并创建接入账号(app-device);
  2. 绑定接入域名:填裸域名(如 mqtt.example.com),手机接入地址就是 wss://<该域名>,不用再拼端口与路径;HTTPS 证书在外层网关 / 负载均衡 / CDN 配置;
  3. 记下接入凭据:页面「接入凭据」卡中可见 app-device 的密码,可显示、复制;
  4. 平台侧回填:管理端「系统管理 → 系统配置 → 平台配置 → MQTT 接入」填接入地址(wss://mqtt.example.com)、账号与密码,保存。

接入域名与配置生效

手机与消息服务是常驻长连接,多数 CDN 对长连接支持有限(超时短或直接断开),会造成频繁掉线、漏播报;接入域名请单独解析到源站 IP,或经支持 WebSocket 的外层网关 / 负载均衡终结 HTTPS。接入地址与账号随设备激活下发,之后再改配置,已激活设备需重新激活才切换。

自建 Artemis 消息管道 ​

源码部署的用户系统本就依赖 Artemis。在 broker 上补齐以下配置即可,片段与面板自动注入的内容一致。

版本要求:broker 2.53+

  • 下限 2.53:平台 JMS 客户端按 2.53 平价对接,且下方主题映射语义(≥ 2.33,ARTEMIS-4532)已包含在内——低于 2.33 时平台发布与设备订阅不同址,消息会静默丢失且无任何报错
  • 镜像建议 apache/artemis:2.57.0-alpine,与面板部署基准一致;2.50 起镜像名已由 apache/activemq-artemis 改为 apache/artemis,旧名不再更新
  • 裸机自建 2.39+ 需 JDK 17 运行;容器镜像自带运行时,无感

主题契约(Artemis 2.33+ / ARTEMIS-4532):设备订阅斜杠主题 daxpay/device/audio/{设备号}(/ 是 MQTT 层级分隔符),broker 映射为 core 地址 daxpay.device.audio.{设备号};平台按同址发布 JMS Topic,ACL 与 address-setting 按点号多段地址匹配。

① 开放 MQTT over WebSocket 端口:在 broker.xml 的 <acceptors> 段内新增 61614 端口:

xml
<acceptor name="mqtt-ws">tcp://0.0.0.0:61614?protocols=MQTT</acceptor>

② 设备消息地址策略:在 <address-settings> 段内新增,设备主题用完自动清理、消息短过期:

xml
<address-setting match="daxpay.device.#"><auto-delete-addresses>true</auto-delete-addresses><auto-delete-queues>true</auto-delete-queues><expiry-delay>600000</expiry-delay></address-setting>

③ 设备地址权限矩阵:在 <security-settings> 段内新增,平台(amq)可发布,接入账号(app-device)只可订阅:

xml
<security-setting match="daxpay.device.#"><permission type="send" roles="amq"/><permission type="createAddress" roles="amq"/><permission type="consume" roles="app-device"/><permission type="createNonDurableQueue" roles="app-device"/><permission type="createDurableQueue" roles="app-device"/><permission type="createAddress" roles="app-device"/></security-setting>

权限必须列全

security-setting 按最具体地址匹配且不继承默认段权限。缺 amq 的 send / createAddress,平台无法发布;缺 app-device 的 createAddress,手机先于平台订阅时会被拒绝。两种缺失在日志里都看不到明确原因。roles 写多个角色时必须逗号分隔(如 amq,app-device),用空格分隔在旧版本会静默失效。

④ 收窄核心端口:把 61616 acceptor 的 protocols 中 MQTT 删掉(若存在),让 61614 成为唯一 MQTT 入口;未声明 protocols 的可不处理。⑤ 创建接入账号(在 Artemis 实例目录执行):

bash
cd /var/lib/artemis-instance && ./bin/artemis user add --user '<管理员账号>' --password '<管理员密码>' --user-command-user 'app-device' --user-command-password '<自定义接入密码>' --role 'app-device'

⑥ 重启 Artemis 使配置生效。⑦ 对外暴露 wss 入口:生产环境由 nginx 等反向代理终结 HTTPS 并转发到 61614;确认主应用能访问该 broker,再到管理端「平台配置 → MQTT 接入」填 wss:// 地址与 app-device 账号密码。内网调试可临时用 ws://,生产请用 wss://:

nginx
location / {
    proxy_pass http://127.0.0.1:61614;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade";
    proxy_read_timeout 180s; proxy_send_timeout 180s; proxy_buffering off;
}

统一按斜杠主题

面板固定使用 apache/artemis:2.57.0-alpine,2.44 等其他 2.3x/2.5x 版本同样按斜杠主题订阅。旧做法「把 catch-all # 段的 consume/create 权限放宽给 app-device」不再推荐:只绕过 ACL,不修正点号订阅的地址映射,还把全部地址的订阅权限开放给设备账号。订阅始终失败时,先核对订阅主题是否为斜杠形态、后端是否已升级并重新激活。

运营端生成与绑定设备 ​

运营端「虚拟设备 → 设备管理」(支付系统菜单下):

  1. 「生成设备」创建虚拟设备,设备号由系统自动生成(VD 开头);
  2. 在设备行「绑定商户」,把设备分配给商户并指定归属应用——未绑定商户的设备无法激活;
  3. 需要验证链路时,用设备行的「试播」/「试打」入口,试打可选择纸宽;删除商户前先解绑或删除其名下设备,删除商户不会自动清理设备。

扫码激活 ​

  1. 商户端「商户中心 → 设备管理 → 虚拟设备」可看到被绑定的设备,设备行提供激活二维码入口;也可在此调整归属应用、绑定门店、启停设备;
  2. 安装收款播报 APP(安卓手机,服务器地址由安装包编译期内置);
  3. 打开 APP 扫描激活二维码——内容为 daxpay:activate:{设备号},仅携带设备号;无法扫码时在激活页手动填写设备号;
  4. 激活成功后 APP 自动连接消息管道并进入后台监听,过程中的异常会有页面提示;发起一笔小额收款(或点「试播」)验证,手机应立即播报,连接打印机的同时出票。

按应用控制播报与打印 ​

播报与小票打印按支付应用粒度控制:两端「应用管理」中分别有「语音播报」「小票打印」两个独立开关,可只播不印或只印不播;「小票版式」当前内置「标准收款小票」一种。运营端在「商户与应用 → 应用配置」、商户端在「商户与应用 → 应用管理」的设备区块配置。

APP 使用要点 ​

  • 保活设置:按引导关闭对本应用的电池优化、允许自启动与后台弹出权限(厂商路径略有差异)。被系统清理后重新打开 APP 即恢复监听;
  • 连接打印机:经典蓝牙(SPP)、USB、网络(同局域网填 IP 与端口,RAW TCP 9100)三种方式,表单带「测试连接」按钮;纸宽须与实际用纸一致;
  • 换环境重新激活:换用指向其他环境的安装包后 APP 会要求重新激活,属预期行为,重新扫码即可;
  • 换机与解绑:设备管理页支持「换机重新激活 / 解绑」,重扫码即轮换密钥并将旧设备踢下线;
  • 诊断自检:「诊断」抽屉逐项检查收款链路、后台运行、播报打印,并支持复制自检报告。

排障入口见播报与小票排障。