在Couchbase Server中，FTS（Full Text Search）提供了独立于文档存储的全文索引能力。它和N1QL中的LIKE查询有本质区别：LIKE只能做简单的模式匹配，而且会触发全表扫描；FTS则使用倒排索引，能够处理词元分析、词频统计和相关性排序。对于CRUD操作频繁的业务系统，FTS还能保持索引与数据同步，不需要额外维护。不过，要把FTS配置好，并不是在控制台点几下就完事，索引类型、字段映射、分析器选择都会直接影响查询效果。
理解FTS索引的核心结构
FTS索引本质上是一套倒排索引，它把文档中的文本内容拆解成词条，再记录每个词条出现在哪些文档的哪个位置。Couchbase中的搜索索引（Search Index）由索引定义、索引副本和索引分区组成。索引定义描述了要对哪些字段建立索引、采用什么分析器以及如何处理父子文档关系。索引副本用于高可用，分区则把数据分散到集群节点，保证搜索性能可以横向扩展。
索引类型分为Full Text Index和Geo Index两种。全文索引处理文本搜索，地理索引处理经纬度范围内的查询。业务中绝大多数需求都属于全文索引。每个全文索引可以对应一个数据桶（Bucket），也可以对应多个桶。索引中每个字段都有独立的类型定义，例如Text、Number、Datetime、Boolean等。字段类型决定了可执行的查询操作：Text字段可以执行分词匹配、短语查询，Number字段可以执行范围查询、数值排序，Datetime字段则用于时间范围过滤。
分析器（Analyzer）是FTS中最重要的概念之一。它负责把文本切分成词条，并做小写化、去停用词、词干提取等处理。Couchbase内置了多种分析器，比如standard、simple、keyword、web等。如果没有特别指定，系统默认使用standard分析器，它对英文的支持比较好，但对中文只按单字切分，搜索结果往往不够理想。如果业务涉及中文内容，就需要自定义分析器，把分词器换成中文分词器，比如配合IK Analyzer或结巴分词。
{
"type": "fulltext-index",
"name": "article_idx",
"sourceType": "couchbase",
"sourceName": "blog_bucket",
"planParams": {
"maxPartitionsPerPIndex": 64
},
"params": {
"doc_config": {
"mode": "type_field",
"type_field": "doc_type"
},
"mapping": {
"types": {
"post": {
"properties": {
"title": {
"analyzer": "standard",
"type": "text"
},
"content": {
"analyzer": "standard",
"type": "text"
}
}
}
}
}
}
}
上面这段JSON是创建FTS索引的基础结构。注意doc_config中指定了mode为type_field，意思是根据文档中某个字段值来区分文档类型。Couchbase的桶本身不强制schema，但FTS索引必须有一个映射规则，否则无法知道哪些字段该走哪个分析器。如果桶中所有文档结构一致，也可以直接把mode设置为dynamic，让索引自动发现字段，但这样会让索引体积变大，查询效率也会下降。
通过控制台和CLI创建搜索索引
创建FTS索引最简单的方式是登录Couchbase Web控制台，进入Search页面，点击Add Index。控制台会引导你选择数据桶、填写索引名称，然后进入索引定义编辑器。编辑器以JSON格式展示索引定义，也可以切换到可视化模式，逐字段添加映射。可视化模式适合初学者，但字段多的时候效率低。直接编辑JSON可以快速复制配置到不同环境。
除了控制台，Couchbase还提供了命令行工具couchbase-cli来创建索引。在自动化部署场景下，CLI方式更可靠。需要注意的是，CLI命令中的索引定义需要写到JSON文件里，然后通过--index-definition参数传递。如果索引名称或字段映射写错，命令会直接报错，不会像控制台那样给出友好提示。
# 通过CLI创建FTS索引 /opt/couchbase/bin/couchbase-cli fts-index-create --cluster http://127.0.0.1:8091 --username admin --password password --index-name article_idx --index-definition /tmp/article_index.json
创建索引后，系统会自动构建初始索引。对于大桶来说，首次构建会占用较长的时间。我们可以在控制台看到构建进度和文档处理数量。如果索引构建期间业务仍然有写入操作，Couchbase会通过DCP（Database Change Protocol）持续捕获变更并增量更新索引。也就是说，索引不是一次性快照，而是始终尽量保持与最新数据同步。
索引副本数也是创建时要考虑的参数。默认情况下，每个索引分区分片有一个副本。如果一个节点宕机，索引会继续从副本提供服务。但副本数增加会占用更多磁盘空间。建议生产环境设置至少一个副本，开发环境可以不设置副本以节省资源。调整副本数需要在索引配置中修改numReplicas字段。
使用N1QL和SDK执行全文搜索
Couchbase FTS提供了REST API、SDK以及N1QL三种访问方式。N1QL中可以直接使用SEARCH()函数调用全文索引。这种写法很适合与SQL查询混合使用，例如先通过全文搜索过滤出符合条件的文档ID集合，再关联其他字段做聚合统计。N1QL方式要求FTS索引和N1QL中的键空间在同一个集群中，查询时语法如下：
SELECT id, title, score
FROM blog_bucket
WHERE SEARCH(blog_bucket, {
"index": "article_idx",
"query": {
"query": "couchbase",
"field": "content"
}
}) LIMIT 10;
SEARCH()函数接受三个参数：键空间别名、FTS查询对象和可选选项。查询对象中的index指定索引名称，query内是具体的查询语句。上面的例子搜索content字段中包含“couchbase”的文档，并返回相关性分数。注意SEARCH函数返回的结果集可能包含文档中不存在的虚拟字段，例如score，它是全文搜索特有的相关性打分。
如果使用Java SDK，代码中需要创建SearchOptions和SearchQuery对象。SDK会负责请求集群中的FTS节点并解析响应。Java SDK推荐的写法如下：
import com.couchbase.client.java.search.SearchQuery;
import com.couchbase.client.java.search.result.SearchResult;
String indexName = "article_idx";
SearchQuery query = SearchQuery.queryString("couchbase")
.field("content")
.limit(10);
SearchResult result = cluster.searchQuery(indexName, query);
result.rows().forEach(row -> {
System.out.println(row.id() + " - " + row.score());
});
SDK返回的SearchResult包含了文档ID、分值、字段片段等信息。要获取文档完整内容，需要再根据文档ID执行一次get操作。这种“搜索后再取文档”的模式是关键词检索的典型用法，它把搜索和读取分离，让索引层只负责定位文档，而数据层负责返回完整内容。
中文分词与检索质量调优
中文环境下，默认的standard分析器会把每个汉字当作独立词条，导致查询“苹果”时命中包含“苹”和“果”任意字的文档，相关性极差。要解决这个问题，必须引入中文分词器。Couchbase本身没有内置专业中文分词器，常见做法是使用自定义分析器，并把第三方分词器打包成分析器插件。或者采用基于词典的“关键字分词”策略，在索引定义中直接配置自定义词典。
自定义分析器的配置位于索引JSON的params.analysis部分。我们需要定义分析器名称、分词器类型和过滤器。下面展示一个使用简单分词器的配置：
{
"params": {
"analysis": {
"analyzer": {
"cjk_analyzer": {
"type": "custom",
"tokenizer": "unicode",
"filter": ["lowercase", "custom_stop"]
}
},
"tokenizer": {
"unicode": {
"type": "unicode",
"max_token_length": 20
}
},
"filter": {
"custom_stop": {
"type": "stop",
"stopwords": ["的", "了", "和", "是"]
}
}
},
"mapping": {
"types": {
"post": {
"properties": {
"content": {
"analyzer": "cjk_analyzer",
"type": "text"
}
}
}
}
}
}
}
上面的unicode分词器能够识别CJK字符，并按字符块切分，再搭配停用词过滤，效果比默认分析器好很多。但是对“信息检索”这种复合词，unicode分词器仍然会把“信息”和“检索”拆开，导致用户搜索“信息检索”时无法精确匹配整个短语。如果业务场景要求短语精确匹配，建议使用专用中文分词插件，或者在索引中把该字段同时配置为keyword类型和text类型，分别用于精确匹配和分词搜索。
除了分析器，查询时还可以利用match、match_phrase、boolean等查询类型提升准确度。比如搜索“Couchbase FTS配置”，可以把它拆解为多个词条，用布尔查询指定“与”或“或”逻辑。同时开启高亮功能，让返回结果中命中的关键词带有标记，方便前端展示。高亮需要配置索引字段的store为true，否则无法取回原文片段。
索引性能监控与故障排查
FTS索引性能下降，通常表现在搜索延迟变高、构建失败或索引状态异常。控制台搜索页面提供每个索引的查询延迟、磁盘使用率和构建进度图表。如果发现某节点的索引分区占用磁盘特别高，说明数据分布不均匀，需要调整maxPartitionsPerPIndex参数。这个值决定每个物理索引分区处理的逻辑分区数量，值越小分区数越多，分布越均匀，但也会增加索引分片的管理开销。
另一个常见问题是查询返回结果为空。这可能是因为索引映射的字段名与文档中的实际字段名不一致。Couchbase默认字段名区分大小写，如果文档里是Title，而索引映射写的是title，就会搜索不到。检查这种问题最快的方法是进入控制台Search页面，点击索引的名称，在“Search”标签下输入测试词，查看是否命中文档。如果没有命中，可以打开“Explain”面板，查看查询计划中的分析结果。
索引重建也需要关注。当我们修改索引定义后，Couchbase会触发全量重建，整个过程包括扫描数据桶、分词、构建倒排列表并写入索引存储。对于大桶，重建可能长达数小时。如果生产环境不能接受长时间重建，建议先创建新的索引验证效果，再切换索引名称，或者使用Couchbase的“索引别名”功能，让应用无感切换。此外，保持集群节点有足够的空闲内存和IO带宽，也能显著缩短重建时间。
# 查看FTS索引状态 /opt/couchbase/bin/couchbase-cli fts-index-status --cluster http://127.0.0.1:8091 --username admin --password password --index-name article_idx
上面的命令输出会包含索引的构建进度、副本数和错误信息。如果出现“mapping not found”或“analyzer not found”之类的错误，几乎都是索引JSON配置里引用了不存在的字段或分析器。修改配置时尤其要注意，某些分析器过滤器的名称不能随意取，例如lowercase是内置过滤器，直接使用就好；自定义过滤器名称必须与filter节的键完全一致。
总结与建议
配置Couchbase FTS其实没有无法逾越的难题，关键是抓住三条主线：索引定义是否合理、分析器是否匹配业务语言、查询方式是否正确。从小的实验索引开始，逐步增加字段映射，并在测试数据集上反复验证检索质量，比一次性配置一个庞杂的大索引更稳妥。对于非文本字段，比如价格、日期，尽量使用数值和日期类型，避免把它们当成文本索引，否则范围查询无法执行，还会浪费磁盘空间。
如果团队已经熟悉Elasticsearch，会发现Couchbase FTS的很多概念与ES相似，但配置方式更依赖JSON手动管理。建议把索引定义纳入版本控制，使用CLI或REST API进行部署，减少人工操作带来的偏差。最后需要记得，全文搜索只能代替LIKE，不能代替所有数据库查询。结构化过滤、聚合分析还是交给N1QL更合适。整体架构中把FTS放在查询入口，配合适当的缓存，才能获得最佳的性能体验。
Couchbase FTS全文搜索配置搜索索引修改时间：2026-08-19 21:22:48