小栈AI综合助手 — 安装使用说明

版本：3.0.0 | 适用于 PHP 8.0 ~ 8.3 | WordPress 6.0+

---

一、环境要求

项目	最低要求
PHP	8.0 及以上
WordPress	6.0 及以上
SourceGuardian Loader	16.0.2 及以上（必须）

---

二、安装 SourceGuardian Loader（关键步骤）

插件核心代码使用 SourceGuardian 16 加密保护，PHP 必须加载 SG Loader 扩展才能运行，否则会提示 “未安装 SourceGuardian Loader” 并无法使用。

2.1 检查是否已安装

进入 WordPress 后台 → 工具 → 站点健康 → 信息 → 找到 PHP 扩展列表，搜索 SourceGuardian。如果有，说明已安装，跳过下面步骤。

也可以上传一个 phpinfo.php 文件到网站根目录，内容如下：

<?php phpinfo(); ?>

访问后 Ctrl+F 搜索 SourceGuardian，如果看到 SourceGuardian Loader Support => enabled 即为已安装。

2.2 宝塔面板安装（推荐）

宝塔面板已内置 SG Loader，一键安装即可。

1. 进入宝塔面板 → 软件商店
2. 找到正在使用的 PHP 版本（如 PHP 8.2）
3. 点击「设置」→「安装扩展」
4. 找到 SourceGuardian → 点击「安装」
5. 等待安装完成后，务必继续看下方 2.2.1 和 2.3 节配置！

2.2.1 重要：移除 shell_exec 禁用

宝塔面板默认将 shell_exec 列入 PHP 禁用函数，但 SG Loader 解码加密文件必须使用此函数。不解除会导致插件启用后网站白屏/500错误，是最常见的部署故障。

操作步骤：

1. 宝塔面板 → 软件商店 → 找到对应 PHP 版本 → 设置
2. 点击「禁用函数」标签
3. 在列表中找到 shell_exec，点击「删除」
4. 返回「服务」→ 重启 PHP

验证是否生效（SSH 执行）：

php -r "echo function_exists('shell_exec') ? '可用' : '已禁用';"

输出「可用」即为成功。

2.3 重要：添加 Hybrid VM 配置（必做！）

安装扩展后，还需要在 php.ini 中添加一行配置，否则加密文件无法解密运行。

操作步骤：

1. 宝塔面板 → 软件商店 → PHP → 设置 → 配置文件
2. 拉到文件最底部，另起一行粘贴：

sourceguardian.enable_vm_hybrid=1

3. 保存 → 重启 PHP

注意：php.ini 有两份（CLI 命令行和 FPM Web 服务），宝塔面板的「配置文件」修改的是 FPM 版本。如果你的网站使用 CLI 模式运行 PHP 任务，也需要在 /www/server/php/XX/etc/php-cli.ini 中加同样一行。

2.3.1 验证 SG Loader 是否加载成功

配置完成后，务必验证，不要等到启用插件报错才回头检查。

SSH 终端执行：

php -m | grep SourceGuardian

如果输出 SourceGuardian 即为成功。如果无输出，请逐项检查：

• 扩展文件是否放在正确的目录（通过 php -i | grep extension_dir 查看）
• php.ini 中 extension= 后面写的文件名是否与扩展目录下的实际文件名完全一致
• 修改后是否重启了 PHP
• 是否改对了 PHP 版本对应的 php.ini（宝塔装了多个 PHP 时容易改错版本）

💡 注意：搜索时用完整单词 SourceGuardian，不要用 sg 或 ixed，因为模块在 PHP 中的注册名是完整拼写。

2.3.2 关于文件名版本号

下载的 Loader 文件名通常带版本号，如 ixed.8.3.lin（PHP 8.3）、ixed.8.2.lin（PHP 8.2）。

有两种配置方式：

• 方式一（推荐）：php.ini 中直接写完整文件名，如 extension=ixed.8.3.lin
• 方式二：创建不带版本号的符号链接，然后写短名。SSH 执行 ln -sf ixed.8.3.lin ixed.lin，php.ini 写 extension=ixed.lin

两种方式选其一，关键是要保证 php.ini 里写的文件名在扩展目录下真实存在。文件名不一致是”扩展安装了但插件仍然报错”的常见原因。

2.4 手动安装（非宝塔环境）

如果未使用宝塔面板，按以下步骤操作：

第一步：下载 Loader

访问 SourceGuardian 官方下载页：

https://www.sourceguardian.com/loaders/download.php

根据你的 PHP 版本、操作系统、线程安全类型选择对应的 Loader 文件。文件名格式为：

ixed.8.x.lin    （Linux 64位）
ixed.8.x.win    （Windows 64位）

第二步：放置文件

将下载的文件放到 PHP 扩展目录（通过 php -i | grep extension_dir 查看路径）。

第三步：编辑 php.ini

在 php.ini 末尾添加：

extension=ixed.8.2.lin    ; 文件名根据实际下载的文件名填写
sourceguardian.enable_vm_hybrid=1

第四步：重启 PHP 服务

# 宝塔
/etc/init.d/php-fpm-82 restart

# 通用
systemctl restart php8.2-fpm

---

三、安装插件

1. WordPress 后台 → 插件 → 安装插件 → 上传插件
2. 上传 xzdbk-ai.zip
3. 点击「现在安装」
4. 安装完成后点击「启用」

插件启用后，左侧菜单会出现「小栈AI

---

四、激活授权

1. 进入「小栈AI」→「授权管理」
2. 输入授权码
3. 点击「激活」

未激活状态下部分功能受限。

---

五、常见问题

Q1：启用插件后网站白屏 / 500 错误

按以下顺序逐项排查，每一项都要检查，大部分情况前两步即可解决：

第1步：检查 shell_exec 是否被禁用（🔥 最高频故障点）

宝塔面板默认将 shell_exec 列入禁用函数，而 SG Loader 解码加密文件必须使用此函数。

# SSH 执行
php -r "echo function_exists('shell_exec') ? 'OK' : '被禁用-需要移除';"

如果输出「被禁用」：宝塔 → 软件商店 → PHP → 设置 → 禁用函数 → 删除 shell_exec → 重启 PHP。

第2步：检查 SG Loader 是否真正加载

php -m | grep SourceGuardian

无输出说明 SG Loader 未加载。请回到本文第 2.3.1 节逐项检查：扩展文件是否正确放置、php.ini 中文件名是否与实际一致、sourceguardian.enable_vm_hybrid=1 是否添加、修改后是否重启了 PHP。

第3步：检查 CLI 和 FPM 的 php.ini 是否都改了

宝塔面板「配置文件」修改的是 FPM（Web 服务）版 php.ini。插件的后台队列任务（Action Scheduler Worker）使用 CLI 模式运行，如果 CLI 的 php.ini（通常为同目录下的 php-cli.ini）没改，后台任务执行时会失败。

验证 CLI 是否加载了 SG：

php -m | grep SourceGuardian

如果 FPM 加载了而 CLI 没加载，需要对 php-cli.ini 也做同样的配置。

第4步：开启 WordPress 调试日志

在 wp-config.php 中添加以下代码：

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);

重现错误后查看 /wp-content/debug.log，里面会记录具体的致命错误信息，可据此进一步排查。

第5步：检查 Loader 版本是否匹配

php -i | grep "Loader Version"

确保版本 ≥ 16.0.2。如果 PHP 是 8.3，建议使用 Loader 17.0+ 以获得更好的兼容性。

Q2：PHP 8.3 网站偶尔 502 错误

PHP 8.3 + SourceGuardian Loader 16.0.2 存在已知兼容性问题，可能导致 PHP 工作进程偶发崩溃。解决方案：

在 PHP-FPM 配置文件中添加进程回收机制。

宝塔路径：软件商店 → PHP 8.3 → 设置 → 配置文件 → 找到 pm.max_requests 行（如没有则在末尾添加）：

pm.max_requests = 500

保存并重启 PHP。这会让每个工作进程处理 500 个请求后自动重启，避免内存问题累积导致崩溃。

Q2.1：PHP 8.3 启动后出现 JIT 警告，是否影响使用？

启用 SG Loader 后，执行 php -v 会显示：

Warning: JIT is incompatible with third party extensions
that setup user opcode handlers. JIT disabled.

这是正常现象，不影响任何功能。 SG Loader 与 PHP JIT 加速不兼容，PHP 会自动关闭 JIT。网上很多教程把这个当错误处理，实际上完全不需要任何干预。

Q3：提示“运行错误[19]：Loader版本过旧”

你的 SourceGuardian Loader 版本低于加密时使用的版本。前往官网下载最新版 Loader：

https://www.sourceguardian.com/loaders/download.php

Q4：重新安装或迁移网站后插件无法使用

1. 检查新服务器的 PHP 版本是否 ≥ 8.0
2. 重新安装 SourceGuardian Loader
3. 重新添加 sourceguardian.enable_vm_hybrid=1
4. 使用授权码重新激活

---

六、版本信息

项目	版本 / 值
插件版本	3.1.8
加密方案	SourceGuardian 16
Loader 最低版本	16.0.2（推荐 17.0+）
兼容 PHP	8.0 / 8.1 / 8.2 / 8.3
兼容 WP	6.0+

七、注意事项

1. 插件文件受版权保护，禁止反编译、破解或二次分发
2. 更换域名或服务器前，请先在后台解绑授权，迁移后重新激活
3. PHP 8.3 用户建议配置 pm.max_requests = 500 参数
4. 授权码与域名绑定，一个授权码仅限一个站点使用
5. 宝塔面板用户请注意：面板在某些操作后可能重置 php.ini。如果插件突然无法使用，首先 SSH 执行 php -m | grep SourceGuardian 确认 SG Loader 仍在加载状态。
6. 插件后台队列（Action Scheduler Worker）依赖 PHP CLI 模式。如果后台任务异常，检查 CLI 的 php.ini（php-cli.ini）是否也配置了 SG Loader 和 Hybrid VM。
7. PHP 8.3 用户建议在 PHP-FPM 配置中设置 pm.max_requests = 200~500，让工作进程定期回收，避免长时间运行导致的内存问题。

相关阅读：WordPress插件