GoFound 上手指南

## 项目简介 GoFound 是一个基于 Golang 实现的全文检索引擎，支持持久化和单机亿级数据毫秒级查找。接口可以通过 HTTP 调用，并集成了 Admin 管理界面。 https://appstore.lazycat.cloud/#/shop/detail/cloud.lazycat.app.xiao.gofound ### 核心特性 - ✅ **持久化存储**：数据自动持久化到磁盘，重启不丢失 - ✅ **高性能查询**：单机亿级数据毫秒级查询 - ✅ **HTTP API**：提供完整的 RESTful API 接口 - ✅ **管理界面**：内置可视化管理后台 - ✅ **中文分词**：自带中文分词和词库，无需额外配置 - ✅ **轻量级**：原生二进制，无外部依赖，内存占用小 - ✅ **多数据库**：支持创建多个独立的数据库 ## 访问服务 ### 管理后台访问地址：`http://your-domain` ![image.png](https://dl.playground.lazycat.cloud/guidelines/921/744bffc7-bb4d-4278-8f45-7209452d5ae9.png "image.png") 默认登录信息： - **用户名**：`admin` - **密码**：`123456` ### API 接口 API 基础地址：`http://your-domain/api` 所有 API 接口支持 HTTP Basic 认证，使用默认账号密码即可。 ## 管理界面使用 ### 仪表盘登录后进入仪表盘，可以查看系统运行状态、索引统计、内存使用等信息。主要功能： - **系统状态**：查看 CPU、内存、磁盘使用情况 - **索引统计**：查看当前索引数量、分片信息 - **运行时间**：查看服务运行时长 ### 数据库在数据库管理页面，可以： - 查看已索引的文档列表 - 添加新文档 - 删除文档 - 搜索文档 ![image.png](https://dl.playground.lazycat.cloud/guidelines/921/70b6852d-84b1-4fdf-8abd-d11dc9c5b78a.png "image.png") 测试文本召回选择对应的数据库，输入关键词，可以测试文本召回 ![image.png](https://dl.playground.lazycat.cloud/guidelines/921/89ce2d55-7c99-4316-922c-2861bc18222d.png "image.png") UI 还是可以创建、删除数据库，为某个数据库添加索引数据。 ![image.png](https://dl.playground.lazycat.cloud/guidelines/921/3a5085b5-23ae-4fe6-b7c2-d0b2100d9136.png "image.png") ### 系统状态系统状态页面显示详细的系统信息，包括： - 索引队列状态 - 内存使用详情 - 系统架构信息 - Go 版本信息 ![image.png](https://dl.playground.lazycat.cloud/guidelines/921/43b52858-5aea-47c4-9737-438ac2070ad8.png "image.png") ## API 快速开始 ### 创建索引创建单个文档索引：设置访问地址环境变量 ```bash export GOFUND_HOST=https://gofound.minicat.heiyu.space export GOFUND_DB=test # 要访问的数据库名称 export GOFUND_PASSWORD=123456 # GoFund 密码 export HC_TOKEN=28da4914-32f8-4ddd-8deb-c06aef926feb # 懒猫的 token ``` ```bash curl -X POST "${GOFUND_HOST}/api/index?database=${GOFUND_DB}" \ -H "Content-Type: application/json" \ -H "Cookie: HC-Auth-Token=${HC_TOKEN}" \ -u admin:${GOFUND_PASSWORD} \ -d '{ "id": 1, "text": "GoFound 是一个全文检索引擎", "document": { "title": "GoFound 简介", "author": "GoFound Team", "category": "搜索引擎" } }' ``` 响应示例： ```json { "state": true, "message": "success" } ``` **参数说明**： - `id`：文档的唯一标识符（必填，uint32 类型） - `text`：需要索引的文本内容（必填） - `document`：附加的文档数据，可以是任意 JSON 对象，搜索时会原样返回 - `database`：指定数据库名（可选，默认为 `default`） ### 批量创建索引批量创建索引可以提高导入效率： ```bash curl -X POST "${GOFUND_HOST}/api/index/batch?database=${GOFUND_DB}" \ -H "Content-Type: application/json" \ -H "Cookie: HC-Auth-Token=${HC_TOKEN}" \ -u admin:${GOFUND_PASSWORD} \ -d '[ { "id": 1, "text": "GoFound 是一个全文检索引擎", "document": { "title": "GoFound 简介", "author": "GoFound Team" } }, { "id": 2, "text": "支持持久化和单机亿级数据查询", "document": { "title": "GoFound 特性", "author": "GoFound Team" } } ]' ``` ### 搜索文档执行全文搜索： ```bash curl -X POST "${GOFUND_HOST}/api/query?database=${GOFUND_DB}" \ -H "Content-Type: application/json" \ -H "Cookie: HC-Auth-Token=${HC_TOKEN}" \ -u admin:${GOFUND_PASSWORD} \ -d '{ "query": "全文检索", "page": 1, "limit": 10, "order": "desc" }' ``` 响应示例： ```json { "state": true, "message": "success", "data": { "time": 0.170589, "total": 1, "pageCount": 1, "page": 1, "limit": 10, "documents": [ { "id": 1, "text": "GoFound 是一个全文检索引擎", "document": { "author": "GoFound Team", "title": "GoFound 简介" }, "score": 3, "keys": [ "gofound", "是", "一个", "全文", "检索", "全文检索", "引擎" ] } ], "words": [ "全文", "检索", "全文检索" ] } } ``` **参数说明**： - `query`：搜索关键词（必填） - `page`：页码，默认为 1 - `limit`：每页返回数量，默认为 100，建议不超过 1000 - `order`：排序方式，`asc` 或 `desc`，默认为 `desc` - `database`：指定数据库名（可选，默认为 `default`） > GoFound 还贴心的将输入词和召回文本的分词结果也返回了，方便用户理解分词匹配逻辑 ### 删除索引删除指定 ID 的文档： ```bash curl -X POST "${GOFUND_HOST}/api/index/remove?database=${GOFUND_DB}" \ -H "Content-Type: application/json" \ -H "Cookie: HC-Auth-Token=${HC_TOKEN}" \ -u admin:${GOFUND_PASSWORD} \ -d '{ "id": 1 }' ``` 响应示例： ```json { "state": true, "message": "success" } ``` ### 查询系统状态获取系统运行状态： ```bash curl "${GOFUND_HOST}/api/status" \ -H "Cookie: HC-Auth-Token=${HC_TOKEN}" \ -u admin:${GOFUND_PASSWORD} ``` 响应示例： ```json { "state": true, "message": "success", "data": { "cpu": { "cores": 16, "usedPercent": 2.07, "modelName": "13th Gen Intel(R) Core(TM) i5-13500H" }, "disk": { "total": 1863.02, "used": 61.72, "free": 1799.04, "fsType": "", "usedPercent": 3.32, "path": "/" }, "memory": { "total": 46.78, "used": 3.32, "free": 36.72, "self": 0.15, "usedPercent": 7.1 }, "system": { "arch": "amd64", "bufferNum": 1000, "cores": 16, "dataPath": "./data", "dataSize": 8.26, "dbs": 1, "debug": false, "dictionaryPath": "./data/dictionary.txt", "enableAuth": true, "enableGzip": true, "executable": "./gofound", "gomaxprocs": 32, "goroutines": 106, "os": "linux", "pid": 18, "shard": 10, "version": "go1.21.13" } } } ``` ### 在线分词测试测试中文分词效果： ```bash curl "${GOFUND_HOST}/api/word/cut?q=GoFound是一个全文检索引擎" \ -H "Cookie: HC-Auth-Token=${HC_TOKEN}" \ -u admin:${GOFUND_PASSWORD} ``` 响应示例： ```json { "state": true, "message": "success", "data": [ "GoFound", "是", "一个", "全文", "检索", "全文检索", "引擎" ] } ``` ## 常用场景示例 ### 示例 1：创建文章索引并搜索假设我们要为博客文章建立索引： ```bash # 1. 创建文章索引 curl -X POST "${GOFUND_HOST}/api/index?database=blog" \ -H "Content-Type: application/json" \ -H "Cookie: HC-Auth-Token=${HC_TOKEN}" \ -u admin:${GOFUND_PASSWORD} \ -d '{ "id": 1001, "text": "GoFound 是一个基于 Golang 实现的全文检索引擎，支持持久化和单机亿级数据毫秒级查找。", "document": { "title": "GoFound 全文检索引擎介绍", "author": "张三", "publishDate": "2024-01-01", "views": 1000, "tags": ["搜索引擎", "Golang", "全文检索"] } }' # 2. 搜索文章 curl -X POST "${GOFUND_HOST}/api/query?database=blog" \ -H "Content-Type: application/json" \ -H "Cookie: HC-Auth-Token=${HC_TOKEN}" \ -u admin:${GOFUND_PASSWORD} \ -d '{ "query": "全文检索", "page": 1, "limit": 10 }' ``` ### 示例 2：批量导入数据批量导入产品信息： ```bash curl -X POST "${GOFUND_HOST}/api/index/batch?database=blog" \ -H "Content-Type: application/json" \ -H "Cookie: HC-Auth-Token=${HC_TOKEN}" \ -u admin:${GOFUND_PASSWORD} \ -d '[ { "id": 2001, "text": "iPhone 15 Pro Max 256GB 深空黑色支持5G", "document": { "name": "iPhone 15 Pro Max", "price": 9999, "stock": 50, "category": "手机" } }, { "id": 2002, "text": "MacBook Pro 14英寸 M3芯片 16GB内存 512GB存储", "document": { "name": "MacBook Pro 14", "price": 14999, "stock": 30, "category": "笔记本" } } ]' ``` ### 示例 3：关键词高亮搜索使用高亮功能标记搜索结果中的关键词： ```bash curl -X POST "${GOFUND_HOST}/api/query?database=blog" \ -H "Content-Type: application/json" \ -H "Cookie: HC-Auth-Token=${HC_TOKEN}" \ -u admin:${GOFUND_PASSWORD} \ -d '{ "query": "深空黑色", "page": 1, "limit": 10, "highlight": { "preTag": "", "postTag": "" } }' ``` 返回的 `text` 字段中，匹配的关键词会被 `` 标签包裹。返回结果： ```json { "state": true, "message": "success", "data": { "time": 0.123852, "total": 1, "pageCount": 1, "page": 1, "limit": 10, "documents": [ { "id": 2001, "text": "iphone 15 pro max 256gb 深空黑色支持5g", "document": { "category": "手机", "name": "iPhone 15 Pro Max", "price": 9999, "stock": 50 }, "originalText": "iPhone 15 Pro Max 256GB 深空黑色支持5G", "score": 2, "keys": [ "iphone15promax256gb", "深空", "黑色", "支持", "5g" ] } ], "words": [ "深空", "黑色" ] } } ``` > GoFound 目前英文的处理还有些问题，比如上面iPhone 15 Pro Max 分词之后变成了 iphone15promax256gb，这点有待开源作者优化。 ## 多数据库支持 GoFound 支持创建多个独立的数据库，每个数据库的索引数据完全隔离。 ### 指定数据库在 API 请求的查询参数中指定数据库名： ```bash # 使用 default 数据库（默认） curl -X POST http://your-domain/api/index?database=default \ -H "Content-Type: application/json" \ -u admin:123456 \ -d '{...}' # 使用 blog 数据库 curl -X POST http://your-domain/api/index?database=blog \ -H "Content-Type: application/json" \ -u admin:123456 \ -d '{...}' # 使用 products 数据库 curl -X POST http://your-domain/api/index?database=products \ -H "Content-Type: application/json" \ -u admin:123456 \ -d '{...}' ``` ### 数据库管理 **删除数据库**： ```bash curl http://your-domain/api/db/drop?database=blog \ -u admin:123456 ``` ⚠️ **注意**：删除数据库操作不可恢复，请谨慎操作。 **自动创建**：如果指定的数据库不存在，GoFound 会自动创建新的数据库。 ## 最佳实践 1. **ID 唯一性**：确保每个文档的 `id` 唯一，相同 `id` 会覆盖已有文档 2. **文本内容**：`text` 字段应该包含所有需要被搜索的内容 3. **文档数据**：`document` 字段可以存储任意 JSON 数据，用于返回额外信息 4. **批量操作**：大量数据导入时使用批量接口，提高效率 5. **分页查询**：搜索结果较多时，使用分页避免一次性返回过多数据 6. **数据库隔离**：不同业务场景使用不同的数据库，便于管理和维护 ## 更多资源 - [官方仓库](https://github.com/sea-team/gofound)