开发者文档

# 开发常见问题

# Q：如何关闭富文本XSS

系统默认启用了全站XSS过滤，如果只是用CMS作为官网等后台产生富文本数据并且发现 HTML 样式丢失，可以选择关闭XSS过滤。

安全提示：XSS是用户端常见的漏洞，非必要情况下强烈建议打开XSS过滤。

编辑文件 vendor/modstart/modstart/src/Core/Util/HtmlUtil.php

修改 filter 函数。

class HtmlUtil{
    // ...
    public static function filter($content)
    {
        if (empty($content)) {
            return $content;
        }
        return Purifier::cleanHtml($content);
    }
    // ...
}
1
2
3
4
5
6
7
8
9
10
11

修改为

class HtmlUtil{
    // ...
    public static function filter($content)
    {
        return $content;
    }
    // ...
}
1
2
3
4
5
6
7
8

# Q：系统是前后端分离的吗？

为提高开发效率，系统使用的是融合开发，不限制前端使用技术栈。

  • 部分交互复杂的页面（如文档管理、CRM、模块管理、题库管理、数据导入等）使用的是前后端分离（ vue + 接口）
  • 使用 Grid、Form、Detail 等内置组件快速开发的是 HTML + PHP 融合开发

# Q：系统内核升级时定制部分被覆盖？

系统定制部分开发在系统升级时经常会被覆盖，为了降低迁移升级成本，需要尽可能做到以下内容：

  • 前端部分
    • /public/asset/ : 该目录是内核必备且变更频率较高的文件，不要修改
    • /public/vendor/ : 该目录是模块静态资源目录，升级时可能会被重置，不要修改
    • /public/theme/ : 定制部分的样式、图片等静态资源放在这个目录中，在升级时不会被覆盖
  • 后端部分
    • 如需要修改全局通用逻辑代码，应复制一份生成新的调用类在需要修改的地方调用，避免影响全局

最佳实践

如果需要修改前端样式，请创建 /public/theme/css/custom.css 文件，在 /resources/views/theme/default/pc/frame.blade.php 中全局引入样式文件。

<link rel="stylesheet" href="@asset('theme/css/custom.css')" />
1

# Q：系统嵌入到iframe中会出现会话不保持问题

系统的 Cookie 默认使用了 SameSite=Lax 的特性，主要是为了预防 CSRF 攻击，在被嵌入到跨域页面时，Cookie 会出现不发送的情况。

如果系统需要嵌入到其他系统中，可以修改 config/session.php 配置文件。

Laravel5版

<?php
return [
    // ...
    // 原配置
    'path' => '/; SameSite=Lax',
    // 修改为
    'path' => '/',
    // ...
];
1
2
3
4
5
6
7
8
9

Laravel9版

<?php
return [
    // ...
    // 原配置
    'same_site' => 'lax',
    // 修改为
    'same_site' => 'none',
    // ...
];
1
2
3
4
5
6
7
8
9

更多参考：https://www.ruanyifeng.com/blog/2019/09/cookie-samesite.html (opens new window)

# Q：系统安装完成后如何修改数据库配置

系统的所有数据库、缓存等配置文件都存储于 <网站根目录>/.env 文件中，可以手动修改该文件，修改完成后清理缓存即可。

清理缓存命令：php artisan config:clear

DB_HOST=xxxxxx:3306
DB_DATABASE=
DB_USERNAME=
DB_PASSWORD=
1
2
3
4

# Q：如何运行 php artisan xxx 命令

Windows

  • ① 打开 cmd 命令行工具
  • ② 进入到网站根目录，如 cd D:\xx\xx，如果当前盘符不是 D 盘，需要先切换盘符（运行 D:）
  • ③ 运行命令，如 php.exe artisan xxx

如果 php 路径没有配置到环境变量中，需要指定 php.exe 的路径，如 D:\php\php.exe artisan xxx

Linux

  • ① 打开 shell 命令行工具
  • ② 进入到网站根目录，如 cd /var/www/xx/xx
  • ③ 切换到 php 的运行用户，如 su www，这一步很重要，如果默认使用 root 来运行命令，可能会导致后期权限运行有问题
  • ④ 运行命令，如 php artisan xxx

如果第③步不能在 shell 模式切换到 php 的运行用户，也可以尝试使用 sudo -u www php artisan xxx 来运行命令

# Q：系统如何清理缓存

可通过命令行的方式进行清理方式

php artisan cache:clear
php artisan view:clear
php artisan config:clear
1
2
3

# Q：后台管理地址不记得如何处理

系统的后台管理地址默认为 /admin，如果忘记了，可以通过修改配置文件 <网站根目录>/.env

# 默认为 /admin 可以修改为其他地址
ADMIN_PATH=/admin/
1
2

# Q：如何手动执行模块安装命令

模块安装、升级时都会自动执行 modstart:module-install 命令，如果出现安装升级模块后部分原因未执行迁移命令（或执行失败），请参考以下命令手动执行。

## 进入网站根目录
cd /wwwroot/example.com
## 手动执行模块安装命令，Xxx为模块标识
php artisan modstart:module-install Xxx
1
2
3
4

# Q：如何关闭后台登录验证码

修改配置文件 vendor/modstart/modstart/config/modstart.php

<?php
return [
    // ...
    'admin' => [
        // ...
        'login' => [
            // 默认开启，修改为 false 表示关闭
            'captcha' => true,
        ],
    ],
];
1
2
3
4
5
6
7
8
9
10
11

# Q：如何关闭后台的升级提醒和自动升级

修改配置文件 vendor/modstart/modstart/config/modstart.php

<?php
return [
    // ...
    'admin' => [
        // ...
        // 禁用版本更新检查，默认为 false，修改为 true 表示禁用更新检查
        'versionCheckDisable' => false,
        // 禁用后台程序升级，默认为 false，修改为 true 表示禁用升级功能
        'upgradeDisable' => false,
    ],
];
1
2
3
4
5
6
7
8
9
10
11

# Q：数据库操作出现错误 xxx Data too long for column 'xxx' at row xxx

系统使用了严格数据库字段模式， 数据库字段长度不够，需要修改数据库字段长度。

可以通过如下 SQL 来修改表 Aaa 中的 bbb 字段长度

ALTER TABLE `Aaa` MODIFY `bbb` VARCHAR(255) DEFAULT NULL COMMENT '字段备注';
1

# Q：数据库修改字段 utf8 编码为 utf8mb4 编码

系统使用了严格数据库字段模式， 数据库字段编码不够，需要修改数据库字段编码。

可以通过如下 SQL 来修改表 Aaa 中的 bbb 字段编码

ALTER TABLE `Aaa` MODIFY `bbb` VARCHAR(255) 
    CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '字段备注';
1
2

# Q：数据库操作操作 emoji 表情出现 Incorrect string value

老的系统使用了 utf8 编码，utf8 编码不支持 EMOJI 表情，需要修改数据库字段编码为 utf8mb4。

可以通过如下 SQL 来修改表 Aaa 中的 bbb 字段编码

ALTER TABLE `Aaa` MODIFY `bbb` VARCHAR(255)
    CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '字段备注';
1
2

# Q：如何修改系统连接 MySQL 的数据库编码？

修改配置文件 config/database.php

<?php
return [
    // ...
    'connections' => [
        // ...
        'mysql' => [
            // ...
            'charset' => 'utf8mb4',
            'collation' => 'utf8mb4_unicode_ci',
            // ...
        ],
        //  ...
    ],
    // ...
];
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

修改为 UTF8

  • charset 修改为 utf8
  • collation 修改为 utf8_unicode_ci

修改为 UTF8MB4

  • charset 修改为 utf8mb4
  • collation 修改为 utf8mb4_unicode_ci

# Q：如何检查队列是否配置成功

参考 开发必看 → 队列调度 进行配置，配置完成后如果异步任务（如文档转换、邮件发送等）一直未执行，可以通过如下命令来检查队列是否配置成功

ps -ef | grep artisan
1

查看是否有类似如下的进程

xxxxx  1234  1234  0 10:00 ?        00:00:00 php /xxx/example.com/artisan queue:work ****
1

如果没有，说明队列未配置成功，可以参考 开发必看 → 队列调度 进行配置。

# Q：遇到 Specified key was too long; max key length is 错误的解决办法

最新的系统使用了严格数据库字段模式，并且使用了 utf8mb4 编码，这样在低版本数据库时会出现 Specified key was too long; max key length is 的错误。

要解决这个问题可以以下几种途径：

  • 更新数据库版本：在一些较老的 MySQL 或 MariaDB 版本中，索引长度限制较低。升级到新版本可能会增加索引长度限制。
  • 修改系统的数据库编码：系统默认使用 utf8mb4 编码，如果数据库版本较低，可以修改为 utf8 编码。参考 如何修改系统连接 MySQL 的数据库编码？
  • 修改系统的编码字段：使用 utf8 最长可以支持 255 个字符。如果使用 utf8mb4 最长可以支持 191 个字符。
    • $table->string('path', 200)->nullable()->comment('')->charset('utf8');

# Q：使用Grid、Form、Detail如何使用自定义主键ID？

系统默认使用 id 作为主键，如果需要使用自定义主键，可以通过数据模型类的方法来实现。

第一步，定义数据模型类

namespace Module\News\Model;

use Illuminate\Database\Eloquent\Model;

class News extends Model
{
    protected $table = 'news';
    // 这里可以自定义主键
    protected $primaryKey = 'nid';
}
1
2
3
4
5
6
7
8
9
10

第二步，使用数据模型类作为Form、Detail、Grid的操作对象

// 表单
$form = Form::make(News::class);
// 详情
$detail = Detail::make(News::class);
// 数据表格
$grid = Grid::make(News::class);
// 快速CRUD
$builder->init(News::class)
1
2
3
4
5
6
7
8

# Q：如何修改登录默认的过期时间？

打开 config/session.php 文件，修改 lifetime 的值即可。

<?php
return [
    // ...
    // 过期时间，单位分钟
    'lifetime' => 120,
    // ...
];
1
2
3
4
5
6
7

注意：

系统默认使用文件会话驱动（file driver），由于每个会话都对应一个文件，如果过期时间很长，文件会积累在 storage/framework/sessions 目录下。 这可能导致文件系统占用过多空间，由于文件系统中的文件数量增加，可能会影响性能，尤其是在文件系统较慢的情况下。 为了避免这些问题，建议将会话过期时间设置为适当的值，根据应用程序的需求和安全性考虑，以及系统资源的可用性。在开发和生产环境中，可以根据具体情况选择合适的会话过期时间。

Last Updated: 6 months ago