如何优雅地解决Laravel单数据库多租户数据隔离问题？使用nunomazer/laravel-samehouse轻而易举！-composer-PHP中文网

如何优雅地解决Laravel单数据库多租户数据隔离问题？使用nunomazer/laravel-samehouse轻而易举！

DDD

发布： 2025-11-05 12:53:02

原创

902人浏览过

如何优雅地解决laravel单数据库多租户数据隔离问题？使用nunomazer/laravel-samehouse轻而易举！

你是否正在构建一个SaaS平台，为不同的客户提供服务，但又希望所有客户的数据都存储在同一个数据库中，以降低运维成本和复杂性？这种单数据库多租户的架构模式虽然高效，却也带来了巨大的挑战：如何确保不同租户之间的数据严格隔离，避免用户看到或修改不属于自己的信息？手动在每一个数据库查询中添加 WHERE tenant_id = current_tenant_id 这样的条件，不仅工作量巨大，容易遗漏导致数据安全隐患，而且会使代码变得臃肿不堪，难以维护。

幸运的是，PHP社区的Composer生态为我们提供了强大的解决方案。今天，我将向你介绍一个能够彻底解决这个痛点的Composer包：nunomazer/laravel-samehouse。它能让你在Laravel应用中实现优雅、自动化的单数据库多租户数据隔离。

Composer在线学习地址：学习地址

为什么选择 `nunomazer/laravel-samehouse`？

nunomazer/laravel-samehouse 是一个基于 HipsterJazzbo/Landlord 和 Torzer/awesome-landlord 改进而来的Laravel/Lumen包，专注于实现单数据库多租户。它的核心理念是：通过自动化的全局作用域（Global Scopes），确保所有针对租户模型的查询都只返回当前租户的数据。这意味着你无需在每个Eloquent查询中手动添加租户ID，大大简化了开发工作。

安装与配置：让魔法开始

首先，使用Composer将 nunomazer/laravel-samehouse 添加到你的项目中：

<code class="bash">composer require nunomazer/laravel-samehouse</code>

登录后复制

对于 Laravel 项目：

在 config/app.php 中注册 ServiceProvider：

<pre class="brush:php;toolbar:false;">    'providers' => [
        // ...
        NunoMazer\Samehouse\LandlordServiceProvider::class,
    ],

登录后复制

如果你喜欢使用 Facade，也可以注册：

<pre class="brush:php;toolbar:false;">    'aliases' => [
        // ...
        'Landlord'   => NunoMazer\Samehouse\Facades\Landlord::class,
    ],

登录后复制

为了更好地控制，你可以发布其配置文件：

<code class="bash">php artisan vendor:publish --provider="NunoMazer\Samehouse\LandlordServiceProvider"</code>

登录后复制

发布后，你可以在 config/landlord.php 中设置 default_tenant_columns，这对于那些没有明确指定 $tenantColumns 属性的模型非常有用。

对于 Lumen 项目：

在 bootstrap/app.php 中注册 ServiceProvider，并确保启用了Eloquent：

<pre class="brush:php;toolbar:false;">$app->register(NunoMazer\Samehouse\LandlordServiceProvider::class);
$app->withEloquent(); // 确保这一行没有被注释掉

登录后复制

核心用法：定义租户上下文

nunomazer/laravel-samehouse 的一个关键点是：它无状态。这意味着你需要在每个请求中明确告知它当前是哪个租户在操作。最常见和推荐的做法是使用中间件（Middleware）。

假设你的用户表（users）中有一个 company_id 字段，用于关联用户所属的公司（租户）。你可以创建一个 SetTenant 中间件：

<code class="bash">php artisan make:middleware SetTenant</code>

登录后复制

然后，编辑 app/Http/Middleware/SetTenant.php 文件：

<pre class="brush:php;toolbar:false;"><?php

namespace App\Http\Middleware;

use Closure;
use NunoMazer\Samehouse\Facades\Landlord; // 引入 Landlord Facade

class SetTenant
{
    /**
     * Handle an incoming request.
     *
     * @param  \Illuminate\Http\Request  $request
     * @param  \Closure  $next
     * @return mixed
     */
    public function handle($request, Closure $next)
    {
        // 确保用户已登录，并且其 company_id 存在
        if (auth()->check() && auth()->user()->company_id) {
            // 将当前请求的租户设置为认证用户的 company_id
            Landlord::addTenant('company_id', auth()->user()->company_id);
        }

        return $next($request);
    }
}

登录后复制

最后，将这个中间件添加到 app/Http/Kernel.php 中的 web 或 api 中间件组，或者添加到特定的路由中：

<pre class="brush:php;toolbar:false;">// app/Http/Kernel.php
protected $middlewareGroups = [
    'web' => [
        // ...
        \App\Http\Middleware\SetTenant::class, // 添加到这里
    ],

    'api' => [
        // ...
        \App\Http\Middleware\SetTenant::class, // 或者添加到这里
    ],
];

登录后复制

通过这种方式，在每个请求开始时，Landlord 就会知道当前操作的租户ID，并将其应用到后续的所有数据库查询中。

你也可以通过 Landlord::removeTenant('company_id') 来移除当前租户上下文，或者使用 Landlord::hasTenant('company_id') 检查某个租户是否已被设置。

FlowIn

AI 时代下的内容共创平台，借助 FlowIn AI 撰写与改写内容十分便利。

324

查看详情

模型关联：自动数据隔离的魔法

要让你的Eloquent模型支持租户隔离，只需简单地使用 BelongsToTenants Trait：

<pre class="brush:php;toolbar:false;"><?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use NunoMazer\Samehouse\BelongsToTenants; // 引入 Trait

class Product extends Model
{
    use BelongsToTenants; // 使用这个 Trait

    // ... 其他模型属性和方法
}

登录后复制

现在，当你在 Product 模型上执行任何查询时，nunomazer/laravel-samehouse 都会自动添加 WHERE company_id = [当前租户ID] 条件：

<pre class="brush:php;toolbar:false;">// 假设当前租户的 company_id 是 1
$products = Product::all(); // 相当于 SELECT * FROM products WHERE company_id = 1

$product = Product::find(5); // 相当于 SELECT * FROM products WHERE id = 5 AND company_id = 1

登录后复制

如果 find(5) 对应的产品不属于当前租户，它将抛出 ModelNotFoundForTenantException 异常，而不是 Laravel 默认的 ModelNotFoundException，这有助于你更快地定位问题。

创建新模型时自动填充租户ID：

当你创建新模型实例时，如果 company_id 尚未设置，Landlord 会自动填充：

<pre class="brush:php;toolbar:false;">// 如果当前租户的 company_id 是 1，则会自动设置 product 的 company_id 为 1
$product = Product::create(['name' => '新产品', 'price' => 99.99]);

登录后复制

指定租户列：

如果你的模型使用的租户列名不是 default_tenant_columns 中定义的，或者你需要为特定模型指定不同的租户列，可以在模型中设置 $tenantColumns 属性：

<pre class="brush:php;toolbar:false;">class Order extends Model
{
    use BelongsToTenants;

    public $tenantColumns = ['client_id']; // 为 Order 模型指定租户列为 client_id
    // ...
}

登录后复制

进阶用法：打破隔离与临时禁用

有时，你可能需要查看所有租户的数据（例如在管理后台），或者在执行某些特定任务时暂时禁用租户隔离。

查看所有租户数据：

使用 allTenants() 方法可以临时禁用租户作用域：

<pre class="brush:php;toolbar:false;">// 这将返回所有公司的产品，忽略当前租户设置
$allProducts = Product::allTenants()->get();

登录后复制

禁用特定租户作用域：

如果你同时设置了多个租户（例如 company_id 和 branch_id），但只想禁用其中一个，可以使用 withoutGlobalScope()：

<pre class="brush:php;toolbar:false;">// 忽略 company_id 作用域，但其他租户作用域（如果有）依然生效
$products = Product::withoutGlobalScope('company_id')->get();

登录后复制

全局禁用/启用租户管理：

对于一些管理任务，你可能需要完全禁用 Landlord 的租户管理功能，然后再重新启用：

<pre class="brush:php;toolbar:false;">if (Landlord::isEnabled()) {
    Landlord::disable(); // 禁用租户管理
    // 执行一些需要访问所有租户数据的管理任务
    Landlord::enable();  // 重新启用租户管理
}

登录后复制