abcfy2/zhparser

zhparser PostgreSQL中文全文搜索镜像

镜像概述

基于zhparser的PostgreSQL中文全文搜索Docker镜像，用于实现PostgreSQL数据库的中文分词与全文检索功能。本镜像从https://github.com/chen-xin/docker_zhparser fork而来，并已升级至新版本。

镜像仓库

• https://hub.docker.com/r/abcfy2/zhparser
• https://github.com/abcfy2/docker_zhparser/pkgs/container/zhparser
• Quay.io

支持的标签及对应Dockerfile链接

注：标签中的数字对应PostgreSQL官方镜像版本。

核心功能与特性

• 集成zhparser扩展：基于Xunsearch的SCWS（Simple Chinese Word Segmentation）分词引擎，实现中文分词
• 全文检索配置：支持自定义文本搜索配置，映射分词类型（n、v、a等）
• 多版本支持：覆盖PostgreSQL 13至17版本，提供Debian和Alpine两种基础镜像
• 自定义词典：支持添加TXT格式或XDB格式的自定义词典，优化分词效果
• 索引支持：可基于中文全文搜索配置创建GIN索引，提升查询性能

使用场景

适用于需要在PostgreSQL中实现中文全文检索的场景，如：

• 内容管理系统（CMS）的文章检索
• 文档管理平台的中文文档搜索
• 博客、论坛的帖子内容检索
• 企业内部知识库的中文信息查询

使用方法

基本运行命令

参考PostgreSQL官方镜像文档，基础运行命令如下：

bash
docker run -p 5432:5432 abcfy2/zhparser

首次配置（默认数据库）

容器首次启动时，需在默认数据库中执行以下SQL脚本配置zhparser。对于新创建的数据库，需手动执行相同脚本：

sql
-- 创建zhparser扩展
CREATE EXTENSION zhparser;

-- 创建文本搜索配置（名称可自定义，如"chinese_zh"）
CREATE TEXT SEARCH CONFIGURATION chinese_zh (PARSER = zhparser);

-- 添加分词类型映射（n:名词, v:动词, a:形容词等）
ALTER TEXT SEARCH CONFIGURATION chinese_zh ADD MAPPING FOR n,v,a,i,e,l WITH simple;

配置说明：

• "chinese_zh"为自定义配置名称，可按需修改
• "n,v,a,i,e,l"为分词类型，未映射的类型将不参与文档分词。使用\dFp+ zhparser可查看zhparser支持的所有分词类型

功能测试

1. 分词调试（ts_debug）

sql
select ts_debug('chinese_zh', '白垩纪是地球上海陆分布和生物界急剧变化、火山活动频繁的时代');

输出示例：

txt
ts_debug
-------------------------------------------
(t,time,白垩纪,{},,)
(v,verb,是,{simple},simple,{是})
(n,noun,地球,{simple},simple,{地球})
(n,noun,上海,{simple},simple,{上海})
(m,numeral,陆,{},,)
(v,verb,分布,{simple},simple,{分布})
(c,conjunction,和,{},,)
(n,noun,生物界,{simple},simple,{生物界})
(d,adverb,急剧,{},,)
(v,verb,变化,{simple},simple,{变化})
(u,auxiliary,、,{},,)
(n,noun,火山,{simple},simple,{火山})
(v,verb,活动,{simple},simple,{活动})
(a,adjective,频繁,{simple},simple,{频繁})
(u,auxiliary,的,{},,)
(n,noun,时代,{simple},simple,{时代})
(16 rows)

2. 文本向量转换（to_tsvector）

sql
select to_tsvector('chinese_zh', '白垩纪是地球上海陆分布和生物界急剧变化、火山活动频繁的时代');

输出示例：

txt
to_tsvector
--------------------------------------------------------------------------------------------
'上海':3 '分布':4 '变化':6 '地球':2 '时代':10 '是':1 '活动':8 '火山':7 '生物界':5 '频繁':9
(1 row)

注：若需包含"白垩纪"，需添加t类型映射：ALTER TEXT SEARCH CONFIGURATION chinese_zh ADD MAPPING FOR t WITH simple;

3. 查询匹配（to_tsquery & @@）

sql
-- 判断"地球"是否在文本中
select to_tsquery('chinese_zh', '地球') @@ to_tsvector('chinese_zh', '白垩纪是地球上海陆分布和生物界急剧变化、火山活动频繁的时代');

输出示例：

txt
?column?
----------
t
(1 row)

在表中使用

创建表与索引

sql
-- 创建测试表
create table testing(
  title text
);

-- 插入测试数据
insert into testing values('白垩纪是地球上海陆分布和生物界急剧变化、火山活动频繁的时代');
insert into testing values('艾泽拉斯包括卡利姆多、东部王国两大大陆，暗夜精灵主城达纳苏斯位于东部王国北端。');

-- 创建GIN索引（基于中文全文搜索配置）
create index ind_testing on testing using gin (to_tsvector('chinese_zh', title));

执行查询

sql
-- 搜索包含"白垩纪"的记录
select * from testing where to_tsquery('chinese_zh', '白垩纪') @@ to_tsvector('chinese_zh', title);

-- 搜索包含"达纳苏斯"的记录
select * from testing where to_tsquery('chinese_zh', '达纳苏斯') @@ to_tsvector('chinese_zh', title);

注：若表数据量较少，PostgreSQL可能选择顺序扫描而非索引扫描。当数据量达到数万级时，GIN索引将显著提升查询性能。

添加自定义词典

1. TXT格式词典

1. 在容器内创建词典文件（路径固定为/usr/share/postgresql/<version>/tsearch_data/，文件名可自定义，如mydict.utf8.txt）：

txt
# 格式：word TF IDF ATTR（TF/IDF为权重，ATTR为分词类型）
艾泽拉斯  1 1 n
卡利姆多  1 1 n
达纳苏斯  1 1 n
遗忘海岸  1 1 n

2. 修改PostgreSQL配置文件postgresql.conf，添加词典路径：

conf
zhparser.extra_dicts = 'mydict.utf8.txt'

3. 重启容器，测试分词效果：

sql
select ts_debug('chinese_zh', '艾泽拉斯');

输出示例：

txt
(n,noun,艾泽拉斯,{simple},simple,{艾泽拉斯})

2. XDB格式词典（推荐）

XDB格式为二进制词典，性能优于TXT格式，步骤如下：

1. 从TXT词典生成XDB文件：

bash
# 进入词典目录
cd /usr/share/postgresql/<version>/tsearch_data/

# 生成XDB词典（需确保scws-gen-dict工具可用）
ldconfig  # 解决可能的库依赖问题
scws-gen-dict -c UTF8 mydict.utf8.txt mydict.utf8.xdb

# 修改文件权限（确保postgres用户可访问）
chown postgres:postgres mydict.utf8.xdb

2. 更新配置文件，使用XDB词典：

bash
sed -i 's/mydict\.utf8\.txt/mydict.utf8.xdb/' /var/lib/postgresql/data/postgresql.conf

3. 重启容器，验证分词效果。

额外资源

• https://github.com/amutu/zhparser
• SCWS分词引擎文档
• https://github.com/aboutstudy/scel2mmseg%EF%BC%9A%E5%8F%AF%E5%B0%86%E6%90%9C%E7%8B%97%E6%8B%BC%E9%9F%B3%E8%AF%8D%E5%BA%93%EF%BC%88.scel%EF%BC%89%E8%BD%AC%E6%8D%A2%E4%B8%BA%E6%96%87%E6%9C%AC%E8%AF%8D%E5%85%B8