laravel-admin 1.5 升级迁移全指南:表结构、路由与配置变更对照
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.0laravel/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)、时间戳 |
与旧版对比,迁移时尤其要注意以下几点:
- 权限模型的变化:
admin_permissions表通过http_method(如GET、GET,PUT)与http_path(支持换行分隔多个路径,text 类型)来定义"路由级权限",这是 1.5 权限校验(check_route_permission)的数据基础; - 菜单表新增
permission字段,用于将菜单项绑定到权限(对应配置项menu_bind_permission); - 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');
});
与旧版相比,新结构包含三个关键变化:
Admin::routes()注册内置路由:登录、登出、用户设置等认证相关路由由这一行统一注册,不再需要在业务路由文件中手工编写;- 路由分组参数全部来自配置:
prefix(默认admin)、namespace(默认App\Admin\Controllers)、middleware(默认['web', 'admin'])与路由命名前缀as都从 config/admin.php 的route段读取。这意味着修改路由前缀只需调整配置或设置ADMIN_ROUTE_PREFIX环境变量,无需改动路由文件; - 业务路由只保留一个最小示例:分组内默认只注册
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 中的布局机制。迁移时,只需把旧项目中调用内置图表组件的代码替换为上述模式即可。
升级迁移核对清单
结合以上四点,整理一份可直接执行的迁移清单:
- 环境准备:确认 PHP ≥ 7.0、Laravel ≥ 5.5(见 composer.json 依赖声明),新建干净的 Laravel 5.5 项目;
- 全新安装:
composer require encore/laravel-admin "1.5.*"→php artisan vendor:publish --provider="Encore\Admin\AdminServiceProvider"→ 修改 config/admin.php 中directory、database等配置 →php artisan admin:install; - 表结构核对:对照 database/migrations/2016_01_04_173148_create_admin_tables.php 确认 9 张表与配置表名一致,按新结构重建 RBAC 数据(参考 src/Auth/Database/AdminTablesSeeder.php);
- 路由迁移:将旧版自定义路由迁移到
app/Admin/routes.php,采用 src/Console/stubs/routes.stub 的分组写法,参数一律读取config('admin.route.*'); - 配置迁移:逐段对照 config/admin.php,同步
route、auth、database、operation_log等段,删除旧版废弃配置键; - 图表替换:将依赖内置图表组件的页面改为"Chart.js 等第三方库 + 自定义视图 +
$content->body()"方案(详见 docs/en/custom-chart.md); - 验证:
php artisan serve后访问http://localhost/admin/,使用admin/admin登录,逐页回归菜单、权限、表单与操作日志功能。
按此清单执行,即可在保留业务代码的基础上,平稳完成从旧版本到 laravel-admin 1.5 的整体迁移。