开发文档 — ZazreAuth

授权验证 API

所有 SDK 最终都调用此 API 进行授权验证。你可以直接使用 HTTP 请求，也可以通过 SDK 封装调用。

验证接口

POST /api/check.php

参数	类型	必填	说明
`domain`	string	必填	当前运行域名，SDK 自动检测
`license_key`	string	必填	授权码，如 ZAZRE-XXXX-XXXX-XXXX-XXXX
`timestamp`	int	可选	Unix 时间戳，用于防重放（建议启用）
`signature`	string	可选	HMAC-SHA256 签名，增强安全性

响应示例

JSON 响应

{
  "code": 0,
  "message": "授权验证通过",
  "data": {
    "domain": "example.com",
    "license_key": "ZAZRE-XXXX-XXXX-XXXX-XXXX",
    "customer_name": "张三",
    "status": "active",
    "expires_at": "2026-12-31 23:59:59"
  }
}

code = 0 表示授权通过；code != 0 表示未授权，具体原因见 message。

在线更新 API

通过此 API 检查产品是否有新版本可更新。SDK 内置的 checkUpdate() 方法封装了此接口。

更新检查接口

POST /api/update.php

请求需通过授权验证，只有已授权的域名 + 授权码组合才能查询更新。

参数	类型	必填	说明
`domain`	string	必填	当前运行域名
`license_key`	string	必填	授权码
`version`	string	可选	当前版本号，如 `1.0.0`。默认 `0.0.0`
`product`	string	可选	产品标识，用于区分不同产品线
`channel`	string	可选	更新通道：`stable`（默认）、`beta`、`alpha`

成功响应 — 有新版本

JSON 响应

{
  "code": 0,
  "message": "发现新版本：2.0.0",
  "data": {
    "version": "2.0.0",
    "changelog": "修复若干 Bug，新增数据导出功能",
    "channel": "stable",
    "download_url": "https://cdn.example.com/releases/v2.0.zip",
    "file_size": 2048576,
    "file_md5": "d41d8cd98f00b204e9800998ecf8427e",
    "release_date": "2026-07-01 12:00:00",
    "product": "my-app"
  }
}

响应 — 已是最新版

JSON 响应

{
  "code": 0,
  "message": "已经是最新版本",
  "data": {
    "current_version": "2.0.0"
  }
}

download_url 返回规则：系统仅支持外部直链（CDN / OSS / GitHub Releases 等）。如果版本未设置直链下载地址，则不会返回给客户端。管理员必须在发布时为每个版本填写有效的 HTTPS 下载直链。

授权过期或被禁用的域名将无法获取更新。版本过低可能要求先升级到中间版本（通过 min_version 控制）。

更新通道 & 灰度发布

更新通道

系统支持三个更新通道，由低到高依次为：

通道	值	适用场景	客户端可匹配的版本
稳定版	`stable`	生产环境，所有用户默认	仅 stable 通道的版本
Beta 版	`beta`	尝鲜用户，功能预览	stable + beta 通道的版本
Alpha 版	`alpha`	内部开发测试	所有通道的版本

客户端 SDK 在 config() 中设置 channel 参数即可切换通道。默认使用 stable。

灰度发布（Canary Release）

管理者可在发布版本时设置灰度比例和白名单，实现渐进式发布：

灰度比例：设置 0%~100%，系统根据域名和授权码的哈希值判断是否命中。
白名单：指定的域名不受灰度比例限制，始终可以获取更新。
全量发布：灰度比例设为 100% 即全体用户可用。

使用建议：先设置 10% 灰度 + 白名单测试域名 → 观察无问题后逐步提升至 50% → 100% 全量。

各语言 SDK 调用示例

PHP

$update = \Zazre\ZazreAuth::checkUpdate();
if ($update['has_update']) {
    echo "新版本: " . $update['version'] . "\n";
    echo "更新日志: " . $update['changelog'] . "\n";
    // 自动下载更新
    \Zazre\ZazreAuth::doUpdate($update);
}

Python

result = auth.check_update()
if result.get('has_update'):
    print(f"新版本: {result['version']}")
    print(f"下载地址: {result['download_url']}")
    auth.do_update(result)  # 自动下载并覆盖更新

Java

ZazreAuth.UpdateInfo info = ZazreAuth.checkUpdate();
if (info.hasUpdate) {
    System.out.println("新版本: " + info.version);
    System.out.println("下载: " + info.downloadUrl);
    ZazreAuth.doUpdate(info); // 自动更新
}

直接 HTTP 调用

cURL

curl -X POST https://your-auth-server.com/api/update.php \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "your-site.com",
    "license_key": "ZAZRE-XXXX-XXXX-XXXX-XXXX",
    "version": "1.0.0",
    "product": "my-app"
  }'

直链下载

系统仅支持外部直链下载，管理员须为每个版本设置外部下载直链（如 CDN、对象存储 OSS/S3、GitHub Releases 等）。未设置直链的版本不会被推送给客户端。

使用直链时请注意： (1) 直链应始终可访问，否则客户端下载会失败；(2) 必须使用 HTTPS 链接；(3) 直链不经过令牌验证，建议使用带过期时间的签名 URL（如 OSS/CDN 签名链接）来保证安全性。

泛域名匹配

系统支持使用 *.example.com 格式的泛域名进行授权，一个泛域名记录可以匹配任意层级的子域名。

匹配规则

授权域名记录	客户端域名	是否匹配	匹配方式
`example.com`	`example.com`	是	精确匹配
`*.example.com`	`www.example.com`	是	泛域名匹配
`*.example.com`	`api.example.com`	是	泛域名匹配
`*.example.com`	`a.b.example.com`	是	泛域名匹配
`*.example.com`	`example.com`	是	泛域名匹配（根域名）
`*.example.com`	`other.cn`	否	不匹配

匹配优先级

当同时存在精确匹配和泛域名匹配时，精确匹配优先。系统还会尝试 www/非www 变体匹配。完整匹配顺序：

精确匹配 — 域名完全一致
www 变体匹配 — 库中有 www.example.com，用户请求 example.com 也能匹配（反之亦然，除 www 以外）
泛域名匹配 — 逐级匹配 *.父域

例如：

数据库中同时有 api.example.com（精确）和 *.example.com（泛域名）
客户端以 api.example.com 请求验证 → 匹配到精确记录 api.example.com
客户端以 www.example.com 请求验证 → 无精确匹配，回退到泛域名 *.example.com
库中有 www.zazre.cn，用户请求 zazre.cn → www 变体匹配到 www.zazre.cn

管理后台查询工具：在「域名管理」页面提供了「泛域名匹配查询」工具，输入任意子域名即可查看匹配到的所有授权记录，包括 www 变体。

SDK 集成指南

通用接入步骤：

将对应语言的 SDK 文件复制到项目目录
配置 license_key（或放置 license.key 文件）
在业务代码入口调用 authorize() 或 check()

建议在生产环境开启 签名验证 和 时间戳校验，防止请求被篡改和重放攻击。

PHP SDK

require_once 'ZazreAuth.php';
\Zazre\ZazreAuth::config([
    'license_key' => 'ZAZRE-XXXX-XXXX-XXXX-XXXX',
    'api_url'     => 'https://auth.yoursite.com/api/check.php',
]);
\Zazre\ZazreAuth::authorize(); // 未授权自动终止并显示友好页面

// 或者只检查不终止
$result = \Zazre\ZazreAuth::check();
if ($result['authorized']) {
    echo '客户: ' . $result['data']['customer_name'];
}

Python SDK

from ZazreAuth import ZazreAuth

auth = ZazreAuth()
auth.config(license_key='ZAZRE-XXXX-XXXX-XXXX-XXXX')
auth.authorize()  # 未授权 sys.exit(1)

result = auth.check()
if result['authorized']:
    print('通过:', result['data']['customer_name'])

Java SDK

ZazreAuth.config(Map.of(
    "license_key", "ZAZRE-XXXX-XXXX-XXXX-XXXX",
    "api_url", "https://auth.yoursite.com/api/check.php"
));
ZazreAuth.authorize(); // 未授权 System.exit(1)

ZazreAuth.Result r = ZazreAuth.check();
if (r.authorized) {
    System.out.println(r.data.customerName);
}

Node.js SDK

const ZazreAuth = require('./ZazreAuth');
const auth = new ZazreAuth({
    license_key: 'ZAZRE-XXXX-XXXX-XXXX-XXXX'
});
await auth.authorize(); // 未授权 process.exit(1)

Go SDK

import "your-project/zazre"

auth := zazre.NewAuth(zazre.Config{
    LicenseKey: "ZAZRE-XXXX-XXXX-XXXX-XXXX",
})
auth.Authorize() // 未授权 os.Exit(1)

Bash SDK

source ZazreAuth.sh
zazre_config "ZAZRE-XXXX-XXXX-XXXX-XXXX"
if zazre_authorize; then
    echo "授权通过，执行业务代码..."
fi

Webhook 通知

当授权状态发生变化（如过期、禁用、续期）时，系统会向你在后台配置的 Webhook URL 发送 POST 通知。

事件	说明
`license.expired`	授权到期
`license.revoked`	授权被禁用
`license.renewed`	授权续期成功
`license.created`	新授权创建

Webhook 请求体为 JSON 格式，包含 event、license_key、domain 和 timestamp 字段。建议验证请求签名。

错误码参考

错误码	说明	解决方案
1001	授权码不存在	检查授权码是否正确，或联系管理员重新发放
1002	授权已过期	在客户中心续期或联系管理员
1003	授权已被禁用	联系管理员了解禁用原因
1004	域名未授权	检查域名绑定是否正确，或添加域名白名单
1005	请求签名无效	检查签名算法和时间戳是否匹配
1006	请求已过期	客户端与服务器时间不同步，或请求被重放
2001	API 参数缺失	检查是否传入了 domain 和 license_key
5001	服务器内部错误	请联系技术支持

安全建议

HTTPS 传输： 生产环境必须部署 HTTPS，防止授权码在传输中被窃取。
签名验证： 开启 signature 参数，使用 HMAC-SHA256 对请求签名。
时间戳校验： 请求携带 timestamp，服务器拒绝超过 5 分钟的时间差请求。
域名绑定： 在后台严格绑定授权域名，防止授权码被滥用。
离线缓存： SDK 支持 24h 离线缓存，但服务器仍会在恢复连接后验证。
代码加密： 使用内置的加密工具对核心代码进行加密，防止逆向。