Laravel 多租户组件 spatie/laravel-multitenancy 指南

spatie/laravel-multitenancy 多租户组件，它可以帮助你快速实现 Laravel 多租户应用。比 tenancy/tenancy 更灵活。

数据库支持单库模式和1中心库+多租户库模式。多租户库模式下，用户表和用户tokens表可选择放在中心库，也可以放在租户库。

安装

composer require spatie/laravel-multitenancy
# 发布配置文件，生成 config/multitenancy.php 配置文件
php artisan vendor:publish --provider="Spatie\Multitenancy\MultitenancyServiceProvider" --tag="multitenancy-config"
# 在 database/migrations/landlord 目录下发布迁移文件，用于创建 tenants 表
php artisan vendor:publish --provider="Spatie\Multitenancy\MultitenancyServiceProvider" --tag="multitenancy-migrations"

Schema::create('tenants', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->string('domain')->unique(); // 用于外部传入id以切换租户，可以改成自己需要的
    $table->string('database')->unique(); // 租户数据库
    $table->timestamps();
});

配置

// config/multitenancy.php
return [
    /*
     * 这个类负责确定哪个租户应该是给定请求的最新租户。
     * 必须继承 `Spatie\Multitenancy\TenantFinder\TenantFinder`
     */
    'tenant_finder' => \App\Multitenancy\TenantFinder\HeaderTenantFinder::class,

    /*
     * 这些字段由`tender:artist`命令用于匹配一个或多个租户。
     */
    'tenant_artisan_search_fields' => [
        'id', 
        'tenant_code', // 默认是domain，根据自己需要修改
        'database'
    ],

    /*
     * 这些任务将在切换租户时执行。
     *
     * 有效的任务是实现 `Spatie\Multitenance\Tasks\SwitchTenantTask` 的任何类
     */
    'switch_tenant_tasks' => [
        \Spatie\Multitenancy\Tasks\PrefixCacheTask::class,
        \Spatie\Multitenancy\Tasks\SwitchTenantDatabaseTask::class,
        \Spatie\Multitenancy\Tasks\SwitchRouteCacheTask::class,
    ],

    /*
     * 这个类是用于在租户上存储配置的模型。
     *
     * 必须是或继承 `Spatie\Multitenancy\Models\Tenant::class`
     */
    'tenant_model' => \App\Models\Landlord\Tenant::class,

    /*
     * 如果在分派作业时有当前租户，则会在作业上自动设置当前租户的id。
     * 执行作业时，作业上设置的租户将变为当前租户。
     */
    'queues_are_tenant_aware_by_default' => true,

    /*
     * 用于连接租户数据库的连接名称。
     *
     * 如果设置为 `null`，则使用默认的数据库连接。
     */
    'tenant_database_connection_name' => 'tenant',

    /*
     * 用于连接主数据库（Landlord 数据库）的连接名称。
     */
    'landlord_database_connection_name' => 'landlord',

    /*
     * 此键名用于在 Laravel 服务容器（Container）中绑定当前租户实例。
     */
    'current_tenant_container_key' => 'currentTenant',

    /**
     * 如果你希望使用 `SwitchRouteCacheTask` 将租户的路由缓存
     * 到一个共享文件中，请将其设置为 `true`。
     */
    'shared_routes_cache' => false,

    /*
     * 你可以通过自定义 Action（动作类）来定制该包的部分行为。
     * 你的自定义 Action 必须继承自默认的 Action 类。
     */
    'actions' => [
        'make_tenant_current_action' => MakeTenantCurrentAction::class,
        'forget_current_tenant_action' => ForgetCurrentTenantAction::class,
        'make_queue_tenant_aware_action' => MakeQueueTenantAwareAction::class,
        'migrate_tenant' => MigrateTenantAction::class,
    ],

    /*
     * 你可以自定义该包将队列任务（Queueable）解析为具体 Job 的方式。
     *
     * 例如，使用 laravel-actions 包（作者：Loris Leiva）时，
     * 你可以将 JobDecorator 解析为 getAction()，配置如下：
     * JobDecorator::class => 'getAction'
     */
    'queueable_to_job' => [
        SendQueuedMailable::class => 'mailable',
        SendQueuedNotifications::class => 'notification',
        CallQueuedClosure::class => 'closure',
        CallQueuedListener::class => 'class',
        BroadcastEvent::class => 'event',
    ],

    /*
     * 即使以下 Job 没有实现 TenantAware 接口，也会自动使其具备租户感知能力。
     */
    'tenant_aware_jobs' => [
        // ...
    ],

    /*
     * 即使以下 Job 没有实现 NotTenantAware 接口，也会强制使其失去租户感知能力。
     */
    'not_tenant_aware_jobs' => [
        // ...
    ],
];

自定义租户查找器

通过 X-Tenant-ID header 来确定当前租户。
在 config/multitenancy.php 中配置 tenant_finder 为这个类。

<?php
namespace App\Multitenancy\TenantFinder;

use App\Models\Landlord\Tenant;
use Illuminate\Http\Request;
use Spatie\Multitenancy\TenantFinder\TenantFinder;

class HeaderTenantFinder extends TenantFinder
{
    /**
     * 3.x 签名：必须返回 Tenant 实例
     */
    public function findForRequest(Request $request): \App\Models\Landlord\Tenant|null
    {
        // 这里可以换成子域名
        $id = (int)trim($request->headers->get('X-Tenant-ID', ''));

        if ($id === 0 || (!$tenant = Tenant::find($id))) {
            abort(400, '无效的商户ID');
        }

        return $tenant;
    }
}

模型集成

• Spatie\Multitenancy\Models\Tenant 类有切换租户的能力。
• Spatie\Multitenancy\Models\Concerns\UsesLandlordConnection 自动把模型数据库连接切换到中心库。
• Spatie\Multitenancy\Models\Concerns\UsesTenantConnection 自动把模型数据库连接切换到租户库。

租户分配模型通过继承 Spatie\Multitenancy\Models\Tenant 类，使用 Spatie\Multitenancy\Models\Concerns\UsesLandlordConnection Trait来集成。
中心库模型使用 Spatie\Multitenancy\Models\Concerns\UsesLandlordConnection Trait 集成。
租户模型使用 Spatie\Multitenancy\Models\Concerns\UsesTenantConnection Trait 集成。

授权

App\Http\Kernel::$middlewareGroups 中添加：

'tenant' => [
    // 获取当前租户
    \Spatie\Multitenancy\Http\Middleware\NeedsTenant::class,
    // 用 session 的时候需要添加
    // \Spatie\Multitenancy\Http\Middleware\EnsureValidTenantSession::class,
],

在路由中使用中间件：

Route::middleware(['tenant', 'auth:sanctum'])->group(function () {
    Route::get('/api/xxx', function () {
        // 这里已经切换到租户数据库连接
        $user = request()->user();
    });
});

使用了 tenant 中间件后，自动调用 HeaderTenantFinder::findForRequest() 查找到租户，并切换到租户数据库。

tenant 和 auth:sanctum 放的顺序很重要。
如果用户表放在中心库，那么 auth:sanctum 中间件必须放在 tenant 中间件之前。
如果用户表放在租户库，那么 tenant 中间件必须放在 auth:sanctum 中间件之前，并且还要设置中间件的优先级，把
\Spatie\Multitenancy\Http\Middleware\NeedsTenant::class, 放到 App\Http\Kernel::$middlewarePriority 最前面。

App\Http\Kernel 没看到 $middlewarePriority，则到父类连其列表值一起复制下来。

临时切换切换到租户数据库

$tenant->execute(closure)：临时切换、自动恢复、安全隔离。
只在闭包内生效，执行完自动切回原来的租户 / 主库，不会污染全局状态。

$tenant = Spatie\Multitenancy\Models\Tenant::find(1);
$tenant->execute(function() {
    // 这里可以执行租户数据库的操作
});

永久切换切换到租户数据库

$tenant->makeCurrent()：永久切换（直到手动改）、全局生效、需手动恢复。
一旦调用，整个后续请求生命周期都用这个租户库，直到你 forgetCurrent() 或切别的租户。

$tenant = Spatie\Multitenancy\Models\Tenant::find(1);
// 直接把当前租户数据库连接切换到租户库
$tenant->makeCurrent();

最简单的集成方式

上面的集成方式比较优雅，通过子域名或header来集成。

最简单的集成方式是通过URL参数来集成。

1. 这个方式不需要实现 App\Multitenancy\TenantFinder\TenantFinder 类。
   在 config/multitenancy.php 中配置 tenant_finder 为 ``。

2. 不需要添加切换租户的路由中间件。

例如：

Route::get('/api/{tenant}/other', function ($tenant) {
    $tenant->execute(function() {
        // 这里已经切换到租户数据库连接了
    });
});

这个方式的缺点是不优雅，所有路由都需要添加租户参数、所有调用租户数据库的地方都是通过 $tenant->execute(closure) 来切换租户。