应用授权（ZsadminKey）使用文档

作者：kuakeba.cn | 版本：1.0.0 | 适用于 Zsens Admin 3.0+（PHP 8.2+）

一、插件简介

以 Zsadmin 为管理后台的应用授权系统，可对接任意编程语言开发的应用（PHP / Java / Python / Go / Node.js / C# 等，只需一次 HTTP 请求即可完成授权验证）。

• 两种授权管理方式：订单授权管理 + Token 授权管理，可只用其中一种，也可两种并用
• 五种 API 回调验证方式：JSON / Base64 / MD5 签名 / AES 加密 / XOR 混淆（每个应用独立配置）
• 四种反馈信息类型：验证失败、验证成功、验证成功但授权已关闭、验证成功但授权已过期
• 自助绑定域名：在 Zsadmin 应用中心销售的应用，用户可通过应用中心 API 验证订单后自助绑定域名，保证购买者合法性与授权有效性
• Token 非实名验证：操作简单，可批量生成后向用户发放；每个订单号和 Token 都可设置最多绑定域名数量与应用授权到期时间

二、数据模型

三、安装

1. 将 ZsadminKey 目录放入 plugins/ 下
2. 后台 应用中心 找到「应用授权」安装（自动建 4 张表）
3. 后台左侧菜单 应用授权 进入管理页

四、后台功能（单页五标签）

1. 接入应用

• 新增应用：名称必填，appid / secret 留空自动生成；选择回调验证方式；可选「强制验签」「应用中心销售」
• 操作：编辑 / 启停 / 删除（删除将同时删除关联订单与域名绑定，Token 转为通用）

2. 订单授权

• 新增订单：选择所属应用、订单号（留空自动生成）、域名上限、到期时间（空=永久）
• 操作：编辑 / 查看&解绑域名 / 关闭开启 / 删除

3. Token 授权

• 批量生成：数量（1-200）、所属应用（空=通用 Token，任意启用应用可用）、域名上限、到期时间、备注
• 生成后弹窗展示全部 Token，可直接复制发放；支持域名查看/解绑、状态关闭、删除

4. API 接入文档

• 展示验证接口地址、参数表、四种反馈类型、五种验证方式说明
• 内置联调测试器：填入 appid/domain/auth 即可发起真实验证请求，支持下拉切换响应编码并自动解码展示

5. 设置

• 启用/停用订单授权、Token 授权（对应方式关闭后 verify 接口不再接受该类凭证）
• 验证时自动绑定域名开关
• 应用中心 API 地址与密钥（本站作为客户端校验市场订单用；同时本站服务端点为 /zskey/market/verify，设置密钥后开放，供其他 Zsadmin 站点回查订单）
• 默认授权时长（天，0=永久）

五、验证 API

GET/POST /zskey/verify

四种反馈类型

成功响应（明文形态）示例：

{
    "code": 1,
    "type": "success",
    "msg": "验证成功",
    "appid": "app_xxx",
    "domain": "demo.com",
    "auth": "ZSK_xxx",
    "auth_type": "token",
    "expire_at": 0,
    "expire": "永久",
    "max_domains": 2,
    "domains": ["demo.com"],
    "bound_now": false,
    "timestamp": 1792079890
}

五种回调验证方式（响应体编码，响应头 X-Zskey-Mode 标识当前方式）

联调时可在请求中附加 mode 临时切换编码方式（如 mode=aes），便于客户端调试；正式接入以应用配置的 verify_mode 为准。

域名验证与自助绑定逻辑

1. domain 规范化为 host（去协议/路径/端口，转小写）
2. 已绑定 → 直接通过；未绑定：

  - 「自动绑定」开启且未达上限 → 自动绑定并通过（bound_now: true）

  - 已达上限 → failed「域名绑定数量已达上限」

  - 「自动绑定」关闭 → failed「域名未授权」（需后台手动绑定）

1. 域名解绑后可重新绑定（占用上限名额随即释放）

六、应用中心（市场）订单互认

• 本站作为客户端（应用标记为「应用中心销售」且设置了市场 API）：订单授权验证时先向市场 API 校验订单合法性（sign = md5(appid.order.timestamp.market_key)），失败即拒绝
• 本站作为服务端：POST /zskey/market/verify 供其他 Zsadmin 站点的 ZsadminKey 插件回查订单；设置 API 密钥后开放，返回 {"code":1,"msg":"ok","data":{"expire_at":...}}

七、各语言接入示例

PHP：

$sign = md5("{$appid}.{$domain}.{$auth}.{$ts}.{$secret}");
$resp = file_get_contents("https://你的站点/zskey/verify?appid=...&domain=...&auth=...×tamp={$ts}&sign={$sign}");
$data = json_decode($resp, true);          // json 模式
if (($data['code'] ?? 0) === 1) { /* 授权有效 */ }

Python：

import hashlib, time, urllib.request, json
ts = str(int(time.time()))
sign = hashlib.md5(f"{appid}.{domain}.{auth}.{ts}.{secret}".encode()).hexdigest()
url = f"https://你的站点/zskey/verify?appid={appid}&domain={domain}&auth={auth}×tamp={ts}&sign={sign}"
data = json.load(urllib.request.urlopen(url))

其他语言同理：拼 URL → 请求 → 按验证方式解码 → 判断 code。

八、常见问题

Q：订单号和 Token 能同时用吗？

能。系统自动识别 auth 参数：先按订单号查（需「订单授权」开启），再按 Token 查（需「Token 授权」开启）。可只启用其中一种方式。

Q：通用 Token 是什么？

所属应用为「通用」的 Token，可用于任意启用应用的验证；绑定域名按 Token 自身上限独立计算。

Q：怎么处理「验证成功但授权已关闭 / 已过期」？

应用端按 code 2/3（或 type closed/expired）给出对应提示（如引导续费）；授权服务器侧不阻断响应，方便业务区分处理。

Q：secret 泄露怎么办？

后台编辑该应用填入新 secret 即可（旧签名/加密立即失效）；建议同时开启「强制验签」。

Q：为什么推荐 aes / sign 模式？

明文 JSON 可被中间人读懂授权结构；aes/sign 模式下响应体不可读/可校验完整性，配合「强制验签」可防参数篡改与重放（timestamp ±300 秒）。