ZFShang 完整安装部署指南

从零开始，手把手教你搭建 ZFShang 授权管理系统。包含宝塔面板配置、系统安装、Loader 扩展编译、代码加密全流程

适用于 PHP 7.4 ~ 8.3 / 宝塔面板 / Nginx / MySQL

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` `gd` `redis` `curl` `sodium`

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 环境

登录宝塔面板 -> 软件商店：

安装 Nginx（推荐 1.22 或以上）

安装 MySQL（推荐 8.0，至少 5.7）

安装 PHP 8.1（推荐，也可选 7.4 / 8.0 / 8.2 / 8.3）

安装 phpMyAdmin（可选）

提示：安装 PHP 后，去 PHP 设置 -> 安装扩展，确保 openssl、pdo_mysql、mbstring、fileinfo、gd、redis 已启用（缺 redis 会导致安装向导环境检查不通过，缺 pdo_mysql 会报 could not find driver）。

2 站点创建 & 配置

2.1 创建站点

宝塔面板 -> 网站 -> 添加站点：

域名：填写你的域名，测试环境可填 IP

根目录：自动生成（如 /www/wwwroot/zfshang.cn）

PHP 版本：选择已安装的 PHP 版本

数据库：选择 MySQL，记录下数据库名、用户名、密码

2.2 上传源码

使用宝塔文件管理器上传 ZIP 并解压，或通过 Git 克隆到网站根目录。

2.3 配置 Nginx 伪静态

宝塔面板 -> 网站 -> 点击域名 -> 伪静态：

location / {
    try_files $uri $uri/ /index.php?$query_string;
}
location ^~ /config/  { deny all; return 404; }
location ^~ /storage/ { deny all; return 404; }
location ^~ /app/     { deny all; return 404; }
location ~ /\.(env|log|sql|lock)$ { deny all; return 404; }
# Loader 下载（配合后台下载限流生效，可选）
location ^~ /downloads/loaders/ {
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root/index.php;
    fastcgi_param DOCUMENT_ROOT $document_root;
    include enable-php-81.conf;  # 81 换成站点实际 PHP 版本
    # ⚠ socket 路径写错会直接 502 Bad Gateway
}

注意：完整配置见 install/nginx.conf.example。敏感目录用 ^~ 前缀匹配而非正则 ~，避免误伤 public 内的正常路径。502 排查：确认此段 fastcgi_pass / include enable-php-XX.conf 与站点实际 PHP 版本一致（宝塔：站点→配置文件→PHP 版本）。

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

2.5 修改网站运行目录（关键，安装前必须完成）

关键步骤：必须将网站运行目录指向 public/ 文件夹，否则无法访问安装向导！

宝塔面板 -> 网站 -> 点击域名 -> 网站目录 -> 选择 /www/wwwroot/zfshang.cn/public -> 保存。

原因：系统入口 index.php 位于 public/ 内，项目根目录没有 index.php。运行目录不指向 public，访问根域名会得到 403/404。

3 数据库创建 & 系统安装

3.1 创建数据库

方式一：宝塔面板 -> 数据库 -> 添加数据库（如果建站时已创建，跳过）

方式二：phpMyAdmin -> 新建数据库，字符集选择 utf8mb4_general_ci

3.2 运行安装向导

# 浏览器访问站点根域名（运行目录已指向 public/，自动进入安装向导）
https://你的域名/

注意：安装向导由 public/index.php 检测到配置文件缺失后自动加载。不要访问 /install/——该路径会被伪静态规则拦截（403/404）。

第一步：环境检查，确保所有必须项绿色（含 Redis 扩展）

第二步：填写数据库、Redis 信息

第三步：设置管理员账号和密码（至少 8 位）

安装完成后：系统自动创建数据表，跳转到登录页。使用管理员账号登录。

安全提示：安装完成后建议立即删除或重命名 install/ 目录。

若页面 403：检查站点根目录下是否有 public/.user.ini（宝塔防跨站配置），若其 open_basedir 路径与实际部署路径不一致，删除或修正该文件后重启 PHP。

3.3 部署 Loader（如需代码加密）

见下方「步骤 4：Loader 扩展编译 & 部署」。如不使用代码加密功能可跳过。

4 Loader 扩展编译 & 部署

需要代码加密功能时必做！如果不需要代码加密可跳过。

4.1 安装 Docker（推荐）

# 宝塔：软件商店 -> 搜索「Docker」-> 安装「Docker 管理器」
# 或命令行：
yum install -y docker && systemctl enable --now docker      # CentOS
apt install -y docker.io && systemctl enable --now docker    # Ubuntu/Debian

Docker 方案在 glibc 2.17/2.28 容器内编译，产物兼容所有 Linux（含 CentOS 7 / 腾讯 / 阿里自研老系统），不受本机系统版本影响。若不想装 Docker，可跳过本节直接看 4.3 本机编译（产物受服务器 glibc 版本限制）。

4.2 一键编译 Loader（Docker，推荐）

cd /www/wwwroot/zfshang.cn/loader/docker
./build.sh

首次自动构建编译镜像（约 10~20 分钟，之后秒级），随后一键编译 PHP 7.4~8.4 全部版本并自动拷贝到 public/downloads/loaders/。可用 --php=7.4,8.1 只编指定版本、--name=完整扩展名 指定 Loader 扩展名（多授权点/多厂商时）。详见 loader/docker/README.md。

4.3 本机编译 Loader（不装 Docker 时）

cd /www/wwwroot/zfshang.cn/loader
chmod +x build.sh
./build.sh --all

输出 done: 3 ok / 2 skip 表示编译完成。skip 表示该 PHP 版本未安装，属正常。--all 会自动编译全部已安装版本（7.4~8.4）并拷贝到 public/downloads/loaders/。⚠️ 本机编译受服务器 glibc 版本限制：服务器系统较新时，产物在 CentOS 7 等老系统会报 GLIBC_2.x not found，对外分发请优先使用 4.2 的 Docker 方案。

4.4 验证下载路径

ls -la /www/wwwroot/zfshang.cn/public/downloads/loaders/

确认能看到 blue_rpbp_loader-*.so 文件。若需要为多个授权点/厂商编译不同扩展名的 Loader，使用 ./build.sh --all --name=完整扩展名（如 --name=pingguo_loader）；不传则默认读后台「系统设置」中的 Loader 扩展名。

4.5 客户侧安装 Loader

# 1. 下载对应 PHP 版本的 loader（如 PHP 8.1）
# 下载地址：https://你的域名/downloads/loaders/blue_rpbp_loader-81.so

# 2. 安装
PHP_VER=$(php -r 'echo PHP_MAJOR_VERSION.".".PHP_MINOR_VERSION;')
PHP_CMP=$(echo $PHP_VER | tr -d '.')
cp blue_rpbp_loader-$PHP_CMP.so $(php -r 'echo ini_get("extension_dir");')/blue_rpbp_loader.so
echo 'extension=blue_rpbp_loader' >> /www/server/php/$PHP_VER/etc/php.ini

# 3. 重启 PHP
/etc/init.d/php-fpm-$PHP_CMP restart

# 4. 验证
php -m | grep blue_rpbp_loader

5 加密密钥配置 & 初次打包

5.1 验证密钥

系统首次运行时已自动生成加密密钥，位于 storage/.encryption_key。

5.2 管理后台配置

登录后台 -> 侧边栏「代码加密」

确认加密功能已开启

检查 RSA 签名密钥状态

5.3 添加产品 & 初次打包

侧边栏「产品管理」-> 添加产品

填写产品名称和产品代码（product_code）

侧边栏「授权打包」-> 选择产品 -> 上传 PHP 项目 ZIP -> 打包

下载产物包含：加密代码、License 文件、安装说明

6 后台主要设置清单

页面	功能	说明
`/admin/settings`	系统设置	站点名称、SMTP 邮件、支付设置（支付宝/微信/QQ）、登录/产品/重要/下载设置
`/admin/vip`	VIP 套餐	VIP 价格、时长、排序
`/admin/products`	产品管理	添加/编辑产品、授权参数
`/admin/licenses`	授权管理	手动添加授权、吊销、查看详情
`/admin/keys`	密钥管理	RSA/KEK 密钥轮换、弃用、Loader 下载
`/admin/package`	授权打包	上传 ZIP -> 注入 SDK -> 加密 -> 下载

7 常见问题排查

Q: 安装时提示 "fileinfo 扩展未安装" 或 "Redis 扩展未通过"

宝塔面板 -> 软件商店 -> PHP 设置 -> 安装扩展 -> 搜索对应扩展（fileinfo / redis）-> 安装 -> 重启 PHP。Redis 是安装向导必查项，缺它环境检查不通过。

Q: 访问站点 403 Forbidden，无法进入安装向导

① 检查网站运行目录是否已指向 public/；② 检查站点根目录是否有 public/.user.ini，其 open_basedir 路径若与实际部署路径不符会导致 PHP 拒绝读取 install 目录，删除或修正后重启 PHP。

Q: 安装完成后间歇性 403 / 405，过 1 分钟自动恢复

服务器防火墙（宝塔 Nginx 防火墙 / CC 防护）将你误判为攻击并临时拉黑约 60 秒。到「Nginx 防火墙 -> 拦截日志」确认，将自己的 IP 加入白名单或调高 CC 阈值。与程序代码无关。

Q: 编译 Loader 时报错

确保三个 C 源文件（zfshang_loader.c、crypto.c、license.c）已上传到 loader/ 目录。推荐用 Docker 一键编译：cd loader/docker && ./build.sh（容器内自带 gcc / PHP dev，不依赖服务器环境）；也可用 ./build.sh --all 本机编译。

Q: 打包后客户代码运行报错

检查：1) 是否安装了正确版本的 Loader 扩展；2) License 文件在项目根目录；3) 域名与 License 绑定一致。

Q: 加密密钥需要备份吗？

必须备份！密钥文件位于 storage/.encryption_key。丢失意味着所有已加密代码无法解密。

Q: 如何更换加密密钥？

/admin/keys -> 点击「更新 KEK 对称主密钥」。注意：旧加密文件需重新打包。

Q: 邮件发送失败

/admin/settings 配置 SMTP。推荐使用 QQ邮箱/163邮箱的 SMTP 服务（需开启授权码）。