# 安装使用常见问题

# Q：安装环境检测提示缺少 xxx 扩展

编辑 php.ini 文件，找到 extension=xxx 相关配置，删除前面的分号 ; 。

例如：

;extension=exif.so

修改为

extension=exif.so

注意：Windows 系统的扩展后缀名为 .dll ，Linux 系统的扩展后缀名为 .so。

如果使用的是宝塔环境，只需要在 PHP → 设置 → 扩展管理启用该扩展。

以上操作完成后需要重启 PHP 服务才能生效。

# Q：安装环境检查提示缺少 xxx 函数

编辑 php.ini 文件，找到 disable_functions 并将其中的 xxx 函数移除，然后重启服务器即可。

为什么要使用这些函数？

proc_open : Laravel 执行 artisan 命令时需要用到
proc_get_status : Laravel 执行 artisan 命令时需要用到
putenv : Laravel 执行 artisan 命令时需要用到

如果使用的是宝塔环境，只需要在 PHP → 设置 → 禁用函数删除该函数。

以上操作完成后需要重启 PHP 服务才能生效。

# Q：安装模块后系统报错打不开

第1步，删除安装的模块 module/Xxx 目录，尝试刷新页面打开，如果打不开请执行第2步
第2步，清除缓存（删除 bootstrap/cache/ 和 storage/framework/cache/ 目录中的所有文件，注意不要删除目录本身），完成后重试

# Q：系统后台一键升级后系统报错

后台一键升级前请备份系统的完整文件和数据库，如果系统有自定义开发，升级不保证不会破坏系统原有数据。

如遇到报错打不开请按照如下步骤排查

第1步，打开调试日志（设置 .env 文件中 APP_DEBUG=true）
第2步，查看系统的错误信息，进行排查

# Q：Rewrite规则错误

在安装过程中，伪静态错误是经常会出现的问题，可以根据以下几种方式进行排错：

如果确信伪静态规则无误，可以通过访问 http://你的域名/install/ping 来访问，如果页面结果为OK则表示伪静态配置成功。

# 基础准备工作

基础工作的准备可以让你更快的定位错误

第一步，打开调试（配置 .env 文件中 APP_DEBUG=true），可以让错误显示在页面上，方便调试
第二步，配置服务器的网站根目录为 /www/example.com/public 或 D:/wwwroot/example.com/public，这一步很多人搞错，需要配置到 /public 目录

# Apache错误诊断

第一步，检测Apache是否支持mod_rewrite

在 Apache 的配置目录（通常为apache/conf/httpd.conf）中找到 rewrite_module 相关配置。

如果未开启（即 #LoadModule rewrite_module 前面有 # ），将前面的 # 号删除即可。
如果没有查找到，则到 LoadModule 区域，在最后一行加入 LoadModule rewrite_module modules/mod_rewrite.so。

完成以上操作后，重启Apache。

第二步，让apache服务器支持.htaccess

修改一下配置文件 httpd.conf ，用文本编辑器打开后，查找

Options FollowSymLinks
AllowOverride None

1
2

改为

Options FollowSymLinks
AllowOverride All

1
2

第三步，检查网站的 .htaccess 文件是否正确

部分软件配置时会覆盖 ModStart 默认的 .htaccess 文件，检查 public/.htaccess 文件是否为一下内容。

<IfModule mod_rewrite.c>
    <IfModule mod_negotiation.c>
        Options -MultiViews
    </IfModule>

    RewriteEngine On

    # Redirect Trailing Slashes If Not A Folder...
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^(.*)/$ /$1 [L,R=301]

    # Handle Front Controller...
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^ index.php [L]
</IfModule>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# Q：500错误/请求出现错误

# 查找应用日志

“500错误”或“请求出现错误”通常是程序处理发生错误。

需要查看 storage/logs/ 目录下的日志文件，找到当天最新的日志文件（如 laravel-2021-01-01.log），查看报错原因并解决。

错误日志需要定位到最新的错误日志，完整的一条错误日志通常如下格式所示，将该错误日志寻求其他开发者帮助（注意隐藏日志中的敏感信息）。

[2022-01-10 10:28:15] product.ERROR: xxx
Stack trace:
#0 xxx
#1 xxx
#2 xxx
#3 xxx
#4 xxx
#5 xxx
#x xxx

1
2
3
4
5
6
7
8
9

如果是发生在测试或开发环境，为了快速定位，可按照如下步骤排查

第1步，打开调试日志（设置 .env 文件中 APP_DEBUG=true）
第2步，直接访问页面查看错误信息，进行排查

如没有在系统目录找到记录的日志，请检查网站的目录权限是否正常，需要保证 PHP 的运行用户可以写入 storage/logs/ 目录。

# 查找服务日志

应用日志没有记录的情况下，通常是由于致命错误导致进程异常结束，可能的原因有内存溢出、底层库调用异常等。

Apache 环境

Apache的错误日志因配置各异，通常情况下

宝塔环境：/www/wwwlogs/
其他环境：自行诊断

Nginx 环境

Nginx的错误日志因配置各异，通常情况下

宝塔环境：/www/wwwlogs/
其他环境：自行诊断

# Q：网站加载速度很慢

使用现代化浏览器（推荐 Chrome ），在页面右击，点击 审查元素，切换到 Network ，查看导致页面加载慢的请求。

如果是静态资源（ js, css 等文件）加载速度慢，需要考虑增加服务器带宽或者使用 CDN 等提高静态资源访问速度。
如果是服务器的接口请求慢，可能是由于服务器配置、数据库连接速度等原因导致，需要咨询专业技术人员进行分析处理。

# Q：网站经过多层 Nginx 转发怎么配置

网站经过多层代理转发，通常在调用 action 方法生成 URL 时会出现异常。

这时可以通过在 .env 文件中设置如下两个配置来修正：

# 修正转发协议
FORCE_SCHEMA = http 或 https
# 修正用户访问URL
SUBDIR_URL = http://www.example.com

1
2
3
4

# Q：网站打不开，页面一直处于加载中

第一步，诊断是否为后端异常

参照 500错误-请求出现错误找到后端报错日志。

第二步，诊断是否为前端异常

使用现代化浏览器（推荐 Chrome ），在页面右击，点击 审查元素，切换到 Console ，查看是否有任何报错。

# Q：迁移环境后出现访问500错误

出现类似如下错误

Failed opening required 'xxx/module/Vendor/Web/routes.php' **
Stack trace:
#0 {main}

1
2
3

系统在运行时为了提高性能会缓存部分文件路径，在新环境如果路径不一致会导致缓存文件加载失败。只需要清除缓存即可，步骤如下：

Tips：删除目录中的所有文件，注意不要删除目录本身，完成后重试

删除 bootstrap/cache/ 中的所有文件
删除 storage/framework/cache/ 中的所有文件

# Q：模块市场出现502请求错误

访问模块市场提示「请求出现错误」，同时接口 后台/module_store/all 返回502错误。

如果其他页面访问正常，通常还会看到 PHP-PMF 的错误日志

[error] 2874786#0: *8565 recv() failed (104: Connection reset by peer) 
while reading response header from upstream ***

1
2

出现该错误，可能的原因有：

（1）TCP/IP问题

主要现象是在服务器完成下载内容之前连接被关闭，可能是网络问题，有可能导致的因素

最大传输单元问题
防火墙问题
未知网络问题

（2）内核Bug

请注意，在v2.6.17之后的一些Linux内核上，TCP窗口扩展存在一些问题，更多参考

（3）PHP 的 CURL 扩展 Bug

这些Bug可能是

我们曾经排查过几个类似问题，最终无果。该问题的影响因素较多，遇到该问题后，我们建议更换 PHP 版本。

# Q：忘记后台用户或密码怎么办？

为了安全起见，系统不支持后台用户密码的找回。如果忘记后台管理密码，只需要使用专业数据库工具修改后台用户表 admin_user 即可。

修改对应的用户 password 和 passwordSalt 字段。

password: 3c20ecadec461ce77179008a44850334
passwordSalt: KUBg1mMi5I

对应的登录密码为：123456

SQL参考

UPDATE admin_user 
    SET password='3c20ecadec461ce77179008a44850334',passwordSalt='KUBg1mMi5I'
    WHERE username = '用户名';

1
2
3

# Q：忘记后台路径怎么办？

查看网站根目录中的 .env 文件，查看 ADMIN_PATH 变量。

# 表示后台路径为 http://www.example.com/admin_xxx/
ADMIN_PATH=/admin_xxx/

1
2

# Q：always_populate_raw_post_data 配置

找到 php.ini 文件，进行如下配置

配置前

配置后（取消注释，去掉分号）

配置完成后需重新 PHP 服务。

宝塔环境

如果是宝塔环境，请在软件商店 → PHP → 设置 → 配置文件查找 always_populate_raw_post_data=-1 去掉之前的分号 ;，完成后操作服务 → 重载配置。

# Q：SSL certificate problem 错误

php在curl的时候报此错误：

cURL error 60: SSL certificate problem: unable to get local issuer certificate
 (see http://curl.haxx.se/libcurl/c/libcurl-errors.html)

1
2

解决办法：

1）从 https://curl.haxx.se/ca/cacert.pem 下载最新的cacert.pem

2）将以下行添加到php.ini（如果这是共享托管和没有访问php.ini然后你可以添加到.user.ini在public_html）

curl.cainfo=cacert.pem路径
# 如 Windows 配置
curl.cainfo=c:\wwwroot\cacert.pem
# 如 Linux 配置
curl.cainfo=/etccacert.pem

1
2
3
4
5

# Q：Ajax请求出现异常该如何排查或提问

第一步，修改 .env 文件，打开调试模式

# 配置调试模式未开启
APP_DEBUG=true

1
2

第二步，查看异常的请求信息（以 Chrome 浏览器为例）

在异常页面上右击，点击“检查”，网页底部弹出开发者工具。

点击 ① “网络” ② “全部”，点击 ③ 清空所有请求历史。

继续在页面上完成正常操作（比如提交动作），这时开发者工具会出现网络异常请求。

通过点击异常的网络请求，查看 Payload、Preview、Response 可以查看到请求数据和返回的错误信息。

在提问时候至少将上述的错误信息发送给其他小伙伴，别人才能帮你解答问题。

# Q：使用 MySQL 8.0 系统提示 Undefined property: stdClass::$column_name

ModStart 使用的 Laravel 5.1 框架默认不支持 MySQL 8.0 数据库，如果需要支持，请参考以下方法。

修改 vendor/laravel/framework/src/Illuminate/Database/Schema/Grammars/MySqlGrammar.php 文件，查找

public function compileColumnExists()
{
    return 'select column_name from information_schema.columns where table_schema = ? and table_name = ?';
}

1
2
3
4

修改为

## `column_name` 改为 `column_name as `column_name`
public function compileColumnExists()
{
    return 'select column_name as `column_name` from information_schema.columns where table_schema = ? and table_name = ?';
}

1
2
3
4
5

参考：Specify lower case column_name (fixes #20190) (opens new window)

# Q：如何在虚拟机上安装 ModStart

!!!郑重说明!!!：虚拟主机通常无法绑定运行目录到子目录，因此部署时会出现太多的安全隐患，配置比较繁琐，我们强烈不推荐！此方法只给技术爱好者作为测试参考，不再提供额外技术支持。

!!!重要的事!!!：在虚拟主机配置环境下，由于网站的所有数据都被暴露在浏览器访问路径下，因此要控制系统的系统文件不被访问到，当配置好之后，至少要测试一下路径不能直接被用户下载，否则系统将会受到严重威胁。

http://www.example.com/.env
http://www.example.com/storage/install.lock

!!!其他说明!!!：使用中遇到问题可直接百度/Google搜索 虚拟主机部署Laravel 关键词自行解决。

使用虚拟主机安装前，请先下载环境的检测程序进行空间自荐，不满足要求的虚拟主机将不能安装。

环境检测脚本：https://modstart.com/env_check.php.zip (opens new window)

如果虚拟主机根目录可以绑定到 <网站目录>/public 目录，请绑定到 <网站目录>/public 目录，随后执行 /install.php 安装向导。

如果虚拟主机根目录不支持绑定到 <网站目录>/public，需要按照如下配置：

配置 Nginx 或 Apache 服务器，请将网站的根目录配置到 <网站目录>，其中 Nginx 和 Apache 配置需要参考如下所示；

Nginx参考配置

server {
    listen       80;
    server_name  www.example.com;
    charset utf-8;
    index index.php index.html;
    root /var/www/html/www.example.com;
    autoindex off;

    location ^~ /.git {
        deny all;
    }

    location ^~ /.env {
        deny all;
    }

    location ^~ /storage/ {
        deny all;
    }

    location / {
        try_files /public$uri /public$uri/ /public/index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass   127.0.0.1:9000;
        fastcgi_index  index.php;
        fastcgi_param  PHP_VALUE  "open_basedir=/var/www/html/www.example.com/:/tmp/:/var/tmp/";
        fastcgi_param  SCRIPT_FILENAME  $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

Apache参考配置

httpd配置

<VirtualHost *:80>
　　ServerName www.example.com
　　DocumentRoot d:/wwwroot/example.com
</VirtualHost>

1
2
3
4

在网站系统根目录增加 .htaccess 文件

<IfModule mod_rewrite.c>
    RewriteEngine on
    RewriteCond %{REQUEST_URI} !^public
    RewriteRule ^(.*)$ public/$1 [L]
</IfModule>

1
2
3
4
5

IIS参考配置

web.config 配置

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <directoryBrowse enabled="false" />
    <rewrite>
      <rules>
        <rule name="Imported Rule 3" stopProcessing="true">
          <match url="^(.*)$" ignoreCase="false" />
          <conditions>
            <add input="{APPL_PHYSICAL_PATH}public/{R:1}" matchType="IsFile" ignoreCase="false" negate="true" />
          </conditions>
          <action type="Rewrite" url="/public/index.php" />
        </rule>
        <rule name="Imported Rule 1" stopProcessing="true">
          <match url="^(.*)$" ignoreCase="false" />
          <action type="Rewrite" url="/public/{R:1}" />
        </rule>
      </rules>
    </rewrite>
  </system.webServer>
</configuration>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

一些已知特殊环境配置说明

阿里云虚拟主机
- 需要开启PHP5.5版本；
- 由于阿里云禁用了putenv函数，这个函数尤为重要，所以需要打一个函数补丁，在程序最开始（public/index.php）的位置嵌入PHP代码，putenv 函数被禁用补丁代码如下

function env($key, $defaultValue = null)
{
    static $envFileConfig = null;
    if (null === $envFileConfig) {
        $envFileConfig = [];
        $envFile = file_get_contents(__DIR__ . '/.env');
        foreach (explode("\n", $envFile) as $line) {
            $line = trim($line);
            if (empty($line) || strpos($line, '#') === 0) {
                continue;
            }
            list($k, $v) = explode('=', $line);
            $envFileConfig[trim($key)] = trim($value);
        }
    }
    if (array_key_exists($key, $envFileConfig)) {
        return $envFileConfig[$key];
    }
    return $defaultValue;
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# Q：系统并发和数据支撑能力

经常遇到如下问题

这个系统支不支持 ****W 的数据？
这个系统支不支持 *** 的并发？
我有 ****W 的数据，能不能支持，会不会卡？

这里统一回复

本系统已有过日均新增数据百万+、单表总量10亿+、集群节点50+的生产环境经验，不同阶段均有不同阶段的技术方案，所以上述问题简单的回答是与不是均不妥。

我们推荐不同阶段关注不同阶段的重点，早期以快为主，后期以稳为主。不同阶段我们我们可以提供弹性的技术方案。

我们会永远对技术保持敬畏之心。

其他还可参考《性能报告参考》《系统运维优化参考》《云端部署参考》《系统安全参考》

# Q：open_basedir restriction in effect

提示如下错误

require(): open_basedir restriction in effect ***

open_basedir 设置是防跨站攻击的，出现这个错误需要进行如下设置。

Nginx 参考处理

在网站的 Nginx 配置增加

server {
    # ...
    location ~ \.php$ {
        # ...
        # 需要设置到网站根目录 www.example.com
        fastcgi_param  PHP_VALUE  "open_basedir=/var/www/html/www.example.com/:/tmp/:/var/tmp/";
        # ...
    }
    # ...
}

1
2
3
4
5
6
7
8
9
10

Apache 参考处理

在 http.conf 文件内加上

# 需要设置到网站根目录
php_admin_value open_basedir E:/wwwroot/www.example.com

1
2

# Q：从数据库读取 Int 型全部变成了 String 型

安装并启用 mysqlnd 扩展

# Q：宝塔等环境提示PHP未禁用危险函数

安装系统时通常会需要解禁 system,exec,passthru,shell_exec,popen,proc_open 等危险函数。部分集成环境会提示危险函数风险，通常可以如下方式解决：

该函数在通常只是在系统 系统安装/系统升级/模块安装/模块升级/模块禁用/模块删除 时使用到，日常系统的运行是不需要依赖该函数的，因此可以在常规运行中将危险函数加入到 disable_functions 中，只需要在必要的情况下再打开。具体为什么使用到这些函数可以参考 Q：安装环境检查提示缺少 xxx 函数。

# Q：宝塔限制目录问题 open_basedir restriction in effect

宝塔系统运行提示 open_basedir restriction in effect *** 这样的错误，通常是运行目录设置错误导致的，可对照下如下配置。

# Q：宝塔Windows版本下系统运行非常慢问题优化

提示：经测试，即使经过如上的优化过程，网站页面的执行时间也只达到 1000ms 左右。PHP 是为 Linux 而生，Windows 下 PHP 性能不如 Linux，强烈推荐使用 Linux 系统

检查数据库连接地址

Windows下数据库连接有域名解析问题，检查配置文件 <网站根目录>/.env，如果是 localhost ，修改为 127.0.0.1

# 如果配置是
DB_HOST=localhost
# 修改为
DB_HOST=127.0.0.1

1
2
3
4

安装opcache

Windows下PHP默认没有安装opcache，可通过宝塔软件商店安装

系统优化

① 打开 CMD 命令窗口 ② 进入到项目根目录，如 cd D:\wwwroot\example.com，默认如果是 C 盘需要切换盘符（执行 D:） ③ 运行 artisan 命令，如 D:\BtSoft\php\70\php.exe artisan optimize

提示：经测试，即使经过如上的优化过程，网站页面的执行时间也只达到 1000ms 左右。PHP 是为 Linux 而生，Windows 下 PHP 性能不如 Linux，强烈推荐使用 Linux 系统

# Q：Allowed memory size of xxx bytes exhausted

运行出现 Allowed memory size of xxx bytes exhausted，通常是由于内存不足导致的，可通过如下方式解决：

修改 php.ini 配置文件，增加 memory_limit 配置，如 memory_limit = 2048M，重启 PHP 服务

如果是宝塔环境，可参考如下修改

# Q：宝塔报错 Your request has been recorded. Tips from BT security !!!

如果开启了堡塔防入侵插件，默认会拦击非root用户的所有操作。可以通过增加需要运行的程序白名单即可

如要运行的命令为 /xxx/xxx start foo 填写 /xxx/xxx 到白名单即可。

# Q：宝塔启动错误 php / nginx 出现 error while loading shared libraries : xxx.so.x.x.x

通常是由于应用程序 php / nginx 找不到某个库导致。通常可通过 ① 手动安装库 ② 链接库操作来完成，其中 ② 是可选步骤。

yum install -y xxx
ln -s /usr/lib64/libxxx.so.x.x.x /usr/lib64/libxxx.so.x

1
2

# Q：安装引导界面点击下一步没反应

通常是由于页面静态资源加载异常或者页面有JS报错导致的。可以通过开发者工具查看是否有报错。

具体查看方法可参考 https://modstart.com/m/Vendor/doc/120 (opens new window)

# Q：收不到邮件是什么原因？

系统邮件发送采用了队列的方式（队列名为 default），如果你开启了队列而没有监听默认队列，则可能会出现收不到邮件的方式。

Laravel5

/xxx/bin/php /www/example.com/artisan queue:work database --queue=default --sleep=3 --tries=1 --timeout=86400

/xxx/bin/php 替换成 PHP 的运行路径，通常为 /usr/bin/php
default 为队列名称，默认为 default，还有其他队列如文档转换 FileConvert

Laravel9

/xxx/bin/php /www/example.com/artisan --queue=default queue:work database --once --sleep=3 --tries=1 --timeout=86400

/xxx/bin/php 替换成 PHP 的运行路径，通常为 /usr/bin/php
default 为队列名称，默认为 default，还有其他队列如文档转换 FileConvert

# Q：系统访问速度变慢该如何排查和解决？

# 第一步，查看 `Apache` 或 `Nginx` 的访问情况

这一个步骤主要需要了解网站的访问情况，如访问量、访问来源、访问IP、访问时间等，以便于后续的排查。

# 第二步，打开网站性能追踪

系统支持记录 LONG_REQUEST、LONG_SQL、MASS_REQUEST_SQL 多种指标，用于性能优化分析。通过在配置文件 .env 增加 TRACK_PERFORMANCE=true 开启新能追踪。

开启后，如果未生效可清除下缓存（删除 bootstrap/cache/ 目录下的所有文件），日志中可能会出现性能信息。

具体可参考性能追踪与优化 (opens new window)

# 第三步，查看日志进行优化

查看第二步网站性能追踪记录的日志信息，分别解决 LONG_REQUEST 慢请求、LONG_SQL 慢SQL 的问题。

# Q：安装引导页面点击下一步无效？

通常是由于页面静态资源加载异常或者页面有JS报错导致的，可尝试通过以下方法来解决：

检查是否有 JS 报错，看页面静态文件是否加载完成;
右击查看页面的HTML源代码，看是否渲染完成。

# 安装使用常见问题

# Q：安装环境检测提示缺少 xxx 扩展

# Q：安装环境检查提示缺少 xxx 函数

# Q：安装模块后系统报错打不开

# Q：系统后台一键升级后系统报错

# Q：Rewrite规则错误

# 基础准备工作

# Apache错误诊断

# Q：500错误/请求出现错误

# 查找应用日志

# 查找服务日志

# Q：网站加载速度很慢

# Q：网站经过多层 Nginx 转发怎么配置

# Q：网站打不开，页面一直处于加载中

# Q：迁移环境后出现访问500错误

# Q：模块市场出现502请求错误

# Q：忘记后台用户或密码怎么办？

# Q：忘记后台路径怎么办？

# Q：always_populate_raw_post_data 配置

# Q：SSL certificate problem 错误

# Q：Ajax请求出现异常该如何排查或提问

# Q：使用 MySQL 8.0 系统提示 Undefined property: stdClass::$column_name

# Q：如何在虚拟机上安装 ModStart

# Q：系统并发和数据支撑能力

# Q：open_basedir restriction in effect

# Q：从数据库读取 Int 型全部变成了 String 型

# Q：宝塔等环境提示PHP未禁用危险函数

# Q：宝塔限制目录问题 open_basedir restriction in effect

# Q：宝塔Windows版本下系统运行非常慢问题优化

# Q：Allowed memory size of xxx bytes exhausted

# Q：宝塔报错 Your request has been recorded. Tips from BT security !!!

# Q：宝塔启动错误 php / nginx 出现 error while loading shared libraries : xxx.so.x.x.x

# Q：安装引导界面点击下一步没反应

# Q：收不到邮件是什么原因？

# Q：系统访问速度变慢该如何排查和解决？

# 第一步，查看 Apache 或 Nginx 的访问情况

# 第二步，打开网站性能追踪

# 第三步，查看日志进行优化

# Q：安装引导页面点击下一步无效？

# 第一步，查看 `Apache` 或 `Nginx` 的访问情况