laravel-admin 1.5 升级迁移全指南:表结构、路由与配置变更对照

原创2026-09-22 12:39:191,668 阅读
文章标签:后端低代码企业应用

laravel-admin 1.5 升级迁移全指南:表结构、路由与配置变更对照

laravel-admin 1.5 对内置表结构、路由文件与配置文件进行了整体重构,并移除了内置图表组件。本文以官方升级注意事项为主线,逐项对照 数据库迁移文件、路由模板 与 配置文件 的源码实现,为你梳理一份可执行、可验证的升级迁移清单。读完本文,你将掌握 1.5 版内置 9 张表的完整结构、新版路由与配置的组织方式,以及图表能力被移除后的自定义替代方案。

为什么 1.5 建议"重装再迁移"

升级文档给出的核心建议是:由于 laravel-admin 1.5 的内置表结构发生修改,推荐重新安装 laravel 5.5 与 laravel-admin 1.5,再把业务代码迁移过来,而不是在旧版本基础上原地升级。

从 composer.json 可以印证 1.5 的运行环境基线:

  • php: >=7.0.0
  • laravel/framework: >=5.5

也就是说,如果你仍在使用 laravel 5.4 或更低版本,必须先升级 laravel 框架本身,这本身就是一个涉及面很广的工程。同时 1.5 的数据库表、路由注册方式和配置键都发生了结构性变化,新旧数据表之间并不保证平滑兼容,因此官方给出的路径是:新环境全新安装 → 验证基础功能 → 再迁移业务代码与数据。

全新安装的流程可参考 docs/en/installation.md:

composer require encore/laravel-admin "1.5.*"
php artisan vendor:publish --provider="Encore\Admin\AdminServiceProvider"
php artisan admin:install

其中 admin:install 命令(见 src/Console/InstallCommand.php)会依次执行 migrate 建表,并在用户表为空时调用 db:seed 写入初始管理员数据。安装完成后运行 php artisan serve,访问 http://localhost/admin/,使用默认账号 admin / admin 即可登录验证。

迁移要点一:内置表结构变更

1.5 对内置表结构做了修改,迁移时必须以新版迁移文件为准。新版建表逻辑全部集中在 database/migrations/2016_01_04_173148_create_admin_tables.php,并且所有表名都通过 config('admin.database.*') 动态读取,也就是说表名本身可以在 config/admin.php 中自定义,升级时应先确认自己的表名配置与迁移文件一致。

迁移文件 up() 方法一共创建 9 张表,各表核心字段如下:

表(默认名) 用途 关键字段
admin_users 管理员用户 id、username(190, unique)、password(60)、name、avatar(nullable)、remember_token(100, nullable)、时间戳
admin_roles 角色 id、name(50, unique)、slug(50, unique)、时间戳
admin_permissions 权限 id、name(50, unique)、slug(50, unique)、http_method(nullable)、http_path(text, nullable)、时间戳
admin_menu 后台菜单 id、parent_id(默认 0)、order(默认 0)、title(50)、icon(50)、uri(nullable)、permission(nullable)、时间戳
admin_role_users 用户-角色关联 role_id、user_id、联合索引 [role_id, user_id]、时间戳
admin_role_permissions 角色-权限关联 role_id、permission_id、联合索引、时间戳
admin_user_permissions 用户-权限关联 user_id、permission_id、联合索引、时间戳
admin_role_menu 角色-菜单关联 role_id、menu_id、联合索引、时间戳
admin_operation_log 操作日志 id、user_id(索引)、path、method(10)、ip、input(text)、时间戳

与旧版对比,迁移时尤其要注意以下几点:

  1. 权限模型的变化:admin_permissions 表通过 http_method(如 GET、GET,PUT)与 http_path(支持换行分隔多个路径,text 类型)来定义"路由级权限",这是 1.5 权限校验(check_route_permission)的数据基础;
  2. 菜单表新增 permission 字段,用于将菜单项绑定到权限(对应配置项 menu_bind_permission);
  3. 4 张中间表(pivot table)统一带有联合索引,down() 方法会按依赖顺序依次 dropIfExists 这 9 张表。

down() 方法的删除顺序也值得迁移参考:先删用户、角色、权限、菜单主表,再删 4 张中间表与操作日志表,避免外键或索引残留。

初始数据的对应关系

建表之后的数据由 src/Auth/Database/AdminTablesSeeder.php 负责填充,迁移时这些种子数据的结构同样发生了变化:

  • 创建默认用户 admin(密码 admin)、角色 Administrator(slug 为 administrator);
  • 预置 5 条权限:*(全部权限)、dashboard、auth.login、auth.setting、auth.management;
  • 预置 7 条菜单(Dashboard 与 Admin 管理分组下的 Users / Roles / Permission / Menu / Operation log);
  • 建立角色-权限、角色-菜单的初始关联。

如果你在旧版中已有大量 RBAC 数据,迁移时建议按"新表结构 → 重新填充权限与菜单 → 再导入业务侧自定义数据"的顺序执行,避免字段缺失导致的数据错位。

迁移要点二:路由文件结构变更

1.5 将后台路由的组织方式改为"系统内置路由 + 用户自定义路由分组"两层结构,新版模板位于 src/Console/stubs/routes.stub:

<?php

use Illuminate\Routing\Router;

Admin::routes();

Route::group([
    'prefix'        => config('admin.route.prefix'),
    'namespace'     => config('admin.route.namespace'),
    'middleware'    => config('admin.route.middleware'),
    'as'            => config('admin.route.prefix') . '.',
], function (Router $router) {

    $router->get('/', 'HomeController@index')->name('home');

});

与旧版相比,新结构包含三个关键变化:

  1. Admin::routes() 注册内置路由:登录、登出、用户设置等认证相关路由由这一行统一注册,不再需要在业务路由文件中手工编写;
  2. 路由分组参数全部来自配置:prefix(默认 admin)、namespace(默认 App\Admin\Controllers)、middleware(默认 ['web', 'admin'])与路由命名前缀 as 都从 config/admin.php 的 route 段读取。这意味着修改路由前缀只需调整配置或设置 ADMIN_ROUTE_PREFIX 环境变量,无需改动路由文件;
  3. 业务路由只保留一个最小示例:分组内默认只注册 GET / 指向 HomeController@index,其余业务路由由你在该分组内自行追加。

安装时该模板由 src/Console/InstallCommand.php 中的 createRoutesFile() 方法写入到 app/Admin/routes.php,并将 DummyNamespace 占位符替换为配置中的命名空间。迁移业务代码时,只需把你旧版中自定义的路由按新分组规则迁移到 app/Admin/routes.php 即可——注意新路由一律使用 Route::group(...) + config('admin.route.*') 的形式,不要再硬编码前缀或中间件。

迁移要点三:配置文件结构变更

1.5 的配置体系集中在 config/admin.php(通过 vendor:publish 发布到项目 config/ 目录),迁移时请逐段对照。以下是与旧版差异最大、迁移时必须关注的配置段:

route 段:路由前缀、命名空间与中间件

'route' => [
    'prefix' => env('ADMIN_ROUTE_PREFIX', 'admin'),
    'namespace' => 'App\\Admin\\Controllers',
    'middleware' => ['web', 'admin'],
],
  • prefix 支持通过环境变量 ADMIN_ROUTE_PREFIX 覆盖,默认 admin,置空则从根路径访问;
  • middleware 中的 admin 是 laravel-admin 自带的路由中间件(位于 src/Middleware),负责认证、权限与 Pjax 等逻辑。

auth 段:认证体系

'auth' => [
    'controller' => App\Admin\Controllers\AuthController::class,
    'guard' => 'admin',
    'guards' => [
        'admin' => [
            'driver'   => 'session',
            'provider' => 'admin',
        ],
    ],
    'providers' => [
        'admin' => [
            'driver' => 'eloquent',
            'model'  => Encore\Admin\Auth\Database\Administrator::class,
        ],
    ],
    'remember' => true,
    'redirect_to' => 'auth/login',
    'excepts' => [
        'auth/login',
        'auth/logout',
    ],
],

迁移时需注意:guard 采用独立的 admin 会话守卫与 admin 用户提供者(Eloquent 驱动,模型为 Administrator),与 Laravel 默认的 web 守卫相互独立;redirect_to 与 excepts 用于控制未授权跳转和免鉴权路由。

database 段:表名与模型映射

'database' => [
    'connection' => '',
    'users_table' => 'admin_users',
    'users_model' => Encore\Admin\Auth\Database\Administrator::class,
    'roles_table' => 'admin_roles',
    'roles_model' => Encore\Admin\Auth\Database\Role::class,
    'permissions_table' => 'admin_permissions',
    'permissions_model' => Encore\Admin\Auth\Database\Permission::class,
    'menu_table' => 'admin_menu',
    'menu_model' => Encore\Admin\Auth\Database\Menu::class,
    'operation_log_table'    => 'admin_operation_log',
    'user_permissions_table' => 'admin_user_permissions',
    'role_users_table'       => 'admin_role_users',
    'role_permissions_table' => 'admin_role_permissions',
    'role_menu_table'        => 'admin_role_menu',
],

这是与迁移文件一一对应的配置段,迁移数据前务必确保这里的表名与迁移创建的表完全一致。connection 留空表示使用 Laravel 默认数据库连接。

operation_log 段:操作日志开关

'operation_log' => [
    'enable' => true,
    'allowed_methods' => ['GET', 'HEAD', 'POST', 'PUT', 'DELETE', 'CONNECT', 'OPTIONS', 'TRACE', 'PATCH'],
    'except' => [
        env('ADMIN_ROUTE_PREFIX', 'admin').'/auth/logs*',
    ],
],

enable 控制全局开关;allowed_methods 限定哪些 HTTP 方法记入日志;except 支持 admin/auth/logs* 或 get:admin/auth/logs 两种写法,用于排除无需记录的路径。注意默认排除了日志查看页面自身,避免日志表被自身查询刷爆。

其他迁移相关配置

  • directory:后台安装目录,默认 app_path('Admin'),必须在运行 admin:install 之前修改才生效(见 config/admin.php 的注释);
  • bootstrap:引导文件路径,默认 app/Admin/bootstrap.php,用于引入自定义 JS/CSS 或注册扩展;
  • check_route_permission、check_menu_roles:是否启用路由权限校验与菜单角色校验;
  • upload:上传磁盘与图片/文件目录(disk => 'admin',对应 config/filesystem.php 中的磁盘);
  • skin、layout、show_version、show_environment 等界面相关配置可直接沿用旧值。

迁移建议:把旧项目的自定义配置逐键对照写入新版 config/admin.php,对已删除或改名的键(尤其是图表相关、旧表名相关配置)进行清理,避免配置残留影响运行。

迁移要点四:图表组件已移除,如何替代

1.5 已移除全部内置图表组件,旧版中直接依赖图表组件的代码将无法继续使用。官方给出的替代思路是"引入第三方图表库 + 自定义视图",完整示例见 docs/en/custom-chart.md,核心流程分三步:

第一步:下载图表库并放到 public 目录。以 Chart.js 为例,将其放入 public/vendor/chartjs 目录。

第二步:在引导文件中引入 JS。编辑 app/Admin/bootstrap.php:

use Encore\Admin\Facades\Admin;

Admin::js('/vendor/chartjs/dist/Chart.min.js');

Admin::js() 是 laravel-admin 的静态资源注入接口,会让该 JS 在所有后台页面加载。

第三步:创建图表视图并在控制器中输出。新建 resources/views/admin/charts/bar.blade.php,放置 Canvas 画布与 Chart.js 初始化脚本;然后在控制器中使用 Admin::content() 将视图渲染到页面内容区:

public function index()
{
    return Admin::content(function (Content $content) {

        $content->header('chart');
        $content->description('.....');

        $content->body(view('admin.charts.bar'));
    });
}

通过这种"引入任意前端图表库 + 自定义 blade 视图 + $content->body() 输出"的组合,可以完全替代旧版内置图表。多图表页面的布局组织方式,可进一步参考 docs/en/content-layout.md 中的布局机制。迁移时,只需把旧项目中调用内置图表组件的代码替换为上述模式即可。

升级迁移核对清单

结合以上四点,整理一份可直接执行的迁移清单:

  1. 环境准备:确认 PHP ≥ 7.0、Laravel ≥ 5.5(见 composer.json 依赖声明),新建干净的 Laravel 5.5 项目;
  2. 全新安装:composer require encore/laravel-admin "1.5.*" → php artisan vendor:publish --provider="Encore\Admin\AdminServiceProvider" → 修改 config/admin.php 中 directory、database 等配置 → php artisan admin:install;
  3. 表结构核对:对照 database/migrations/2016_01_04_173148_create_admin_tables.php 确认 9 张表与配置表名一致,按新结构重建 RBAC 数据(参考 src/Auth/Database/AdminTablesSeeder.php);
  4. 路由迁移:将旧版自定义路由迁移到 app/Admin/routes.php,采用 src/Console/stubs/routes.stub 的分组写法,参数一律读取 config('admin.route.*');
  5. 配置迁移:逐段对照 config/admin.php,同步 route、auth、database、operation_log 等段,删除旧版废弃配置键;
  6. 图表替换:将依赖内置图表组件的页面改为"Chart.js 等第三方库 + 自定义视图 + $content->body()"方案(详见 docs/en/custom-chart.md);
  7. 验证:php artisan serve 后访问 http://localhost/admin/,使用 admin / admin 登录,逐页回归菜单、权限、表单与操作日志功能。

按此清单执行,即可在保留业务代码的基础上,平稳完成从旧版本到 laravel-admin 1.5 的整体迁移。

登录后查看全文
laravel-admin