codelibs/fess · 上手攻略
- 仓库：codelibs/fess
- 链接：https://github.com/codelibs/fess
- 分类：企业搜索 · 搜索服务器 · 知识管理
- 作者：Jay
- 更新：2026-08-30
这是什么
Fess 是一款开源的、自托管的企业级搜索服务器，基于 OpenSearch 构建。通过浏览器管理界面配置，无需深入了解 OpenSearch 本身。内置爬虫支持网站、文件系统、数据库等多种数据源，支持全文检索、分面搜索、搜索建议、权限过滤等企业级功能。
本质上是「开源版 Google Search Appliance / Elasticsearch Site Search」，让你在自有基础设施上快速搭一个企业内部搜索或公开网站搜索。
核心能力
- 全文检索：支持分面（faceting）搜索、排序、搜索建议（autocomplete）
- 多数据源爬虫：网站、文件系统、数据库（SaaS/云存储/本地数据库均可）
- 多格式支持：Microsoft Office、PDF、ZIP 归档等常见办公格式
- 浏览器管理界面：无需写代码，通过 Web UI 配置爬取目标、索引和搜索功能
- REST API：程序化调用搜索接口，嵌入到现有系统
- 权限过滤：基于角色和权限的搜索结果过滤，支持 LDAP、OIDC、SAML、SPNEGO、Microsoft Entra ID 单点登录
- 多语言：支持 20+ 语言的分词和搜索 UI 本地化
- 插件扩展：数据源插件（Confluence/Jira/Box/S3/Salesforce/SharePoint/Slack 等）、主题插件、日志插件
快速安装
方式一：下载安装包（推荐，Java 21+）
# Fess 15.8，从 Releases 页面下载 ZIP
unzip fess-15.8.x.zip
cd fess-15.8.x
./bin/fess
# 启动后访问：
# 搜索 UI：http://localhost:8080/
# 管理后台：http://localhost:8080/admin/ （默认账号 admin/admin）
⚠️ 安装前需确认已安装 Java 21 或更高版本。RPM/DEB 包安装方式同理，需提前安装 Java 21+。
方式二：Docker（最快）
# Fess Docker 镜像已发布在 ghcr.io
# docker-fess 仓库提供 docker-compose 一键启动
git clone https://github.com/codelibs/docker-fess.git
cd docker-fess/compose
docker-compose up -d
# 搜索 UI：http://localhost:8080/
# 管理后台：http://localhost:8080/admin/
⚠️ Docker 镜像已内置 OpenSearch，无需单独安装 OpenSearch。
配置爬取目标
登录管理后台（http://localhost:8080/admin/，账号 admin / admin）：
网站爬取
- 进入 Web 爬虫配置 页面，添加目标网站 URL
- 设置爬取深度、URL 过滤规则（包含/排除正则）
- 在 调度器页面 配置定时爬取任务并启动
文件系统爬取
- 进入 文件爬虫配置 页面，添加目标目录路径
- 设置文件类型过滤（如只爬
.pdf、.docx） - 启动调度器
数据库爬取（Data Store）
Fess 支持从以下数据源直接爬取（需安装对应数据源插件）：
| 数据源类型 | 说明 |
|---|---|
| 数据库（DB） | JDBC 连接的任意关系型数据库 |
| CSV | 导入 CSV 文件作为数据源 |
| S3 | 爬取 Amazon S3 存储桶内容 |
| SharePoint | 爬取 SharePoint 文档库 |
| Office 365 | 爬取 OneDrive / SharePoint Online |
| Salesforce | 爬取 Salesforce 对象 |
| Slack | 爬取 Slack 频道消息 |
| Elasticsearch | 爬取已有 ES/OpenSearch 集群内容 |
| Git | 爬取 Git 仓库中的代码文件 |
| Confluence / Jira | 爬取 Atlassian 协作平台内容 |
| Box / Dropbox | 爬取云盘文件 |
| Google Workspace | 爬取 Google Drive 内容 |
REST API 使用
Fess 提供完整的 REST API，可程序化调用：
# 健康检查
curl -s "http://localhost:8080/api/v1/health"
# 搜索（默认 JSON 格式）
curl "http://localhost:8080/json/?q=关键词"
# XML 格式
curl "http://localhost:8080/xml/?q=关键词"
# 指定返回字段和分页
curl "http://localhost:8080/json/?q=关键词&num=10&start=0"
⚠️ 以上 API 路径基于 Fess 15.x 文档，具体的 API 端点格式（
/json/vs/api/v1/search）以实际部署版本的官方文档为准，建议启动后先查阅管理 UI 中的 API 文档页面。
搜索结果嵌入网站
<!-- 最简单的嵌入式搜索框 -->
<form action="http://localhost:8080/json/" method="get">
<input type="text" name="q" placeholder="搜索..." />
<button type="submit">搜索</button>
</form>
Fess 还提供专门的 Fess Site Search (FSS) 作为 Google Site Search 的免费替代方案，可直接嵌入网站。
典型使用场景
| 场景 | 说明 |
|---|---|
| 企业内网搜索 | 打通多个内部系统（Wiki/邮件/文档库/代码仓库），员工一框搜索全部 |
| 公开网站搜索 | 替代 Google Site Search / Algolia，自托管、无按查询收费 |
| 知识库检索 | 将散落在不同系统的文档集中索引，提供统一检索入口 |
| 文档归档检索 | 爬取历史文件服务器/网盘，建立可搜索档案 |
| 电商/内容平台搜索 | 将商品/内容数据库通过 Data Store 插件索引，提供带权限控制的搜索 |
坑与注意
- Java 21 是硬性要求：低于 Java 21 的运行环境无法启动 Fess 15.x；部分旧版 Fess（如 14.x）支持 Java 11/17，但功能较旧。
- OpenSearch 需单独安装（非 Docker）：Docker 镜像内置 OpenSearch，但传统安装方式需要先搭好 OpenSearch 集群，再让 Fess 连接。具体版本兼容性见官方安装指南。
- 数据源插件需单独安装：基础包不带所有数据源连接器（如 Salesforce/Confluence），需要在管理 UI 的插件页面中上传对应插件。
- 爬虫性能调优：大规模爬取时注意 OpenSearch 的 JVM 内存配置，默认值可能不够，建议根据数据量调整
opensearch.yml中的heap.size。 - 中文分词：Fess 基于 OpenSearch，中文分词依赖 IK Analysis 等插件，Fess 本身未内置开箱即用的中文分词器，需在管理界面或配置文件中额外安装和配置。
- 安全加固：默认账号
admin/admin为测试用途，生产环境必须立即修改密码并配置 HTTPS。
与同类对比
| 产品 | 与 Fess 的主要区别 |
|---|---|
| Elasticsearch + 自建搜索 | Elasticsearch 是通用搜索引擎，Fess 是开箱即用的企业搜索产品，无需写代码配爬虫和 UI |
| Algolia / Elastic Cloud（SaaS） | Fess 完全自托管，无按查询收费；适合数据主权要求高、预算有限但有运维能力的团队 |
| Google Search Appliance（已停售） | Fess 可视为其开源替代品，功能覆盖范围相似 |
| MeiliSearch | MeiliSearch 更轻量，适合中小型项目；Fess 更适合需要多数据源爬虫、权限管理、企业 SSO 的大型场景 |
| Apache Solr | Solr 功能丰富但配置复杂；Fess 在保留企业搜索能力的同时大幅降低了上手门槛 |
一句话总结：Fess 是企业搜索的「交钥匙方案」—— 基于 OpenSearch 的成熟开源产品，浏览器配一配就能爬网站/文件/数据库，无需掌握搜索底层原理，适合搭建内部知识搜索或替代 Google Site Search。
⚠️ 声明：以上信息基于 2026-08-30 GitHub README 页面 web_fetch 获取。版本号（15.8）、API 端点格式、Java 版本要求以官方最新文档为准。生产环境使用请务必修改默认账号密码并启用 HTTPS。