一、SDK 介绍
本 SDK 是「神优软件销售平台」官方提供的 PHP 客户端验证库,用于让你的 PHP 软件(CLI 脚本、Web 应用、WordPress 插件、本地工具等)能够接入许可证授权体系。
🎯 适用场景
CLI 脚本
Cron 任务、数据批处理、定时脚本
Web 应用
SaaS 化部署、客户自己部署的 PHP 应用
WordPress 插件
付费主题/插件授权
本地工具
个人 PHP 工具、命令行小工具
商业软件
企业级 PHP 软件交付
扩展模块
为已有系统加许可证层
✨ 核心特性
- 设备绑定:每张卡密只能绑定一台电脑,防止共享
- 离线缓存:本地加密缓存,24 小时内无需联网验证
- 心跳保活:防止服务器 300 秒无响应自动踢号
- 权限分级:VIP 等级、功能开关、使用次数等多维控制
- 签名验证:MD5 签名 + 时间戳防重放攻击
- Web/CLI 双模:浏览器自动弹激活窗口,命令行交互式输入
- 零依赖:仅依赖 PHP 7.0+ 和 cURL 扩展
🛡️ 安全机制
| 威胁 | 防护手段 |
|---|---|
| 伪造 API 请求 | MD5 签名 + 时间戳(5分钟过期) |
| 卡密共享 | 设备指纹绑定(CPU/MAC/SHA256) |
| 重放攻击 | Nonce 随机数 + 时间戳窗口 |
| 暴力请求 | 服务端 60 次/分钟限流 |
| 恶意踢号 | 60 秒顶号冷却 |
| 本地缓存破解 | XOR + SHA256 加密(绑定硬件) |
二、快速开始
只需 3 步 就能为你的 PHP 软件加上授权保护:
登录后台 → API 项目管理 → 新建项目 → 记下
project_id 和 api_secret
把
license_decorator.php 放到你的项目里,引入并实例化
在你 PHP 软件的入口文件(如
index.php)第一行加验证逻辑
完整示例(Web 版)
<?php // 第一步:引入 SDK require_once 'license_decorator.php'; // 第二步:配置(在后台「API 项目管理」获取) const PROJECT_ID = '1001'; const API_SECRET = 'f2113e6c61b86a7c61a74c3756b684fa'; const APP_NAME = '我的营销软件 v2.0'; const CACHE_SUFFIX = 'my_app_v2'; // 第三步:入口验证(带 Web 弹窗) $license = require_license(PROJECT_ID, API_SECRET, APP_NAME, CACHE_SUFFIX); // === 验证通过!运行你的软件 === $info = $license->getLicenseInfo(); echo "✅ 已授权 (剩 " . $info['remaining_days'] . " 天)\n"; // 权限控制 if (!$license->checkFeature('api_access')) { die('❌ 您的许可证未开通 API 功能'); } // ===== 你的业务代码 ===== runMySoftware();
完整示例(CLI 命令行版)
<?php // 命令行模式(cron 任务、批处理脚本) require_once 'license_decorator.php'; $license = new PhpLicenseValidator( '1001', 'f2113e6c61b86a7c61a74c3756b684fa', '我的批处理脚本', 'batch_v1' ); // 检查激活 if (!$license->check()) { echo "❌ 软件未授权\n"; $license->showActivationDialog(); // 命令行下交互式输入卡密 exit(1); } // 验证通过,执行批处理 echo "✅ 已授权,开始处理...\n"; processData();
三、安装部署
📦 SDK 文件清单
下载 SDK 压缩包 后,解压得到以下文件:
php-sdk/
├── license_decorator.php ← SDK 主文件(必需)
├── README.md ← 简易说明
└── example/
├── web_demo.php ← Web 模式示例
├── cli_demo.php ← CLI 模式示例
└── wp_plugin_demo.php ← WordPress 插件示例
🚀 部署步骤
your_project/license_decorator.php
db/ 目录需要可写权限(755 或 777)
php -m | grep curl 检查
某些加密函数依赖 OpenSSL
⚙️ 环境要求
| 项目 | 最低版本 | 推荐版本 |
|---|---|---|
| PHP | 7.0 | 7.4 / 8.0+ |
| cURL 扩展 | 必需 | 任意版本 |
| OpenSSL | 推荐 | 任意版本 |
| 磁盘空间 | 1MB | — |
db/ 目录生成 license_cache_*.bin 和 license_cache_*.json 缓存文件。该目录必须可写,否则无法保存授权状态。
四、使用方法
1️⃣ 完整集成流程
<?php require_once 'license_decorator.php'; // 实例化(4个参数都必填) $license = new PhpLicenseValidator( '1001', // 项目 ID 'f2113e6c61b86a7c61a74c3756b684fa', // API 密钥 '我的软件名称', // 软件名 'app_v1' // 缓存后缀(多产品区分用) ); // 检查是否已激活 if (!$license->check()) { // 未激活 → 弹窗(Web)或交互输入(CLI) $license->showActivationDialog(); exit; } // 已激活 → 获取详情 $info = $license->getLicenseInfo(); print_r($info); /* 输出示例: Array ( [is_validated] => 1 [is_vip] => 1 [license_code] => DAY-A5F3B9D2C1E7F4G6 [expires] => 2027-04-22 12:00:00 [remaining_days] => 201 [license_type] => 年卡 [status] => active ... ) */
2️⃣ 获取后台配置信息
project_id 和 api_secret?
- 登录你的「神优后台」:
https://apk.com/admin/login.php?key=密钥 - 进入「🔧 API 项目管理」
- 找到你要授权的项目,记下:
- 项目 ID(如
1001) - API 密钥(如
f2113e6c61b86a7c61a74c3756b684fa)
- 项目 ID(如
- 把这两个值配置到 SDK 中
3️⃣ 修改 API 服务器地址
默认指向 http://apk.com/api.php。如果你的服务端部署在其他域名,第 5 个参数:
$license = new PhpLicenseValidator( '1001', 'f2113e6c61b86a7c61a74c3756b684fa', '我的软件', 'v1', 'https://api.your-domain.com/api.php' // 自定义 API 地址 );
4️⃣ 主动调用 API(高级用法)
// 检查某个卡密是否存在(不绑定) $result = $license->checkLicense('DAY-A5F3B9D2C1E7'); print_r($result); // 续期卡密(旧卡密换新卡密) $result = $license->renewLicense('OLD-1234-5678', 'NEW-ABCD-EFGH'); // 解绑当前设备(换电脑用) $result = $license->deactivateLicense(); // 心跳保活(防长时间运行被踢下线) $result = $license->heartbeat();
五、权限控制
SDK 支持「按功能开关」和「按数量限制」两种权限控制方式。
🎛️ 功能权限(布尔型)
| 方法 | 说明 |
|---|---|
checkFeature('export_excel') | 是否允许导出 Excel |
checkFeature('batch_import') | 是否允许批量导入 |
checkFeature('advanced_analytics') | 是否允许高级分析 |
checkFeature('api_access') | 是否允许 API 调用 |
checkFeature('custom_template') | 是否允许自定义模板 |
// 场景:导出按钮根据权限启用/禁用 if (!$license->checkFeature('export_excel')) { echo "⚠️ 您的许可证不支持导出 Excel\n"; // 或者在 UI 上禁用按钮 } else { exportToExcel($data); }
📊 数量限制(数值型)
| 方法 | 默认值 | 说明 |
|---|---|---|
getMaxProjects() | 999 | 最大可管理的项目数 |
getMaxServers() | 999 | 最大可管理的服务器数 |
getLimit('daily_queries') | 99999 | 每日查询次数上限 |
getLimit('concurrent_users') | 99 | 最大并发用户数 |
// 场景:限制用户最多创建 N 个项目 $maxProjects = $license->getMaxProjects(); $currentCount = getCurrentProjectCount(); if ($currentCount >= $maxProjects) { die("❌ 已达项目数上限 ($currentCount/$maxProjects),请升级许可证"); } // 场景:每日查询次数限制 $dailyLimit = $license->getLimit('daily_queries', 99999); $todayUsed = getTodayUsageCount(); if ($todayUsed >= $dailyLimit) { die("❌ 今日使用次数已达上限 ($todayUsed/$dailyLimit)"); }
🎯 VIP 等级(多档套餐)
$info = $license->getLicenseInfo(); if ($info['is_vip']) { echo "🎖️ VIP 用户\n"; echo " 等级:" . $info['vip_info']['level'] . "\n"; echo " 到期:" . $info['vip_info']['expiry'] . "\n"; // 启用 VIP 专属功能... }
六、API 参考
📌 构造函数
PhpLicenseValidator( string $projectId, // 项目 ID string $projectApiSecret, // API 密钥 string $appName = '软件名称', // 软件名 string $cacheSuffix = '', // 缓存后缀 string $apiBase = '...' // API 地址 )
🔧 核心方法
| 方法 | 返回 | 说明 |
|---|---|---|
check() |
bool |
一键检查激活状态(自动用缓存或在线验证) |
activateLicense($code) |
array |
激活卡密(绑定当前设备) |
validateLicenseOnline($code) |
array |
在线验证卡密有效性 |
deactivateLicense($code) |
array |
解绑设备(换电脑时用) |
renewLicense($old, $new) |
array |
续期(旧卡密换新卡密) |
heartbeat($code) |
array |
心跳保活(防踢号) |
showActivationDialog() |
void |
弹出激活窗口(自动适配 Web/CLI) |
getLicenseInfo() |
array|null |
获取当前许可证详细信息 |
getDeviceFingerprint() |
string |
获取设备指纹(32位MD5) |
getDeviceInfo() |
array |
获取完整设备信息(指纹+MAC+硬件ID) |
🔐 权限方法
| 方法 | 返回 | 说明 |
|---|---|---|
checkFeature($name) | bool | 检查功能权限 |
getLimit($name, $default) | int | 获取数量限制 |
getMaxProjects() | int | 最大项目数 |
getMaxServers() | int | 最大服务器数 |
getRequiredPermissions() | array | 完整权限配置字典 |
💾 缓存方法
| 方法 | 说明 |
|---|---|
loadCache($forceOnlineCheck) | 从本地加载缓存(24小时内有效) |
saveCache() | 保存当前状态到本地 |
clearCache() | 清除本地缓存 |
🛠️ 全局函数
// 一行接入(带激活窗口) $license = require_license('1001', 'secret', '软件名', 'v1'); // 返回 LicenseValidator 实例 // 如果未激活,自动弹出激活窗口,用户激活后自动 reload
七、源码加密(防破解)
require_license())。SDK 本身 是必须明文的(否则 PHP 解释器无法运行),但你的业务代码必须加密。
🛡️ 推荐方案:Swoole Compiler
Swoole Compiler 是国产的 PHP 字节码加密工具,加密后完全不可还原,性能损耗 < 5%。
步骤 1:购买编译器
- 官网:https://www.swoole.com/swoole-cl
- 价格:¥599 / 年(个人开发者版)
- 企业版:¥2999 / 年
步骤 2:加密你的业务代码
# 在开发机上加密(加密的是你的业务代码,不是 SDK) ./swoole-compiler encrypt \ --input my_app.php \ --output my_app.compiled.php \ --license my_license.key # 加密整个目录 ./swoole-compiler encrypt \ --src-dir ./my_software \ --dst-dir ./my_software_encrypted \ --license my_license.key
步骤 3:客户端部署
# 1. 在客户服务器安装 Loader wget https://compiler.swoole.com/static/loader-v4.5.0-linux-x64.tar.gz tar -xzf loader-*.tar.gz # 2. 复制到 PHP 扩展目录 cp loader/swoole_loader.so /usr/lib/php/extensions/ # 3. 修改 php.ini echo "extension=swoole_loader.so" >> /etc/php.ini echo "swoole_loader.license=/path/to/license.key" >> /etc/php.ini # 4. 部署加密后的代码 scp my_app.compiled.php user@server:/path/to/app/ # 5. 加密后的代码由 Swoole Loader 解释执行
📝 加密策略建议
| 文件 | 是否加密 | 原因 |
|---|---|---|
license_decorator.php(SDK) | ❌ 不加密 | PHP 解释器需要直接执行 |
你的业务主文件(如 my_app.php) | ✅ 加密 | 核心商业逻辑 |
配置文件(如 config.php) | ✅ 加密 | 包含敏感信息 |
第三方库(如 vendor/) | ❌ 不加密 | 已开源,无需加密 |
| 前端资源(CSS/JS/HTML) | ❌ 不加密 | 前端本身可见 |
heartbeat(),如果服务器端检测到异常(如缓存文件被改),立即吊销许可证。
八、实战案例
📌 案例 1:WordPress 插件授权
// 在插件主文件 my-plugin.php require_once plugin_dir_path(__FILE__) . 'sdk/license_decorator.php'; $license = new PhpLicenseValidator( '1001', 'f2113e6c61b86a7c61a74c3756b684fa', '我的 WordPress 插件', 'wp_plugin_v1' ); if (!$license->check()) { add_action('admin_notices', function() { echo '<div class="notice notice-error">请先激活插件许可证 <a href="' . admin_url('?page=my-plugin-activate') . '">立即激活</a></div>'; }); return; // 不加载插件功能 } // 已激活,加载插件功能 require_once plugin_dir_path(__FILE__) . 'includes/main.php';
📌 案例 2:Crontab 定时任务
#!/usr/bin/env php <?php // /usr/local/bin/my-cron.php require_once '/var/www/myapp/sdk/license_decorator.php'; $license = new PhpLicenseValidator( '1001', 'f2113e6c61b86a7c61a74c3756b684fa', '定时任务脚本', 'cron_v1' ); if (!$license->check()) { file_put_contents('/var/log/myapp-error.log', date('Y-m-d H:i:s') . ' 软件未激活,跳过执行' . PHP_EOL, FILE_APPEND); exit(1); } // 执行定时任务 processScheduledTasks(); // 每次执行心跳(防长时间未访问被踢) $license->heartbeat();
📌 案例 3:数据导出工具(带权限)
<?php require_once 'license_decorator.php'; $license = require_license( '1001', 'f2113e6c61b86a7c61a74c3756b684fa', '数据导出工具', 'export_v1' ); // 权限检查 if (!$license->checkFeature('export_excel')) { http_response_code(403); die('<h1>403 权限不足</h1><p>您的套餐未包含此功能</p>'); } // 导出逻辑 header('Content-Type: application/vnd.ms-excel'); header('Content-Disposition: attachment; filename="data.xls"'); // 输出 Excel 数据 echo "ID\t名称\t价格\n"; foreach (getData() as $row) { echo "{$row['id']}\t{$row['name']}\t{$row['price']}\n"; }
📌 案例 4:带使用次数统计
<?php require_once 'license_decorator.php'; $license = require_license('1001', 'secret', '查询工具'); // 检查每日查询次数 $dailyLimit = $license->getLimit('daily_queries', 100); // 读取今日已用次数(你自己存到文件/数据库) $counterFile = 'db/usage_count_' . date('Ymd') . '.txt'; $used = (int)(file_exists($counterFile) ? file_get_contents($counterFile) : 0); if ($used >= $dailyLimit) { die("❌ 今日查询次数已达上限 ($used/$dailyLimit),明天再来"); } // 执行查询... $result = doQuery($_GET['keyword']); // 增加计数 file_put_contents($counterFile, $used + 1); echo "✅ 查询成功(今日 $used/$dailyLimit)\n"; print_r($result);
九、常见问题
❓ Q1: 卡密激活后多久需要联网一次?
A:本地缓存默认有效期 24 小时。超过 24 小时后下次启动会自动在线验证一次。如果你的软件需要 7×24 不间断运行(如 SaaS 服务),建议每 12 小时主动调用一次 heartbeat()。
❓ Q2: 客户换电脑了怎么办?
A:让客户在你的「神优后台」→ 订单管理 → 「解绑设备」按钮,或在软件内调用:
$license = new PhpLicenseValidator(...); $result = $license->deactivateLicense(); // 当前设备解绑
❓ Q3: API 服务器挂了怎么办?
A:SDK 会自动 fallback 到本地缓存。如果缓存也在 24 小时内,则继续放行(用户体验更好);如果都失效,则拒绝服务。建议在 check() 调用前先 load_cache_no_check() 兜底。
❓ Q4: 客户修改了 SDK 文件怎么办?
A:SDK 本身是明文的,理论上客户可以注释掉 require_license() 调用绕过验证。建议:
- 在你的业务代码中也加入服务端 API 调用(即使 SDK 被绕过,关键功能也会失效)
- 使用 Swoole Compiler 加密业务代码
- 服务端定期审计可疑许可证
❓ Q5: API 签名失败(code: INVALID_SIGNATURE)?
A:常见原因:
- 系统时间不准(签名含 timestamp) → 同步服务器时间
- API 密钥错误 → 重新从后台复制
- 服务端使用 HTTPS 但客户端强制 HTTP → 改
$apiBase为 HTTPS
❓ Q6: 如何更新 SDK 版本?
A:下载最新版 license_decorator.php 直接覆盖即可,向后兼容。
❓ Q7: 能否自定义激活窗口样式?
A:可以。继承 PhpLicenseValidator 重写 showActivationDialog() 方法,或在调用前输出自定义 HTML。
十、更新日志
v1.0.0 (2026-10-03)
- ✅ 首版本发布
- ✅ 支持 Web / CLI 双模式
- ✅ 设备指纹 + 离线缓存 + 心跳保活
- ✅ 7 个 API 动作(check/validate/activate/deactivate/renew/heartbeat)
- ✅ 完整权限控制(功能开关 + 数量限制)
- ✅ 一键装饰器函数
require_license()
📮 技术支持
- 📖 文档:https://github.com/yourname/license-sdk-php
- 🐛 问题反馈:GitHub Issues
- 💬 QQ 群:123456789(神优软件用户群)
- 📧 邮件:support@apk.com