acf549c43c
- 实现基于 Laravel 11 和 Filament 3.X 的文档管理系统 - 添加用户认证和分组管理功能 - 实现文档上传、分类和权限控制 - 集成 Word 文档自动转换为 Markdown - 集成 Meilisearch 全文搜索引擎 - 实现文档在线预览功能 - 添加安全日志和审计功能 - 完整的简体中文界面 - 包含完整的项目文档和部署指南 技术栈: - Laravel 11.x - Filament 3.X - Meilisearch 1.5+ - Pandoc 文档转换 - Redis 队列系统 - Pest PHP 测试框架
259 lines
5.8 KiB
Markdown
259 lines
5.8 KiB
Markdown
# 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)
|