KnowledgeBase/docs/MEILISEARCH_SETUP.md

Meilisearch 安装和配置指南

概述

本项目使用 Meilisearch 作为全文搜索引擎，为文档内容提供快速准确的搜索功能。

安装方式

方式 1：使用 Docker（推荐）

项目已经配置了 docker-compose.yml 文件，可以快速启动 Meilisearch 服务。

启动服务

# 启动 Meilisearch 服务
docker-compose up -d meilisearch

# 查看服务状态
docker-compose ps

# 查看服务日志
docker-compose logs -f meilisearch

停止服务

# 停止服务
docker-compose down

# 停止服务并删除数据卷
docker-compose down -v

方式 2：本地安装（macOS）

使用 Homebrew 安装：

# 安装 Meilisearch
brew install meilisearch

# 启动服务
meilisearch --master-key="your-master-key-change-this-in-production"

方式 3：本地安装（Linux）

# 下载 Meilisearch
curl -L https://install.meilisearch.com | sh

# 启动服务
./meilisearch --master-key="your-master-key-change-this-in-production"

方式 4：本地安装（Windows）

从 Meilisearch 官方网站 下载 Windows 版本，然后运行：

.\meilisearch.exe --master-key="your-master-key-change-this-in-production"

Laravel Scout 安装

本项目使用 Laravel Scout 作为搜索抽象层。

安装依赖包

# 安装 Laravel Scout
composer require laravel/scout

# 安装 Meilisearch PHP SDK
composer require meilisearch/meilisearch-php http-interop/http-factory-guzzle

# 发布 Scout 配置文件
php artisan vendor:publish --provider="Laravel\Scout\ScoutServiceProvider"

安装完成后，会在 config/scout.php 中生成配置文件。

配置

主密钥（Master Key）

重要：在生产环境中，必须更改默认的主密钥！

1. 在 docker-compose.yml 中修改 MEILI_MASTER_KEY 环境变量
2. 在 .env 文件中更新 MEILISEARCH_KEY 配置

环境变量

在 .env 文件中配置以下变量：

SCOUT_DRIVER=meilisearch
MEILISEARCH_HOST=http://127.0.0.1:7700
MEILISEARCH_KEY=your-master-key-change-this-in-production

Scout 索引配置

在 config/scout.php 中已配置 documents 索引的设置：

'meilisearch' => [
    'host' => env('MEILISEARCH_HOST', 'http://localhost:7700'),
    'key' => env('MEILISEARCH_KEY'),
    'index-settings' => [
        'documents' => [
            'filterableAttributes' => ['type', 'group_id', 'uploaded_by', 'conversion_status'],
            'sortableAttributes' => ['created_at', 'title', 'updated_at'],
            'searchableAttributes' => ['title', 'description', 'markdown_content'],
            'displayedAttributes' => ['id', 'title', 'description', 'type', 'group_id', 'uploaded_by', 'created_at', 'updated_at'],
        ],
    ],
],

配置说明：

• filterableAttributes: 可用于筛选的字段（类型、分组、上传者、转换状态）
• sortableAttributes: 可用于排序的字段（创建时间、标题、更新时间）
• searchableAttributes: 可搜索的字段（标题、描述、Markdown 内容）
• displayedAttributes: 搜索结果中返回的字段

验证安装

访问 Meilisearch 管理界面：

http://localhost:7700

或使用 curl 测试：

curl -X GET 'http://localhost:7700/health'

应该返回：

{"status":"available"}

数据持久化

使用 Docker 方式时，Meilisearch 数据存储在 storage/meilisearch 目录中。

注意：请确保将此目录添加到 .gitignore 文件中，避免将索引数据提交到版本控制系统。

索引管理

查看所有索引

curl -X GET 'http://localhost:7700/indexes' \
  -H 'Authorization: Bearer your-master-key-change-this-in-production'

删除索引

curl -X DELETE 'http://localhost:7700/indexes/documents' \
  -H 'Authorization: Bearer your-master-key-change-this-in-production'

重建索引

在 Laravel 项目中运行：

# 清空所有索引
php artisan scout:flush "App\Models\Document"

# 重新导入所有文档
php artisan scout:import "App\Models\Document"

故障排除

服务无法启动

1. 检查端口 7700 是否被占用：

   lsof -i :7700
   

2. 查看 Docker 日志：

   docker-compose logs meilisearch
   

搜索不返回结果

1. 检查文档是否已索引：

   php artisan scout:import "App\Models\Document"
   

2. 验证索引配置：

   curl -X GET 'http://localhost:7700/indexes/documents/settings' \
     -H 'Authorization: Bearer your-master-key-change-this-in-production'
   

权限错误

确保 storage/meilisearch 目录有正确的写入权限：

chmod -R 775 storage/meilisearch

性能优化

生产环境配置

在生产环境中，建议：

1. 使用强密钥作为 MEILI_MASTER_KEY
2. 设置 MEILI_ENV=production
3. 配置适当的资源限制（CPU、内存）
4. 定期备份 storage/meilisearch 目录

索引优化

根据实际使用情况调整索引设置：

// config/scout.php
'meilisearch' => [
    'index-settings' => [
        'documents' => [
            'filterableAttributes' => ['type', 'group_id', 'uploaded_by'],
            'sortableAttributes' => ['created_at', 'title'],
            'searchableAttributes' => ['title', 'description', 'markdown_content'],
            'rankingRules' => [
                'words',
                'typo',
                'proximity',
                'attribute',
                'sort',
                'exactness',
            ],
        ],
    ],
],

更多信息

• Meilisearch 官方文档
• Laravel Scout 文档
• Meilisearch PHP SDK