DEVELOPER

开发文档

青点教务云 V4.0 的部署激活流程与在线验证 API 对接说明，面向学校信息中心与运维人员

📦 部署激活 🔌 API 对接 ⚠️ 错误码 💡 接入建议

一、部署激活（.lic 文件）

购买并下载授权文件

在授权商城选好档位完成支付（余额 / 微信扫码 / 线下转账均可），系统秒级自动签发授权。登录用户中心 → 我的授权，点击「下载 .lic 文件」。

获取本机机器码

运行青点教务云 V4.0 安装包，启动页会显示本机机器码（MC- 开头）。购买时填写的机器码必须与此一致，否则校验不通过。

放置授权文件

将下载的 .lic 文件放入教务云安装目录（与应用同目录）。文件包含 RS256 签名的授权信息：授权号、版本、绑定机器码、有效期。

qdedu-cloud/
├── edu-cloud.jar        # 教务云应用
├── license.lic          # ← 授权文件放这里
└── application.yml

启动并确认激活

启动教务云，控制台输出授权校验通过即激活成功。若提示校验失败，请核对：① 文件名未改动；② 机器码一致；③ 未过期未吊销（可在首页输入授权号核验）。

💡 换服务器？ 不用重新购买：用户中心 → 我的授权 → 更换机器码，填新机器码保存后重新下载 .lic 即可。每月限 2 次，全程留痕。

二、在线验证 API

教务云服务器端可调用本接口实时校验授权状态。相比仅校验本地 .lic 文件，在线接口可感知吊销、过期、机器码变更，建议配合使用（本地秒验 + 在线兜底）。

请求地址

GEThttps://auth.qd-edu.cn/api/license/verify 或 POSThttps://auth.qd-edu.cn/api/license/verify

无需登录、无需鉴权 Key，参数通过 URL Query 或 Form 表单传递。/api/verify 为等价短地址。

请求参数

参数	必填	类型	说明
`licenseId`	是	string	授权号，LIC- 开头，如 `LIC-20261026-267E62`
`machineCode`	否	string	当前服务器机器码。传入后会做一致性比对，不一致返回 MACHINE_MISMATCH

响应示例（生效中）

{
  "code": 200,
  "valid": true,
  "reason": null,
  "data": {
    "licenseId": "LIC-20261026-267E62",
    "customerId": "CUST-2026-0001",
    "customerName": "测试大学",
    "edition": "BASIC",
    "editionName": "基础版",
    "type": "SUBSCRIPTION",
    "validTo": "2027-10-25",
    "machineCode": "MC-TEST-2026-0001"
  }
}

响应字段

字段	类型	说明
`code`	int	200 成功；400 参数缺失
`valid`	boolean	true 授权有效；false 无效（看 reason）
`reason`	string\|null	无效原因，见下方错误码表
`data.edition`	string	BASIC / PROFESSIONAL / PERPETUAL
`data.validTo`	string\|null	到期日 yyyy-MM-dd；null 表示永久授权

调用示例

cURL：

curl "https://auth.qd-edu.cn/api/license/verify?licenseId=LIC-20261026-267E62&machineCode=MC-TEST-2026-0001"

Java（HttpClient，教务云内置可复用）：

HttpClient client = HttpClient.newHttpClient();
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://auth.qd-edu.cn/api/license/verify"
        + "?licenseId=" + URLEncoder.encode(licenseId, UTF_8)
        + "&machineCode=" + URLEncoder.encode(machineCode, UTF_8)))
    .timeout(Duration.ofSeconds(5))
    .GET().build();
HttpResponse<String> resp = client.send(req, HttpResponse.BodyHandlers.ofString());
// 解析 JSON：valid=true 放行；false 时按 reason 处理

PHP：

$ch = curl_init("https://auth.qd-edu.cn/api/license/verify");
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => http_build_query([
        'licenseId'   => $licenseId,
        'machineCode' => $machineCode,
    ]),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 5,
]);
$resp = json_decode(curl_exec($ch), true);
if (!empty($resp['valid'])) {
    // 授权有效
}

三、无效原因（reason）对照

reason	含义	建议处理
`LICENSE_NOT_FOUND`	授权号不存在	提示客户核对授权号；可能是伪造
`REVOKED`	授权已被吊销	立即停止服务并联系商务（欠费/退款场景）
`EXPIRED`	授权已过期	引导用户中心续费，续费后自动恢复
`MACHINE_MISMATCH`	机器码与授权绑定不符	系统被迁移到未授权服务器；如为客户正常换机，请其走换绑流程

四、接入建议

校验频率：启动时必校验一次，运行期每 1–6 小时轮询一次即可，无需高频调用。
失败策略：接口网络不通时不要立即锁死系统，建议放行并记日志，连续失败超过 72 小时再降级提示，避免授权站网络抖动影响客户正常使用。
宽限期：EXPIRED 建议给 3 天宽限提示，期满未续费再限制功能。
安全：本接口为只读公开接口，请勿在教务云侧泄露客户授权号明文日志；HTTPS 直连，无需额外加签。
对账：客户/授权台账可在管理后台随时导出 CSV，供合同与审计核对。

还没有授权？

前往授权商城公开核验授权