Skip to content

ZL 支付回调中心 ​

「ZL 支付回调中心」是 ZL-售卡系统的云端配套服务,为插件提供多用户支付通知、云端店铺与库存同步能力;用户无需准备域名,可直接在网页统一管理商品、加密卡密、支付配置、邮件配置和群组开关。

✨ 功能特性 ​

服务整体工作流程如下:

text
支付通知 -> 专属回调 URL -> 本服务持久化通知 -> 插件主动领取并验签 -> 云端原子出库 -> 插件发货 -> 回报结果

每个插件实例拥有两种不同凭据,职责严格分离:

  • 公开回调 ID:只用于接收微信通知,出现在通知 URL 中;
  • 私有连接 Token:只用于插件领取和确认通知,数据库仅保存其 SHA-256 哈希。
分类功能说明
账号与会话邮箱注册、登录和 30 天安全会话,密码采用 PBKDF2-SHA256 哈希存储
实例管理支持多插件实例,可停用实例并重置连接 Token
通知接收支持微信 API v2 XML 与 API v3 JSON 原始通知接收
通知管道通知去重、离线暂存、领取次数与 ACK 状态全程跟踪
状态监控提供插件心跳与在线状态
云端数据每个账号拥有独立的云端店铺、商品、库存、群组和订单
数据同步首次连接导入插件本地数据,之后按数据版本自动同步
加密存储卡密、支付密钥和邮件授权码使用 AES-GCM 加密存储
卡密出库支付成功后云端原子分配卡密,同一订单幂等重试
网页管理网页批量导入/作废卡密、商品上下架与群组开关
安全防护请求限流、1 MB 正文限制、安全响应头
数据保留已处理通知保留 7 天,其他通知最长保留 30 天
存储架构SQLite WAL 模式,支持本地单机部署
多端适配提供桌面端与移动端控制台

🚀 部署指南 ​

服务支持本地运行、Docker 部署与跨平台发布三种方式,生产环境推荐使用 Docker 部署并配合 Nginx 提供 HTTPS 访问。

本地运行 ​

适用于本机试用与功能验证:

powershell
dotnet restore
dotnet run --urls http://127.0.0.1:18888

启动后访问 http://127.0.0.1:18888,并可通过以下命令确认健康状态:

powershell
Invoke-RestMethod http://127.0.0.1:18888/health

Docker 部署 ​

bash
docker compose up -d --build
docker compose logs -f

端口绑定与数据备份

容器只把服务绑定到服务器本机 127.0.0.1:18888,公网 HTTPS 由 Nginx 提供。数据库保存在 ./data/relay.db,必须纳入备份。

Nginx 与域名 ​

  1. 将 uniqq.pay.zxiaolin.com 解析到服务器公网 IP;
  2. 安装有效 HTTPS 证书;
  3. 复制 deploy/nginx.conf.example 的 server 配置;
  4. 替换证书路径后检查并重载 Nginx;
  5. 访问 https://uniqq.pay.zxiaolin.com/health;
  6. 确认返回 "ok":true。

反向代理要求

Nginx 反向代理必须传递 Host、X-Forwarded-For 和 X-Forwarded-Proto 请求头,并且不要把 Kestrel 的 18888 端口直接暴露到公网。

发布 Windows/Linux 文件 ​

如需以独立文件方式部署 Windows 或 Linux 服务器,可执行:

powershell
.\publish.ps1

输出位于 publish/ 目录,压缩包为 ZLPaymentRelay-server.zip。

上线前生产检查 ​

正式对外提供服务前,请逐项确认:

  • 使用正式 HTTPS 域名,不使用 IP 或临时隧道地址;
  • 服务器时间同步正常;
  • data 目录仅服务账号可读写;
  • 每天备份 relay.db;
  • 设置进程自动重启;
  • 为 /api/auth/* 和 /wechat/notify/* 保留限流;
  • 监控 /health 和磁盘空间;
  • 正式开放注册前补充邮箱验证、隐私政策和服务条款。

插件接入 ​

服务部署完成并通过健康检查后,按以下步骤将插件接入回调中心:

  1. 用户登录网站并创建插件实例;
  2. 复制一次性显示的插件连接密钥;
  3. 插件选择「ZL 官方回调中心」;
  4. 回调中心地址填写 https://uniqq.pay.zxiaolin.com;
  5. 填写连接密钥,保存并重启插件;
  6. 插件自动取得专属 notify_url 并开始领取通知。

🔒 安全配置 ​

以下事项为安全部署必做项,上线前请逐条核对:

  1. 在服务器项目目录创建 .env,配置 ZL_MASTER_KEY 与 ZL_LICENSE_SIGNING_PRIVATE_KEY。
  2. 两个密钥不得提交 Git、粘贴到工单或与数据库备份放在同一位置。
  3. ZL_MASTER_KEY 丢失后无法解密支付私钥、SMTP 密码和历史卡密,必须离线备份。
  4. 授权签名私钥必须与桌面插件内置公钥配对。更换私钥时,需要同步更新并重新发布插件。
  5. 更新清单使用独立的离线私钥 .signing.env,不要把它部署到服务器。签名原文固定为 pluginId + 换行 + latestVersion + 换行 + packageUrl + 换行 + 小写sha256,使用 RSA-PSS/SHA-256 签名并把 Base64 签名写入 signature 字段。
  6. 反向代理只开放 HTTPS,并添加 HSTS;容器端口继续只绑定 127.0.0.1。
  7. 数据库与 .env 分开备份,备份文件加密后再离开服务器。
  8. 首次启动非 root 容器前执行 mkdir -p data && chown -R 1654:1654 data && chmod 700 data,确保只有容器应用用户可以读取数据库。

密钥管理红线

ZL_MASTER_KEY 一旦丢失,支付私钥、SMTP 密码与历史卡密将无法解密。该密钥必须离线备份,且不得与数据库备份放在同一位置。

🧩 第三方组件 ​

本服务界面中使用的部分素材改编自第三方项目,相关声明如下:

组件使用范围许可证版权信息
Koi UIwwwroot/assets/ 目录下的登录插图与 koi-*.svg 界面图标(改编自 Koi UI)MITCopyright (c) 2025 Yu Xin

完整许可文本请查阅发行包内的 THIRD_PARTY_NOTICES.md 文件。

❓ 常见问题 ​

为什么不能把 18888 端口直接暴露到公网?

容器只把服务绑定到服务器本机 127.0.0.1:18888,公网访问一律经由 Nginx 提供的 HTTPS 反向代理转发。反向代理必须传递 Host、X-Forwarded-For 和 X-Forwarded-Proto 请求头。

如何确认服务运行正常?

访问 /health 健康检查端点,返回 "ok":true 即表示服务正常。生产环境建议持续监控 /health 与磁盘空间。

通知数据会保留多久?

已处理通知保留 7 天,其他通知最长保留 30 天。

ZL_MASTER_KEY 丢失后有什么影响?

ZL_MASTER_KEY 丢失后无法解密支付私钥、SMTP 密码和历史卡密。该密钥必须在部署时离线备份,丢失后无法恢复。

插件如何接入回调中心?

登录网站创建插件实例,复制一次性显示的连接密钥;在插件中选择「ZL 官方回调中心」,回调中心地址填写 https://uniqq.pay.zxiaolin.com,粘贴连接密钥后保存并重启插件。插件会自动取得专属 notify_url 并开始领取通知。

正式开放注册前还需要做什么?

需要在网页补充邮箱验证、隐私政策和服务条款后,再正式开放注册。

🆘 获取帮助 ​

  • 部署或使用中遇到问题时,请先访问 /health 端点确认服务状态;
  • 排查故障时请同时检查服务日志与 Nginx 访问、错误日志;
  • 第三方组件的完整许可信息请查阅发行包内的 THIRD_PARTY_NOTICES.md 文件;
  • 其他问题请通过 ZL 插件的官方发布与支持渠道反馈。

薇薇官机平台 · ZL 系列插件