1. 接口概览

全部接口位于总后台域名 https://zht.yuxian.cyou/api/ 下，支持 POST JSON 与 POST 表单， 响应统一为 UTF-8 JSON，字段包含 code、msg、data、timestamp、sign。

2. 通用约定

公共请求参数

安全策略

• 时间戳窗口默认 300 秒，可在总后台「系统设置」调整；两端服务器需保持时间同步。
• nonce 一次性写入数据库并保留 10 分钟，重复请求直接拒绝。
• 接口按来源 IP 做每分钟频率限制，默认 120 次。
• 响应 sign 为 data 的 HMAC 值，分后台须校验后再采信，防止中间人篡改。
• 授权码、域名、来源 IP 任一命中黑名单，接口直接返回 blacklist。

3. 签名算法

签名原文按固定顺序以竖线连接：action|license_key|domain|timestamp|nonce|mode|[附加字段...]。 附加字段由具体接口定义，缺失时按空字符串参与拼接。校验接口在请求携带 current_version 时， 该字段作为附加字段追加到末尾；未携带时按基础六字段拼接即可。

$fields = ['verify', $license_key, $domain, $timestamp, $nonce, $mode];
if ($current_version !== '') {
    $fields[] = $current_version;   // 与请求中实际携带的字段保持一致
}
$canonical = implode('|', $fields);
$secret = ($mode === 'activate') ? $license_key : $license_secret;
$sign   = hash_hmac('sha256', $canonical, $secret);

响应验签：

$payload = json_encode($resp['data'], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
$ok = hash_equals(hash_hmac('sha256', $payload, $secret), $resp['sign']);

4. 授权校验 verify.php

请求示例

{
  "license_key": "ZY-ABCD-EFGH-JKLM-NPQR",
  "domain": "kefu.example.com",
  "timestamp": 1730000000,
  "nonce": "a1b2c3d4e5f6...",
  "mode": "verify",
  "current_version": "v1.0.0",
  "sign": "..."
}

成功响应 data 字段

安装激活（mode=activate）时，若域名未绑定且未超出 max_domains，接口会自动完成首次绑定； 运行期校验则要求域名必须已绑定且处于生效状态。

5. 版本检查 check_update.php

附加签名字段：current_version。签名原文：

check_update|{license_key}|{domain}|{timestamp}|{nonce}|verify|{current_version}

返回 has_update、version（含 force 强制标记、package_hash、 min_version）、download_endpoint 与 need_pre_upgrade。强制更新版本优先下发。

6. 升级包下载 download_package.php

附加签名字段：version。校验通过且升级包存在时返回 application/zip 二进制流； 失败返回 JSON。分后台下载后须按 package_hash 做 SHA256 比对，不一致立即终止升级。

7. 状态上报 report_status.php

附加签名字段顺序固定：current_version|target_version|upgrade_status|message。 upgrade_status 取值：none / pending / success / failed / rollback。 总后台按「授权码 + 域名」唯一键登记，形成全网版本分布视图。

8. 站内通知 notice.php

附加签名字段：limit（1-20，默认 5）。返回 notices 数组，含标题、正文、类型、置顶与发布时间。

9. 状态码与分级

分后台采用四级失效控制：normal（正常）、warning（到期预警，仅提示）、 grace（断网缓冲 72 小时内只读降级）、disabled（业务停用）。

10. 完整对接示例（PHP / 分后台侧）

$payload = [
  'license_key' => $licenseKey,
  'domain'      => $domain,
  'timestamp'   => time(),
  'nonce'       => bin2hex(random_bytes(16)),
  'mode'        => 'activate',
];
$payload['sign'] = hash_hmac('sha256',
  'verify|'.$payload['license_key'].'|'.$payload['domain'].'|'
  .$payload['timestamp'].'|'.$payload['nonce'].'|'.$payload['mode'],
  $licenseKey);

$ch = curl_init('https://zht.yuxian.cyou/api/verify.php');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode($payload),
  CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_TIMEOUT => 15,
]);
$resp = json_decode(curl_exec($ch), true);
if ($resp['code'] === 0) {
    $secret = $resp['data']['secret'];  // 保存到本地配置
}