# 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` 配置

### 环境变量

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

```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 索引的设置：

```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 测试：

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

应该返回：

```json
{"status":"available"}
```

## 数据持久化

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

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

## 索引管理

### 查看所有索引

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

### 删除索引

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

### 重建索引

在 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
```

## 性能优化

### 生产环境配置

在生产环境中，建议：

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

### 索引优化

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

```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',
            ],
        ],
    ],
],
```

## 更多信息

- [Meilisearch 官方文档](https://www.meilisearch.com/docs)
- [Laravel Scout 文档](https://laravel.com/docs/scout)
- [Meilisearch PHP SDK](https://github.com/meilisearch/meilisearch-php)