Laravel Tenancy 中 Sanctum 迁移文件被错误执行到中央数据库的问题解析

问题背景

在使用 Laravel Tenancy 多租户扩展包时，开发者可能会遇到一个典型问题：原本应该只在租户数据库中执行的迁移文件（如 Sanctum 的个人访问令牌表迁移），却被意外执行到了中央数据库中。这种情况通常发生在将 Laravel Sanctum 集成到多租户环境时。

问题根源分析

这个问题的根本原因在于 Laravel Sanctum 的默认行为。Sanctum 的服务提供者会在注册时自动发布并加载其迁移文件。具体来说：

1. Sanctum 的服务提供者使用 publishesMigrations 方法注册迁移文件
2. 这个方法不仅会发布迁移文件到指定目录，还会隐式地将这些迁移注册到应用的迁移系统中
3. 当运行 php artisan migrate 时，这些迁移会被当作中央数据库的迁移执行

解决方案

要解决这个问题，有以下几种方法：

方法一：忽略默认 Sanctum 迁移

在 AppServiceProvider 的 register 方法中添加以下代码：

$this->app->afterResolving('migrator', function ($migrator) {
    $migrator->path(module_path('Tenant', 'Database/Migrations'));
});

方法二：创建空迁移文件

在中央数据库的迁移目录中创建一个同名但内容为空的迁移文件，这样可以防止 Sanctum 的原始迁移被执行：

// database/migrations/2019_12_14_000001_create_personal_access_tokens_table.php
return new class extends Migration {
    public function up() {}
    public function down() {}
};

方法三：修改 Sanctum 服务提供者

通过扩展 Sanctum 的服务提供者并重写相关方法，可以阻止默认迁移的注册：

namespace App\Providers;

use Laravel\Sanctum\SanctumServiceProvider as BaseSanctumServiceProvider;

class SanctumServiceProvider extends BaseSanctumServiceProvider
{
    public function boot()
    {
        // 不调用父类的boot方法，避免注册默认迁移
    }
}

最佳实践建议

1. 在多租户环境中，明确区分中央数据库和租户数据库的迁移文件存放位置
2. 对于需要在租户数据库中创建的表，确保迁移文件只存在于租户迁移目录中
3. 使用 tenancy:migrate 命令专门执行租户迁移，而不是普通的 migrate 命令
4. 定期检查数据库迁移记录表，确保没有意外的迁移被执行

总结

理解 Laravel 包如何注册和加载迁移文件对于构建稳定的多租户应用至关重要。通过上述方法，开发者可以确保 Sanctum 的相关表只在租户数据库中创建，从而保持中央数据库的整洁和租户数据的隔离性。这种精细的控制是多租户架构成功实施的关键因素之一。