文档

宝塔面板安装教程

宝塔官网
本文档以 Linux + 宝塔面板 为例，图文步骤请以实际面板版本为准

一、环境要求

软件版本要求说明
宝塔面板7.x 及以上Linux 面板，本文以 CentOS / Ubuntu 为例
Web 服务器Nginx 1.20+推荐 Nginx，本教程按 Nginx 编写
PHP8.1 / 8.2系统源码加密，必须使用 PHP 8.1+ 并安装 Swoole Loader 扩展
MySQL5.7+推荐 MySQL 8.0
域名已备案/已解析需将域名解析 A 记录指向服务器 IP

二、PHP 禁用函数要求

YPay 正常运行不依赖任何被禁用的高危函数（如 exec、shell_exec、system、pcntl_*、putenv 等），宝塔 PHP 的默认禁用函数列表保持默认即可，不影响安装与运行。

但以下函数必须启用（切勿加入禁用列表），否则会导致支付、回调、接口异常：

函数用途
curl_init / curl_exec支付回调、API 请求、通道通信（系统大量使用）
file_get_contents / file_put_contents远程获取、日志写入
fsockopen / stream_socket_client部分通道长连接通信

建议 PHP 开启的扩展：curl、fileinfo、openssl、mbstring、pdo_mysql、gd、opcache。

切勿在宝塔「PHP 8.1 → 设置 → 禁用函数」中勾选 curl_exec、curl_init、file_get_contents，否则会出现支付回调失败、二维码无法生成等问题。

三、第一步：安装 PHP 8.1 及 Swoole Loader 扩展

3.1 安装 PHP 8.1

  1. 登录宝塔面板，进入 软件商店；
  2. 搜索 PHP，安装 PHP 8.1（安装方式选编译安装）；
  3. PHP 8.1 安装完成后，在软件商店 PHP 8.1 → 设置 中安装以下扩展：fileinfo、opcache、redis（可选）、swoole_loader（见 3.2）。
缺少 Swoole Loader 扩展时，访问网站会跳转到 /help/swoole-compiler-loader.php 提示页，无法进入系统，必须按 3.2 完成安装。

3.2 安装 Swoole Compiler Loader 扩展（必须）

  1. 打开 Swoole 官方下载页：https://www.swoole.com/loader；
  2. 选择对应环境：Linux 64 位 + PHP 8.1，下载文件 swoole_loader81.so；
  3. 将 swoole_loader81.so 上传到 PHP 8.1 的扩展目录（NTS）： 
    /www/server/php/81/lib/php/extensions/no-debug-non-zts-20210902/
  4. 编辑 PHP 配置文件： 
    /www/server/php/81/etc/php.ini
    在文件末尾追加（也可在宝塔 PHP 8.1 → 设置 → 配置文件 中追加）： 
    extension=/www/server/php/81/lib/php/extensions/no-debug-non-zts-20210902/swoole_loader81.so
  5. 重启 PHP-FPM：进入宝塔 软件商店 → PHP 8.1 → 设置 点击 重启，或执行命令： 
    /etc/init.d/php-fpm-81 restart
  6. 验证扩展是否加载成功： 
    php -m | grep swoole_loader
# 输出 swoole_loader 即安装成功

四、第二步：上传源码

  1. 在服务器 /www/wwwroot 下创建站点目录（如 /www/wwwroot/ypay）；
  2. 将 YPay 源码压缩包上传到该目录，或在宝塔 文件 中上传压缩包；
  3. 右键压缩包点击 解压，解压后确认目录结构包含以下内容（入口在 public 目录）： 
    ypay/
├── app/          # 应用代码
├── config/       # 配置文件（database.php 由安装向导生成）
├── public/       # 网站运行目录（宝塔运行目录需选择 /public）
│   ├── index.php    # 前台入口
│   ├── admin.php    # 后台入口（/admin.php）
│   └── install.php  # 安装文件（首次安装运行）
├── view/         # 模板文件
├── vendor/       # 依赖包
└── think         # ThinkPHP 命令行入口

五、第三步：创建网站

  1. 进入宝塔 网站 → 添加站点；
  2. 填写信息：
    项目填写内容
    域名你的支付域名，如 pay.example.com
    根目录/www/wwwroot/ypay
    PHP 版本PHP-8.1
  3. 提交后到域名服务商处，把域名解析 A 记录 指向服务器公网 IP，等待生效。

六、第四步：设置运行目录（重要）

系统入口为 public/index.php，必须把运行目录设置为 /public，否则访问会出现 404 或无法加载。
  1. 进入 网站 → 设置 → 网站目录；
  2. 将 运行目录 选择为 /public；
  3. 将 防跨站攻击（open_basedir） 取消勾选（部分环境开启后会导致框架无法读取上级目录配置）；
  4. 点击保存。

七、第五步：设置伪静态（Nginx）

  1. 进入 网站 → 设置 → 伪静态；
  2. 选择 thinkphp 模板，或手动填写以下规则： 
    location / {
    if (!-e $request_filename){
        rewrite  ^(.*)$  /index.php?s=$1  last;
        break;
    }
}
  3. 保存后重启 Nginx 或重载配置。

八、第六步：配置 SSL 证书（HTTPS）

  1. 进入 网站 → 设置 → SSL；
  2. 选择 Let's Encrypt 免费证书，勾选域名后点击 申请；
  3. 申请成功后开启 强制 HTTPS；
  4. 也可填写已购买的证书（.pem / .key）。

九、第七步：设置目录权限

  1. 在宝塔 文件 中，将站点根目录所有者修改为 www；
  2. 确保以下目录可写（权限 755，属主 www）： 
    runtime/            # 框架运行时缓存/日志，必须可写
public/upload/      # 图片/上传文件目录，必须可写
extend/             # 扩展类库目录，必须可写
view/               # 模板（如写入模板缓存）

十、第八步：开始安装

  1. 浏览器访问安装地址： 
    http://pay.example.com/install.php
    或在宝塔 文件 中打开 install.php 按提示操作；
  2. 安装向导中填写数据库信息：
    项目填写内容
    数据库地址127.0.0.1
    数据库端口3306
    数据库名/账号/密码宝塔 → 数据库 中创建的信息
  3. 安装完成后，系统会自动生成 public/install.lock 锁定安装（或手动创建该空文件）；
  4. 删除或重命名运行目录下的 public/install.php（安全建议）。
拷贝安装提醒：若你是把已有站点的完整源码拷贝到新服务器安装，请务必先删除源码包中的 public/install.lock 文件（以及旧站生成的 config/database.php，安装向导会自动重新生成），否则访问 install.php 会提示"你已经成功安装"而无法进入安装流程。另外建议：清空 runtime/ 目录下的缓存文件（runtime/cache、runtime/route_list.php 等，框架会自动重建），并不要拷贝 backup_db/ 等数据库备份目录（内含旧站数据，属敏感信息）。

十一、安装完成

  1. 访问前台：https://pay.kls1314.com；
  2. 访问后台：https://pay.kls1314.com/admin.php，使用安装时设置的账号密码登录；
  3. 在后台 系统设置 中完成：站点名称、支付通道、对接密钥等配置。
💡 常见问题：
1. 访问跳转到 help/swoole-compiler-loader.php → Swoole Loader 扩展未安装，见 3.2 节；
2. 首页 404 → 运行目录未设置为 /public，见 第四节；
3. 接口 404 → 伪静态未配置，见 第五节；
4. 页面报"目录不可写" → runtime 目录权限不足，见 第七节；
5. 修改 PHP 代码后不生效 → 在 PHP 8.1 设置中关闭 opcache 或重载 PHP-FPM；
6. 登录或修改密码时报 "Data too long" → 数据库 admin_admin.password / ypay_user.password 字段为旧版长度（varchar(30)/varchar(50)），需手动执行以下 SQL 升级为 varchar(255)： 
ALTER TABLE `admin_admin` MODIFY COLUMN `password` varchar(255) NOT NULL;
ALTER TABLE `ypay_user`   MODIFY COLUMN `password` varchar(255) DEFAULT NULL;

十二、安全加固建议（可选）

  1. 在网站伪静态 / Nginx 配置中禁止上传目录执行 PHP，防止恶意文件执行： 
    location ~ ^/(upload|home)/.*\.(php|php[0-9]|phtml|pht)$ { return 403; }
  2. 数据库账号仅授予业务所需权限，可移除 DROP / ALTER / GRANT： 
    REVOKE ALTER, DROP ON `库名`.* FROM '数据库账号'@'localhost';
FLUSH PRIVILEGES;
  3. 建议配置每日自动备份数据库（宝塔 → 计划任务 → 备份数据库）。
上一篇 单笔订单查询