全文检索
校对日期:2026-11-16。适用于社区版及全部商业版。更新本站索引 需要商业版基础版,用定时任务定期重建索引需要标准版, 改用 Elasticsearch 需要高级版。
全文检索用于网站前台按关键词搜索文章:按中文分词匹配文章的标题和正文,结果里命中的词会高亮。 索引随文章的保存自动更新,平时不需要任何操作;只有索引与数据库里的文章对不上时,才需要重建索引。 控制台“文章管理”里的查询直接查数据库,不使用全文索引。
一、前台搜索
默认主题页头右侧有搜索图标,也可以直接访问 /search。输入关键词后点 搜索,还可以用 所属栏目、时间范围 缩小范围。

默认主题的搜索页按以下规则给出结果:
- 同时搜索标题和正文,标题命中的排得更靠前;关键词被分成几个词时,每个词都要出现。
- “正文”除了文章正文,还包括副标题、完整标题、摘要,以及图片集里每张图片的名称和描述。
- 发布日期越近的文章排得越靠前。
- 只列出已发布的文章,并且文章所在的栏目要允许搜索(见“让一个栏目不被搜到”一节)。
二、让一个栏目不被搜到
进入 内容 → 栏目管理,编辑栏目,关闭 允许搜索,保存。这个栏目里的文章不再出现在前台的搜索结果中。

- 新建栏目时,允许搜索 默认与上级栏目相同;没有上级栏目时默认开启。
- 一批栏目可以在栏目管理的 批量设置 里一次改完,见栏目管理的“批量设置”一节。
- 修改这个开关之后要重建索引才生效(见“重建索引”一节):开关的值是在建立索引时写进去的。
三、重建索引
进入 系统 → 生成管理,在 文章全文索引 一行:

| 按钮 | 作用 | 版本 |
|---|---|---|
| 更新全部索引 | 清空整个索引,再把所有站点的文章重新写入 | 全部 |
| 更新本站索引 | 只清空并重建当前站点的索引,其它站点不受影响 | 基础版 |
重建在后台执行,页面下方的 任务列表 里可以看到这次任务的完成数和状态。重建是先清空、再逐篇写入的, 任务完成之前搜索结果不完整;文章很多的站点建议在访问量低的时候执行。
需要重建索引的情况:
- 直接修改过数据库里的文章,或用其它方式把文章导入了数据库。
- 索引文件被删除,或者升级、迁移程序时没有带上索引目录。
- 修改了栏目的 允许搜索。
- 在 配置 → 站点设置 → 固定链接 里切换了文章链接形态:索引里保存了文章地址,不重建的话搜索结果仍指向旧地址。
- 全文检索从 Lucene 切换到了 Elasticsearch(首次切换时索引是空的)。
- 保存文章时索引写入失败(例如磁盘已满)。这种情况文章照常保存,只在服务器日志里记录一条错误,重建后即可搜到。
在 用户 → 角色管理 的权限树里,这两个按钮对应“生成管理”下的 更新全部索引、更新本站索引 两项权限。
定时重建(标准版):在 系统 → 定时任务 里新增一个类型为 生成本站索引 的任务,按 Cron 表达式定期重建当前站点的索引。
四、索引保存在哪里
默认使用 Lucene,索引是服务器上的一组文件,位置由 application. 里的 ujcms. 决定:
# 默认值:程序目录下的 WEB-INF/lucene
ujcms.lucene-path: /WEB-INF/lucene
# 也可以放到程序目录之外
#ujcms.lucene-path: file:/data/ujcms/lucene- Jar 部署时默认位置是安装目录下的
static/,Tomcat 部署时是WEB-INF/ lucene/ webapps/。ROOT/ WEB-INF/ lucene/ - 升级、迁移时这个目录可以不保留,之后重建一次索引即可,见升级。
- 多个节点组成集群时,每个节点各有一份本地索引,文章在哪个节点保存就只更新那个节点的索引, 各节点的搜索结果会不一致。集群请改用 Elasticsearch(商业版高级版),配置方法见 集群部署的“Elasticsearch 全文检索”一节。切换后模板和接口都不用改。
五、模板与接口
搜索页的模板是主题里的 sys_search.html,用 EsArticlePage 指令取分页结果(不分页用 EsArticleList):
[#assign queryText = Params.q!''/]
[#assign selectedChannelId = Params.channelId!''/]
[@EsArticlePage q=queryText channelId=selectedChannelId isOperatorAnd='true' fragmentSize='200' dateExpScale='365'; pagedList]
<p>共 ${pagedList.totalElements} 篇</p>
[#list pagedList.content as bean]
<a href="${bean.url}">[#noescape]${bean.highlightTitle!bean.title!}[/#noescape]</a>
<p>[#noescape]${bean.highlightBody!}[/#noescape]</p>
[/#list]
[/@EsArticlePage]highlightTitle、highlightBody 是带高亮标签的标题和正文片段,要用 [#noescape] 输出;没有命中时为空,上例中标题退回到 title。
常用参数:
| 参数 | 说明 | 默认 |
|---|---|---|
q | 关键词,匹配标题和正文 | — |
isIncludeBody | 是否搜索正文;false 时只搜标题 | true |
isOperatorAnd | 关键词分出的每个词是否都要匹配 | false |
channelId | 只搜某个栏目,多个用逗号分隔 | 全站 |
isIncludeSubChannel | 是否包含子栏目的文章 | true |
beginPublishDate、endPublishDate | 发布日期范围,如 2026-01-01 | — |
isWithImage | 只要有标题图的(true)或没有标题图的(false) | 不限 |
excludeId | 排除的文章 ID,多个用逗号分隔 | — |
fragmentSize | 高亮片段的长度 | 100 |
dateExpScale | 日期衰减半径(天)。大于 0 时发布日期参与排序,越新越靠前;dateExpOffset、dateExpDecay、dateExpBoost 进一步调节 | 0(不参与) |
isAllSite、siteId、isIncludeSubSite | 搜索全部站点、指定站点、连同子站点 | 当前站点 |
对应的公开接口是 GET /(列表,用 offset、limit)和 GET /(分页,用 page、pageSize), 参数与指令相同。接口只返回已发布、已归档的文章,并且不会返回关闭了 允许搜索 的栏目里的文章。
文章列表指令和 GET / 的 q 参数、文章编辑页的 标题重复检测、相关文章的 智能推荐 用的也是这份索引。 索引不完整时,这些功能的结果同样不完整。指令的通用写法见模板编写的“使用 CMS 指令取数”一节。
六、常见问题
文章发布了,前台搜不到。 先确认文章是已发布状态、所在栏目开着 允许搜索;都没问题的话,到 系统 → 生成管理 重建索引。
搜索结果里的文章点开是 404,或者地址是旧的。 索引与数据库不一致,重建索引。
集群里每个节点搜到的结果不一样。 各节点用的是自己的本地索引,见“索引保存在哪里”一节。