Laravel单库多租户应用用spatie/laravel-permission遇角色重复问题求解

核心问题原因 #

Spatie的laravel-permission包默认通过name+guard_name组合做唯一约束，单库多租户场景下不同租户的同名角色会触发唯一性校验错误。

最优解决方案：扩展Spatie包实现租户隔离 #

1. 给角色表添加租户关联字段 #

生成迁移文件：

php artisan make:migration add_tenant_id_to_roles_table

编辑迁移文件，添加租户外键：

public function up()
{
    Schema::table('roles', function (Blueprint $table) {
        $table->foreignId('tenant_id')->constrained()->onDelete('cascade');
    });
}

public function down()
{
    Schema::table('roles', function (Blueprint $table) {
        $table->dropForeign(['tenant_id']);
        $table->dropColumn('tenant_id');
    });
}

执行迁移：

php artisan migrate

2. 自定义Role模型并替换包默认模型 #

首先发布包的配置文件：

php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider"

修改config/permission.php中的models.role配置，指向自定义模型：

'models' => [
    'role' => App\Models\Role::class,
    // 其他配置保持不变
],

创建自定义Role模型，继承Spatie的Role类并扩展逻辑：

namespace App\Models;

use Spatie\Permission\Models\Role as SpatieRole;
use Spatie\Permission\Exceptions\RoleDoesNotExist;
use Illuminate\Database\Eloquent\Builder;

class Role extends SpatieRole
{
    // 关联租户模型
    public function tenant()
    {
        return $this->belongsTo(Tenant::class);
    }

    // 重写findByName方法，加入租户ID校验
    public static function findByName(string $name, $guardName = null): self
    {
        $guardName = $guardName ?? config('auth.defaults.guard');
        
        $role = static::where('name', $name)
            ->where('guard_name', $guardName)
            ->where('tenant_id', tenant()->id) // 替换为你获取当前租户ID的逻辑
            ->first();

        if (! $role) {
            throw new RoleDoesNotExist();
        }

        return $role;
    }

    // 添加全局作用域，确保租户只能查询自己的角色
    protected static function boot()
    {
        parent::boot();

        static::addGlobalScope('tenant', function (Builder $builder) {
            if (tenant()->check()) { // 替换为你判断当前租户是否存在的逻辑
                $builder->where('tenant_id', tenant()->id);
            }
        });
    }
}

3. 创建角色时自动注入租户ID #

在业务逻辑中创建角色时，手动传入当前租户ID：

use App\Models\Role;

Role::create([
    'name' => 'Admin',
    'guard_name' => 'admin',
    'tenant_id' => auth()->user()->tenant_id, // 或根据你的租户获取方式调整
]);

备选方案 #

临时方案：角色名添加租户前缀 #

创建角色时给名称加上租户标识（如租户ID或域名前缀），例如tenant_1_Admin，但会影响租户端的显示体验，仅适合快速临时解决。

自定义权限系统 #

如果不想依赖第三方包，可以自行实现基于租户隔离的权限系统：

• 创建roles表，包含name、guard_name、tenant_id字段
• 创建permissions表，由超级管理员维护，无需租户字段
• 创建role_permission中间表，关联角色和权限
• 创建user_role中间表，关联用户和角色
• 编写权限校验逻辑，查询时自动带上当前租户ID过滤角色

替代包建议 #

可以选择原生支持多租户的权限管理包，但需注意包的维护状态和功能匹配度，避免引入不必要的复杂度。

内容的提问来源于stack exchange，提问作者Durgesh