# 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)