ALM (App License Manager) 多应用授权管理系统 — 客户端接入指南
本文档面向插件/主题开发者，帮助你将 ALM 授权保护集成到自己的产品中。
一、整体流程概览
┌──────────────┐ 生成 SDK ┌──────────────────┐ 引入文件 ┌──────────────────┐
│ ALM 后台管理 │ ───────────────> │ alm-guard.php │ ───────────────> │ 你的插件/主题 │
│ (服务端 Admin) │ 一键下载 │ (自动生成的文件) │ require_once │ (客户端产品) │
└──────────────┘ └──────────────────┘ └──────────────────┘
用户购买 → 获取授权码 → 在你的插件后台输入授权码 → 验证通过 → 功能解锁只需 3 步：
- 在 ALM 后台「应用管理」创建应用
- 点击「生成 SDK」下载
alm-guard.php - 在你的产品中
require这个文件，用on_authorized包裹功能代码
二、在 ALM 后台生成 SDK
2.1 创建应用
- 登录 ALM 管理后台，进入 应用管理
- 点击右上角 「新建应用」
- 填写信息：
- 应用名称：你的产品名（如「子比超级插件」）
- 应用类型：
WordPress 插件/WordPress 主题/PHP 应用 - 当前版本：如
1.0.0
- 保存后系统自动生成
App Key和App Secret
2.2 一键生成 SDK
- 在应用列表，找到你的应用，点击 「更多」→「生成 SDK」
- 在弹出窗口中：
- 确认应用类型
- 填写菜单名称（用户在后台看到的菜单名，留空默认「应用名 + 授权管理」）
- 点击 「一键生成并下载」
- 浏览器将下载一个
alm-guard.php文件
这个文件是完全自包含的，内嵌了 SDK 客户端、授权守卫、WordPress 自动集成、纯 PHP 兼容，无需任何额外依赖。
三、WordPress 插件接入（最常用）
3.1 文件放置
将 alm-guard.php 复制到你的插件目录下：
wp-content/plugins/your-plugin/
├── your-plugin.php ← 插件主文件
├── alm-guard.php ← 放在这里
├── includes/
│ └── main.php
└── ...3.2 修改插件主文件
在插件主文件（your-plugin.php）中：
“`php path=null start=null
<?php
/**
- Plugin Name: 你的插件名
- Version: 1.0.0
*/
// 第 1 步：引入授权守卫
require_once DIR . ‘/alm-guard.php’;
// 第 2 步：把所有功能代码放进 on_authorized 回调
// ★ 未授权时，下面的代码不会执行，插件功能自动锁定
alm_f47d39_on_authorized( function() {
// 你的插件功能全部写在这里
require_once __DIR__ . '/includes/main.php';
add_action('init', 'my_plugin_init');
add_action('admin_menu', 'my_plugin_menu');
add_filter('the_content', 'my_plugin_filter');});
> **注意：** `alm_f47d39` 是示例前缀，你实际下载的文件中会有不同的前缀。查看 `alm-guard.php` 头部注释即可看到你的实际前缀。
### 3.3 什么代码应该放在回调外面
以下代码**不需要**放在 `on_authorized` 回调里（放在外面即可）：php path=null start=null
// ✅ 这些放在 require alm-guard.php 之前或之后都可以
require_once DIR . ‘/vendor/autoload.php’; // Composer 自动加载
register_activation_hook(FILE, ‘my_activate’); // 激活钩子
register_deactivation_hook(FILE, ‘my_deactivate’); // 停用钩子
以下代码**必须**放在 `on_authorized` 回调里：php path=null start=null
// ✅ 这些必须放在 on_authorized 回调里
add_action(‘init’, …); // 注册自定义文章类型、路由等
add_action(‘admin_menu’, …); // 注册后台菜单
add_filter(‘the_content’, …); // 内容过滤器
add_shortcode(‘xxx’, …); // 短代码
require_once ‘includes/main.php’; // 功能模块
### 3.4 授权后的效果
**未授权时：**
- 后台顶部显示红色提醒横幅：「XXX 尚未授权，所有功能已锁定」
- 后台左侧出现授权管理菜单页（让用户输入授权码）
- 前台页脚显示未授权提示
- `on_authorized` 内的代码**不执行**，插件功能完全锁定
**授权后：**
- 红色横幅消失
- 所有功能正常加载
- 授权管理页面显示「已授权」状态
---
## 四、WordPress 主题接入
### 4.1 文件放置wp-content/themes/your-theme/
├── functions.php ← 主题功能文件
├── alm-guard.php ← 放在这里
├── style.css
└── …
### 4.2 修改 functions.phpphp path=null start=null
<?php
// 第 1 步：引入授权守卫
require_once DIR . ‘/alm-guard.php’;
// 第 2 步：把主题的功能代码放进 on_authorized 回调
alm_xxxxxx_on_authorized( function() {
// 主题功能模块
require_once __DIR__ . '/inc/theme-setup.php';
require_once __DIR__ . '/inc/customizer.php';
require_once __DIR__ . '/inc/widgets.php';});
> **提示：** 生成 SDK 时选择「WordPress 主题」类型，生成的文件会自动适配主题场景。
---
## 五、纯 PHP 应用接入
适用于非 WordPress 的 PHP 项目（如自研后台、SAAS 系统等）。
### 5.1 引入文件php path=null start=null
<?php
require_once DIR . ‘/alm-guard.php’;
// 方式一：使用 on_authorized 回调
alm_xxxxxx_on_authorized( function() {
// 你的应用功能
echo “应用已授权，功能正常运行！”;
});
// 方式二：手动判断
if ( alm_xxxxxx_is_authorized() ) {
// 已授权，执行功能
} else {
die(‘未授权，请先激活授权码’);
}
### 5.2 手动激活/撤销
纯 PHP 环境没有 WordPress 后台界面，你需要自行构建授权页面：php path=null start=null
// 激活授权
$result = ALM_XXXXXX_Guard::activate(‘你的授权码’);
if ($result[‘status’] === 1) {
echo $result[‘message’]; // “授权验证成功”
} else {
echo $result[‘message’]; // 错误信息
}
// 撤销授权
ALM_XXXXXX_Guard::deactivate();
### 5.3 纯 PHP 存储说明
在纯 PHP 环境下，授权数据存储在 `alm-guard.php` 同目录的 `.alm-guard-data.json` 文件中。请确保该目录可写。
---
## 六、API 参考
### 6.1 公开函数
| 函数 | 说明 | 返回值 |
|------|------|--------|
| `{prefix}_is_authorized()` | 检查当前是否已授权 | `bool` |
| `{prefix}_on_authorized($callback)` | 注册授权后执行的回调 | `void` |
### 6.2 Guard 类方法
| 方法 | 说明 | 返回值 |
|------|------|--------|
| `{PREFIX}_Guard::isAuthorized()` | 检查授权状态（带缓存） | `bool` |
| `{PREFIX}_Guard::activate($key)` | 激活授权 | `['status'=>0\|1, 'message'=>string]` |
| `{PREFIX}_Guard::deactivate()` | 撤销授权 | `bool` |
| `{PREFIX}_Guard::getDomain()` | 获取当前域名 | `string` |
### 6.3 Client 类方法
| 方法 | 说明 |
|------|------|
| `verify($licenseKey, $domain)` | 验证授权 |
| `activate($licenseKey, $domain)` | 激活（绑定域名） |
| `deactivate($licenseKey, $domain)` | 解绑域名 |
| `checkUpdate($currentVersion)` | 检查更新 |
### 6.4 常量配置
生成的 `alm-guard.php` 包含以下自动配置的常量：
| 常量 | 说明 |
|------|------|
| `{PREFIX}_SERVER` | 授权服务器地址 |
| `{PREFIX}_APP_KEY` | 应用密钥 |
| `{PREFIX}_APP_SECRET` | 应用签名密钥 |
| `{PREFIX}_APP_NAME` | 应用名称 |
| `{PREFIX}_MENU_TITLE` | 后台菜单名称 |
---
## 七、缓存机制
SDK 内置了智能缓存，避免每次页面加载都请求服务器：
- **授权成功缓存**：1 小时（`CACHE_TTL = 3600`）
- **授权失败缓存**：5 分钟（`FAIL_TTL = 300`）
- WordPress 环境使用 `transient`，纯 PHP 环境使用 JSON 文件
> 用户输入授权码后，会立即刷新缓存，无需等待。
---
## 八、高级用法
### 8.1 条件判断授权状态
在 `on_authorized` 回调之外，你也可以在任意位置判断授权状态：php path=null start=null
// 例如：根据授权状态显示不同内容
function my_shortcode_handler() {
if ( alm_xxxxxx_is_authorized() ) {
return ‘
高级功能内容’;
} else {
return ‘
请先授权以解锁此功能’;
}
}
add_shortcode(‘premium’, ‘my_shortcode_handler’);
### 8.2 锁定前台访问（可选）
默认情况下，未授权时前台仍可访问（只是功能被锁定）。如果你希望前台也完全不可用，打开 `alm-guard.php` 找到以下被注释的代码，取消注释即可：php path=null start=null
// 取消下面的注释以锁定前台：
if (!{PREFIX}_Guard::isAuthorized()) {
add_action(‘template_redirect’, function () {
wp_die(‘该站点使用的插件/主题尚未完成授权验证…’, ‘未授权’, [‘response’ => 403]);
});
}
### 8.3 自动更新检查
SDK 内置了更新检查接口，可用于实现插件自动更新：php path=null start=null
$client = new ALM_XXXXXX_Client(ALM_XXXXXX_SERVER, ALM_XXXXXX_APP_KEY, ALM_XXXXXX_APP_SECRET);
$update = $client->checkUpdate(‘1.0.0’); // 传入当前版本号
if (!empty($update[‘has_update’])) {
echo ‘有新版本: ‘ . $update[‘latest_version’];
echo ‘下载地址: ‘ . $update[‘download_url’];
}
---
## 九、完整接入示例
以一个 WordPress 插件 `my-awesome-plugin` 为例：php path=null start=null
<?php
/**
- Plugin Name: My Awesome Plugin
- Description: 一个需要授权的高级插件
- Version: 1.2.0
*/
// Composer 自动加载（不需要授权保护）
if (file_exists(DIR . ‘/vendor/autoload.php’)) {
require_once DIR . ‘/vendor/autoload.php’;
}
// 引入 ALM 授权守卫
require_once DIR . ‘/alm-guard.php’;
// 激活/停用钩子（不需要授权保护）
register_activation_hook(FILE, function() {
// 创建数据库表等
});
register_deactivation_hook(FILE, function() {
// 清理缓存等
});
// ★ 核心：所有功能代码放进授权回调
alm_a1b2c3_on_authorized( function() {
// 加载功能模块
require_once __DIR__ . '/includes/admin.php';
require_once __DIR__ . '/includes/frontend.php';
require_once __DIR__ . '/includes/api.php';
// 注册钩子
add_action('init', 'map_register_post_types');
add_action('admin_menu', 'map_register_admin_pages');
add_action('wp_enqueue_scripts', 'map_enqueue_assets');
add_filter('the_content', 'map_filter_content');
add_shortcode('awesome', 'map_shortcode_handler');});
“`
十、常见问题
Q: 授权码在哪里获取？
用户在你的 ALM 授权服务器注册账号 → 购买产品 → 在「用户中心 → 授权管理」获取授权码。
Q: 一个授权码能绑定多少个域名？
取决于你在服务端为该授权设置的最大域名数。默认 1 个，可在后台调整。
Q: 换了域名怎么办？
用户在「用户中心 → 授权管理」可以变更域名。或者在 WordPress 后台的授权管理页面点击「撤销授权」，然后在新域名重新激活。
Q: 插件更新后 alm-guard.php 会被覆盖吗？
不会。alm-guard.php 是你主动放入的文件，WordPress 插件更新不会影响它。但如果你的更新包包含了此文件，请确保版本一致。
Q: 授权验证失败怎么办？
- 检查网络：确保客户端能访问授权服务器
- 检查域名：确保授权码绑定的域名与当前域名一致（含端口号）
- 检查时间：服务器时间偏差过大可能导致签名验证失败
- 清除缓存：在 WordPress 中删除
{prefix}_aut_cachetransient
Q: 如何支持纯 IP + 端口的环境？
SDK 自动检测 HTTP_HOST，天然支持 192.168.1.100:8080 这种格式，无需额外配置。
Q: 离线环境如何处理？
授权缓存有效期内（默认 1 小时）无需联网验证。如果需要更长的离线时间，可以修改 alm-guard.php 中的 CACHE_TTL 常量值（单位：秒）。
十一、文件安全建议
- 不要将
alm-guard.php提交到公开仓库 — 它包含App Secret - 使用 PHP 加密工具 — ALM 内置了 PHP 加密功能，可对
alm-guard.php加密后再发布 - 定期轮换密钥 — 在 ALM 后台可以重置
App Secret，重置后需要重新生成 SDK
文档版本：2.1.7 | 最后更新：2026-02-22
暂无评论内容