Laravel 动态数据库切换：实现多租户应用的用户数据隔离

胖浩吖_1227

发布时间：2025-11-27 14:40:01

698人浏览过

来源于php中文网

原创

laravel 动态数据库切换：实现多租户应用的用户数据隔离

本教程详细阐述了在 Laravel 8+ SaaS 应用中，如何根据用户登录信息动态切换数据库连接。通过配置多个数据库连接、利用 `DB::connection()` 方法以及在 Eloquent 模型中指定连接，实现用户数据的隔离。文章还提供了在登录流程中集成动态切换逻辑的指导，并强调了相关注意事项，旨在帮助开发者构建高效、安全的定制化多租户解决方案。

在构建多租户 SaaS（软件即服务）应用程序时，根据不同用户或租户隔离数据是一个常见且关键的需求。Laravel 框架提供了灵活的数据库连接管理机制，允许开发者根据用户登录信息动态切换到特定的数据库连接，从而实现数据的物理隔离。本文将详细介绍如何在 Laravel 8+ 应用中实现这一功能。

1. 配置多个数据库连接

Laravel 允许您在 config/database.php 配置文件中定义多个数据库连接。对于多租户应用，除了主数据库（通常用于存储租户信息和用户认证信息）外，您还需要为每个租户预留或动态创建数据库连接配置。

以下是一个 config/database.php 中定义多个连接的示例：

<?php

return [

    // ... 其他配置

    'connections' => [

        'mysql' => [
            'driver' => 'mysql',
            'url' => env('DATABASE_URL'),
            'host' => env('DB_HOST', '127.0.0.1'),
            'port' => env('DB_PORT', '3306'),
            'database' => env('DB_DATABASE', 'forge'), // 主数据库，存储租户信息
            'username' => env('DB_USERNAME', 'forge'),
            'password' => env('DB_PASSWORD', ''),
            'unix_socket' => env('DB_SOCKET', ''),
            'charset' => 'utf8mb4',
            'collation' => 'utf8mb4_unicode_ci',
            'prefix' => '',
            'prefix_indexes' => true,
            'strict' => true,
            'engine' => null,
            'options' => extension_loaded('pdo_mysql') ? array_filter([
                PDO::MYSQL_ATTR_SSL_CA => env('MYSQL_ATTR_SSL_CA'),
            ]) : [],
        ],

        // 这是一个占位符，用于动态连接。
        // 实际的租户连接配置将在运行时构建
        'tenant_connection' => [
            'driver' => 'mysql',
            'host' => '', // 运行时填充
            'port' => '', // 运行时填充
            'database' => '', // 运行时填充
            'username' => '', // 运行时填充
            'password' => '', // 运行时填充
            'charset' => 'utf8mb4',
            'collation' => 'utf8mb4_unicode_ci',
            'prefix' => '',
            'strict' => true,
            'engine' => null,
        ],

        // 您也可以在这里预定义一些固定的租户连接，如果租户数量有限
        'tenant_one_db' => [
            'driver' => 'mysql',
            'host' => '127.0.0.1',
            'port' => '3306',
            'database' => 'tenant_one_database',
            'username' => 'tenant_one_user',
            'password' => 'tenant_one_password',
            'charset' => 'utf8mb4',
            'collation' => 'utf8mb4_unicode_ci',
            'prefix' => '',
            'strict' => true,
            'engine' => null,
        ],

    ],

    // ... 其他配置
];

在上述配置中，mysql 是您的主数据库连接，用于存储用户和租户的元数据。tenant_connection 是一个通用模板，其详细参数将在用户登录后根据租户信息动态填充。

2. 动态切换数据库连接

Laravel 提供了多种方式来动态切换数据库连接。

2.1 使用 DB::connection() 方法进行查询

对于使用 DB Facade 进行的原始查询或查询构建器操作，您可以使用 connection() 方法指定要使用的数据库连接。

use Illuminate\Support\Facades\DB;

// 从主数据库获取租户信息
$tenant = DB::connection('mysql')->table('tenants')->where('user_id', auth()->id())->first();

if ($tenant) {
    // 假设租户信息包含数据库连接详情
    $tenantDbName = $tenant->db_name;
    $tenantDbUser = $tenant->db_username;
    $tenantDbPass = $tenant->db_password;

    // 动态添加或修改一个数据库连接配置
    config()->set('database.connections.dynamic_tenant', [
        'driver' => 'mysql',
        'host' => '127.0.0.1', // 或从租户信息中获取
        'port' => '3306',
        'database' => $tenantDbName,
        'username' => $tenantDbUser,
        'password' => $tenantDbPass,
        'charset' => 'utf8mb4',
        'collation' => 'utf8mb4_unicode_ci',
        'prefix' => '',
        'strict' => true,
        'engine' => null,
    ]);

    // 使用动态连接执行查询
    $tenantUsers = DB::connection('dynamic_tenant')->table('users')->get();

    // 或者，如果您想设置默认连接，以便后续所有操作都使用此连接
    // config(['database.default' => 'dynamic_tenant']);
    // $tenantProducts = DB::table('products')->get(); // 这将使用 'dynamic_tenant' 连接
}

2.2 Eloquent 模型动态连接

对于 Eloquent 模型，您可以覆盖模型的 $connection 属性或 getConnectionName() 方法来指定其使用的数据库连接。

方法一：在模型中设置 $connection 属性

如果您的模型始终属于某个特定的租户连接，您可以在模型定义中直接指定连接名称。但这对于动态切换来说不够灵活。

Pandas 配置文件报告生成器

使用ydata-profiling（前身为pandas-profiling）生成全面的数据质量报告，包含相关性分析、缺失值模式和基数检测。导出交互式HTML仪表板和JSON摘要。

下载

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Product extends Model
{
    protected $connection = 'tenant_one_db'; // 假设这个模型总是连接到 tenant_one_db
    // ...
}

方法二：通过一个基类动态设置连接

更常见且灵活的做法是创建一个基类模型，所有租户相关的模型都继承自它。在基类中，您可以动态地获取当前租户的连接名称。

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Support\Facades\Config;

abstract class TenantModel extends Model
{
    public function getConnectionName()
    {
        // 尝试从当前请求或会话中获取租户数据库连接名称
        // 这需要您在登录或中间件中设置好
        return Config::get('database.default', 'mysql'); // 默认为主数据库
    }
}

// 您的租户相关模型
class Product extends TenantModel
{
    protected $fillable = ['name', 'price'];
    // ...
}

class Order extends TenantModel
{
    protected $fillable = ['total_amount', 'status'];
    // ...
}

当您访问 Product::all() 或 Order::find(1) 时，getConnectionName() 方法会被调用，从而使用当前设置的默认数据库连接。

3. 实现用户登录后的数据库切换逻辑

最理想的实现方式是在用户成功登录后，通过中间件或事件监听器来动态设置数据库连接。

3.1 登录流程中的逻辑

用户登录认证： 用户通过主数据库进行认证。
获取租户信息： 认证成功后，从主数据库中根据用户信息（如用户ID）查询对应的租户信息，包括该租户专用的数据库名称、用户名和密码。
动态配置连接： 使用获取到的租户数据库信息，动态地在 Laravel 的配置中注册一个新的数据库连接，或者修改默认连接。

3.2 使用中间件实现动态切换

创建一个中间件，在每个需要租户隔离的请求之前执行数据库切换逻辑。

php artisan make:middleware SetTenantDatabase

编辑 app/Http/Middleware/SetTenantDatabase.php：

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Config;
use Illuminate\Support\Facades\Auth;

class SetTenantDatabase
{
    /**
     * Handle an incoming request.
     *
     * @param  \Illuminate\Http\Request  $request
     * @param  \Closure(\Illuminate\Http\Request): (\Illuminate\Http\Response|\Illuminate\Http\RedirectResponse)  $next
     * @return \Illuminate\Http\Response|\Illuminate\Http\RedirectResponse
     */
    public function handle(Request $request, Closure $next)
    {
        if (Auth::check()) {
            // 1. 从主数据库获取租户信息
            // 假设您的User模型中有一个tenant_id，或者您有一个Tenant模型关联User
            $user = Auth::user();
            $tenant = DB::connection('mysql')->table('tenants')->where('id', $user->tenant_id)->first();

            if ($tenant) {
                // 2. 动态配置租户数据库连接
                $connectionName = 'tenant_db_' . $tenant->id; // 为每个租户创建唯一连接名

                Config::set('database.connections.' . $connectionName, [
                    'driver' => 'mysql',
                    'host' => $tenant->db_host ?? env('DB_HOST', '127.0.0.1'),
                    'port' => $tenant->db_port ?? env('DB_PORT', '3306'),
                    'database' => $tenant->db_name,
                    'username' => $tenant->db_username,
                    'password' => $tenant->db_password,
                    'charset' => 'utf8mb4',
                    'collation' => 'utf8mb4_unicode_ci',
                    'prefix' => '',
                    'strict' => true,
                    'engine' => null,
                ]);

                // 3. 设置当前请求的默认数据库连接
                Config::set('database.default', $connectionName);

                // 如果您的Eloquent模型继承自TenantModel，它们将自动使用此连接
                // 否则，您需要显式地使用 DB::connection($connectionName)
            }
        }

        return $next($request);
    }
}

注册中间件到 app/Http/Kernel.php 的 web 或 api 中间件组，或者直接在路由中应用：

// app/Http/Kernel.php
protected $middlewareGroups = [
    'web' => [
        // ...
        \App\Http\Middleware\SetTenantDatabase::class, // 在认证后执行
    ],
    // ...
];

或者在路由中：

Route::middleware(['auth', 'set.tenant.database'])->group(function () {
    // 所有这些路由都将使用租户数据库
    Route::resource('products', ProductController::class);
});

别忘了在 app/Http/Kernel.php 中为 set.tenant.database 定义一个别名：

protected $routeMiddleware = [
    // ...
    'set.tenant.database' => \App\Http\Middleware\SetTenantDatabase::class,
];

4. 注意事项与最佳实践

安全性： 租户的数据库凭据应安全地存储在主数据库中（例如，加密存储密码）。在运行时动态配置连接时，确保这些凭据不会泄露。
性能考量： 频繁地动态创建和销毁数据库连接可能会带来一定的性能开销。然而，对于大多数Web请求，这种开销通常在可接受范围内。如果遇到性能瓶颈，可以考虑连接池或优化租户数据库的连接参数。
事务管理： 在跨数据库进行操作时（例如，从主数据库获取租户信息，然后写入租户数据库），需要特别注意事务的一致性。Laravel 的 DB::transaction() 仅限于单个连接。如果需要跨数据库事务，可能需要手动管理或采用分布式事务解决方案。
缓存： 租户的数据库配置信息可以被缓存起来，以减少每次请求都从主数据库查询的开销。
命令行工具和队列： 对于 Artisan 命令和队列任务，它们通常不经过 Web 中间件。您需要为这些场景单独实现数据库切换逻辑，例如在任务执行前手动设置连接。
测试： 针对多租户应用进行测试时，确保能够模拟不同的租户环境并验证数据隔离的正确性。
数据库迁移： 管理多个租户数据库的迁移是一个复杂的问题。您可以为每个租户数据库运行独立的迁移，或者使用一些专门的包来简化多租户迁移管理。

总结

通过在 Laravel 中动态配置和切换数据库连接，您可以有效地为多租户 SaaS 应用实现数据隔离。核心思路是在用户登录后，根据其租户信息动态构建并设置数据库连接，无论是通过 DB::connection() 方法进行查询，还是通过 Eloquent 模型的基类自动切换。结合中间件，可以优雅地将这一逻辑集成到应用的请求生命周期中，从而构建出安全、可扩展的多租户解决方案。务必关注安全性、性能和事务管理等方面的最佳实践，以确保应用的健壮性。

PHP 8.1 网站数据库索引失效怎么排查

使用Laravel Sail怎么安装项目完整操作

怎样在MySQL云数据库RDS中自定义创建高权限账号

虚拟机环境怎么搭建并安装Laravel

为什么MySQL报Packet too large错误及如何调优