本指南将带您逐步实现多租户 Laravel 应用中的搜索功能。我们将以客户关系管理(CRM)应用为例，该应用允许用户存储联系人。

​
前提条件

本指南需要:

  • 已配置使用 meilisearch 驱动器的 Laravel 10 应用（需安装 Laravel Scout）
  • 运行中的 Meilisearch 服务器 — 参见我们的 快速入门
  • 搜索 API 密钥 — 可在您的 Meilisearch 仪表板中获取
  • 搜索 API 密钥 UID — 使用 密钥端点 获取

更倾向于自托管？请阅读我们的 安装指南。

​
模型与关系

我们的示例 CRM 是一个多租户应用，每个用户只能访问属于其组织的数据。

在技术层面上，这意味着：

  • User 模型属于一个 Organization
  • Contact 模型属于一个 Organization（只能被同一组织的用户访问）
  • Organization 模型拥有多个 User 和多个 Contact

基于此，第一步是定义这些模型及其关系：

在 app/Models/Contact.php 中：

<?php

namespace App\Models;

use Laravel\Scout\Searchable;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;

class Contact extends Model
{
    use Searchable;

    public function organization(): BelongsTo
    {
        return $this->belongsTo(Organization::class, 'organization_id');
    }
}

在 app/Models/User.php 中：

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens, Notifiable;

    /**
     * 可批量赋值的属性
     *
     * @var array<int, string>
     */
    protected $fillable = [
        'name',
        'email',
        'password',
    ];

    /**
     * 序列化时应隐藏的属性
     *
     * @var array<int, string>
     */
    protected $hidden = [
        'password',
        'remember_token',
    ];

    /**
     * 应进行类型转换的属性
     *
     * @var array<string, string>
     */
    protected $casts = [
        'email_verified_at' => 'datetime',
        'password' => 'hashed',
    ];

    public function organization()
    {
        return $this->belongsTo(Organization::class, 'organization_id');
    }
}

在 app/Models/Organization.php 中：

<?php
namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\HasMany;

class Organization extends Model
{
    public function contacts(): HasMany
    {
        return $this->hasMany(Contact::class);
    }
}

现在你已经对应用的模型及其关系有了扎实的理解，可以开始生成租户令牌了。

​
生成租户令牌

目前，所有 User 都可以搜索属于所有 Organization 的数据。为了防止这种情况发生，您需要为每个组织生成一个租户令牌。然后可以使用此令牌来验证对 Meilisearch 的请求，并确保用户只能访问其组织的数据。同一个 Organization 内的所有 User 将共享相同的令牌。

在本指南中，您将在从数据库检索组织时生成令牌。如果组织没有令牌，您将生成一个并将其存储在 meilisearch_token 属性中。

更新 app/Models/Organization.php：

<?php

namespace App\Models;

use DateTime;
use Laravel\Scout\EngineManager;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\HasMany;
use Illuminate\Support\Facades\Log;

class Organization extends Model
{

    public function contacts(): HasMany
    {
        return $this->hasMany(Contact::class);
    }

    protected static function booted()
    {
        static::retrieved(function (Organization $organization) {
            // 您可能希望添加一些逻辑来跳过在某些环境中生成令牌
            if (env('SCOUT_DRIVER') === 'array' && env('APP_ENV') === 'testing') {
                $organization->meilisearch_token = 'fake-tenant-token';
                return;
            }

            // 如果组织已有令牌则提前返回
            if ($organization->meilisearch_token) {
                Log::debug('Organization ' . $organization->id . ': already has a token');
                return;
            }
            Log::debug('Generating tenant token for organization ID: ' . $organization->id);

            // 下面的对象用于生成租户令牌，该令牌：
            // • 适用于所有索引
            // • 仅筛选 `organization_id` 等于此组织 ID 的文档
            $searchRules = (object) [
                '*' => (object) [
                    'filter' => 'organization_id = ' . $organization->id,
                ]
            ];

            // 替换为您自己的 Search API key 和 API key UID
            $meiliApiKey = env('MEILISEARCH_SEARCH_KEY');
            $meiliApiKeyUid = env('MEILISEARCH_SEARCH_KEY_UID');

            // 生成令牌
            $token = self::generateMeiliTenantToken($meiliApiKeyUid, $searchRules, $meiliApiKey);

            // 将令牌保存到数据库
            $organization->meilisearch_token = $token;
            $organization->save();
        });
    }

    protected static function generateMeiliTenantToken($meiliApiKeyUid, $searchRules, $meiliApiKey)
    {
        $meilisearch = resolve(EngineManager::class)->engine();

        return $meilisearch->generateTenantToken(
            $meiliApiKeyUid,
            $searchRules,
            [
                'apiKey' => $meiliApiKey,
                'expiresAt' => new DateTime('2030-12-31'),
            ]
        );
    }
}

现在 Organization 模型已能生成租户令牌，您需要向前端提供这些令牌，以便其安全地访问 Meilisearch。

​
在 Laravel Blade 中使用租户令牌

使用 视图合成器 为视图提供搜索令牌。这种方式可以确保所有视图都能获取到令牌，而无需手动传递。

如果愿意，你也可以使用 with 方法手动将令牌传递给每个视图。

创建一个新的 app/View/Composers/AuthComposer.php 文件：

<?php

namespace App\View\Composers;

use App\Models\User;
use Illuminate\Support\Facades\Auth;
use Illuminate\Support\Facades\Vite;
use Illuminate\View\View;

class AuthComposer
{
    /**
     * 创建新的个人资料合成器
     */
    public function __construct() {}

    /**
     * 绑定数据到视图
     */
    public function compose(View $view): void
    {
        $user = Auth::user();
        $view->with([
            'meilisearchToken' => $user->organization->meilisearch_token,
        ]);
    }
}

现在，在 AppServiceProvider 中注册这个视图合成器：

<?php

namespace App\Providers;

use App\View\Composers\AuthComposer;
use Illuminate\Support\Facades\View;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * 注册应用服务
     */
    public function register(): void
    {
        //
    }

    /**
     * 启动应用服务
     */
    public function boot(): void
    {
        // 在所有视图中使用此视图合成器
        View::composer('*', AuthComposer::class);
    }
}

搞定！现在所有视图都可以访问 meilisearchToken 变量了。你可以在前端使用这个变量。

​
构建搜索界面

本指南使用 Vue InstantSearch 来构建搜索界面。Vue InstantSearch 是一套用于在 Vue 应用中构建搜索界面的组件和工具集。如果您偏好其他 JavaScript 框架，请查看我们的其他前端集成方案。

首先安装依赖项：

npm install vue-instantsearch @meilisearch/instant-meilisearch

现在创建一个使用 Vue InstantSearch 的 Vue 应用。新建 resources/js/vue-app.js 文件：

import { createApp } from 'vue'
import InstantSearch from 'vue-instantsearch/vue3/es'
import Meilisearch from './components/Meilisearch.vue'

const app = createApp({
  components: {
    Meilisearch
  }
})

app.use(InstantSearch)
app.mount('#vue-app')

该文件初始化了您的 Vue 应用并配置其使用 Vue InstantSearch。同时它还注册了接下来要创建的 Meilisearch 组件。

Meilisearch 组件负责初始化 Vue Instantsearch 客户端。它使用 @meilisearch/instant-meilisearch 包来创建与 Instantsearch 兼容的搜索客户端。

在 resources/js/components/Meilisearch.vue 中创建该组件：

<script setup lang="ts">
import { instantMeiliSearch } from "@meilisearch/instant-meilisearch"

const props = defineProps<{
  host: string,
  apiKey: string,
  indexName: string,
}>()

const { searchClient } = instantMeiliSearch(props.host, props.apiKey)
</script>

<template>
  <ais-instant-search :search-client="searchClient" :index-name="props.indexName">
    <!-- 插槽允许您在此组件内渲染内容，例如搜索结果 -->
    <slot name="default"></slot>
  </ais-instant-search>
</template>

您可以在任何 Blade 视图中使用 Meilisearch 组件，只需为其提供租户令牌即可。别忘了添加 @vite 指令来将 Vue 应用包含到您的视图中。

<!-- resources/views/contacts/index.blade.php -->

<div id="vue-app">
    <meilisearch index-name="contacts" api-key="{{ $meilisearchToken }}" host="https://edge.meilisearch.com">
    </meilisearch>
</div>

@push('scripts')
    @vite('resources/js/vue-app.js')
@endpush

大功告成！您现在拥有一个安全且支持多租户的搜索界面。用户只能访问其组织的数据，您可以放心其他租户的数据是安全的。

​
总结

在本指南中，您了解了如何在 Laravel 应用中实现安全的多租户搜索功能。您为每个组织生成了租户令牌（tenant token），并使用它们来保护对 Meilisearch 的访问。同时，您还使用 Vue InstantSearch 构建了搜索界面，并为其提供了租户令牌。

本指南中的所有代码都是我们在 Laravel CRM 示例应用中实现的简化版本。完整代码请查看 GitHub。