索引管理

概述

Fess 处理的数据作为 OpenSearch 的索引进行管理。 搜索索引的备份与恢复对系统稳定运行不可或缺。 本章节介绍使用 OpenSearch 快照功能进行索引备份、恢复及迁移的操作步骤。

Note

Fess 除了本章节介绍的 OpenSearch 快照索引备份之外，还提供通过管理界面导出/导入配置信息（爬取配置、用户信息、系统设置等）的功能。若仅需备份或迁移配置信息，请参考 备份。OpenSearch 快照适用于对包含搜索文档的完整索引进行物理备份的场景。

索引构成

Fess 使用以下索引。

索引名 说明
fess.{时间戳} 搜索文档索引。重建索引时以 fess.{yyyyMMddHHmmssSSS} 格式（毫秒精度时间戳）创建，通过 fess.search （用于搜索）和 fess.update （用于更新）别名引用。
fess_config.* 系统配置信息（由 fess_config.web_config、fess_config.scheduled_job、fess_config.data_config 等多个子索引构成）
fess_user.* 用户信息（fess_user.user、fess_user.role、fess_user.group）
fess_log.* 搜索日志及点击日志等（fess_log.search_log、fess_log.click_log、fess_log.favorite_log、fess_log.user_info、fess_log.notification_queue）
fess_crawler.* 爬取过程中使用的临时索引（fess_crawler.queue、fess_crawler.data、fess_crawler.filter）。爬取完成后不再需要，通常无需纳入备份范围。
configsync 词典文件（同义词、停用词、映射等）的内容。由 OpenSearch 的 configsync 插件管理，并以文件形式写出到 OpenSearch 的 config/dictionary 下。搜索文档索引和建议（Suggest）索引引用这些文件，因此请务必将此索引纳入备份。

Warning

快照只包含索引，不包含 OpenSearch config/dictionary 下的词典文件本身。 如果未备份 configsync 索引，恢复到新的 OpenSearch 时词典文件不存在， fess.{时间戳} 和 fess_suggest_analyzer 会因 IOException while reading ..._path: file not readable 而无法打开（集群状态变为 red）。

索引备份与恢复

可以使用 OpenSearch 的快照功能执行索引的备份与恢复。

快照仓库配置

首先，配置用于保存备份数据的仓库。

文件系统仓库:

  1. 在 OpenSearch 配置文件 (opensearch.yml) 中添加仓库路径。

path.repo: ["/var/opensearch/backup"]

  1. 重启 OpenSearch。

  2. 注册仓库。

curl -X PUT "localhost:9200/_snapshot/fess_backup" -H 'Content-Type: application/json' -d'
{
  "type": "fs",
  "settings": {
    "location": "/var/opensearch/backup",
    "compress": true
  }
}'

Note

Fess 默认连接 9200 端口的 OpenSearch（ZIP 版为 bin/fess.in.sh 中的 SEARCH_ENGINE_HTTP_URL ，软件包版为环境配置文件 /etc/sysconfig/fess （RPM）或 /etc/default/fess （DEB））。如果 OpenSearch 监听其他端口，请相应替换端口号。

AWS S3仓库:

将 S3 作为备份目标时，请安装并配置 repository-s3 插件。

curl -X PUT "localhost:9200/_snapshot/fess_s3_backup" -H 'Content-Type: application/json' -d'
{
  "type": "s3",
  "settings": {
    "bucket": "my-fess-backup-bucket",
    "region": "ap-northeast-1",
    "base_path": "fess-snapshots"
  }
}'

创建快照（备份）

备份所有索引

备份所有索引。

curl -X PUT "localhost:9200/_snapshot/fess_backup/snapshot_1?wait_for_completion=true" -H 'Content-Type: application/json' -d'
{
  "indices": "*",
  "ignore_unavailable": true,
  "include_global_state": false
}'

备份特定索引

仅备份特定索引。以下是针对 Fess 相关索引（以 fess 开头的索引）以及保存词典文件的 configsync 索引的示例。若省略 configsync，将无法恢复词典文件。

curl -X PUT "localhost:9200/_snapshot/fess_backup/snapshot_fess_only?wait_for_completion=true" -H 'Content-Type: application/json' -d'
{
  "indices": "fess*,configsync",
  "ignore_unavailable": true,
  "include_global_state": false
}'

定期自动备份

可以使用 cron 等方式定期执行备份。

#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
curl -X PUT "localhost:9200/_snapshot/fess_backup/snapshot_${DATE}?wait_for_completion=true" -H 'Content-Type: application/json' -d'
{
  "indices": "*",
  "ignore_unavailable": true,
  "include_global_state": false
}'

确认快照

确认已创建的快照列表。

curl -X GET "localhost:9200/_snapshot/fess_backup/_all?pretty"

确认特定快照的详情。

curl -X GET "localhost:9200/_snapshot/fess_backup/snapshot_1?pretty"

从快照恢复

恢复所有索引

请先恢复 configsync 索引并写出词典文件，然后再恢复 Fess 的索引（fess*）。请在 Fess 停止的状态下执行恢复。

无法使用 "indices": "*" 一次性恢复。OpenSearch 启动时会自行创建 configsync 等索引，因此即使是新的 OpenSearch，恢复也会以 cannot restore index [configsync] because an open index with same name already exists in the cluster 失败。 另外，如果只恢复 fess*，由于词典文件不存在， fess.{时间戳} 和 fess_suggest_analyzer 无法打开，集群变为 red，此时启动 Fess 也会启动失败（所有页面都返回 404）。

  1. 删除 configsync 插件启动时创建的空 configsync 索引，然后从快照恢复 configsync。

curl -X DELETE "localhost:9200/configsync"

curl -X POST "localhost:9200/_snapshot/fess_backup/snapshot_1/_restore?wait_for_completion=true" -H 'Content-Type: application/json' -d'
{
  "indices": "configsync",
  "include_global_state": false
}'

  1. 重启 OpenSearch（多节点集群中为所有节点），待 configsync 索引可用后，将恢复的词典内容写出到 OpenSearch 的 config/dictionary 下。

curl -X GET "localhost:9200/_cluster/health/configsync?wait_for_status=yellow&timeout=60s&pretty"

curl -X POST "localhost:9200/_configsync/flush"

Note

在 configsync 插件 3.8.0 及更早版本中， _configsync/flush 只写出在该节点上次开始写出处理（定期执行或 _configsync/flush ）之后登记的文件。恢复的 configsync 文件带有在拍摄快照的集群上登记时的时间，因此在 OpenSearch 启动约 1 分钟后首次定期写出完成之后，不重启而执行 _configsync/flush 不会写出任何词典文件，步骤 3 之后集群会变为 red。重启会重置该时间点，因此重启后执行 _configsync/flush 即可写出所有词典文件。每写出一个文件，OpenSearch 日志中都会输出 ConfigSyncService 的 Updated {文件路径}。

  1. 恢复 Fess 的索引。

curl -X POST "localhost:9200/_snapshot/fess_backup/snapshot_1/_restore?wait_for_completion=true" -H 'Content-Type: application/json' -d'
{
  "indices": "fess*",
  "ignore_unavailable": true,
  "include_global_state": false
}'

  1. 确认集群状态变为 green （无法分配副本的配置下为 yellow ）后，再启动 Fess。

curl -X GET "localhost:9200/_cluster/health?wait_for_status=yellow&timeout=60s&pretty"

Note

在运行中的集群上以相同名称重新恢复时，如果要恢复的索引处于打开状态则会失败。请在步骤 3 之前关闭（_close）目标索引。

恢复特定索引

搜索文档索引的名称格式为 fess.{yyyyMMddHHmmssSSS}。请通过 _cat/indices 等方式确认实际索引名后再执行恢复。

curl -X POST "localhost:9200/_snapshot/fess_backup/snapshot_1/_restore?wait_for_completion=true" -H 'Content-Type: application/json' -d'
{
  "indices": "fess.20250101000000000",
  "ignore_unavailable": true,
  "include_global_state": false
}'

更改索引名恢复

恢复时也可以更改索引名。

curl -X POST "localhost:9200/_snapshot/fess_backup/snapshot_1/_restore?wait_for_completion=true" -H 'Content-Type: application/json' -d'
{
  "indices": "fess.20250101000000000",
  "rename_pattern": "fess\\.(.+)",
  "rename_replacement": "restored_fess.$1",
  "ignore_unavailable": true,
  "include_global_state": false
}'

Note

恢复搜索文档索引（fess.{时间戳}）后，请务必确认 fess.search 和 fess.update 别名是否指向已恢复的索引。快照中包含别名信息，因此以原名称恢复全部索引时，别名通常也会一并还原。但是，若使用 rename_pattern 更改索引名恢复，或迁移至其他集群时，别名可能无法正确设置。此时请按如下方式手动重新设置别名（请将索引名替换为实际名称）。

curl -X POST "localhost:9200/_aliases" -H 'Content-Type: application/json' -d'
{
  "actions": [
    { "add": { "index": "restored_fess.20250101000000000", "alias": "fess.search" } },
    { "add": { "index": "restored_fess.20250101000000000", "alias": "fess.update" } }
  ]
}'

删除快照

可以删除旧快照以节省存储容量。

curl -X DELETE "localhost:9200/_snapshot/fess_backup/snapshot_1"

配置文件备份

除 OpenSearch 索引外，还请备份以下配置文件。配置文件的存放位置因安装方式不同而有所差异。

备份对象文件

文件/目录 安装方式 说明
app/WEB-INF/conf/system.properties ZIP 系统设置（通用设置）
/etc/fess/system.properties RPM/DEB 系统设置（通用设置）
app/WEB-INF/classes/fess_config.properties ZIP Fess 详细配置
/etc/fess/fess_config.properties RPM/DEB Fess 详细配置
app/WEB-INF/classes/log4j2.xml ZIP 日志配置
/usr/share/fess/app/WEB-INF/classes/log4j2.xml RPM/DEB 日志配置
app/WEB-INF/classes/fess_indices/ ZIP 索引定义文件
/usr/share/fess/app/WEB-INF/classes/fess_indices/ RPM/DEB 索引定义文件
app/WEB-INF/thumbnails/ ZIP 缩略图（按需备份）
/var/lib/fess/thumbnails/ RPM/DEB 缩略图（按需备份）

Note

RPM/DEB 软件包版中，/etc/fess/ 目录除 fess_config.properties 外，还存放有 fess_env_crawler.properties 等 fess_env_*.properties 文件以及 tika.xml 等配置文件。建议备份整个 /etc/fess/ 目录。system.properties 在管理界面的”系统 > 通用”中保存设置时，将以 /etc/fess/system.properties 的形式创建或更新。

配置文件备份示例

以下是 RPM/DEB 软件包版的配置文件备份示例。

#!/bin/bash
BACKUP_DIR="/backup/fess/$(date +%Y%m%d_%H%M%S)"
mkdir -p ${BACKUP_DIR}

# 复制配置文件（包含 system.properties、fess_config.properties 等）
cp -r /etc/fess/ ${BACKUP_DIR}/

# 索引定义文件与日志配置
cp -r /usr/share/fess/app/WEB-INF/classes/fess_indices/ ${BACKUP_DIR}/
cp /usr/share/fess/app/WEB-INF/classes/log4j2.xml ${BACKUP_DIR}/

# 可选：缩略图
# cp -r /var/lib/fess/thumbnails/ ${BACKUP_DIR}/

echo "Backup completed: ${BACKUP_DIR}"

数据迁移

迁移到其他环境的步骤

  1. 在迁移源创建备份

    • 创建 OpenSearch 快照。

    • 备份配置文件。

  2. 准备迁移目标

    • 在新环境安装 Fess。

    • 启动 OpenSearch。

  3. 恢复配置文件

    • 将备份的配置文件复制到新环境。

    • 根据需要修改路径和主机名等。

  4. 恢复索引

    • 配置快照仓库。

    • 按照“恢复所有索引”的步骤，先恢复 configsync 并写出词典文件，然后再恢复 Fess 的索引。

    • 恢复后，确认 fess.search 和 fess.update 别名是否指向已恢复的索引。

    • 确认集群状态为 green （或 yellow ）。如果在 red 状态下启动 Fess，将启动失败。

  5. 运行确认

    • 启动 Fess。

    • 访问管理界面，确认配置。

    • 确认搜索功能是否正常运行。

版本升级注意事项

在不同版本的 Fess 之间迁移数据时，请注意以下几点。

  • OpenSearch 主版本不同时，可能出现兼容性问题。

  • 索引结构有变更时，可能需要重新索引。

  • 若需跨越索引结构变更迁移配置信息，请考虑使用管理界面的备份功能（备份）进行逻辑导出/导入，而非使用 OpenSearch 快照。

  • 详情请参考各版本的升级指南。

故障排除

快照创建失败

  1. 请确认仓库路径的访问权限。

  2. 请确认磁盘容量是否充足。

  3. 请在 OpenSearch 日志文件中确认错误消息。

恢复失败

  1. 请确认是否已存在同名索引。OpenSearch 无法恢复至已处于打开状态的同名索引。请在恢复前关闭（_close）或删除目标索引，或使用 rename_pattern 以其他名称恢复。

  2. 请确认 OpenSearch 版本是否兼容。

  3. 请确认快照是否损坏。

恢复后集群变为 red

如果在恢复 fess* 后集群状态变为 red，并出现以下情况，说明缺少词典文件。

  • _cluster/allocation/explain 中出现 IOException while reading mappings_path: file not readable （也可能是 keywords_path 等）

  • 启动 Fess 时， fess.log 中出现 Failed to initialize Lasta Di （SuggestHelper 的 init 中的 NullPointerException），所有页面都返回 404

执行 _cluster/reroute?retry_failed=true 或仅放置词典文件都无法恢复。恢复失败的分片在其索引被关闭或删除并重新恢复之前不会被分配。请按以下步骤恢复。

  1. 按照“恢复所有索引”的步骤 1 和 2，恢复 configsync，重启 OpenSearch 并写出词典文件。

  2. 确认 red 状态的索引。

    curl -X GET "localhost:9200/_cat/indices?v&health=red"

  3. 关闭 red 状态的索引，并从快照重新恢复（请将索引名替换为实际名称）。

    curl -X POST "localhost:9200/fess.20250101000000000,fess_suggest_analyzer/_close"

curl -X POST "localhost:9200/_snapshot/fess_backup/snapshot_1/_restore?wait_for_completion=true" -H 'Content-Type: application/json' -d'
{
  "indices": "fess.20250101000000000,fess_suggest_analyzer",
  "include_global_state": false
}'

恢复后无法搜索

  1. 请确认索引是否正常恢复：curl -X GET "localhost:9200/_cat/indices?v"

  2. 请确认 fess.search 和 fess.update 别名是否指向已恢复的索引：curl -X GET "localhost:9200/_cat/aliases?v"。若别名未设置，请通过 _aliases API 重新配置。

  3. 请在 Fess 日志文件中确认是否有错误。

  4. 请确认配置文件是否已正确恢复。

相关主题

参考信息

详细信息请参考 OpenSearch 官方文档。