docs: 添加 Meilisearch 配置指南
- 说明如何配置 Meilisearch - 提供 Docker 运行命令 - 包含常见问题和解决方案 - 说明索引管理和搜索配置 - 提供生产环境配置建议 - 包含性能优化建议
This commit is contained in:
@@ -1,95 +1,10 @@
|
||||
# Meilisearch 安装和配置指南
|
||||
# Meilisearch 配置指南
|
||||
|
||||
## 概述
|
||||
|
||||
本项目使用 Meilisearch 作为全文搜索引擎，为文档内容提供快速准确的搜索功能。
|
||||
本系统使用 Meilisearch 作为全文搜索引擎，为文档提供快速、相关的搜索功能。
|
||||
|
||||
## 安装方式
|
||||
|
||||
### 方式 1：使用 Docker（推荐）
|
||||
|
||||
项目已经配置了 `docker-compose.yml` 文件，可以快速启动 Meilisearch 服务。
|
||||
|
||||
#### 启动服务
|
||||
|
||||
```bash
|
||||
# 启动 Meilisearch 服务
|
||||
docker-compose up -d meilisearch
|
||||
|
||||
# 查看服务状态
|
||||
docker-compose ps
|
||||
|
||||
# 查看服务日志
|
||||
docker-compose logs -f meilisearch
|
||||
```
|
||||
|
||||
#### 停止服务
|
||||
|
||||
```bash
|
||||
# 停止服务
|
||||
docker-compose down
|
||||
|
||||
# 停止服务并删除数据卷
|
||||
docker-compose down -v
|
||||
```
|
||||
|
||||
### 方式 2：本地安装（macOS）
|
||||
|
||||
使用 Homebrew 安装：
|
||||
|
||||
```bash
|
||||
# 安装 Meilisearch
|
||||
brew install meilisearch
|
||||
|
||||
# 启动服务
|
||||
meilisearch --master-key="your-master-key-change-this-in-production"
|
||||
```
|
||||
|
||||
### 方式 3：本地安装（Linux）
|
||||
|
||||
```bash
|
||||
# 下载 Meilisearch
|
||||
curl -L https://install.meilisearch.com | sh
|
||||
|
||||
# 启动服务
|
||||
./meilisearch --master-key="your-master-key-change-this-in-production"
|
||||
```
|
||||
|
||||
### 方式 4：本地安装（Windows）
|
||||
|
||||
从 [Meilisearch 官方网站](https://www.meilisearch.com/docs/learn/getting_started/installation) 下载 Windows 版本，然后运行：
|
||||
|
||||
```powershell
|
||||
.\meilisearch.exe --master-key="your-master-key-change-this-in-production"
|
||||
```
|
||||
|
||||
## Laravel Scout 安装
|
||||
|
||||
本项目使用 Laravel Scout 作为搜索抽象层。
|
||||
|
||||
### 安装依赖包
|
||||
|
||||
```bash
|
||||
# 安装 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` 配置
|
||||
## 配置说明
|
||||
|
||||
### 环境变量
|
||||
|
||||
@@ -97,162 +12,303 @@ php artisan vendor:publish --provider="Laravel\Scout\ScoutServiceProvider"
|
||||
|
||||
```env
|
||||
SCOUT_DRIVER=meilisearch
|
||||
MEILISEARCH_HOST=http://127.0.0.1:7700
|
||||
MEILISEARCH_KEY=your-master-key-change-this-in-production
|
||||
MEILISEARCH_HOST=http://localhost:7700
|
||||
MEILISEARCH_KEY=dev-master-key
|
||||
```
|
||||
|
||||
### Scout 索引配置
|
||||
**重要**：`MEILISEARCH_KEY` 必须与 Meilisearch 服务器的 master key 一致。
|
||||
|
||||
在 `config/scout.php` 中已配置 documents 索引的设置：
|
||||
## 使用 Docker 运行 Meilisearch
|
||||
|
||||
```php
|
||||
'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 测试：
|
||||
### 启动 Meilisearch 容器
|
||||
|
||||
```bash
|
||||
curl -X GET 'http://localhost:7700/health'
|
||||
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 密钥
|
||||
|
||||
使用 Docker 方式时，Meilisearch 数据存储在 `storage/meilisearch` 目录中。
|
||||
```bash
|
||||
curl -H "Authorization: Bearer dev-master-key" http://localhost:7700/indexes
|
||||
```
|
||||
|
||||
**注意**：请确保将此目录添加到 `.gitignore` 文件中，避免将索引数据提交到版本控制系统。
|
||||
应该返回索引列表（可能为空）。
|
||||
|
||||
### 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
|
||||
curl -X GET 'http://localhost:7700/indexes' \
|
||||
-H 'Authorization: Bearer your-master-key-change-this-in-production'
|
||||
php artisan tinker
|
||||
```
|
||||
|
||||
```php
|
||||
$client = app(\Meilisearch\Client::class);
|
||||
$indexes = $client->getAllIndexes();
|
||||
foreach ($indexes as $index) {
|
||||
echo $index->getUid() . PHP_EOL;
|
||||
}
|
||||
```
|
||||
|
||||
### 删除索引
|
||||
|
||||
```bash
|
||||
curl -X DELETE 'http://localhost:7700/indexes/documents' \
|
||||
-H 'Authorization: Bearer your-master-key-change-this-in-production'
|
||||
php artisan scout:flush "App\Models\Document"
|
||||
```
|
||||
|
||||
### 重建索引
|
||||
|
||||
在 Laravel 项目中运行：
|
||||
|
||||
```bash
|
||||
# 清空所有索引
|
||||
# 先清空
|
||||
php artisan scout:flush "App\Models\Document"
|
||||
|
||||
# 重新导入所有文档
|
||||
# 再导入
|
||||
php artisan scout:import "App\Models\Document"
|
||||
```
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 服务无法启动
|
||||
|
||||
1. 检查端口 7700 是否被占用：
|
||||
```bash
|
||||
lsof -i :7700
|
||||
```
|
||||
|
||||
2. 查看 Docker 日志：
|
||||
```bash
|
||||
docker-compose logs meilisearch
|
||||
```
|
||||
|
||||
### 搜索不返回结果
|
||||
|
||||
1. 检查文档是否已索引：
|
||||
```bash
|
||||
php artisan scout:import "App\Models\Document"
|
||||
```
|
||||
|
||||
2. 验证索引配置：
|
||||
```bash
|
||||
curl -X GET 'http://localhost:7700/indexes/documents/settings' \
|
||||
-H 'Authorization: Bearer your-master-key-change-this-in-production'
|
||||
```
|
||||
|
||||
### 权限错误
|
||||
|
||||
确保 `storage/meilisearch` 目录有正确的写入权限：
|
||||
### 查看索引统计
|
||||
|
||||
```bash
|
||||
chmod -R 775 storage/meilisearch
|
||||
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` 命令批量导入，而不是逐个保存模型。
|
||||
|
||||
1. 使用强密钥作为 `MEILI_MASTER_KEY`
|
||||
2. 设置 `MEILI_ENV=production`
|
||||
3. 配置适当的资源限制（CPU、内存）
|
||||
4. 定期备份 `storage/meilisearch` 目录
|
||||
### 2. 异步索引
|
||||
|
||||
### 索引优化
|
||||
|
||||
根据实际使用情况调整索引设置：
|
||||
|
||||
```php
|
||||
// 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',
|
||||
],
|
||||
],
|
||||
],
|
||||
],
|
||||
在 `.env` 中配置：
|
||||
```env
|
||||
SCOUT_QUEUE=true
|
||||
```
|
||||
|
||||
## 更多信息
|
||||
这样索引操作会在队列中异步执行。
|
||||
|
||||
- [Meilisearch 官方文档](https://www.meilisearch.com/docs)
|
||||
### 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)
|
||||
|
||||
Reference in New Issue
Block a user