客户端开发者技术交付说明
客户端开发者（技术对接）
域名白名单授权系统 · 角色交付说明
一、最简单接入（三行即可）
把 client-skeleton/ 整目录复制为你的项目，在入口包含守卫（骨架已内置）：
define('AUTH_SERVER_URL', 'https://shouquan.ie14.cn/api/check.php');
require_once __DIR__ . '/auth-guard/guard.php';
AuthGuard::check();校验失败（未授权/过期/吊销/验签不过）时守卫输出锁定页并终止脚本。AuthGuard::check() 必须在任何业务代码之前执行，不要包 try/catch 吞掉终止。
二、可配置常量（require guard.php 之前 define）
| 常量 | 默认 | 说明 |
|---|---|---|
AUTH_SERVER_URL | https://shouquan.ie14.cn/api/check.php | 校验接口地址（必填） |
AUTH_ONLINE_MODE | best_effort | best_effort：连不上走缓存兜底；strict：连不上立即锁 |
AUTH_GRACE_DAYS | 7 | 离线宽限天数，超时即锁 |
AUTH_WL_CACHE_FILE | auth-guard/.wl_cache | 签名应答缓存（需可写） |
AUTH_LAST_OK_FILE | auth-guard/.last_online_ok | 最近成功校验时间戳（需可写） |
AUTH_LOCK_PAGE_CUSTOM | '' | 自定义锁页模板路径，留空用默认（去 Logo 增值服务用） |
本模式依赖联网（curl 扩展），客户服务器必须能访问授权后台。
三、读取授权信息（业务层）
AuthGuard::info()读取tier/quota。AuthGuard::quota()读取额度上限（0 = 不限），用于实现额度/档位逻辑。
四、部署域名
- 把项目部署到的域名告诉服务商加入白名单；或在商城付款后自动开通白名单。
- 部署域名必须与白名单精确匹配（含/不含
www要一致）。
五、部署必做：屏蔽敏感文件
- Apache：已随附
.htaccess（禁*.pem、禁缓存文件、禁目录列表），无需操作。 - Nginx / 宝塔（
.htaccess不生效）：把nginx.example.conf内容粘贴到「站点设置 → 伪静态」。核心：*.pemdeny（公钥）/config/deny/auth-guard/下的.wl_cache、.last_online_okdeny
验证：浏览器访问 域名/auth-guard/public_key.pem 与 域名/auth-guard/.wl_cache，必须 403/404。
六、验签机制（防伪造）
校验应答带 RSA 私钥签名（SHA256+RSA），签名串：whitelist|{domain}|{valid:1/0}|{expires_at}|{ts}。客户端用 public_key.pem 验签并核对域名，伪造服务器/劫持 hosts 无法通过。
七、私有化 / 防破解（增值服务）
购买对应增值服务后，按交付指南替换密钥或混淆守卫。public_key.pem 须与所用后台同源（私有化换成客户自有公钥）。
八、锁定原因速查
| reason | 含义 | 处理 |
|---|---|---|
trial_expired | 自动试用已到期 | 后台「试用域名」续费转正 |
expired | 白名单已到期 | 后台改到期日 |
revoked | 已吊销 | 后台「恢复」 |
bad_server_sig | 验签失败 | 检查 public_key.pem 是否与服务端配对 |
offline | 连不上且无缓存（或 strict） | 检查出网/后台可用性 |
offline_grace | 连续离线超宽限 | 恢复网络连通 |
九、常见问题
- 本地开发：给开发域名（如
localhost）单独加白名单，或走自动试用。 - 客户换域名：新域名未授权自动试用；付费白名单让服务商加新域名。
- 续期要给客户发东西吗？ 不用，后台改到期日即可。
- 服务端换密钥？ 必须把新
public_key.pem覆盖到所有客户项目。 - 交付客户的代码：不要遗留
.wl_cache、.last_online_ok缓存文件。