启动、停止、初始设置

本页面说明 Fess 服务器的启动、停止和初始设置步骤。

Important

启动 Fess 前，必须先启动 OpenSearch。 如果 OpenSearch 未启动，Fess 将无法正常工作。

启动方法

根据安装方法的不同，启动步骤也不同。

ZIP 版的情况

启动 OpenSearch

$ cd /path/to/opensearch-3.9.0
$ ./bin/opensearch

在后台启动:

$ ./bin/opensearch -d

Note

bin/fess-setup install opensearch 会将 OpenSearch 放在 Fess 目录下的 opensearch/opensearch-3.9.0 中。

Important

请以普通用户启动 OpenSearch。它拒绝以 root 身份运行，并以 can not run opensearch as root 结束。被拒绝的启动仍会留下 config/opensearch.keystore 等归 root 所有的文件，之后以普通用户启动时会因 AccessDeniedException 而失败。再次启动之前，请将 OpenSearch 目录的所有者改回该用户，例如:

$ sudo chown -R <user> /path/to/opensearch-3.9.0

启动 Fess

$ cd /path/to/fess-15.9.0
$ ./bin/fess

在后台启动:

$ ./bin/fess -d

Note

启动可能需要几分钟。 可以在 logs/ 目录的日志文件中确认启动状态。fess.log 记录 Fess 本身的消息， server_0.log 记录内嵌 Tomcat 的消息（包括启动完成消息）。

ZIP 版的情况（Windows）

启动 OpenSearch

  1. 打开 OpenSearch 的安装目录

  2. 双击 bin 文件夹中的 opensearch.bat

或者，从命令提示符:

C:\> cd C:\opensearch-3.9.0
C:\opensearch-3.9.0> bin\opensearch.bat

启动 Fess

  1. 打开 Fess 的安装目录

  2. 双击 bin 文件夹中的 fess.bat

或者，从命令提示符:

C:\> cd C:\fess-15.9.0
C:\fess-15.9.0> bin\fess.bat

RPM/DEB 版的情况 (chkconfig)

启动 OpenSearch:

$ sudo service opensearch start

启动 Fess:

$ sudo service fess start

确认启动状态:

$ sudo service fess status

RPM/DEB 版的情况 (systemd)

启动 OpenSearch:

$ sudo systemctl start opensearch.service

启动 Fess:

$ sudo systemctl start fess.service

确认启动状态:

$ sudo systemctl status fess.service

启用服务自动启动:

$ sudo systemctl enable opensearch.service
$ sudo systemctl enable fess.service

Docker 版的情况

Note

compose.yaml 和 compose-opensearch3.yaml 并不包含在 Fess 本体中。 这些文件由 docker-fess 项目（https://github.com/codelibs/docker-fess）提供； 请获取该仓库，并在 compose 目录中执行以下命令。

使用 Docker Compose 启动:

$ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d

确认启动状态:

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

确认日志:

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

确认启动

确认 Fess 是否正常启动。

健康检查

在浏览器或使用 curl 命令访问以下 URL:

http://localhost:8080/

如果正常启动，会显示 Fess 的搜索页面。

在命令行确认:

$ curl -I http://localhost:8080/

如果返回 HTTP/1.1 200 OK，则正常启动。

确认日志

确认启动日志，检查是否有错误。

ZIP 版:

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

RPM/DEB 版:

$ sudo tail -f /var/log/fess/fess.log

或使用 journalctl:

$ sudo journalctl -u fess.service -f

Docker 版:

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

Tip

启动成功完成后，如下启动完成消息会写入日志目录（ZIP 版为 logs/，RPM/DEB 版为 /var/log/fess/）中的 server_0.log。控制台和 fess.log 中都不会输出该消息:

...Booting the Tomcat: port=8080 contextPath=
...
Boot successful: url -> http://localhost:8080

在浏览器中访问

访问以下 URL 确认 Web 界面。

搜索页面

URL: http://localhost:8080/

显示 Fess 的搜索页面。初始状态下，由于未进行爬取配置，不会显示搜索结果。

搜索页面使用 Fess 内置的静态主题 bootstrap 。要更改其外观， 可以在管理页面的「系统」→「主题」中或使用 bin/fess-setup install theme <name> （参见 fess-setup 命令 ）安装其他主题， 也可以复制内置主题并修改副本（参见 自定义内置主题 ）。

管理页面

URL: http://localhost:8080/admin

默认管理员账号：

  • 用户名: admin

  • 密码: admin

Warning

关于安全的重要注意事项

必须更改默认密码。 特别是在生产环境中，强烈建议在首次登录后立即更改密码。

初始设置

登录管理页面后，进行以下初始配置。

步骤 1: 更改管理员密码

  1. 登录管理页面（http://localhost:8080/admin）

  2. 点击左侧菜单的「用户」→「用户」

  3. 点击 admin 用户

  4. 在 [密码] 字段输入新密码

  5. 在 [密码 (确认)] 字段再次输入相同密码

  6. 点击 [更新] 按钮

Important

推荐密码满足以下条件：

  • 8个字符或以上（password.min.length 所设置的最低长度要求）

  • 组合使用大写字母、小写字母、数字、符号

  • 不易被猜测

默认情况下，仅要求满足最低长度（8个字符），不强制要求字符类型组合。 可通过 password.require.uppercase 等设置启用字符类型要求。

步骤 2: 创建爬取配置

创建要爬取的网站或文件系统的配置。

  1. 点击左侧菜单的「爬虫」→「网页」

  2. 点击「新建」按钮

  3. 输入必要信息：

    • 名称: 爬取配置的名称（例：公司网站）

    • URL: 要爬取的目标 URL（例：https://www.example.com/）。如需指定多个 URL，请每行输入一个 URL

    • 最大访问数: 爬取文档数的上限（可选）

    • 间隔: 各次访问之间的等待时间（毫秒；默认值：10000）

    Note

    其他项目（如用户代理、线程数、深度等）留空时将使用默认值。

  4. 点击「创建」按钮

步骤 3: 执行爬取

  1. 点击左侧菜单的 [系统] → [调度器]

  2. 打开 [Default Crawler] 作业，点击「立即开始」按钮

  3. 等待爬取完成（可在仪表板查看进度）

步骤 4: 确认搜索

  1. 访问搜索页面（http://localhost:8080/）

  2. 输入搜索关键词

  3. 确认显示搜索结果

Note

爬取可能需要较长时间。 对于大规模网站，可能需要数小时到数天。

其他推荐设置

在生产环境运行时，还需要考虑以下设置。

通过环境变量进行主要设置

端口号、JVM 堆大小、OpenSearch 连接 URL 等设置可通过环境变量更改。 ZIP 版请编辑 bin/fess.in.sh，RPM 版请编辑 /etc/sysconfig/fess，DEB 版请编辑 /etc/default/fess。 更改后需要重启 Fess。

环境变量 默认值 说明
FESS_PORT 8080 Fess 监听的 HTTP 端口。
FESS_HEAP_SIZE （未设置） JVM 堆大小。最小值和最大值设置为相同的值。未设置时，最小值为 256m，最大值为 2g（ZIP 版（Windows）最大值为 1g）；RPM/DEB 版使用 512m。
SEARCH_ENGINE_HTTP_URL http://localhost:9200 连接的 OpenSearch 的 URL。ZIP 版由 bin/fess.in.sh 默认设置此值。当 OpenSearch 在不同端口或主机上运行时，请设置环境变量或编辑 bin/fess.in.sh。RPM/DEB 版通过软件包环境配置文件设置。
FESS_LOG_LEVEL warn Fess 的日志级别。
FESS_HEAP_NEWSIZE （未设置） JVM 堆新生代的大小（-Xmn），例如 256m。未设置时由 JVM 决定。
FESS_TEMP_PATH Fess 目录下的 temp（RPM/DEB 版为 /var/tmp/fess） 存放临时文件的目录，包括内嵌 Tomcat 的工作目录。运行 Fess 的用户必须对其有写入权限。
FESS_CONF_PATH （未设置）（RPM/DEB 版为 /etc/fess） 存放配置文件的目录。 bin/fess 会将该目录添加到类路径开头，并以 -Dfess.conf.path 传递给 Fess。对于 lib/classes 中的 tomcat_config.properties 等文件，优先使用该目录中的文件。但在 ZIP 版中，Web 应用程序会先读取 app/WEB-INF/classes 中的文件，因此放在该目录中的 fess_config.properties 无法覆盖 app/WEB-INF/classes 中 fess_config.properties 的值（爬虫等子进程会先于 WEB-INF/classes 读取该目录）。在 ZIP 版中要修改 fess_config.properties 时，请编辑 app/WEB-INF/classes 中的文件。RPM/DEB 版不会在 app/WEB-INF/classes 中放置 fess_config.properties，只使用 /etc/fess 中的文件。
FESS_USE_IPV4 （未设置） 设置任意非空值后，JVM 仅使用 IPv4 协议栈（-Djava.net.preferIPv4Stack=true）。
FESS_USE_GC_LOGGING （未设置） 设置任意非空值后，JVM 会将 GC 日志写入日志目录下的 gc-fess.log（最多 5 个文件，每个 64 MB）。

Note

Windows ZIP 版的 bin\fess.in.bat 读取的环境变量，除了这些环境变量中的 FESS_HEAP_SIZE、FESS_HEAP_NEWSIZE、FESS_USE_IPV4 和 FESS_USE_GC_LOGGING 之外， 还有表中没有列出的以下环境变量。

  • FESS_MIN_MEM、FESS_MAX_MEM：分别指定最小和最大堆大小（设置了 FESS_HEAP_SIZE 时将被忽略）。

  • FESS_DIRECT_SIZE：直接内存的上限（-XX:MaxDirectMemorySize）。

  • FESS_DICTIONARY_PATH：OpenSearch 的 config\dictionary 目录。

  • FESS_PROXY_HOST、FESS_PROXY_PORT、FESS_NON_PROXY_HOSTS：代理设置。

  • FESS_JAVA_OPTS：fess.in.bat 会将 JVM 选项追加到已设置的值之后。

  • PLAYWRIGHT_NODEJS_PATH：Playwright 插件使用的 Node.js 可执行文件。

  • JAVA_HOME：必需。

FESS_PORT、FESS_LOG_LEVEL、FESS_TEMP_PATH、FESS_CONF_PATH、SEARCH_ENGINE_HTTP_URL 不会被读取。这些值直接写在文件中，如需更改请直接编辑 bin\fess.in.bat。

邮件服务器设置

为了通过邮件接收故障通知等消息，请配置 SMTP 服务器和通知收件人地址。

  1. 在 fess_env_web.properties 和 fess_env_crawler.properties 中，通过 mail.smtp.server.main.host.and.port（默认值：localhost:25）指定 SMTP 服务器的主机名和端口。ZIP 包的这些文件位于 app/WEB-INF/classes/ 中，RPM/DEB 包则位于 /etc/fess/ 中。Fess Web 进程读取前者，发送爬取完成邮件的爬虫读取后者；不使用 fess_env.properties。更改后需要重启 Fess。

  2. 在管理界面中，点击左侧菜单的 [系统] → [通用]。

  3. 在 [通知邮件] 字段输入收件人邮件地址。

  4. 点击 [更新] 按钮。

  5. 可使用 [发送测试邮件] 按钮验证邮件是否正常发送。

时区设置

Fess 使用服务器（操作系统 / JVM）的时区。管理界面中没有更改时区的设置项。 如需更改时区，请修改操作系统的时区设置，或在 bin/fess.in.sh 的 FESS_JAVA_OPTS 中添加 JVM 选项 -Duser.timezone=Asia/Tokyo（Windows 系统请编辑 bin\fess.in.bat）。

调整日志级别

在生产环境中，可以调整日志级别以减少磁盘使用量。

Fess 的整体日志级别可通过 FESS_LOG_LEVEL 环境变量更改（默认值：warn）。 如需对各个日志记录器进行精细控制，请编辑配置文件 app/WEB-INF/classes/log4j2.xml。 爬取、suggest 和缩略图生成作为独立进程运行，因此请分别在 app/WEB-INF/env/{crawler,suggest,thumbnail}/resources/log4j2.xml 中配置各自的日志级别。

详情请参阅 Fess 管理员指南。

停止方法

ZIP 版的情况

停止 Fess

终止进程:

$ ps aux | grep fess
$ kill <PID>

或者，在前台运行时可以使用 Ctrl+C 停止。

停止 OpenSearch:

$ ps aux | grep opensearch
$ kill <PID>

RPM/DEB 版的情况 (chkconfig)

停止 Fess:

$ sudo service fess stop

停止 OpenSearch:

$ sudo service opensearch stop

RPM/DEB 版的情况 (systemd)

停止 Fess:

$ sudo systemctl stop fess.service

停止 OpenSearch:

$ sudo systemctl stop opensearch.service

Docker 版的情况

停止容器:

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

停止并删除容器:

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

Warning

如果使用 down 命令时同时删除卷，请添加 -v 选项。 这种情况下会删除所有数据，请注意。

重启方法

ZIP 版的情况

先停止后启动。

RPM/DEB 版的情况

chkconfig:

$ sudo service fess restart

systemd:

$ sudo systemctl restart fess.service

Docker 版的情况

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

故障排除

无法启动的情况

  1. 确认 OpenSearch 是否启动

    $ curl http://localhost:9200/

    如果 OpenSearch 未启动，请先启动 OpenSearch。

  2. 确认端口号冲突

    $ sudo ss -tuln | grep 8080

    已安装 net-tools 的环境中，也可以使用 sudo netstat -tuln | grep 8080 获得相同的信息。

    如果端口 8080 已被使用，请更改端口号。

    • ZIP 版：在 bin/fess.in.sh 中更改 FESS_PORT

    • ZIP 版（Windows）：直接编辑 bin\fess.in.bat 中的 -Dfess.port=8080

    • RPM 版：在 /etc/sysconfig/fess 中更改 FESS_PORT

    • DEB 版：在 /etc/default/fess 中更改 FESS_PORT

  3. 确认日志

    确认错误消息以找出问题。

  4. 确认 Java 版本

    $ java -version

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

详细的故障排除请参阅 故障排除。

下一步

Fess 正常启动后，请参阅以下文档开始运维：