Skip to content

服务端组件 ​

本板块收录 ZL 插件生态官方服务端组件的部署与管理文档,面向部署者与服务器管理员。

ZL 官方提供两个服务端组件:ZL 支付回调中心负责支付通知与云端店铺、库存同步;ZL-LicenseServer 授权服务负责插件授权码的签发与在线验证。两个组件均采用「服务只监听服务器本机端口、公网访问由 HTTPS 反向代理转发」的部署架构。部署前请确认服务器已具备 Docker 环境与有效的 HTTPS 域名证书。

本板块文档覆盖以下内容:

  • 各组件的功能定位与工作方式;
  • 完整的部署步骤与上线前检查清单;
  • 安全部署必做项与日常运维要点;
  • 常见问题的排查指引。

📚 文档目录 ​

文档说明
ZL 支付回调中心支付回调服务的功能介绍、部署步骤、安全部署必做项与常见问题
ZL-LicenseServer 授权服务授权服务的安全设计、部署方式、管理后台与管理接口说明

🧭 组件速览 ​

组件定位默认监听地址部署形态
ZL 支付回调中心多用户支付通知、云端店铺与库存同步127.0.0.1:18888Docker Compose 或独立发布包,SQLite WAL 存储
ZL-LicenseServer 授权服务授权码签发、设备绑定与在线验证127.0.0.1:18931独立 Docker 容器

💳 ZL 支付回调中心 ​

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

工作流程如下:

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

每个插件实例拥有两种不同凭据:

  • 公开回调 ID:只用于接收微信通知,出现在通知 URL 中;
  • 私有连接 Token:只用于插件领取和确认通知,数据库仅保存 SHA-256 哈希。

核心能力包括:

  • 微信 API v2 XML、API v3 JSON 原始通知接收,通知去重、离线暂存与 ACK 状态跟踪;
  • 每个账号独立的云端店铺、商品、库存、群组和订单,首次连接导入插件本地数据,之后按数据版本自动同步;
  • 卡密、支付密钥和邮件授权码使用 AES-GCM 加密存储,支付成功后云端原子分配卡密,同一订单幂等重试;
  • 请求限流、1 MB 正文限制与安全响应头,提供桌面端与移动端控制台。

部署流程概览:本地验证或 docker compose 部署 → 配置 Nginx 与 HTTPS 域名 → 完成上线前生产检查 → 在网页创建插件实例并接入插件。

🔑 ZL-LicenseServer 授权服务 ​

ZL-LicenseServer 是独立 Docker 授权服务,默认仅监听宿主机 127.0.0.1:18931,供 HTTPS 反向代理使用。

安全设计包括:

  • 授权码只保存带服务端 pepper 的 SHA-256 摘要;
  • 一个授权码可限制设备数量;
  • ECDSA P-256 私钥只在服务器数据目录生成和保存;
  • 插件只内置公钥,验证 30 分钟短期签名凭证;
  • 支持授权到期、停用和设备解绑;
  • 管理接口使用独立高强度 X-Admin-Key;
  • 公共激活和续租接口有限流;
  • 容器使用非 root 用户、只读根文件系统和独立网络。

日常管理可通过访问 https://你的授权域名/manage 的可视化管理后台完成,也可使用服务器附带的管理脚本创建授权、查看授权列表、查看设备与停用授权。

部署流程概览:部署 Docker 服务 → 配置 HTTPS 反向代理至 http://127.0.0.1:18931 → 通过 GET /health 确认服务状态 → 使用管理脚本或可视化管理后台签发授权。

🛡 术语说明 ​

术语出处含义
公开回调 ID支付回调中心只用于接收微信通知的凭据,出现在通知 URL 中
私有连接 Token支付回调中心只用于插件领取和确认通知的凭据,数据库仅保存 SHA-256 哈希
插件连接密钥支付回调中心创建插件实例后一次性显示的密钥,用于插件接入回调中心
notify_url支付回调中心插件接入回调中心后自动取得的专属支付通知地址
relay.db支付回调中心服务数据库文件,保存在 ./data/ 目录,必须纳入备份
授权码授权服务由管理后台或管理接口创建,仅在创建响应中返回一次
管理密钥授权服务保存在服务器文件 /opt/zl-keyword-license/admin.key 中,用于登录管理后台
X-Admin-Key授权服务调用授权服务管理接口时必须携带的请求头
短期签名凭证授权服务有效期为 30 分钟的签名凭证,由插件使用内置公钥验证

🛡 通用安全基线 ​

以下要求适用于全部服务端组件,完整的安全配置请参阅各组件文档:

  • 服务端口只绑定服务器本机 127.0.0.1,公网访问一律由 Nginx 等 HTTPS 反向代理转发,不要把服务端口直接暴露到公网;
  • 反向代理只开放 HTTPS,并添加 HSTS;
  • 密钥不得提交 Git、粘贴到工单或与数据库备份放在同一位置;
  • 独立的离线签名私钥不要部署到服务器;
  • 数据库与密钥配置文件分开备份,备份文件加密后再离开服务器。

密钥安全

ZL_MASTER_KEY 等关键密钥丢失后无法恢复对应数据,必须在部署时离线备份并妥善保管。

✅ 部署后检查 ​

  • 通过各组件的 /health 端点确认服务状态;
  • 确认反向代理域名解析与 HTTPS 证书配置正确;
  • 确认数据目录的备份计划已经建立;
  • 确认服务器时间同步正常。

🛠 日常运维 ​

事项说明
数据备份支付回调中心的 relay.db 需每天备份;备份文件加密后再离开服务器
进程守护为服务进程设置自动重启,避免异常退出后服务长时间不可用
健康监控持续监控各组件的 /health 端点与服务器磁盘空间
限流保留保留支付回调中心 /api/auth/* 与 /wechat/notify/* 的请求限流
目录权限支付回调中心的 data 目录仅服务账号可读写;授权服务的管理密钥文件仅管理员可读取
审计追踪授权服务可通过管理后台或 GET /admin/audit 查看审计日志

🆘 获取帮助 ​

部署或运维中遇到问题时,请先查阅对应组件文档中的「常见问题」章节,并通过 /health 端点与组件日志确认服务状态,再通过 ZL 插件的官方发布与支持渠道反馈。

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