コマンドラインからFessを操作する

FessCTLとは

FessCTLは、Fessをコマンドラインから操作できるツールです。通常はFessの管理画面から行う設定・ジョブ実行を、API経由でCLIから実行できます。

主な利用シーンは以下のとおりです。

• 定期的なクロールや設定変更を自動化
• Web UIを利用しないで、設定やジョブ実行
• 複数サイトのクロール設定を一括登録・更新

今回はFessCTLを使って、クロール設定からクロールジョブ実行までの操作を説明します。

FessCTLの利用方法

FessCTLは、Dockerを利用するか、pip installでインストールして利用するか、のどちらかの方法で利用することができます。

Dockerイメージは、ghcr.io/codelibs/fessctl:0.1.0をPullして利用することができます。ビルドして利用する場合は、以下のように、ソースコードを取得してから、docker buildして、Dockerイメージを作成することができます。

git clone https://github.com/codelibs/fessctl.git
cd fessctl
docker build -t fessctl:latest .

アクセストークンの生成

次に、Fessサーバを起動し、APIを利用するためのアクセストークンを生成します。今回は、Fess 15.1.0を利用して説明します。

Fessを起動後、Fessの管理APIを利用するためアクセストークンを作成します。管理画面にログインし、左メニューの「システム」＞「アクセストークン」＞「新規作成」をクリックして以下を入力後、「作成」ボタンをクリックします。

• 名前：任意の名前
• パーミッション：{role}admin-api

生成されたアクセストークンを確認するには、アクセストークンの一覧ページから作成した設定をクリックします。ここで「トークン」の欄に表示されている値を保存しておいてください。

• 

FessCTLの実行

FessCTL実行時は次の変数を指定する必要があります。

• FESS_ENDPOINT: FessサーバーのAPIエンドポイントURL（例：http://localhost:8080）
• FESS_ACCESS_TOKEN: アクセストークン画面で生成した値
• FESS_VERSION: 利用するFessのバージョン（例：15.1.0）

ここでは以下で記載していますが、利用環境に合わせた値に置き換えてください。

• $your_endpoint_url
• $your_access_token
• $your_fess_version

クロール設定

今回は例として https://fess.codelibs.org/ja/をクロールする設定を作成します。

FessCTLのコマンドやオプションは --helpを指定して実行することで確認できます。ウェブクロール設定の作成はfessctl webconfig createです。設定したい項目の名前も--helpで確認することができるので、記事内で書かれていない項目については以下のコマンドを実行して項目名を確認してみてください。

$ docker run --rm \
   -e FESS_ENDPOINT=$your_endpoint_url \
   -e FESS_ACCESS_TOKEN=$your_access_token \
   -e FESS_VERSION=$your_fess_version \
   ghcr.io/codelibs/fessctl:0.1.0 webconfig create --help

今回は以下の項目を設定します。

• 名前
• URL
• クロール対象とするURL
• 最大アクセス数
• 説明

コマンドは以下になります。

$ docker run --rm \
   -e FESS_ENDPOINT=$your_endpoint_url \
   -e FESS_ACCESS_TOKEN=$your_access_token \
   -e FESS_VERSION=$your_fess_version \
   ghcr.io/codelibs/fessctl:0.1.0 webconfig create \
     --name "Fess" \
     --url "https://fess.codelibs.org/ja/" \
     --included-url "https://fess.codelibs.org/ja/.*" \
     --max-access-count 30 \
     --description "Fess Document"

コマンド実行後にcreated successfullyと表示されれば、正常に作成されたことを意味します。

  WebConfig 'mJizp5gBMSiBAIeMhb2d' created successfully.

管理画面で確認すると、新しいWebクロール設定が追加されていることが分かります。指定した項目以外にも値が設定されていますが、これらはデフォルトで設定されたものです。詳しくはwebconfig create --helpのコマンドで確認してください。

• 

クロールジョブの実行

次にジョブを開始してクロールを実行します。まずはジョブIDを確認します。

$ docker run --rm \
   -e FESS_ENDPOINT=$your_endpoint_url \
   -e FESS_ACCESS_TOKEN=$your_access_token \
   -e FESS_VERSION=$your_fess_version \
   ghcr.io/codelibs/fessctl:0.1.0 scheduler list
                                   Schedulers                                   
┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━┓
┃ ID                 ┃ NAME                  ┃ AVAILAB… ┃ TARGET ┃ CRON        ┃
┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━┩
│ default_crawler    │ Default Crawler       │ true     │ all    │ 0 0 * * *   │
│ suggest_indexer    │ Suggest Indexer       │ true     │ all    │ 0 12 * * *  │
│ log_aggregator     │ Log Aggregator        │ true     │ all    │ * * * * *   │
│ log_purger         │ Log Purger            │ true     │ all    │ 0 0 * * *   │
│ doc_purger         │ Doc Purger            │ true     │ all    │ * * * * *   │
│ thumbnail_generate │ Thumbnail Generator   │ true     │ all    │ * * * * *   │
│ thumbnail_purger   │ Thumbnail Purger      │ true     │ all    │ 0 0 * * *   │
│ reload_config      │ Config Reloader       │ true     │ all    │ */10 * * *… │
│ ping_es            │ Search Engine Monitor │ true     │ all    │ * * * * *   │
│ score_booster      │ Score Updater         │ true     │ all    │ 0 * * * *   │
│ label_updater      │ Label Updater         │ true     │ all    │ -           │
└────────────────────┴───────────────────────┴──────────┴────────┴─────────────┘```

表示されたジョブ名の中から、実行したいジョブのIDを指定します。今回はDefault Crawlerを起動するのでdefault_crawlerを指定します。

docker run --rm \
  -e FESS_ENDPOINT=$your_endpoint_url \
  -e FESS_ACCESS_TOKEN=$your_access_token \
  -e FESS_VERSION=$your_fess_version \
  ghcr.io/codelibs/fessctl:0.1.0 scheduler start default_crawler

以下のようなレスポンスが返ってくれば成功です。

  Scheduler 'default_crawler' started successfully.

ジョブの実行状況はジョブログで確認できます。以下はjson形式で表示した結果です。「job_status」が「running」は実行中。「ok」に変わるまでしばらく待ちます。

$ docker run --rm \
    -e FESS_ENDPOINT=$your_endpoint_url \
    -e FESS_ACCESS_TOKEN=$your_access_token \
    -e FESS_VERSION=$your_fess_version \
    ghcr.io/codelibs/fessctl:0.1.0 joblog list -o json
{
  "response": {
    "logs": [
      {
        "crud_mode": 0,
        "id": "mZjLp5gBMSiBAIeMj70f",
        "job_name": "Default Crawler",
        "job_status": "running",
        "target": "all",
        "script_type": "groovy",
        "script_data": "return container.getComponent(\"crawlJob\").logLevel(\"info\").gcLogging().execute(executor);",
        "start_time": "1755161792286"
      },
      {
        "crud_mode": 0,
        "id": "VJgmnpgBMSiBAIeMzr3U",
        "job_name": "Suggest Indexer",
        "job_status": "ok",
        "target": "all",
        "script_type": "groovy",
        "script_data": "return container.getComponent(\"suggestJob\").logLevel(\"info\").sessionId(\"SUGGEST\").execute(executor);",
        "script_result": "Session Id: SUGGEST\n",
        "start_time": "1755000000209",
        "end_time": "1755000009741"
      }
    ],
    "total": 2,
    "version": "15.1",
    "status": 0
  }
}

検索

クロールジョブが終了したら、検索してみましょう。指定したサイトのインデックスが検索できていれば成功です。

• 

*　*　*

FessCTLを導入すれば、管理画面に依存せずに設定やジョブを自動化でき、運用効率の大幅な向上が期待できます。CI/CDパイプラインやスクリプトから直接利用できるため、定常運用の省力化だけでなく、運用の安定性向上にもつながります。今後の運用改善にぜひ取り入れてみてください。