KnowledgeBase/docs/MEILISEARCH_SETUP.md

Meilisearch 配置指南

概述

本系统使用 Meilisearch 作为全文搜索引擎，为文档提供快速、相关的搜索功能。

配置说明

环境变量

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

SCOUT_DRIVER=meilisearch
MEILISEARCH_HOST=http://localhost:7700
MEILISEARCH_KEY=dev-master-key

重要：MEILISEARCH_KEY 必须与 Meilisearch 服务器的 master key 一致。

使用 Docker 运行 Meilisearch

启动 Meilisearch 容器

docker run -d \
  --name meilisearch \
  -p 7700:7700 \
  -e MEILI_MASTER_KEY=dev-master-key \
  -v $(pwd)/storage/meilisearch:/meili_data \
  getmeili/meilisearch:latest

检查容器状态

docker ps | grep meilisearch

查看容器日志

docker logs meilisearch

停止容器

docker stop meilisearch

重启容器

docker restart meilisearch

验证配置

1. 检查 Meilisearch 健康状态

curl http://localhost:7700/health

应该返回：

{"status":"available"}

2. 测试 API 密钥

curl -H "Authorization: Bearer dev-master-key" http://localhost:7700/indexes

应该返回索引列表（可能为空）。

3. 在 Laravel 中测试

php artisan tinker

然后执行：

$client = app(\Meilisearch\Client::class);
$health = $client->health();
print_r($health);

常见问题

1. "The provided API key is invalid" 错误

原因：.env 文件中的 MEILISEARCH_KEY 与 Meilisearch 服务器的 master key 不一致。

解决方案：

1. 检查 Docker 容器的环境变量：

   docker inspect meilisearch | grep MEILI_MASTER_KEY
   

2. 更新 .env 文件中的 MEILISEARCH_KEY 为相同的值

3. 清除配置缓存：

   php artisan config:clear
   

2. "Connection refused" 错误

原因：Meilisearch 服务未运行。

解决方案：

# 检查容器是否运行
docker ps | grep meilisearch

# 如果未运行，启动容器
docker start meilisearch

# 或者重新创建容器（见上文）

3. 索引未更新

原因：文档模型的 searchable 配置可能有问题。

解决方案：

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

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

# 重新索引
php artisan scout:import "App\Models\Document"

索引管理

查看所有索引

php artisan tinker

$client = app(\Meilisearch\Client::class);
$indexes = $client->getAllIndexes();
foreach ($indexes as $index) {
    echo $index->getUid() . PHP_EOL;
}

删除索引

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

重建索引

# 先清空
php artisan scout:flush "App\Models\Document"

# 再导入
php artisan scout:import "App\Models\Document"

查看索引统计

php artisan tinker

$client = app(\Meilisearch\Client::class);
$index = $client->index('documents');
$stats = $index->stats();
print_r($stats);

搜索配置

可搜索字段

在 Document 模型中配置：

public function toSearchableArray()
{
    return [
        'id' => $this->id,
        'title' => $this->title,
        'description' => $this->description,
        'markdown_content' => $this->markdown_content,
        'file_name' => $this->file_name,
    ];
}

搜索设置

可以在 Meilisearch 中配置：

• 可搜索属性（searchable attributes）
• 可过滤属性（filterable attributes）
• 可排序属性（sortable attributes）
• 同义词（synonyms）
• 停用词（stop words）

参考：Meilisearch 文档

生产环境配置

安全建议

1. 使用强密钥：不要在生产环境使用 dev-master-key

   # 生成随机密钥
   openssl rand -base64 32
   

2. 限制访问：配置防火墙规则，只允许应用服务器访问 Meilisearch

3. 使用 HTTPS：在生产环境使用 HTTPS 连接

Docker Compose 配置

在 docker-compose.yml 中：

meilisearch:
  image: getmeili/meilisearch:latest
  ports:
    - "7700:7700"
  environment:
    - MEILI_MASTER_KEY=${MEILISEARCH_KEY}
    - MEILI_ENV=production
  volumes:
    - ./storage/meilisearch:/meili_data
  restart: unless-stopped

性能优化

1. 批量索引

使用 scout:import 命令批量导入，而不是逐个保存模型。

2. 异步索引

在 .env 中配置：

SCOUT_QUEUE=true

这样索引操作会在队列中异步执行。

3. 索引设置

优化 Meilisearch 的索引设置以提高搜索性能：

$client = app(\Meilisearch\Client::class);
$index = $client->index('documents');

// 设置可搜索属性
$index->updateSearchableAttributes([
    'title',
    'description',
    'markdown_content',
]);

// 设置可过滤属性
$index->updateFilterableAttributes([
    'type',
    'group_id',
    'uploaded_by',
]);

// 设置可排序属性
$index->updateSortableAttributes([
    'created_at',
    'updated_at',
]);

监控

查看 Meilisearch 统计

访问：http://localhost:7700/stats

或使用 API：

curl -H "Authorization: Bearer dev-master-key" http://localhost:7700/stats

日志

Docker 容器日志：

docker logs -f meilisearch

相关文档

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