GoFound 上手指南

项目简介

GoFound 是一个基于 Golang 实现的全文检索引擎，支持持久化和单机亿级数据毫秒级查找。接口可以通过 HTTP 调用，并集成了 Admin 管理界面。

核心特性

• ✅ 持久化存储：数据自动持久化到磁盘，重启不丢失
• ✅ 高性能查询：单机亿级数据毫秒级查询
• ✅ HTTP API：提供完整的 RESTful API 接口
• ✅ 管理界面：内置可视化管理后台
• ✅ 中文分词：自带中文分词和词库，无需额外配置
• ✅ 轻量级：原生二进制，无外部依赖，内存占用小
• ✅ 多数据库：支持创建多个独立的数据库

访问服务

管理后台

访问地址：http://your-domain

默认登录信息：

• 用户名：admin
• 密码：123456

API 接口

API 基础地址：http://your-domain/api

所有 API 接口支持 HTTP Basic 认证，使用默认账号密码即可。

管理界面使用

仪表盘

登录后进入仪表盘，可以查看系统运行状态、索引统计、内存使用等信息。

主要功能：

• 系统状态：查看 CPU、内存、磁盘使用情况
• 索引统计：查看当前索引数量、分片信息
• 运行时间：查看服务运行时长

数据库

在数据库管理页面，可以：

• 查看已索引的文档列表
• 添加新文档
• 删除文档
• 搜索文档

测试文本召回

选择对应的数据库，输入关键词，可以测试文本召回

UI 还是可以创建、删除数据库，为某个数据库添加索引数据。

系统状态

系统状态页面显示详细的系统信息，包括：

• 索引队列状态
• 内存使用详情
• 系统架构信息
• Go 版本信息

API 快速开始

创建索引

创建单个文档索引：

设置访问地址环境变量

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

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": "搜索引擎"
    }
  }'

响应示例：

{
  "state": true,
  "message": "success"
}

参数说明：

• id：文档的唯一标识符（必填，uint32 类型）
• text：需要索引的文本内容（必填）
• document：附加的文档数据，可以是任意 JSON 对象，搜索时会原样返回
• database：指定数据库名（可选，默认为 default）

批量创建索引

批量创建索引可以提高导入效率：

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"
      }
    }
  ]'

搜索文档

执行全文搜索：

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"
  }'

响应示例：

{
  "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 的文档：

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
  }'

响应示例：

{
  "state": true,
  "message": "success"
}

查询系统状态

获取系统运行状态：

curl "${GOFUND_HOST}/api/status" \
  -H "Cookie: HC-Auth-Token=${HC_TOKEN}" \
  -u admin:${GOFUND_PASSWORD}

响应示例：

{
  "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"
    }
  }
}

在线分词测试

测试中文分词效果：

curl "${GOFUND_HOST}/api/word/cut?q=GoFound是一个全文检索引擎" \
  -H "Cookie: HC-Auth-Token=${HC_TOKEN}" \
  -u admin:${GOFUND_PASSWORD}

响应示例：

{
  "state": true,
  "message": "success",
  "data": [
    "GoFound",
    "是",
    "一个",
    "全文",
    "检索",
    "全文检索",
    "引擎"
  ]
}

常用场景示例

示例 1：创建文章索引并搜索

假设我们要为博客文章建立索引：

# 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：批量导入数据

批量导入产品信息：

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：关键词高亮搜索

使用高亮功能标记搜索结果中的关键词：

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": "<mark>",
      "postTag": "</mark>"
    }
  }'

返回的 text 字段中，匹配的关键词会被 <mark> 标签包裹。

返回结果：

{
  "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 <mark>深空</mark><mark>黑色</mark> 支持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 请求的查询参数中指定数据库名：

# 使用 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 '{...}'

数据库管理

删除数据库：

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. 数据库隔离：不同业务场景使用不同的数据库，便于管理和维护

更多资源

• 官方仓库