Fess 15.9.0 配置参数详解

目标：以官方发行版默认配置为基线，逐类解析 Fess 15.9.0 的配置载体与核心参数——/etc/fess/fess_config.properties（814 个键）的六大键空间、system.properties 与 FESS_JAVA_OPTS 的分工与优先级，并给出每种修改方式的实测验证与生产模板。全部键值取自实机默认文件，修改效果均经重启与 API 实测。

一、环境信息

• 操作系统：Ubuntu 22.04 LTS（x86_64）
• 软件版本：Fess 15.9.0（2026-10-15 发布）+ OpenSearch 3.9.0（fess-opensearch 定制发行版）
• 配置目录：/etc/fess/（发行包固定路径，属 Fess 运行时 classpath 前部）
• 端口：8080（Fess Web/管理/API）、9200（搜索引擎 HTTP）
• 管理账号：admin / q1w2e3r4（首登强制改密后设定，见部署篇 4.5 节）
• JVM：Fess 应用堆 512m（FESS_HEAP_SIZE 设定），搜索引擎堆 512m（OPENSEARCH_JAVA_OPTS 设定）
• 配置文件实测清单（ls -la /etc/fess/ 回显）：

total 120
-rw-r--r-- 1 fess fess 79806 Oct 15 07:03 fess_config.properties
-rw-r--r-- 1 fess fess  2266 Oct 15 07:03 fess_env_chunk.properties
-rw-r--r-- 1 fess fess  2266 Oct 15 07:03 fess_env_crawler.properties
-rw-r--r-- 1 fess fess  2266 Oct 15 07:03 fess_env_suggest.properties
-rw-r--r-- 1 fess fess  2266 Oct 15 07:03 fess_env_thumbnail.properties
-rw-r--r-- 1 fess fess  2266 Oct 15 07:03 fess_env_web.properties
-rw-r--r-- 1 fess fess   609 Oct 15 07:02 logging.properties
-rw-r--r-- 1 fess fess     0 Oct 15 10:06 system.properties
-rw-r--r-- 1 fess fess   150 Oct 15 07:03 tika.xml
-rw-r--r-- 1 fess fess  1014 Oct 15 07:02 tomcat_config.properties

二、前置条件

1. 已按部署指南完成 Fess 15.9.0 与 OpenSearch 3.9.0 安装并启动，http://<服务器IP>:8080/api/v2/health 返回 "status":0。
2. 对 Fess 进程有读取权限，能执行 ps -ef / jps -v 验证 JVM 参数。
3. 修改配置前备份原文件：cp /etc/fess/fess_config.properties /etc/fess/fess_config.properties.bak。

💡 说明：Fess 15.9.0 的配置「值」全部存于 fess_config.properties（官方 properties 参考页声明「The values themselves live in fess_config.properties」）；其余 fess_env_*.properties 是按子进程（爬虫/建议/缩略图/分块/Web）拆分的环境变量映射文件，tomcat_config.properties 管内嵌容器参数，tika.xml 控制文本抽取解析器。

三、参数查看与修改方式

3.1 查看当前配置

# 全部键值（814 个键，1922 行）
grep -cE '^[a-z]' /etc/fess/fess_config.properties    # 实测：814
wc -l /etc/fess/fess_config.properties               # 实测：1922 /etc/fess/fess_config.properties

# 查看某个键的默认值（含官方注释）
grep -B2 '^query.timeout=' /etc/fess/fess_config.properties
# 实测回显：
# Timeout of the search query.
# (毫秒，超时后返回部分结果)
query.timeout=10000

# 运行中进程实际生效的 JVM 参数
ps -ef | grep -o 'Xms[0-9]*[a-z] -Xmx[0-9]*[a-z]' | head -1
# 实测回显：Xms512m -Xmx512m

3.2 修改方式与优先级（三种，按推荐顺序）

方式一：FESS_JAVA_OPTS 附加系统属性（推荐，改动最小、可回滚）

以 -Dfess.config.<键名>=<值> 的形式覆盖任意 fess_config.properties 键。在 Fess 启动环境（RPM 安装为 /etc/sysconfig/fess，DEB 为 /etc/default/fess，脚本启动为导出环境变量）中设置后重启：

# /etc/sysconfig/fess 追加一行
FESS_JAVA_OPTS="-Dfess.config.query.additional.api.response.fields=lang,expires"
systemctl restart fess

实测验证（进程命令行出现该属性）：

ps -ef | grep -oE 'Dfess.config.query.additional.api.response.fields=\S+' | head -1
# 实测回显：
Dfess.config.query.additional.api.response.fields=lang,expires

行为变化实测：默认搜索 API 响应含 23 个字段（title/url/score/digest 等），设置后响应新增 "lang":"zh-cn" 字段；删除该变量重启后字段恢复原状。

⚠️ 注意：-Dfess.config.<键> 的键名必须是 fess_config.properties 中已定义的键。实测两组反例：-Dfess.config.web.api.json.response.fields=...（文件中无此键，静默不生效）；-Dfess.config.query.additional.response.fields=lang,host（键存在但作用于其他链路，search API 无变化）。改参数前先 grep 确认键名，再验证行为。

方式二：直接编辑 fess_config.properties

vi /etc/fess/fess_config.properties   # 修改目标键
systemctl restart fess                 # 重启生效

适合批量调整；缺点是版本升级时会被新包覆盖，需要 diff 合并。

方式三：system.properties 文件（仅备注，实测不可用于覆盖 fess.config.*）

该文件默认为空（0 字节），属于 index.backup.targets 配置备份清单成员。实测向其写入 query.additional.api.response.fields=lang 并重启 Fess 后，搜索 API 响应未出现 lang 字段——不能用它覆盖 fess.config.* 配置键，JVM 级系统属性请统一走 FESS_JAVA_OPTS。

3.3 启动脚本参数链（fess.in.sh，实测摘录）

Fess 启动脚本按以下顺序拼装 JVM 参数，理解它才能正确设堆：

# 1) FESS_HEAP_SIZE 未设置时的默认值（实测脚本第 13/16 行）
FESS_MIN_MEM=256m
FESS_MAX_MEM=2g
# 2) FESS_HEAP_SIZE 同时覆盖上下限（第 18-20 行）
if [ "x$FESS_HEAP_SIZE" != "x" ]; then
    FESS_MIN_MEM=$FESS_HEAP_SIZE
    FESS_MAX_MEM=$FESS_HEAP_SIZE
fi
# 3) 最终拼装（第 53-66 行）
FESS_JAVA_OPTS="$FESS_JAVA_OPTS -Xms${FESS_MIN_MEM}"
FESS_JAVA_OPTS="$FESS_JAVA_OPTS -Xmx${FESS_MAX_MEM}"
FESS_JAVA_OPTS="$FESS_JAVA_OPTS -XX:MaxMetaspaceSize=256m -XX:CompressedClassSpaceSize=32m"
FESS_JAVA_OPTS="$FESS_JAVA_OPTS -Djava.awt.headless=true -Dhttp.maxConnections=20"

⚠️ 注意：脚本开头显式检测并忽略裸 JAVA_OPTS 环境变量，打印警告「ignoring JAVA_OPTS=...; pass JVM parameters via FESS_JAVA_OPTS」——设堆只能用 FESS_HEAP_SIZE 或 FESS_JAVA_OPTS。同理，搜索引擎侧的堆由 OPENSEARCH_JAVA_OPTS（如 -Xms512m -Xmx512m）控制，验证手段为查询引擎 _nodes/jvm 接口的 heap_max_in_bytes（536870912 = 512m，实测值）。

四、参数总览

fess_config.properties 共 814 个键，按前缀分布（实测 grep -c 统计）：

💡 技术拓展：jvm.crawler.options 等四个键控制爬虫/建议等子 JVM 进程的堆（默认 -Xmx512m）。大文档量爬取 OOM 时优先调这里，而不是调主进程堆。

五、核心参数分类详解

5.1 引擎与索引（index.*）

5.2 爬虫（crawler.*）

5.3 查询与高亮（query.*）

5.4 对外 API 与安全（api.*）

5.5 子进程 JVM（jvm.*）

六、生产配置模板

模板 A：小规模（4 GB 内存，Fess 与引擎同机，文档 ≤10 万）

# /etc/sysconfig/fess（或 /etc/default/fess）
FESS_HEAP_SIZE=512m
FESS_JAVA_OPTS="-Dfess.config.query.timeout=10000 -Duser.timezone=Asia/Shanghai"

引擎侧堆 512m（OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m），两进程合计约 1 GB 堆，4 GB 物理内存安全。index.number_of_shards 保持默认 5。

模板 B：中规模（8 GB 内存以上，引擎独立，文档 10 万~百万）

FESS_HEAP_SIZE=1g
FESS_JAVA_OPTS="-Dfess.config.crawler.http.thread_pool.size=2 -Dfess.config.query.timeout=8000"

引擎堆建议物理内存一半以内（如 4 GB），api.cors.allow.origin 收紧为业务域名，api.search.export=true 按需开启并保留限流默认值。

💡 说明：两模板均以实测默认值为基线仅微调三项（堆、超时、线程池）；Fess 的默认参数已针对通用场景优化，逐键调优前先用默认值压测定位瓶颈。

七、常见问题

Q1：改了 fess_config.properties 不生效？ 未重启 Fess（配置仅在启动时读取），或改的是 -Dfess.config.<键> 但键名拼写与文件中不一致（实测：不存在的键静默忽略）。先 grep '^<键名>' /etc/fess/fess_config.properties 确认存在，再重启并 ps -ef 验证参数已挂上。

Q2：设了 JAVA_OPTS 环境变量没效果？ 启动脚本会显式忽略它并打警告，改用 FESS_HEAP_SIZE / FESS_JAVA_OPTS。

Q3：爬虫子进程 OOM 而主进程正常？ OOM 的是爬虫独立 JVM，调 jvm.crawler.options（如 -Xmx1g）而非主进程堆。

Q4：搜索接口响应想多带几个原始字段？ 用 query.additional.api.response.fields（实测设 lang,expires 后响应出现 lang: zh-cn）；注意字段须为索引中实际存储的字段，值为空的字段不会出现在响应中。

Q5：system.properties 能用来覆盖配置吗？ 实测不能（写入 fess.config.* 键重启后无效果）。它是配置备份清单的成员文件，JVM 属性统一走 FESS_JAVA_OPTS。

Q6：中文分词不理想，改哪个键？ 分词词典不在 fess_config.properties 中管理，走管理后台「系统 → 词典」维护（存储于引擎 dictionary 目录）；配置文件里仅 crawler.document.site.encoding 等编码项影响中文解析。

八、参考链接

1. 官方配置参数参考（全部 814 键逐键说明）：https://fess.codelibs.org/stable/config/properties.html （查询日期 2026-10-24）
2. JVM 内存配置官方说明（FESS_HEAP_SIZE/FESS_MIN_MEM/FESS_MAX_MEM）：https://fess.codelibs.org/stable/config/setup-memory.html （查询日期 2026-10-24）
3. 搜索引擎连接类型说明：https://fess.codelibs.org/stable/config/search-engine-type.html （查询日期 2026-10-24）
4. 本专栏姊妹篇：《Fess 15.9.0 介绍与选型指南》、《Fess 15.9.0 Docker Compose 部署指南》、《Fess 15.9.0 查询语言详解》