feat: 初始化知识库系统项目
- 实现基于 Laravel 11 和 Filament 3.X 的文档管理系统 - 添加用户认证和分组管理功能 - 实现文档上传、分类和权限控制 - 集成 Word 文档自动转换为 Markdown - 集成 Meilisearch 全文搜索引擎 - 实现文档在线预览功能 - 添加安全日志和审计功能 - 完整的简体中文界面 - 包含完整的项目文档和部署指南 技术栈: - Laravel 11.x - Filament 3.X - Meilisearch 1.5+ - Pandoc 文档转换 - Redis 队列系统 - Pest PHP 测试框架
This commit is contained in:
Knowledge Base System
258
docs/MEILISEARCH_SETUP.md
Normal file
258
docs/MEILISEARCH_SETUP.md
Normal file
@@ -0,0 +1,258 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user