概要
本ガイドでは、Fess クローラーの高度な設定について説明します。 基本的なクローラー設定については、クローラー設定:Web、ファイルサーバー、データベースクロール を参照してください。
警告
本ページの設定は、システム全体に影響する可能性があります。 設定を変更する際は、十分にテストを行ってから本番環境に適用してください。
全般設定
設定ファイルの場所
クローラーの詳細設定は、以下のファイルで行います。
メイン設定:
/etc/fess/fess_config.properties(またはapp/WEB-INF/classes/fess_config.properties)コンテンツ長設定:
app/WEB-INF/classes/crawler/contentlength.xmlコンポーネント設定:
app/WEB-INF/classes/crawler/container.xml
デフォルトスクリプト
クローラーのデフォルトスクリプト言語を設定します。
| プロパティ | 説明 | デフォルト |
|---|---|---|
crawler.default.script | クローラースクリプトの言語 | groovy |
HTTPスレッドプール
HTTPクローラーのスレッドプール設定です。
| プロパティ | 説明 | デフォルト |
|---|---|---|
crawler.http.thread_pool.size | HTTPスレッドプールサイズ | 0 |
ドキュメント処理設定
基本設定
| プロパティ | 説明 | デフォルト |
|---|---|---|
crawler.document.max.site.length | サイト名フィールドの最大文字数 | 100 |
crawler.document.site.encoding | ドキュメントサイトのエンコーディング | UTF-8 |
crawler.document.unknown.hostname | 不明なホスト名の代替値 | unknown |
crawler.document.use.site.encoding.on.english | 英語ドキュメントでサイトエンコーディングを使用 | false |
crawler.document.append.data | ドキュメントにデータを追加 | true |
crawler.document.append.filename | ファイル名をドキュメントに追加 | false |
設定例
単語処理設定
| プロパティ | 説明 | デフォルト |
|---|---|---|
crawler.document.max.alphanum.term.size | 英数字単語の最大長 | 20 |
crawler.document.max.symbol.term.size | 記号単語の最大長 | 10 |
crawler.document.duplicate.term.removed | 重複単語の削除 | false |
設定例
注釈
max.alphanum.term.size を大きくすると、長いID、トークン、URLなどを 完全な形でインデックスできますが、インデックスサイズが増加します。
文字処理設定
| プロパティ | 説明 | デフォルト |
|---|---|---|
crawler.document.space.chars | 空白文字の定義 | u0009u000A... |
crawler.document.fullstop.chars | 句点文字の定義 | u002eu06d4... |
設定例
プロトコル設定
対応プロトコル
| プロパティ | 説明 | デフォルト |
|---|---|---|
crawler.web.protocols | Webクロールのプロトコル | http,https |
crawler.file.protocols | ファイルクロールのプロトコル | file,smb,smb1,ftp,storage,s3,gcs |
crawler.crawling.data.encoding | クロールデータのエンコーディング | UTF-8 |
設定例
環境変数パラメーター
| プロパティ | 説明 | デフォルト |
|---|---|---|
crawler.data.env.param.key.pattern | 環境変数パラメーターキーのパターン | ^FESS_ENV_.* |
データシリアライザー
| プロパティ | 説明 | デフォルト |
|---|---|---|
crawler.data.serializer | クロールデータのシリアライズ方式 | kryo |
robots.txt 設定
| プロパティ | 説明 | デフォルト |
|---|---|---|
crawler.ignore.robots.txt | robots.txtを無視 | false |
crawler.ignore.robots.tags | robotsメタタグを無視 | false |
crawler.ignore.content.exception | コンテンツ例外を無視 | true |
警告
crawler.ignore.robots.txt=true に設定すると、サイトの利用規約に 違反する可能性があります。外部サイトをクロールする際は注意してください。
エラー処理設定
| プロパティ | 説明 | デフォルト |
|---|---|---|
crawler.failure.url.status.codes | 失敗とみなすHTTPステータスコード(カンマ区切り) | 404,403,410 |
システム監視設定
| プロパティ | 説明 | デフォルト |
|---|---|---|
crawler.system.monitor.interval | システム監視間隔(秒) | 60 |
ホットスレッド設定
| プロパティ | 説明 | デフォルト |
|---|---|---|
crawler.hotthread.ignore_idle_threads | アイドルスレッドを無視 | true |
crawler.hotthread.interval | スナップショット間隔 | 500ms |
crawler.hotthread.snapshots | スナップショット数 | 10 |
crawler.hotthread.threads | 監視スレッド数 | 3 |
crawler.hotthread.timeout | タイムアウト | 30s |
crawler.hotthread.type | 監視タイプ | cpu |
設定例
メタデータ設定
| プロパティ | 説明 | デフォルト |
|---|---|---|
crawler.metadata.content.excludes | 除外するメタデータ | resourceName,X-Parsed-By... |
crawler.metadata.name.mapping | メタデータ名のマッピング | title=title:string... |
HTML クローラー設定
XPath 設定
HTML要素を抽出するためのXPath設定です。
| プロパティ | 説明 | デフォルト |
|---|---|---|
crawler.document.html.content.xpath | コンテンツのXPath | //BODY |
crawler.document.html.lang.xpath | 言語のXPath | //HTML/@lang |
crawler.document.html.digest.xpath | ダイジェストのXPath | //META[@name='description']/@content |
crawler.document.html.canonical.xpath | カノニカルURLのXPath | //LINK[@rel='canonical'][1]/@href |
設定例
カスタム XPath の例
HTML タグ処理
| プロパティ | 説明 | デフォルト |
|---|---|---|
crawler.document.html.pruned.tags | 削除するHTMLタグ | noscript,script,style,header,footer,aside,nav,a[rel=nofollow] |
crawler.document.html.max.digest.length | ダイジェストの最大長 | 120 |
crawler.document.html.default.lang | デフォルト言語 | (空) |
設定例
URLパターンフィルター
| プロパティ | 説明 | デフォルト |
|---|---|---|
crawler.document.html.default.include.index.patterns | インデックスに含めるURLパターン | (空) |
crawler.document.html.default.exclude.index.patterns | インデックスから除外するURLパターン | (?i).*(css|js|jpeg...) |
crawler.document.html.default.include.search.patterns | 検索結果に含めるURLパターン | (空) |
crawler.document.html.default.exclude.search.patterns | 検索結果から除外するURLパターン | (空) |
設定例
ファイルクローラー設定
基本設定
| プロパティ | 説明 | デフォルト |
|---|---|---|
crawler.document.file.name.encoding | ファイル名のエンコーディング | (空) |
crawler.document.file.no.title.label | タイトルなしファイルのラベル | No title. |
crawler.document.file.ignore.empty.content | 空のコンテンツを無視 | false |
crawler.document.file.max.title.length | タイトルの最大長 | 100 |
crawler.document.file.max.digest.length | ダイジェストの最大長 | 200 |
設定例
コンテンツ処理
| プロパティ | 説明 | デフォルト |
|---|---|---|
crawler.document.file.append.meta.content | メタデータをコンテンツに追加 | true |
crawler.document.file.append.body.content | 本文をコンテンツに追加 | true |
crawler.document.file.default.lang | デフォルト言語 | (空) |
設定例
ファイルURLパターンフィルター
| プロパティ | 説明 | デフォルト |
|---|---|---|
crawler.document.file.default.include.index.patterns | インデックスに含めるパターン | (空) |
crawler.document.file.default.exclude.index.patterns | インデックスから除外するパターン | (空) |
crawler.document.file.default.include.search.patterns | 検索結果に含めるパターン | (空) |
crawler.document.file.default.exclude.search.patterns | 検索結果から除外するパターン | (空) |
設定例
MIMEタイプ検出オーバーライド
Fess はデフォルトで Apache Tika を使用してコンテンツベースのMIMEタイプ検出を行います。 しかし、一部のケースでコンテンツベースの検出が誤った結果を返すことがあります。 たとえば、REM コメントで始まるOracle SQLファイルは、REM キーワードが バッチファイルのマジックパターンに一致するため、application/x-bat として 誤検出される場合があります。
crawler.document.mimetype.extension.overrides プロパティを使用すると、 ファイル拡張子に基づいてMIMEタイプ検出をオーバーライドし、 特定のファイルタイプに対するコンテンツベース検出をバイパスできます。
| プロパティ | 説明 | デフォルト |
|---|---|---|
crawler.document.mimetype.extension.overrides | 拡張子からMIMEタイプへのオーバーライドマッピング(1行に1つ、形式: .ext=mime/type) | (空) |
設定例
各行は .拡張子=MIMEタイプ の形式で記述します。 複数のマッピングは \n(改行)で区切ります。 拡張子のマッチングは大文字小文字を区別しません(.SQL と .sql は同じ扱い)。
注釈
ファイル拡張子がこのマップのエントリに一致する場合、設定されたMIMEタイプが コンテンツベース検出を行わずに即座に返されます。 マップにない拡張子のファイルは、通常のTika検出が使用されます。
キャッシュ設定
ドキュメントキャッシュ
| プロパティ | 説明 | デフォルト |
|---|---|---|
crawler.document.cache.enabled | ドキュメントキャッシュを有効化 | true |
crawler.document.cache.max.size | キャッシュの最大サイズ(バイト) | 2621440 (2.5MB) |
crawler.document.cache.supported.mimetypes | キャッシュ対象のMIMEタイプ | text/html |
crawler.document.cache.html.mimetypes | HTMLとして扱うMIMEタイプ | text/html |
設定例
注釈
キャッシュを有効にすると、検索結果にキャッシュリンクが表示され、 ユーザーはクロール時点のコンテンツを参照できます。
JVM オプション
クローラープロセスのJVMオプションを設定できます。
| プロパティ | 説明 | デフォルト |
|---|---|---|
jvm.crawler.options | クローラーのJVMオプション | -Xms128m -Xmx512m... |
デフォルト設定
注釈
上記は主要なオプションの抜粋です。実際のデフォルト値には、jcifs SMBタイムアウト、Netty設定、Log4j設定、G1GC詳細設定、PDFBox設定など、約40のオプションが含まれています。 完全なデフォルト値は fess_config.properties を参照してください。 カスタマイズ時は必要なオプションのみを変更し、他のデフォルト値は維持してください。
主要なオプションの説明
| オプション | 説明 |
|---|---|
-Xms128m | 初期ヒープサイズ(128MB) |
-Xmx512m | 最大ヒープサイズ(512MB) |
-XX:MaxMetaspaceSize=128m | Metaspaceの最大サイズ(128MB) |
-XX:+UseG1GC | G1ガベージコレクターを使用 |
-XX:MaxGCPauseMillis=60000 | GC停止時間の目標値(60秒) |
-XX:-HeapDumpOnOutOfMemoryError | OutOfMemory時のヒープダンプを無効化 |
カスタム設定例
大きなファイルをクロールする場合:
デバッグ時:
詳細は メモリ設定 を参照してください。
パフォーマンスチューニング
クロール速度の最適化
1. スレッド数の調整
並列クロール数を増やすことで、クロール速度を向上できます。
ただし、対象サーバーへの負荷に注意してください。
2. タイムアウトの調整
応答が遅いサイトの場合、タイムアウトを調整します。
3. 不要なコンテンツの除外
画像、CSS、JavaScriptファイルなどを除外することで、クロール速度が向上します。
4. リトライ設定
HTTPクロールのリトライ回数(デフォルト5回)とリトライ間隔(デフォルト500ミリ秒)は 組み込みの固定値であり、クロール設定の「設定パラメーター」では変更できません。 応答しないURLでの待ち時間を短縮したい場合は、上記のタイムアウト調整や不要なURLの 除外を行ってください。
メモリ使用量の最適化
1. ヒープサイズの調整
2. キャッシュサイズの調整
3. 大きなファイルの除外
詳細は メモリ設定 を参照してください。
インデックス品質の向上
1. XPathの最適化
不要な要素(ナビゲーション、広告など)を除外します。
2. ダイジェストの最適化
3. メタデータマッピング
トラブルシューティング
メモリ不足
症状:
OutOfMemoryErrorがfess_crawler.logに記録されるクロールが途中で停止する
対策:
クローラーのヒープサイズを増やす
並列スレッド数を減らす
大きなファイルを除外する
詳細は メモリ設定 を参照してください。
クロールが遅い
症状:
クロールに時間がかかりすぎる
タイムアウトが頻発する
対策:
スレッド数を増やす(対象サーバーの負荷に注意)
タイムアウトを調整する
不要なURLを除外する
特定のコンテンツが抽出できない
症状:
ページのテキストが正しく抽出されない
重要な情報が検索結果に含まれない
対策:
XPathを確認・調整する
削除タグを確認する
JavaScriptで動的に生成されるコンテンツの場合、別の方法(APIクロールなど)を検討
文字化けが発生する
症状:
検索結果で文字化けが発生する
特定の言語が正しく表示されない
対策:
エンコーディング設定を確認
ファイル名のエンコーディングを設定
ログでエンコーディングエラーを確認
ベストプラクティス
テスト環境で検証
本番環境に適用する前に、テスト環境で十分に検証してください。
段階的な調整
設定を一度に大きく変更せず、段階的に調整して効果を確認してください。
ログの監視
設定変更後は、ログを監視してエラーやパフォーマンスの問題がないか確認してください。
バックアップ
設定ファイルを変更する前に、必ずバックアップを取ってください。
ドキュメント化
変更した設定とその理由をドキュメント化してください。
S3/GCSクローラー設定
S3クローラー
S3およびS3互換ストレージ(MinIO等)をクロールするための設定です。 ファイルクロール設定の「設定パラメーター」に以下を記述します。
| パラメーター | 説明 | デフォルト |
|---|---|---|
client.endpoint | S3エンドポイントURL | (必須) |
client.accessKey | アクセスキー | (必須) |
client.secretKey | シークレットキー | (必須) |
client.region | AWSリージョン | us-east-1 |
client.maxContentLength | 取得するオブジェクトの最大サイズ(バイト)。超過したオブジェクトはスキップ | (無制限) |
client.maxCachedContentSize | メモリにキャッシュする最大サイズ(バイト)。超過分は一時ファイルを使用 | 1048576 (1MB) |
client.accessTimeout | アクセスタイムアウト(秒)。未設定の場合は無効 | (無制限) |
設定例
GCSクローラー
Google Cloud Storageをクロールするための設定です。 ファイルクロール設定の「設定パラメーター」に以下を記述します。
| パラメーター | 説明 | デフォルト |
|---|---|---|
client.projectId | Google CloudプロジェクトID | (必須) |
client.credentialsFile | サービスアカウントJSONファイルパス | (オプション) |
client.endpoint | カスタムエンドポイント | (オプション) |
client.maxContentLength | 取得するオブジェクトの最大サイズ(バイト)。超過したオブジェクトはスキップ | (無制限) |
client.maxCachedContentSize | メモリにキャッシュする最大サイズ(バイト)。超過分は一時ファイルを使用 | 1048576 (1MB) |
client.accessTimeout | アクセスタイムアウト(秒)。未設定の場合は無効 | (無制限) |
設定例
注釈
credentialsFile を省略した場合、環境変数 GOOGLE_APPLICATION_CREDENTIALS が使用されます。
動的コンテンツのクロール (Playwright)
JavaScript で描画されるページ (SPA など) は、通常の HTTP クローラーでは 描画前の HTML しか取得できないため、本文がインデックスされません。 Playwright クローラーを使用すると、ヘッドレスブラウザーでページを描画してから コンテンツを取得できます。
有効化
ウェブクロール設定の「設定パラメーター」に以下を記述します。
playwright: に続く部分は、Playwright で取得する URL の正規表現です。 上記の例では、すべての HTTP/HTTPS の URL が Playwright で取得されます。 特定のサイトだけを Playwright で取得する場合は、次のように指定します。
注釈
Playwright のブラウザー本体は Fess のパッケージには含まれていません。 初回のクロール時にダウンロードされるため、外部ネットワークに接続できない 環境では、クローラーを実行する OS ユーザーであらかじめインストールして おいてください。
設定パラメーター
以下のパラメーターは、クロール設定の「設定パラメーター」に client. を 付けて記述します。
| パラメーター | 説明 | デフォルト |
|---|---|---|
client.renderedState | コンテンツを取得する前に待機する読み込み状態。LOAD 、DOMCONTENTLOADED 、NETWORKIDLE のいずれかを大文字で指定 | NETWORKIDLE |
client.renderedStateTimeout | renderedState を待機する上限 (ミリ秒)。0 以下の場合は Playwright の既定値 (30000) | 0 |
client.navigationTimeout | ページ遷移の上限 (ミリ秒)。0 以下の場合は Playwright の既定値 (30000) | (未設定) |
client.contentWaitDuration | renderedState に到達してからコンテンツを取得するまでの追加の待機時間 (ミリ秒) | 0 |
client.sharedClient | Playwright のワーカー (ブラウザー) を全クライアントで共有する | false |
client.blockedResourceTypes | ブラウザーが取得しないリソース種別 (カンマ区切り) | (空) |
client.ignoreHttpsErrors | HTTPS 証明書の検証エラーを無視する | false |
client.proxyBypass | プロキシを経由しないホスト (カンマ区切り) | (空) |
設定例
注釈
ユーザーエージェントとリクエストヘッダーは、クロール設定の 「ユーザーエージェント」およびリクエストヘッダーの設定がそのまま使用されます。 client.proxyHost 、client.proxyPort 、client.maxContentLength などの 共通のパラメーターもブラウザーに適用されます。
注釈
1 つの Playwright クライアントは 1 つのブラウザーページを使用し、 リクエストは直列に処理されます。クロール設定のスレッド数を増やしても、 Playwright での取得はその分速くはなりません。
DI 定義でのみ設定できる項目
以下の項目は「設定パラメーター」では変更できません。変更する場合は app/WEB-INF/classes/crawler/client+playwrightClient.xml を作成し、 playwrightClient コンポーネントを再定義します。
| プロパティ | 説明 | デフォルト |
|---|---|---|
browserName | 使用するブラウザー。chromium 、firefox 、webkit | chromium |
launchOptions | ブラウザーの起動オプション (BrowserType.LaunchOptions) | headless=true |
newContextOptions | ブラウザーコンテキストのオプション (Browser.NewContextOptions) | (なし) |
downloadTimeout | ファイルのダウンロードを待機する上限 (秒) | 15 |
closeTimeout | ブラウザーの終了処理を待機する上限 (秒) | 15 |
設定例
注釈
playwrightClient を再定義すると、プラグインが持つ crawler/client++.xml のコンポーネント定義は完全に置き換わります。 記述しなかったプロパティは既定値に戻るため、上記の例のように必要な プロパティをすべて記述してください。なお crawler/client++.xml を そのままコピーして配置すると、同じコンポーネントが二重に登録されて 起動に失敗します。
警告
downloadTimeout と closeTimeout の単位は秒です。 navigationTimeout 、renderedStateTimeout 、contentWaitDuration は ミリ秒であるため、混同しないよう注意してください。
不要なリソースのブロック
client.blockedResourceTypes には、ブラウザーが取得しないリソース種別を カンマ区切りで指定します。指定できるのは Playwright のリソース種別 (stylesheet 、image 、media 、font 、script 、 texttrack 、xhr 、fetch 、eventsource 、websocket 、 manifest 、other 、ping 、cspreport 、beacon) です。 既定では何もブロックしません。
image 、media 、font 、ping 、beacon 、cspreport は 安全に指定できる組です。後の 3 つはビーコン系のトラッカー通信であり、 ページ側が読み返すことはありません。
クロールが読み取らない種別だけを指定してください。ページの表示に必要な リソースの取得を減らすことで、クロールの所要時間と転送量を削減できます。
警告
document は指定しないでください。ページ本体の取得がブロックされて クロールが成立しないため、警告を出して無視されます。
注釈
一覧にない種別を指定した場合も警告が出ます。images のような複数形の 打ち間違いは、どのリクエストにも一致しないため何もブロックしません。 また、上記の一覧は 3 つのブラウザーエンジンが報告する種別の和集合であるため、 使用するブラウザーによっては報告されない種別があります。texttrack は Chromium のみが報告し、WebKit は media と manifest を報告しません。 報告されない種別を指定しても、単に何もブロックしないだけです。
注釈
script や xhr をブロックすると JavaScript による描画が行われなくなり、 Playwright を使用する意味がなくなります。サーバーサイドレンダリングのみを 対象とするクロールでは有効ですが、通常は上記の安全に指定できる種別の中から 選んでください。
15.8 での変更点
15.7 以前からアップグレードする場合、Playwright クローラーの動作が 以下のように変わっています。
ユーザーエージェント: クロール設定の「ユーザーエージェント」が 実際にブラウザーから送信されるようになりました。15.7 以前はブラウザー既定の
HeadlessChrome/...が送信されていました。ユーザーエージェントによって 応答を出し分けているサイトでは、取得内容が変わる場合があります。リクエストヘッダー: クロール設定のリクエストヘッダーがブラウザーに 反映されるようになりました。同じ名前のヘッダーが複数ある場合は、 カンマ区切りの 1 つの値にまとめられます。
リダイレクト経由のダウンロード: 記録される URL がリダイレクト先 (実際にファイルを返した URL) になりました。リダイレクト先がクロール対象外の URL の場合は、対象外として除外されます。
``renderedState`` の待機: 待機がタイムアウトしても失敗とはみなされず、 その時点で読み込めていた内容がそのまま使用されるようになりました。
NETWORKIDLEに到達しないページもインデックスできます。タイムアウトの指定: ページ全体の読み込み時間を制限する
client.navigationTimeoutとclient.renderedStateTimeoutが 追加されました。client.connectionTimeoutとclient.soTimeoutは ソケット単位のタイムアウトであり、ブラウザーには適用されません。
参考情報
クローラー設定:Web、ファイルサーバー、データベースクロール - クローラー基本設定
サムネイル画像の設定 - サムネイル設定
メモリ設定 - メモリ設定
ログ設定 - ログ設定
検索関連の設定 - 高度な検索設定