Voyager 1.6 入门指南：Laravel 管理后台的安装、配置与 Admin 用户创建

Voyager 1.6 入门指南Laravel 管理后台的安装、配置与 Admin 用户创建【免费下载链接】voyagerVoyager - The Missing Laravel Admin项目地址: https://gitcode.com/gh_mirrors/vo/voyagerVoyager 是面向 Laravel 的开源管理后台Admin Panel扩展包官方定位为 The Missing Laravel Admin缺失的那块 Laravel 管理后台。本指南以 docs/introduction.md 为入口系统梳理 Voyager 1.6 的安装流程、前置条件、核心配置、Admin 用户创建与升级路径并结合仓库源码InstallCommand、AdminCommand、voyager.php 配置 等说明其底层执行细节帮助你从零开始跑起一个可登录、可管理数据的 Voyager 后台。读完本文你将掌握Voyager 的能力边界是什么、不是什么、环境前置要求、标准安装与带示例数据安装的区别、手动/高级安装流程、voyager.php全量配置项的语义以及从 1.5 升级到 1.6 的注意事项。什么是 Voyager一个为 Laravel 定制的管理界面在动手安装之前官方文档建议先花一点时间弄清楚 Voyager是什么、不是什么详见 docs/getting-started/what-is-voyager.md。Voyager 是什么一个为你的 Laravel 应用提供后台管理界面的扩展包一种为应用快速添加/编辑/删除数据的便捷方式一个菜单构建器在 Voyager 后台中直接构建应用菜单一个媒体管理器管理上传的文件一个 CRUD/BREAD 生成器BREAD 即 Browse、Read、Edit、Add、Delete详见 BREAD 介绍。Voyager 本身只负责管理后台前端表现完全由你自己的 Laravel 应用决定。你可以借助它来录入数据、编辑用户、创建菜单、完成各类管理任务而业务逻辑依然掌握在自己手中。Voyager 不是什么不是一个内容管理系统CMS不是一个博客平台不是 WordPress。它开箱即用时既不是 CMS 也不是博客平台但可以基于它搭建出 CMS 或博客平台。正如 What is Voyager 中所强调的Laravel 与 Voyager 只是让构建更容易的工具应用最终长什么样由你决定。从仓库结构可以印证这一设计核心代码集中在src/包含 Voyager.php 门面实现、Http/Controllers控制器、Models、FormFields表单字段处理器等同时提供routes/voyager.php路由文件、migrations/迁移与publishable/可发布资源配置、语言包、静态资源、Seeder。它是以 Composer 包形式嵌入 Laravel 应用的组件而非独立应用。前置条件Laravel 与 PHP 版本要求根据 docs/getting-started/prerequisites.md安装 Voyager 前需要满足Laravel 8 或 Laravel 9PHP 7.3 或更高版本使用 Laravel 9 时Laravel 本身要求 PHP 8 或更高。同时参考仓库根目录的 composer.json其实际声明的能力范围更宽php: ^7.3|^7.4|^8.0|^8.1|^8.2|^8.3illuminate/support: ~8.0|~9.0|~10.0|~11.0。也就是说从包约束层面看Voyager 1.6 对 Laravel 8/9/10/11 及 PHP 7.3–8.3 都有兼容声明若使用 Laravel 10README.md 还提供了分支安装方式composer require tcg/voyager dev-1.6-l10。文档正文以 Laravel 8/9 为推荐前提其余版本请以实际安装结果为准。标准安装流程从 composer 到 /admin 登录页第 1 步引入扩展包创建好新的 Laravel 应用后执行composer require tcg/voyager第 2 步配置数据库与 APP_URL新建数据库并把凭据写入.env文件APP_URLhttp://localhost:8000 DB_HOSTlocalhost DB_DATABASEhomestead DB_USERNAMEhomestead DB_PASSWORDsecret其中APP_URL需要改为你站点的实际地址。第 3 步运行安装器不带示例数据安装php artisan voyager:install带示例数据安装php artisan voyager:install --with-dummy两种方式的差异在于示例数据内容详见 docs/getting-started/installation.md1 个管理员账号仅当数据库中还没有任何用户时才会创建1 个示例页面demo page4 篇示例文章demo posts2 个示例分类categories7 项设置settings。从源码看示例数据由 VoyagerDummyDatabaseSeeder.php 依次调用CategoriesTableSeeder、UsersTableSeeder、PostsTableSeeder、PagesTableSeeder、TranslationsTableSeeder、PermissionRoleTableSeeder完成。安装完成后启动本地服务并访问后台php artisan serve浏览器打开http://localhost:8000/admin即可看到登录页。voyager:install 命令内部都做了什么InstallCommand.php 展示了这条命令的完整执行链命令名voyager:install支持--force与--with-dummy两个选项通过vendor:publish发布 Seeder--tagseeders执行php artisan migrate --force生产环境下可用--force强制执行迁移 Voyager 数据表自动把app/User.php或app/Models/User.php中的extends Authenticatable替换为extends \TCG\Voyager\Models\User若找不到用户模型文件会给出警告并要求手动修改自动在routes/web.php末尾追加Route::group([prefix admin], ...)路由组若尚未存在Voyager::routes()根据是否带--with-dummy发布 dummy 相关资源dummy_seeders、dummy_content、dummy_config、dummy_migrations或常规的config、voyager_avatar资源执行composer dump-autoload重新加载新文件执行db:seed --classVoyagerDatabaseSeeder写入基础数据若带--with-dummy再迁移 dummy 表并执行VoyagerDummyDatabaseSeeder执行php artisan storage:link建立public/storage符号链接最后输出 Successfully installed Voyager! Enjoy。Voyager::routes()的实现位于 src/Voyager.php#L270-L273其作用是直接引入routes/voyager.php路由文件该文件内所有路由以as voyager.前缀分组并包含login、postlogin等认证路由以及受admin.user中间件保护的后台路由组见 routes/voyager.php。创建 Admin 用户使用示例数据安装的情况若安装了示例数据系统已创建默认管理员登录凭据为email:adminadmin.compassword:password注意示例用户只会在数据库中没有任何用户时创建。为现有用户授予管理员权限未使用示例数据时可以把管理员权限授予一个已存在用户php artisan voyager:admin youremail.com创建全新管理员如果希望直接创建一个新的管理员账号加--create标志php artisan voyager:admin youremail.com --create命令会交互式地提示输入用户名和密码。AdminCommand 的底层逻辑AdminCommand.php命令名voyager:admin支持--create选项的执行流程如下通过getUser()获取或创建用户创建时会校验邮箱是否已存在已存在则提示无法创建、两次密码是否一致随后用Hash::make()加密密码并forceCreate不创建时则按邮箱firstOrFail()查找通过getAdministratorRole()按name admin查找角色不存在则以display_name Administrator创建取全部Permission通过$role-permissions()-sync(...)把所有权限同步给 admin 角色将用户的role_id设为 admin 角色并保存最后输出 The user now has full access to your site.。也就是说这条命令保证存在一个拥有全部权限的管理员用户。高级/手动安装在已有 Laravel 项目上接入 Voyager如果你是在已有的 Laravel 安装上接入 Voyager或希望手动控制每一步详见 docs/getting-started/installation.md 的 Advanced 章节可以按以下步骤操作。1. 发布资源php artisan vendor:publish --providerTCG\Voyager\VoyagerServiceProvider php artisan vendor:publish --providerIntervention\Image\ImageServiceProviderLaravelRecent2. 迁移数据表php artisan migrate提示若想修改迁移例如换一张用户表不要直接 migrate。改为把 Voyager 的迁移文件复制到database/migrations做必要修改后在配置中关闭database.autoload_migrations再执行迁移。3. 让 User 模型继承 Voyager 用户模型打开应用的用户模型通常是app/User.php把继承关系改为?php class User extends \TCG\Voyager\Models\User { // ... }4. 注册路由在routes/web.php中添加?php Route::group([prefix admin], function () { Voyager::routes(); });5. 填充基础数据并建立存储链接php artisan db:seed --classVoyagerDatabaseSeeder php artisan storage:link6. 完成安装composer dump-autoloadVoyagerDatabaseSeeder的手动调用同样有测试覆盖tests/Feature/SeederTest.php中的testVoyagerDatabaseSeederCanBeCalled会通过artisan(db:seed, [--class VoyagerDatabaseSeeder])验证其可执行性tests/Feature/SeederTest.php。配置文件详解config/voyager.php安装 Voyager 后应用中会生成config/voyager.php配置文件仓库内的发布模板位于 publishable/config/voyager.php文档讲解见 docs/getting-started/configurations.md。修改配置后若开启了配置缓存请记得执行php artisan config:clear。下面按配置组逐一说明语义。用户useruser [ add_default_role_on_register true, default_role user, default_avatar users/default.png, redirect /admin, ],add_default_role_on_register是否在注册时为每个新用户赋予默认角色default_role新用户的默认角色名default_avatar默认头像路径仓库中对应publishable/dummy_content/users/default.pngredirect登录成功后的跳转路径。文档版本中还出现过admin_permission查看后台仪表盘所需权限与namespace应用 User 类命名空间两个键模板配置中以admin_permission由权限系统管理、namespace通过继承模型体现请以你安装后实际生成的配置文件为准。控制器controllerscontrollers [ namespace TCG\\Voyager\\Http\\Controllers, ],指定 Voyager 控制器的默认命名空间。想覆盖核心功能时可以复制 Voyager 控制器到你自己的命名空间并修改此项。若只想覆盖单个控制器可在AppServiceProvider的register方法中绑定$this-app-bind(VoyagerBreadController::class, MyBreadController::class);模型modelsmodels [ //namespace App\\, ],指定从后台数据库区域创建模型时使用的模型命名空间需包含结尾反斜杠。未定义时使用应用默认命名空间。资产路径assets_pathassets_path /vendor/tcg/voyager/assets,站点若部署在子目录需要在路径前加上该目录若想复制并自定义已发布的资产也应修改此项。升级 Voyager 时/vendor/tcg/voyager/assets下的资源可能被覆盖因此自定义样式的最佳做法是复制整个目录并指定新的assets_path。存储storagestorage [ disk public, ],默认使用public本地磁盘也可以换成config/filesystems.php中任意驱动如 S3、Google Cloud Storage 等。在 src/Voyager.php#L261-L268 的image()辅助方法中可以看到config(voyager.storage.disk)被实际用于拼接文件 URL。数据库databasedatabase [ tables [ hidden [migrations, data_rows, data_types, menu_items, password_resets, permission_role, personal_access_tokens, settings], ], autoload_migrations true, ],tables.hidden在 Voyager 数据库管理界面中隐藏的表autoload_migrations是否在php artisan migrate时自动加载 Voyager 的迁移文件置为false可避免加载。多语言multilingualmultilingual [ enabled false, default en, locales [ en, //pt, ], ],enabled是否启用多语言default默认语言locales支持的语种列表。详见 多语言。仪表盘dashboarddashboard [ navbar_items [ Profile [ route voyager.profile, classes class-full-of-rum, icon_class voyager-person, ], Home [ route /, icon_class voyager-home, target_blank true, ], Logout [ route voyager.logout, icon_class voyager-power, ], ], widgets [ TCG\\Voyager\\Widgets\\UserDimmer, TCG\\Voyager\\Widgets\\PostDimmer, TCG\\Voyager\\Widgets\\PageDimmer, ], ],navbar_items在顶部用户下拉菜单中追加菜单项支持route、icon_class、target_blank等字段widgets管理仪表盘上的 Widget示例类见仓库src/Widgets/下的 UserDimmer、PostDimmer、PageDimmer。模板配置中widgets默认为空数组文档示例默认启用三个 Dimmer可按需增删。主题与开发提示primary_color #22A7F0, // 后台主色默认浅蓝 show_dev_tips true, // 是否显示开发提示How To Use:附加样式与脚本additional_css [ //css/custom.css, ], additional_js [ //js/custom.js, ],在后台主布局中追加自定义 CSS/JS路径会传给 Laravel 的asset()辅助函数理论上可借此为 Voyager 打造整套新主题。详见 附加 CSS/JS。Google Maps坐标字段googlemaps [ key env(GOOGLE_MAPS_KEY, ), center [ lat env(GOOGLE_MAPS_DEFAULT_CENTER_LAT, 32.715738), lng env(GOOGLE_MAPS_DEFAULT_CENTER_LNG, -117.161084), ], zoom env(GOOGLE_MAPS_DEFAULT_ZOOM, 11), ],Voyager 提供coordinates数据类型在 Google 地图上拖拽图钉即可把经纬度存入数据库。这里的key、默认中心点与缩放级别都可以通过.env覆盖。媒体上传 MIME 白名单media [ allowed_mimetypes [ image/jpeg, image/png, image/gif, image/bmp, video/mp4, ], path /, show_folders true, allow_upload true, allow_move true, allow_delete true, allow_create_folder true, allow_rename true, ],媒体管理器只允许上传白名单中的 MIME 类型全部放行可写allowed_mimetypes *,模板中还包含hidden_files是否显示.gitignore等隐藏文件、bread.add_menu_item/bread.default_menu/bread.add_permission/bread.default_role新增 BREAD 时自动创建菜单项与权限的开关及目标、settings.cache设置值是否走 Laravel 缓存、compass_in_production非 local 环境是否启用 Compass 工具等配置项建议安装后通读一遍生成的config/voyager.php注释。从 1.5 升级到 1.6升级说明见 docs/getting-started/upgrading.md更新 composer.json把require中的版本约束改为tcg/voyager: 1.6.*然后执行composer update检查 TinyMCE 配置Voyager 1.6 将 TinyMCE 升级到了版本 6大量配置项随之变化。若你在控制台看到错误且修改过 TinyMCE 配置请核对是否使用了 TinyMCE 6 文档中的最新选项与取值TinyMCE 相关的表单字段说明见 docs/bread/formfields/tinymce.md。安装后Voyager 文档地图完成安装并登录后台后可以按文档目录见 docs/summary.md继续深入BREAD从 BREAD 介绍 开始学习 Browse/Read/Edit/Add/Delete 的字段配置随后探索 关系管理 与各表单字段Checkbox、坐标、日期时间、下拉、图片、媒体选择器、数字、TinyMCE 等核心概念路由、媒体管理器、菜单与菜单构建器、数据库管理器、设置、Compass、角色与权限、辅助方法、多语言自定义覆盖文件、覆盖路由、启用软删除、添加自定义表单字段、自定义 guard、操作按钮 等故障排查HTTPS 环境使用、缺失必需参数。至此你已经完成了从认识 Voyager、安装部署、创建管理员到配置调优与版本升级的完整入门闭环。接下来就可以在http://localhost:8000/admin上体验 BREAD 生成器、媒体管理器和菜单构建器把这份后台能力接入到你的 Laravel 应用中。【免费下载链接】voyagerVoyager - The Missing Laravel Admin项目地址: https://gitcode.com/gh_mirrors/vo/voyager创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考