DzzOffice Elasticsearch 全文检索插件（esSearch）使用指南

前言

在DzzOffice网盘系统中，原生的搜索功能只能通过文件名来搜索。如果文档内容很多、很杂，这种"按文件名搜索"的方式效率很低——你可能明明记得文档里的某个关键词，却怎么也想不起文件名。

esSearch 插件正是为了解决这个问题而生：它基于 Elasticsearch 为 DzzOffice 网盘提供文件内容级全文检索能力。索引建立后，你可以直接搜索文档的正文内容，而不仅仅是文件名。

本插件主要面向自建 DzzOffice 网盘、希望提升搜索体验、且有一定技术基础的用户。

一、功能特性

• 全文检索：基于 Elasticsearch 实现文件内容级搜索，可检索文件正文而非仅文件名。
• 中文分词：优先使用 IK 中文分词器；未安装 IK 时自动回退标准分词器（standard），保证中英文均可检索。
• 多格式支持：内置解析纯文本、Office 文档（docx/xlsx/pptx）、PDF及 WPS 系列等。
• 可配置解析器：通过后台"文件解析器配置"页面软编码管理各扩展名的内容解析方式，无需修改代码即可扩展新格式。
• 自动索引同步：利用 DzzOffice 内置文件操作钩子，实现文件创建、上传、编辑、删除、恢复后自动同步 ES 索引，无需手动重建。
• 多主机随机负载均衡：支持配置多个 ES 主机地址（逗号分隔），每次请求随机选择一个主机执行；注意这是随机负载均衡，若选中的主机不可用，不会自动切换到其他主机（无故障转移），适合多副本分担查询压力的场景。
• 索引管理：提供独立的索引管理菜单，支持手动重建索引、删除索引、查看索引状态（文档数/大小/健康度）。
• 解析器分类管理：文件解析器按类别（Office 文档 / 纯文本 / 代码文件 / 配置文件 / 命令行 / 未分类）分组展示，支持分类的增删改、解析器的分类内增删和跨类移动，页面清晰易用。
• 多语言：内置简体中文（zh-cn）与英文（en-us）语言包。

二、环境要求

注意：解析 PDF/XLS/DOC/PPT/WPS 等格式需要容器内安装相应命令行工具，详见下文"安装可选解析工具"。

三、工作原理

用户搜索 → explorer/searchFile.php
              ├─ 原生 SQL 搜索（不影响原生功能）
              └─ 调用 ES 查询（关键词命中即返回结果）
                     │
                Elasticsearch 索引
                     ▲
                    │ 自动同步（Hook）
              DzzOffice 文件操作
      ┌──────────────┬──────────────┬──────────────┐
  创建/上传      编辑内容       删除          恢复
 (createafter   (setfilecontent (deleteafter  (recoverafter
  _addindex)     _after)         _delindex)     _addindex)

• 索引写入：利用 DzzOffice 核心 dzz_io.php 内置的文件操作钩子，文件创建、上传、编辑、删除、恢复后自动同步 ES（恢复依赖核心 Recover() 预留的 recoverafter_addindex 钩子）。
• 内容提取：由 ESFileParser 策略类按扩展名映射的解析器提取文本。
• 搜索集成：通过 searchfile_return 钩子对原生搜索结果进行 ES 增强，ES 命中时返回全文检索结果，不影响原生搜索。
• 解析器分类：解析器配置按类别分组管理，分类可自定义、增删改、排序，跨类移动方便维护。

四、文件结构

dzz/esSearch/
├── README.md                     # 说明文档
├── dzz_app_esSearch.xml          # 应用市场安装配置（含内置图标）
├── enable.php / disable.php      # 启用 / 停用脚本
├── uninstall.php                 # 卸载脚本（按配置删除 ES 索引）
├── admin.php                     # 后台管理页面入口
├── api.php                       # 后台 AJAX 接口（保存/测试/重建/状态）
├── index.php                     # 前台入口（状态页）
├── classes/
│   ├── ESConfig.php              # 配置工具类（含解析器分类管理）
│   ├── ESClient.php              # Elasticsearch HTTP 客户端（cURL 封装）
│   ├── ESFileParser.php          # 文件内容解析策略类（含内置默认解析器）
│   └── ESIndexer.php             # 索引构建器（全量/增量/单文档索引）
├── hooks/
│   ├── ESIndexHook.php           # 文件操作自动同步钩子
│   └── ESSearchHook.php          # 搜索结果增强钩子
├── language/
│   ├── zh-cn/lang.php            # 简体中文语言包
│   └── en-us/lang.php            # 英文语言包
└── template/
    ├── esSearch_setting.htm      # 设置页
    ├── esSearch_parser.htm       # 文件解析器配置页（分组折叠 + 分类管理）
    ├── esSearch_index.htm        # 索引管理页
    ├── status.htm                # 前台状态页
    └── lyear_left.htm            # 左侧树型菜单

五、安装与配置

1. 安装插件

1. 将 esSearch 目录上传至 DzzOffice 的 dzz 目录下。
2. 登录 DzzOffice 管理后台 → 应用市场 → 找到 ES全文检索 → 点击"启用"。

启用前必须先完成 ES 连接配置，否则会提示"无法启用插件"。

2. 配置 ES 连接

启用插件后，进入 ES全文检索 → 设置 页面：

关于多主机：ES 主机地址 填写多个地址时，插件每次请求会随机挑选其中一个执行（array_rand）。这是随机负载均衡，目的是把查询压力分散到多个 ES 节点；若选中的主机不可用，本次请求会直接失败，不会自动重试其他主机（无故障转移/失败切换）。如需高可用，建议在前方部署 ES 集群或反向代理做健康检查与故障转移。

配置完成后点击 测试连接 验证 ES 连通性，通过后点击 保存。

3. 初始化索引

新上传的文件会自动同步到 ES，但已存在的历史文件需要手动全量重建一次：

1. 进入 ES全文检索 → 索引管理 页面。
2. 点击 开始重建，插件会分批（默认每批 200 条）将 DzzOffice 中所有文件索引到 ES。
3. 等待重建进度条完成。

重建完成后，之后的新增/编辑/删除/恢复文件均由钩子自动同步，无需再次全量重建。

六、安装可选解析工具

如需检索以下文件内容，请在服务器容器内安装相应命令行工具：

纯文本（txt/md/js/css 等）与 Office 新格式（docx/xlsx/xlsm/pptx）无需额外工具即可解析。

七、文件解析器配置

1. 解析类型

2. 解析器分类管理

解析器配置按类别分组展示，方便维护：

• 分类分组：Office 文档 / 纯文本 / 代码文件 / 配置文件 / 命令行 / 未分类
• 分类管理：支持新增、编辑、删除分类；删除分类时其下解析器自动移入"未分类"，不会丢失
• 分类排序：支持上移/下移调整分类顺序，"未分类"固定在最后
• 解析器操作：每个分类内可添加/删除解析器，也可通过"移动到"下拉把解析器跨类移动
• 分类内排序：分类内解析器按扩展名自动排序
• 折叠显示：所有分类默认折叠，点击标题栏可展开/收起，页面清爽

💡 添加新格式的正确顺序：先在"文件解析器配置"添加/修改解析器并保存，再到"索引管理"重建索引。顺序不能颠倒——只有先保存新解析器配置，重建时插件才会强制读取最新配置并用它重新解析文件。

⚠️ 常见误区：docx/xlsx/pptx 是 ZIP 容器，应使用 zipxml 解析；doc/ppt/xls/wps 等老式二进制格式才用 soffice。配置错误会导致内容提取为空。

八、使用说明

全文检索

在 DzzOffice 资源管理器的搜索框中输入关键词，即会同时执行原生搜索与 ES 全文检索，并返回匹配的文件。

索引管理

索引管理 菜单提供：

• 开始重建：全量重建索引（分批执行，带进度条）。
• 删除索引：红色按钮，确认后直接删除 ES 中的索引数据，与卸载时删除索引使用同一逻辑。
• 当前索引状态：查看索引名称、文档数、索引大小、健康状态，可点击 刷新状态 实时更新。

九、常见问题

Q1：为什么搜索不到文件内容？

• 请先确认已执行"重建索引"（新增文件会自动同步，历史文件需手动重建一次）。
• 检查 ES 索引状态是否正常（绿色），文档数是否为预期值。
• 确认该文件类型已配置解析器，且容器内已安装对应解析工具。

Q2：中文搜索不到？

• 推荐在 ES 中安装 IK 分词器插件；未安装时插件自动回退 standard 分词器，中文按整词匹配，仍可搜索连续中文。

Q3：为什么启用插件提示需要配置 ES？

• esSearch 是无 ES 配置就无法工作的插件，因此强制要求先配置 ES 主机地址后才能启用。

Q4：修改了解析器配置后不生效？

• 修改解析器配置后需在"索引管理"中重新重建索引，让新配置对已存在文件生效。

Q5：添加了新文件格式但检索不到？

• 确认已在"文件解析器配置"中为新格式添加了解析器，并先添加解析器、后重建索引。
• 确认解析类型正确（docx/xlsx/pptx 用 zipxml，doc/ppt/xls 用 soffice）。

Q6：如何部署 Elasticsearch？

• 可用 Docker 部署，命令参考：

docker run -d \
  --name elasticsearch \
  -p 9200:9200 \
  -e "discovery.type=single-node" \
  -e "xpack.security.enabled=false" \
  -e "ES_JAVA_OPTS=-Xms512m -Xmx512m" \
  docker.elastic.co/elasticsearch/elasticsearch:9.4.4

• 如需安全认证，设置 xpack.security.enabled=true 并为内置用户设置密码。

十、升级与卸载

升级

1. 用新版本文件覆盖 dzz/esSearch/ 目录。
2. 若有配置变更，重新在 设置 页面保存一次。
3. 如有解析器或字段变更，在 索引管理 中重新重建索引。

卸载

1. 在 应用市场 中停用或卸载插件。
2. 若在 设置 中勾选了 卸载时删除索引，卸载时（uninstall.php）会同时删除 ES 中的索引数据；未勾选则仅停用插件、保留索引数据，以便日后重新启用。

十一、总结

esSearch 插件为 DzzOffice 网盘补齐了文件内容级全文检索能力，支持中文分词、多格式解析、自动索引同步、解析器分类管理等。配合 Elasticsearch，可以显著提升大文件库的检索效率，让"按内容找文件"成为可能。

如果你正在使用 DzzOffice 网盘，且希望搜索体验更进一步，这个插件是一个不错的选择。

提示：本插件基于 DzzOffice 开源协议，仅供 DzzOffice 社区使用。部署前请确保服务器环境满足要求，并已安装好 Elasticsearch。