ZFShang 完整安装部署指南
从零开始，手把手教你搭建 ZFShang 授权管理系统。包含宝塔面板配置、系统安装、Loader 扩展编译、代码加密全流程
1 服务器 & 宝塔面板安装
1.1 服务器要求
| 项目 | 最低配置 | 推荐 |
|---|---|---|
| 操作系统 | CentOS 7 / Ubuntu 18.04 | CentOS 8+ / Ubuntu 22.04 |
| 内存 | 1 GB | 2 GB+ |
| 磁盘 | 20 GB | 40 GB+ SSD |
| Web 服务器 | Nginx 1.18+ | Nginx 1.22+ |
| PHP | 7.4 | 8.1 / 8.2 |
| 数据库 | MySQL 5.7 | MySQL 8.0 |
| PHP 扩展 | openssl pdo_mysql json mbstring fileinfo | |
1.2 安装宝塔面板
SSH 登录服务器后执行：
# CentOS / OpenCloudOS
yum install -y wget && wget -O install.sh https://download.bt.cn/install/install_6.0.sh && bash install.sh
# Ubuntu / Debian
wget -O install.sh https://download.bt.cn/install/install-ubuntu_6.0.sh && bash install.sh
提示：安装完成后会显示面板地址、用户名和密码，请务必保存。
1.3 安装 LNMP 环境
登录宝塔面板 -> 软件商店：
提示：安装 PHP 后，去 PHP 设置 -> 安装扩展，确保
openssl、pdo_mysql、mbstring、fileinfo 已启用。2 站点创建 & 配置
2.1 创建站点
宝塔面板 -> 网站 -> 添加站点：
/www/wwwroot/zfshang.cn）2.2 上传源码
使用宝塔文件管理器上传 ZIP 并解压，或通过 Git 克隆到网站根目录。
2.3 配置 Nginx 伪静态
宝塔面板 -> 网站 -> 点击域名 -> 伪静态：
location / {
try_files $uri $uri/ /index.php?$query_string;
}
location ~ /(config|storage|app|vendor|install)/ {
deny all; return 403;
}
location ~ \.env$ {
deny all; return 403;
}
2.4 设置文件权限
chown -R www:www /www/wwwroot/zfshang.cn
chmod -R 755 /www/wwwroot/zfshang.cn
chmod -R 777 /www/wwwroot/zfshang.cn/storage
chmod -R 777 /www/wwwroot/zfshang.cn/public/uploads
3 数据库创建 & 系统安装
3.1 创建数据库
方式一：宝塔面板 -> 数据库 -> 添加数据库（如果建站时已创建，跳过）
方式二：phpMyAdmin -> 新建数据库，字符集选择 utf8mb4_general_ci
3.2 运行安装向导
# 浏览器访问
https://你的域名/install/
安装完成后：系统自动创建数据表，跳转到登录页。使用管理员账号登录。
安全提示：安装完成后建议立即删除或重命名
install/ 目录。3.3 修改网站运行目录
关键步骤：必须将网站运行目录指向
public/ 文件夹！宝塔面板 -> 网站 -> 点击域名 -> 网站目录 -> 选择 /www/wwwroot/zfshang.cn/public -> 保存。
4 Loader 扩展编译 & 部署
需要代码加密功能时必做！如果不需要代码加密可跳过。
4.1 安装编译工具
# CentOS / OpenCloudOS
yum install -y gcc make openssl-devel
# Ubuntu / Debian
apt install -y gcc make libssl-dev
4.2 确认 PHP 开发工具
ls -la /www/server/php/81/bin/phpize
ls -la /www/server/php/82/bin/phpize
如果提示 No such file，在宝塔面板 -> 软件商店 -> 点击对应 PHP -> 安装扩展 -> 找到 phpize 并安装。
4.3 编译 Loader 扩展
cd /www/wwwroot/zfshang.cn/loader
chmod +x build.sh
./build.sh --all
输出
done: 3 ok / 2 skip 表示编译完成。skip 表示该 PHP 版本未安装，属正常。4.4 部署到下载路径
mkdir -p /www/wwwroot/zfshang.cn/public/downloads/loaders
cp /www/wwwroot/zfshang.cn/storage/loaders/zfshang_loader-php*.so \
/www/wwwroot/zfshang.cn/public/downloads/loaders/
4.5 客户侧安装 Loader
# 1. 下载对应 PHP 版本的 loader（如 PHP 8.1）
# 下载地址：https://你的域名/downloads/loaders/zfshang_loader-php8.1.so
# 2. 安装
PHP_VER=$(php -r 'echo PHP_MAJOR_VERSION.".".PHP_MINOR_VERSION;')
cp zfshang_loader-php$PHP_VER.so $(php -r 'echo ini_get("extension_dir");')/zfshang_loader.so
echo 'extension=zfshang_loader' >> /www/server/php/$PHP_VER/etc/php.ini
# 3. 重启 PHP
/etc/init.d/php-fpm-$PHP_VER restart
# 4. 验证
php -m | grep zfshang
5 加密密钥配置 & 初次打包
5.1 验证密钥
系统首次运行时已自动生成加密密钥，位于 storage/.encryption_key。
5.2 管理后台配置
5.3 添加产品 & 初次打包
6 后台主要设置清单
| 页面 | 功能 | 说明 |
|---|---|---|
/admin/settings | 系统设置 | 站点名称、SMTP 邮件、安全设置 |
/admin/payment | 支付设置 | 支付宝/微信支付通道配置 |
/admin/vip | VIP 套餐 | VIP 价格、时长、排序 |
/admin/products | 产品管理 | 添加/编辑产品、授权参数 |
/admin/licenses | 授权管理 | 手动添加授权、吊销、查看详情 |
/admin/encryption | 代码加密 | 加密开关、密钥轮换、Loader 下载 |
/admin/package | 授权打包 | 上传 ZIP -> 注入 SDK -> 加密 -> 下载 |
7 常见问题排查
Q: 安装时提示 "fileinfo 扩展未安装"
宝塔面板 -> 软件商店 -> PHP 设置 -> 安装扩展 -> 搜索 fileinfo -> 安装 -> 重启 PHP。
Q: 编译 Loader 时报错
确保三个 C 源文件（zfshang_loader.c、crypto.c、license.c）已上传到 loader/ 目录，且使用 ./build.sh --all 脚本执行。
Q: 打包后客户代码运行报错
检查：1) 是否安装了正确版本的 Loader 扩展；2) License 文件在项目根目录；3) 域名与 License 绑定一致。
Q: 加密密钥需要备份吗？
必须备份！密钥文件位于 storage/.encryption_key。丢失意味着所有已加密代码无法解密。
Q: 如何更换加密密钥？
/admin/encryption -> 点击「轮换加密密钥」。注意：旧加密文件需重新打包。
Q: 邮件发送失败
/admin/settings 配置 SMTP。推荐使用 QQ邮箱/163邮箱的 SMTP 服务（需开启授权码）。