故障排除

本页面说明 Fess 的安装、启动、运维时的常见问题及其解决方法。

安装时的问题

Java 未被识别

症状:

-bash: java: command not found

或:

'java' is not recognized as an internal or external command

原因:

Java 未安装，或 PATH 环境变量未正确设置。

解决方法:

  1. 确认 Java 是否已安装:

    $ which java
$ java -version

  2. 如未安装，请安装 Java 21:

    # Ubuntu/Debian
$ sudo apt-get update
$ sudo apt-get install openjdk-21-jdk

# RHEL/CentOS
$ sudo yum install java-21-openjdk

    Debian 12 的标准软件源中没有 openjdk-21-jdk 软件包。在 Debian 12 上，请改为按照 Adoptium 的 Linux 安装说明 中适用于 Debian 的步骤安装 Eclipse Temurin 21。

  3. 设置 JAVA_HOME 环境变量:

    $ export JAVA_HOME=/path/to/java
$ export PATH=$JAVA_HOME/bin:$PATH

    要永久设置，请添加到 ~/.bashrc 或 /etc/profile。

插件安装失败

症状:

ERROR: Plugin installation failed

原因:

  • 网络连接问题

  • 插件版本与 OpenSearch 版本不匹配

  • 权限问题

解决方法:

  1. 确认 OpenSearch 版本:

    $ /path/to/opensearch/bin/opensearch --version

  2. 将插件版本与 OpenSearch 版本匹配:

    $ /path/to/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip

  3. 确认权限:

    $ sudo /path/to/opensearch/bin/opensearch-plugin install ...

  4. 通过代理安装:

    $ export ES_JAVA_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080"
$ /path/to/opensearch/bin/opensearch-plugin install ...

启动时的问题

Fess 无法启动

症状:

执行 Fess 的启动命令时出现错误或立即终止。

确认项目:

  1. 确认 OpenSearch 是否启动:

    $ curl http://localhost:9200/

    如果正常，会返回 JSON 响应。

    没有 OpenSearch 响应时，Fess 会重试约 1 分钟后停止启动，并在控制台和 logs/fess.log 中输出以下消息:

    The search engine at http://localhost:9200 did not become available within 60221ms. Check that OpenSearch is running and reachable. If there is none yet, run bin/fess-setup install opensearch to set one up.

    请启动 OpenSearch，或确认 SEARCH_ENGINE_HTTP_URL。新安装的 ZIP 版在使用 bin/fess-setup install opensearch 设置之前没有 OpenSearch；请参阅 在 Linux 上安装（详细步骤）。

  2. 确认端口号冲突:

    $ sudo ss -tuln | grep 8080

    如果端口 8080 已被使用，请在配置文件中更改端口号。

  3. 确认日志文件:

    $ tail -f /path/to/fess/logs/fess.log

    从错误消息中找出原因。

  4. 确认 Java 版本:

    $ java -version

    请确认已安装 Java 21 或更高版本。

  5. 确认内存不足:

    $ free -h

    如果内存不足，请调整堆大小或增加系统内存。

OpenSearch 无法启动

症状:

ERROR: bootstrap checks failed

原因:

系统配置不满足 OpenSearch 的要求。

解决方法:

  1. 设置 vm.max_map_count:

    $ sudo sysctl -w vm.max_map_count=262144

    永久设置:

    $ echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf
$ sudo sysctl -p

  2. 增加文件描述符上限:

    $ sudo vi /etc/security/limits.conf

    添加以下内容:

    opensearch  -  nofile  65535
opensearch  -  nproc   4096

  3. 设置内存锁定:

    $ sudo vi /etc/security/limits.conf

    添加以下内容:

    opensearch  -  memlock  unlimited

  4. 重启 OpenSearch:

    $ sudo systemctl restart opensearch

无法创建索引（词典文件路径）

症状:

访问 Fess 时返回 HTTP 404，并且 fess.log 中输出以下错误:

Failed to create index: index=fess, path=fess_indices/fess.json
... reason=Resource path must be inside config directory: /var/lib/opensearch/data/config/ja/mapping.txt

原因:

从 OpenSearch 3.8.0 开始，如果词典文件位于 OpenSearch 配置目录之外，OpenSearch 会拒绝创建索引。 configsync.config_path 和 FESS_DICTIONARY_PATH 指向了配置目录之外的位置（如 data/config/）。

解决方法:

  1. 将 configsync.config_path 和 FESS_DICTIONARY_PATH 更改为 OpenSearch 配置目录下的目录。

    • RPM/DEB 版：/etc/opensearch/dictionary/

    • ZIP 版：/path/to/opensearch-3.9.0/config/dictionary/

  2. 如果已有词典文件，请将其复制到新目录。

  3. 按 OpenSearch、Fess 的顺序重新启动。

详情请参阅 在 Linux 上安装（详细步骤）。

端口号冲突

症状:

Address already in use

解决方法:

  1. 确认使用中的端口:

    $ sudo ss -tuln | grep 8080
$ sudo lsof -i :8080

  2. 停止使用中的进程，或更改 Fess 的端口号

    有关更改端口号，请参阅 :doc:端口与网络配置 <../config/setup-port-network>。

连接问题

Fess 无法连接到 OpenSearch

症状:

日志中显示以下错误:

Connection refused
或
No route to host

解决方法:

  1. 确认 OpenSearch 是否启动:

    $ curl http://localhost:9200/

  2. 确认连接 URL

    确认 fess.in.sh 或 fess.in.bat 中设置的 URL 是否正确:

    SEARCH_ENGINE_HTTP_URL=http://localhost:9200

  3. 确认防火墙:

    $ sudo firewall-cmd --list-all

    确认端口 9200 是否开放。

  4. 确认网络连接

    如果在其他主机上运行 OpenSearch:

    $ ping opensearch-host
$ telnet opensearch-host 9200

无法从浏览器访问 Fess

症状:

无法在浏览器中访问 http://localhost:8080/。

解决方法:

  1. 确认 Fess 是否启动:

    $ ps aux | grep fess

  2. 尝试在本地主机访问:

    $ curl http://localhost:8080/

  3. 确认防火墙:

    $ sudo firewall-cmd --list-all

    确认端口 8080 是否开放。

  4. 从其他主机访问

    确认 Fess 是否在本地主机以外监听:

    $ ss -tuln | grep 8080

    如果是 127.0.0.1:8080，请更改配置为 0.0.0.0:8080 或特定 IP 地址监听。

性能问题

搜索速度慢

原因:

  • 索引大小大

  • 内存不足

  • 磁盘 I/O 慢

  • 查询复杂

解决方法:

  1. 增加堆大小

    将 FESS_HEAP_SIZE 作为环境变量传入并启动 Fess:

    $ FESS_HEAP_SIZE=4g bin/fess

    如果在 bin/fess.in.sh 中设置，请将 FESS_HEAP_SIZE=4g 写在决定堆大小的那一行（设置 FESS_MIN_MEM 默认值的那一行）之前。即使追加到文件末尾，此时堆大小已经确定，因此不会生效。RPM/DEB 版请在 /etc/sysconfig/fess（DEB 版为 /etc/default/fess）中设置。

    同时调整 OpenSearch 的堆大小:

    export OPENSEARCH_JAVA_OPTS="-Xms4g -Xmx4g"

  2. 使用 SSD

    如果磁盘 I/O 是瓶颈，请迁移到 SSD。

  3. 启用缓存

    在配置文件中启用查询缓存。

爬取速度慢

原因:

  • 爬取间隔长

  • 目标网站响应慢

  • 线程数少

解决方法:

  1. 调整爬取间隔

    在管理页面的爬取配置中缩短「间隔」（毫秒单位）。

    Warning

    间隔太短会对目标网站造成负担。请设置适当的值。

  2. 增加线程数

    在管理页面中增大爬取配置的「线程数」。默认值：Web 爬取为 1，文件系统爬取为 5。

  3. 调整超时值

    对于响应慢的网站，请增加超时值。

数据问题

不显示搜索结果

原因:

  • 索引未创建

  • 爬取失败

  • 搜索查询错误

解决方法:

  1. 确认索引:

    $ curl http://localhost:9200/_cat/indices?v

    确认 Fess 的索引是否存在。

  2. 确认爬取日志

    从管理页面的「系统信息」→「日志文件」下载爬取日志（fess-crawler.log），检查是否有错误。

  3. 重新执行爬取

    从管理页面的「系统」→「调度器」执行「Default Crawler」。

  4. 简化搜索查询

    先使用简单关键词搜索，确认是否返回结果。

索引损坏

症状:

搜索时出现错误或返回意外结果。

解决方法:

  1. 删除并重建索引

    Warning

    删除索引会丢失所有搜索数据。请务必获取备份。

    $ curl -X DELETE http://localhost:9200/fess*

  2. 重启 Fess

    索引在 Fess 启动时创建。刚删除之后，用户信息的索引也已丢失，因此无法登录管理页面（/api/v2/health 仍会返回 200）。重启 Fess 后，索引、默认作业和初始用户（admin）会被重新创建。

  3. 重新执行爬取

    从管理页面执行「Default Crawler」，重新登记要检索的文档。

Docker 特有的问题

容器无法启动

症状:

docker compose up 容器无法启动。

解决方法:

  1. 确认日志:

    $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs

  2. 确认内存不足

    增加分配给 Docker 的内存（从 Docker Desktop 的设置）。

  3. 确认端口冲突:

    $ docker ps

    确认其他容器是否在使用端口 8080 或 9200。

  4. 确认 Docker Compose 文件

    确认 YAML 文件是否有语法错误:

    $ docker compose -f compose.yaml -f compose-opensearch3.yaml config

容器启动但无法访问 Fess

解决方法:

  1. 确认容器状态:

    $ docker compose -f compose.yaml -f compose-opensearch3.yaml ps

  2. 确认日志:

    $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs fess

  3. 确认网络设置:

    $ docker network ls
$ docker network inspect <network_name>

Windows 特有的问题

路径问题

症状:

路径包含空格或日文时出现错误。

解决方法:

请安装到不包含空格或日文的目录。

例:

C:\opensearch  (推荐)
C:\Program Files\opensearch  (不推荐)

无法注册为服务

解决方法:

使用 NSSM 等第三方工具注册为 Windows 服务。

详情请参阅 在 Windows 上安装（详细步骤）。

其他问题

更改日志级别

要确认详细日志，请将日志级别更改为 DEBUG。

编辑 log4j2.xml:

<Logger name="org.codelibs.fess" level="debug"/>

重置数据库

要重置配置，请删除 OpenSearch 的索引:

$ curl -X DELETE 'http://localhost:9200/fess_config.*'

Warning

执行此命令会删除所有配置数据。

忘记管理员密码

如果忘记了管理员密码，可以直接更新 OpenSearch 的 fess_user.user 索引中的用户文档来重置密码。密码以 {bcrypt}$2a$... 形式的哈希保存在 password 字段中。更新后无需重启 Fess 即可生效。

  1. 生成新密码的哈希。Fess 只接受以 $2a$ 开头的 bcrypt 哈希，因此请将 htpasswd（包含在 apache2-utils 或 httpd-tools 软件包中）输出的 $2y$ 替换为 $2a$。请将 NewPassword 替换为新密码:

    $ HASH=$(htpasswd -bnBC 10 "" 'NewPassword' | tr -d ':\n' | sed 's/^\$2y/$2a/')

  2. 更新 admin 用户文档中的密码。初始状态下 admin 用户的文档 ID 为 YWRtaW4=:

    $ curl -X POST 'http://localhost:9200/fess_user.user/_update/YWRtaW4=?refresh=true' \
       -H 'Content-Type: application/json' \
       -d "{\"doc\":{\"password\":\"{bcrypt}${HASH}\"}}"

    要重置其他用户的密码，请用 curl 'http://localhost:9200/fess_user.user/_search?q=name:用户名' 查询 _id，并指定该 ID。如果为 OpenSearch 启用了认证，请在 curl 中指定认证信息。

  3. 确认可以使用新密码登录管理页面。如果命令历史中残留了密码，请在登录后通过 [用户 > 用户] 重新设置密码。

支持信息

如果问题无法解决，请使用以下支持资源：

社区支持

商业支持

如需商业支持，请联系 N2SM, Inc.：

收集调试信息

报告问题时，收集以下信息会有所帮助：

  1. 版本信息（bin/fess -v 从 15.9 起可用）:

    $ /path/to/fess/bin/fess -v
$ /path/to/opensearch/bin/opensearch --version
$ java -version

  2. 系统信息:

    $ uname -a
$ cat /etc/os-release
$ free -h
$ df -h

  3. 日志文件:

    $ tar czf fess-logs.tar.gz /path/to/fess/logs/

  4. 配置文件（删除机密信息后）:

    $ tar czf fess-config.tar.gz /path/to/fess/app/WEB-INF/conf/

  5. OpenSearch 状态:

    $ curl http://localhost:9200/_cluster/health?pretty
$ curl http://localhost:9200/_cat/indices?v