服务端组件
本板块收录 ZL 插件生态官方服务端组件的部署与管理文档,面向部署者与服务器管理员。
ZL 官方提供两个服务端组件:ZL 支付回调中心负责支付通知与云端店铺、库存同步;ZL-LicenseServer 授权服务负责插件授权码的签发与在线验证。两个组件均采用「服务只监听服务器本机端口、公网访问由 HTTPS 反向代理转发」的部署架构。部署前请确认服务器已具备 Docker 环境与有效的 HTTPS 域名证书。
本板块文档覆盖以下内容:
- 各组件的功能定位与工作方式;
- 完整的部署步骤与上线前检查清单;
- 安全部署必做项与日常运维要点;
- 常见问题的排查指引。
📚 文档目录
| 文档 | 说明 |
|---|---|
| ZL 支付回调中心 | 支付回调服务的功能介绍、部署步骤、安全部署必做项与常见问题 |
| ZL-LicenseServer 授权服务 | 授权服务的安全设计、部署方式、管理后台与管理接口说明 |
🧭 组件速览
| 组件 | 定位 | 默认监听地址 | 部署形态 |
|---|---|---|---|
| ZL 支付回调中心 | 多用户支付通知、云端店铺与库存同步 | 127.0.0.1:18888 | Docker Compose 或独立发布包,SQLite WAL 存储 |
| ZL-LicenseServer 授权服务 | 授权码签发、设备绑定与在线验证 | 127.0.0.1:18931 | 独立 Docker 容器 |
💳 ZL 支付回调中心
ZL 支付回调中心为 ZL-售卡系统提供多用户支付通知、云端店铺与库存同步。用户无需准备域名,可直接在网页统一管理商品、加密卡密、支付配置、邮件配置和群组开关。
工作流程如下:
支付通知 -> 专属回调 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 插件的官方发布与支持渠道反馈。
