# 开发常见问题

# 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 days ago