接入文档 · LOAKPHP

接入文档

安装 loader、启用扩展、部署容器产物与授权绑定，10 分钟完成接入。

01环境要求

运行端只安装 loader 扩展；容器产物由授权服务签发后放入项目目录。两者可以部署在同一台机器，也可以完全分离。

运行环境	Linux x86_64，php-fpm 或 CLI
PHP 版本	7.1 – 8.5，NTS 构建
扩展目录	可通过 php -i \| grep extension_dir 确认
权限	安装扩展需 root 或管理员权限
其他组件	授权与容器产物由 auth.loakphp.com 提供

02安装 loader 扩展

下载与目标 PHP 版本匹配的扩展包，安装后通过 php --ri 确认版本与容器能力。

shell · loader 1.4.2

# 1. 从下载页获取对应版本的 loader（以 PHP 8.3 为例）
#    文件名形如 loakphp_loader-php8.3-nts-linux-x86_64.so

# 2. 放入扩展目录并统一命名
sudo cp loakphp_loader-php8.3-nts-linux-x86_64.so \
  /www/server/php/83/lib/php/extensions/no-debug-non-zts-20230831/loakphp_loader.so

# 3. 写入独立 ini，避免与其他扩展冲突
echo "extension=loakphp_loader.so" | sudo tee /www/server/php/83/etc/php.d/99-loakphp.ini

# 4. 重启并验证
sudo systemctl restart php-fpm-83
php --ri loakphp_loader

当前公开发布提供 Linux x86_64（NTS）构建；ZTS、Windows 与其他架构可通过联系页面申请。

03启用与自检

确认扩展被正确加载，并记录版本号，便于后续排查。

shell · verify

# 确认扩展已加载
$ php -m | grep loakphp_loader

# 查看版本与容器能力
$ php --ri loakphp_loader | head -6
loakphp loader => enabled
loader version => 1.4.2
container format => LKP1 v2

# 核对安装包指纹
$ sha256sum loakphp_loader-php8.3-nts-linux-x86_64.so

如果 php -m 中没有出现扩展名，先检查 ini 是否被扫描、扩展目录是否正确。

04部署容器产物

容器目录按常规方式部署即可，模板、静态资源与配置文件保持明文。

shell · deploy

# 容器文件由授权服务签发，按项目目录放置即可
$ rsync -av ./protected/ deploy@HOST:/var/www/app/

# 模板、静态资源与配置文件保持明文
# 首次访问后检查装载日志
$ tail -n 50 /var/www/app/storage/logs/app.log | grep LOAK

若启用 OPcache，建议为容器目录单独设置 revalidate 策略，避免缓存与容器版本不一致。

05授权与域名绑定

授权服务负责域名绑定、签发与续期；容器在装载阶段本地校验授权描述，不依赖实时外网请求。

auth · 授权服务

# 授权在授权服务中管理：
# https://auth.loakphp.com

# 绑定域名、查看到期时间与授权状态
# 容器装载时本地校验授权描述，不依赖实时外网请求

授权描述参与容器校验，修改后需要重新签发；到期前 30 天可续期。前往 https://auth.loakphp.com 管理授权。

06错误码

运行端错误码统一为 LK-E1xxx 段位，日志中会附带容器路径与目标版本。

错误码	含义	处理建议
`LK-E1001`	容器版本不受当前 loader 支持	升级 loader 或使用匹配版本重新签发
`LK-E1002`	容器校验失败，可能被改动	重新签发并核对 SHA-256
`LK-E1003`	授权已到期	在授权服务续期后重新签发
`LK-E1004`	当前域名或路径不在授权范围	在授权服务中补充域名或调整部署路径
`LK-E1005`	目标 PHP 版本与容器不匹配	按实际运行版本重新签发

07下一步

跑通链路之后，建议按顺序完成三件事：

在目标环境记录首载耗时与内存增量，作为后续版本对比基线。
把容器目录纳入发布流程，回滚时直接切换目录。
阅读版本矩阵，确认多版本交付策略。

需要帮助？遇到文档未覆盖的问题，把 loader 版本、PHP 版本与错误码一起发到 support@loakphp.com，我们会尽快回复。