ZL 支付回调中心
「ZL 支付回调中心」是 ZL-售卡系统的云端配套服务,为插件提供多用户支付通知、云端店铺与库存同步能力;用户无需准备域名,可直接在网页统一管理商品、加密卡密、支付配置、邮件配置和群组开关。
✨ 功能特性
服务整体工作流程如下:
支付通知 -> 专属回调 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 访问。
本地运行
适用于本机试用与功能验证:
dotnet restore
dotnet run --urls http://127.0.0.1:18888启动后访问 http://127.0.0.1:18888,并可通过以下命令确认健康状态:
Invoke-RestMethod http://127.0.0.1:18888/healthDocker 部署
docker compose up -d --build
docker compose logs -f端口绑定与数据备份
容器只把服务绑定到服务器本机 127.0.0.1:18888,公网 HTTPS 由 Nginx 提供。数据库保存在 ./data/relay.db,必须纳入备份。
Nginx 与域名
- 将
uniqq.pay.zxiaolin.com解析到服务器公网 IP; - 安装有效 HTTPS 证书;
- 复制
deploy/nginx.conf.example的 server 配置; - 替换证书路径后检查并重载 Nginx;
- 访问
https://uniqq.pay.zxiaolin.com/health; - 确认返回
"ok":true。
反向代理要求
Nginx 反向代理必须传递 Host、X-Forwarded-For 和 X-Forwarded-Proto 请求头,并且不要把 Kestrel 的 18888 端口直接暴露到公网。
发布 Windows/Linux 文件
如需以独立文件方式部署 Windows 或 Linux 服务器,可执行:
.\publish.ps1输出位于 publish/ 目录,压缩包为 ZLPaymentRelay-server.zip。
上线前生产检查
正式对外提供服务前,请逐项确认:
- 使用正式 HTTPS 域名,不使用 IP 或临时隧道地址;
- 服务器时间同步正常;
data目录仅服务账号可读写;- 每天备份
relay.db; - 设置进程自动重启;
- 为
/api/auth/*和/wechat/notify/*保留限流; - 监控
/health和磁盘空间; - 正式开放注册前补充邮箱验证、隐私政策和服务条款。
插件接入
服务部署完成并通过健康检查后,按以下步骤将插件接入回调中心:
- 用户登录网站并创建插件实例;
- 复制一次性显示的插件连接密钥;
- 插件选择「ZL 官方回调中心」;
- 回调中心地址填写
https://uniqq.pay.zxiaolin.com; - 填写连接密钥,保存并重启插件;
- 插件自动取得专属
notify_url并开始领取通知。
🔒 安全配置
以下事项为安全部署必做项,上线前请逐条核对:
- 在服务器项目目录创建
.env,配置ZL_MASTER_KEY与ZL_LICENSE_SIGNING_PRIVATE_KEY。 - 两个密钥不得提交 Git、粘贴到工单或与数据库备份放在同一位置。
ZL_MASTER_KEY丢失后无法解密支付私钥、SMTP 密码和历史卡密,必须离线备份。- 授权签名私钥必须与桌面插件内置公钥配对。更换私钥时,需要同步更新并重新发布插件。
- 更新清单使用独立的离线私钥
.signing.env,不要把它部署到服务器。签名原文固定为pluginId + 换行 + latestVersion + 换行 + packageUrl + 换行 + 小写sha256,使用 RSA-PSS/SHA-256 签名并把 Base64 签名写入signature字段。 - 反向代理只开放 HTTPS,并添加 HSTS;容器端口继续只绑定
127.0.0.1。 - 数据库与
.env分开备份,备份文件加密后再离开服务器。 - 首次启动非 root 容器前执行
mkdir -p data && chown -R 1654:1654 data && chmod 700 data,确保只有容器应用用户可以读取数据库。
密钥管理红线
ZL_MASTER_KEY 一旦丢失,支付私钥、SMTP 密码与历史卡密将无法解密。该密钥必须离线备份,且不得与数据库备份放在同一位置。
🧩 第三方组件
本服务界面中使用的部分素材改编自第三方项目,相关声明如下:
| 组件 | 使用范围 | 许可证 | 版权信息 |
|---|---|---|---|
| Koi UI | wwwroot/assets/ 目录下的登录插图与 koi-*.svg 界面图标(改编自 Koi UI) | MIT | Copyright (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 插件的官方发布与支持渠道反馈。
