lizhuoran
93919956b7
- 说明如何配置 Meilisearch - 提供 Docker 运行命令 - 包含常见问题和解决方案 - 说明索引管理和搜索配置 - 提供生产环境配置建议 - 包含性能优化建议
315 lines
5.5 KiB
Markdown
315 lines
5.5 KiB
Markdown
# Meilisearch 配置指南
|
||
|
||
## 概述
|
||
|
||
本系统使用 Meilisearch 作为全文搜索引擎，为文档提供快速、相关的搜索功能。
|
||
|
||
## 配置说明
|
||
|
||
### 环境变量
|
||
|
||
在 `.env` 文件中配置以下变量：
|
||
|
||
```env
|
||
SCOUT_DRIVER=meilisearch
|
||
MEILISEARCH_HOST=http://localhost:7700
|
||
MEILISEARCH_KEY=dev-master-key
|
||
```
|
||
|
||
**重要**：`MEILISEARCH_KEY` 必须与 Meilisearch 服务器的 master key 一致。
|
||
|
||
## 使用 Docker 运行 Meilisearch
|
||
|
||
### 启动 Meilisearch 容器
|
||
|
||
```bash
|
||
docker run -d \
|
||
--name meilisearch \
|
||
-p 7700:7700 \
|
||
-e MEILI_MASTER_KEY=dev-master-key \
|
||
-v $(pwd)/storage/meilisearch:/meili_data \
|
||
getmeili/meilisearch:latest
|
||
```
|
||
|
||
### 检查容器状态
|
||
|
||
```bash
|
||
docker ps | grep meilisearch
|
||
```
|
||
|
||
### 查看容器日志
|
||
|
||
```bash
|
||
docker logs meilisearch
|
||
```
|
||
|
||
### 停止容器
|
||
|
||
```bash
|
||
docker stop meilisearch
|
||
```
|
||
|
||
### 重启容器
|
||
|
||
```bash
|
||
docker restart meilisearch
|
||
```
|
||
|
||
## 验证配置
|
||
|
||
### 1. 检查 Meilisearch 健康状态
|
||
|
||
```bash
|
||
curl http://localhost:7700/health
|
||
```
|
||
|
||
应该返回：
|
||
```json
|
||
{"status":"available"}
|
||
```
|
||
|
||
### 2. 测试 API 密钥
|
||
|
||
```bash
|
||
curl -H "Authorization: Bearer dev-master-key" http://localhost:7700/indexes
|
||
```
|
||
|
||
应该返回索引列表（可能为空）。
|
||
|
||
### 3. 在 Laravel 中测试
|
||
|
||
```bash
|
||
php artisan tinker
|
||
```
|
||
|
||
然后执行：
|
||
```php
|
||
$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 容器的环境变量：
|
||
```bash
|
||
docker inspect meilisearch | grep MEILI_MASTER_KEY
|
||
```
|
||
|
||
2. 更新 `.env` 文件中的 `MEILISEARCH_KEY` 为相同的值
|
||
|
||
3. 清除配置缓存：
|
||
```bash
|
||
php artisan config:clear
|
||
```
|
||
|
||
### 2. "Connection refused" 错误
|
||
|
||
**原因**：Meilisearch 服务未运行。
|
||
|
||
**解决方案**：
|
||
```bash
|
||
# 检查容器是否运行
|
||
docker ps | grep meilisearch
|
||
|
||
# 如果未运行，启动容器
|
||
docker start meilisearch
|
||
|
||
# 或者重新创建容器（见上文）
|
||
```
|
||
|
||
### 3. 索引未更新
|
||
|
||
**原因**：文档模型的 `searchable` 配置可能有问题。
|
||
|
||
**解决方案**：
|
||
```bash
|
||
# 重新索引所有文档
|
||
php artisan scout:import "App\Models\Document"
|
||
|
||
# 清空索引
|
||
php artisan scout:flush "App\Models\Document"
|
||
|
||
# 重新索引
|
||
php artisan scout:import "App\Models\Document"
|
||
```
|
||
|
||
## 索引管理
|
||
|
||
### 查看所有索引
|
||
|
||
```bash
|
||
php artisan tinker
|
||
```
|
||
|
||
```php
|
||
$client = app(\Meilisearch\Client::class);
|
||
$indexes = $client->getAllIndexes();
|
||
foreach ($indexes as $index) {
|
||
echo $index->getUid() . PHP_EOL;
|
||
}
|
||
```
|
||
|
||
### 删除索引
|
||
|
||
```bash
|
||
php artisan scout:flush "App\Models\Document"
|
||
```
|
||
|
||
### 重建索引
|
||
|
||
```bash
|
||
# 先清空
|
||
php artisan scout:flush "App\Models\Document"
|
||
|
||
# 再导入
|
||
php artisan scout:import "App\Models\Document"
|
||
```
|
||
|
||
### 查看索引统计
|
||
|
||
```bash
|
||
php artisan tinker
|
||
```
|
||
|
||
```php
|
||
$client = app(\Meilisearch\Client::class);
|
||
$index = $client->index('documents');
|
||
$stats = $index->stats();
|
||
print_r($stats);
|
||
```
|
||
|
||
## 搜索配置
|
||
|
||
### 可搜索字段
|
||
|
||
在 `Document` 模型中配置：
|
||
|
||
```php
|
||
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 文档](https://docs.meilisearch.com/)
|
||
|
||
## 生产环境配置
|
||
|
||
### 安全建议
|
||
|
||
1. **使用强密钥**：不要在生产环境使用 `dev-master-key`
|
||
```bash
|
||
# 生成随机密钥
|
||
openssl rand -base64 32
|
||
```
|
||
|
||
2. **限制访问**：配置防火墙规则，只允许应用服务器访问 Meilisearch
|
||
|
||
3. **使用 HTTPS**：在生产环境使用 HTTPS 连接
|
||
|
||
### Docker Compose 配置
|
||
|
||
在 `docker-compose.yml` 中：
|
||
|
||
```yaml
|
||
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` 中配置：
|
||
```env
|
||
SCOUT_QUEUE=true
|
||
```
|
||
|
||
这样索引操作会在队列中异步执行。
|
||
|
||
### 3. 索引设置
|
||
|
||
优化 Meilisearch 的索引设置以提高搜索性能：
|
||
|
||
```php
|
||
$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：
|
||
```bash
|
||
curl -H "Authorization: Bearer dev-master-key" http://localhost:7700/stats
|
||
```
|
||
|
||
### 日志
|
||
|
||
Docker 容器日志：
|
||
```bash
|
||
docker logs -f meilisearch
|
||
```
|
||
|
||
## 相关文档
|
||
|
||
- [Meilisearch 官方文档](https://docs.meilisearch.com/)
|
||
- [Laravel Scout 文档](https://laravel.com/docs/scout)
|
||
- [Meilisearch PHP SDK](https://github.com/meilisearch/meilisearch-php)
|