typo3-solr

TYPO3 向け Apache Solr

出典：https://github.com/dirnbauer/webconsulting-skills

互換性： このスキルは TYPO3 v14.x を対象としています。公式バージョンマトリックス と Packagist を確認し、EXT:solr（および Solr サーバーのバージョン）を合わせてください。14.0.x はドキュメントへの反映が遅れる場合があります。安定版タグが公開されるまでは、プロジェクトでドキュメント化されているブランチ／マトリックスを使用してください。 すべてのカスタム PHP の例では、TYPO3 v14 の規約（PHP 8.2 以降、コンストラクターのプロパティ昇格、記載されている場合は #[AsEventListener]）を使用しています。

TYPO3 API を優先： カスタム実装を作成する前に、必ず TYPO3 の組み込み API と EXT:solr の TypoScript／PSR-14 イベントを使用してください。EXT:solr がすでに提供している機能を再実装しないでください。

ソース

このスキルは、以下の信頼できる情報源に基づいています。

1. EXT:solr ドキュメント
2. EXT:tika ドキュメント
3. バージョンマトリックス
4. GitHub：TYPO3-Solr/ext-solr
5. GitHub：main ブランチ（14.0.x-dev）
6. Apache Solr リファレンスガイド
7. Solr の高密度ベクトル検索
8. Solr のテキストからベクトルへの変換（LLM）
9. typo3-solr.com
10. hosted-solr.com
11. ddev-typo3-solr
12. Mittwald Solr ドキュメント
13. helhum/dotenv-connector

1. アーキテクチャの概要

EXT:solr は TYPO3 CMS を Apache Solr 検索サーバーに接続し、全文検索、ファセットナビゲーション、オートコンプリート、さらに有効化されている場合は（対応する Solr 9.x ビルドで）高密度ベクトル／セマンティック機能を提供します。

graph LR
    subgraph typo3 [TYPO3 CMS]
        Editor[Editor creates/edits content]
        Monitor[Monitoring detects changes]
        Queue[Index Queue]
        Scheduler[Scheduler Worker]
        Plugin[Search Plugin]
    end
    subgraph solr [Apache Solr Server]
        Core[Solr Core]
        Schema[Schema / Configset]
    end
    Editor --> Monitor
    Monitor --> Queue
    Queue --> Scheduler
    Scheduler -->|HTTP POST documents| Core
    Plugin -->|HTTP GET query| Core
    Core --> Plugin

ドキュメントのライフサイクル

sequenceDiagram
    participant E as Editor
    participant T as TYPO3
    participant M as Monitor
    participant Q as Index Queue
    participant S as Scheduler
    participant Solr as Solr Server

    E->>T: Create/edit record
    T->>M: DataHandler triggers PSR-14 event
    M->>Q: Add/update queue item
    Note over Q: tx_solr_indexqueue_item
    S->>Q: Poll for pending items
    Q->>S: Return items to index
    S->>Solr: POST document (JSON)
    Solr-->>S: 200 OK
    S->>Q: Mark item as indexed

コンポーネントの概要

コンポーネント	パッケージ	用途	必須？
EXT:solr	apache-solr-for-typo3/solr	コア検索の統合	はい
EXT:tika	apache-solr-for-typo3/tika	ファイルからのテキスト／メタデータ抽出	ファイルのインデックス作成時のみ
EXT:solrfal	資金提供を受けている拡張機能	FAL ファイルの Solr へのインデックス作成	ファイルのインデックス作成時のみ
EXT:solrconsole	資金提供を受けている拡張機能	バックエンド管理コンソール	任意
EXT:solrdebugtools	資金提供を受けている拡張機能	クエリのデバッグ、スコア分析	任意（開発時に推奨）

2. バージョン互換性マトリックス（上流）

このスキルの対象： TYPO3 v14.x と、公式バージョンマトリックスで使用する Core に適合する EXT:solr のリリース行です。古い行はレガシーサイト向けの参考情報のみです。

EXT:solr	TYPO3	Apache Solr	Configset	PHP	EXT:tika	EXT:solrfal
14.0.x（マトリックス／Packagist を参照）	14.x	マトリックスに準拠	使用する場合は ext_solr_14_0_0	^8.2	マトリックスに準拠	マトリックスに準拠
13.1.x	(このコレクションの対象ではありません)	9.10.1	ext_solr_13_1_0	^8.2	13.1	13.0

Packagist に 14.0.x の安定版タグがなく（ベータ版は公開されています）、安定版タグが公開されるまでは、以下の「TYPO3 v14 対応状況」サブセクション（^14.0@beta／ドキュメントのワークフロー）に従ってください。

TYPO3 v14 対応状況

バージョンマトリックスの対象は、**TYPO3 14.3 + EXT:solr 14.0 + Apache Solr 10.0.0 + ext_solr_14_0_0**です（Solr 9.10.1 は EXT:solr 13.1/12.1 に対応します）。アップストリームでの開発はmainで行われています。

• mainではtypo3/cms-core: ^v14.3.0が必要です（mainのcomposer.jsonを参照）
• ブランチエイリアスは**dev-main -> 14.0.x-dev**です
• Composer の現状：14.0.0-beta1～beta3はPackagistで公開されています。安定版の14.0タグはまだ存在しないため、@betaの安定性フラグを使ってインストールしてください（または、最新の開発版を使う場合はdev-mainにフォールバックしてください）。

安定版の14.0がPackagistで公開されるまで：

composer require apache-solr-for-typo3/solr:^14.0@beta

**警告：**アップグレード時にPackagist/GitHubを再確認してください。安定版がリリースされたらすぐに、^14.0@betaから通常の^14.0制約に切り替えてください。

CVE-2025-24814 の移行

Apache Solr 9.8.0以降では、configset内のlibディレクティブを介したjarファイルの読み込みが無効になっています。CVE-2025-24814はリモートコード実行に分類される問題です。Solrが信頼できるものとして扱うconfigsetファイルを攻撃者が置き換えたり提供したりできる場合、Solrはそのconfigsetから攻撃者が制御するJAR（libディレクティブを介したものを含む）を読み込み、任意のコード実行につながるおそれがあります。より厳格なデフォルト設定により、configsetからのクラスパス読み込みがブロックされます。solr-typo3-pluginは、Solrサーバーのルートにある/configsets/ext_solr_*/typo3lib/から/typo3lib/へ移動する必要があります。Dockerユーザーは、移行を自動実行するためにEXT:solrコンテナーイメージ13.0.1以降（TYPO3 Coreではなくイメージタグ）を使用してください。

3. インストールとセットアップ

Composer

composer require apache-solr-for-typo3/solr

DDEV のセットアップ

推奨されるローカル開発環境では、ddev-typo3-solrアドオンを使用します。

ddev add-on get ddev/ddev-typo3-solr
ddev restart

**Solr イメージのバージョン：**DDEV Solr アドオンでは、SOLR_BASE_IMAGEのデフォルトはsolr:9.10で、生成されるcomposeファイルは.ddev/docker-compose.typo3-solr.yamlです。明示的に指定するには、.ddev/.env.typo3-solrで上書きしてください（例：ddev dotenv set .ddev/.env.typo3-solr --solr-base-image="solr:9.10.1"）。その後、Solrサービスを再ビルドします。

.ddev/typo3-solr/config.yamlを設定します。

config: 'vendor/apache-solr-for-typo3/solr/Resources/Private/Solr/solr.xml'
typo3lib: 'vendor/apache-solr-for-typo3/solr/Resources/Private/Solr/typo3lib'
configsets:
  - name: 'ext_solr_14_0_0'
    path: 'vendor/apache-solr-for-typo3/solr/Resources/Private/Solr/configsets/ext_solr_14_0_0'
    cores:
      - name: 'core_en'
        schema: 'english/schema.xml'
      - name: 'core_de'
        schema: 'german/schema.xml'

.ddev/config.yamlで、起動時にコアを自動初期化します。

hooks:
  post-start:
    - exec-host: ddev solrctl apply

便利なDDEVコマンド：

コマンド	説明
ddev solrctl apply	設定からコアを作成します
ddev solrctl wipe	すべてのコアを削除します
ddev exec -s typo3-solr solr --version	Solrサービス内でSolrのバージョンを確認します
ddev launch :8984	Solr Admin UIを開きます
ddev logs -s typo3-solr	Solrログを表示します

Docker（本番環境）

services:
  solr:
    # Note: as of March 2026, no stable 14.0 tag exists on Docker Hub.
    # Use 14.0.x-dev for testing, or 13.1 for production until 14.0 ships.
    image: typo3solr/ext-solr:14.0.x-dev
    ports:
      - "8983:8983"
    volumes:
      - solr-data:/var/solr
    restart: unless-stopped

volumes:
  solr-data:
    driver: local

イメージには、すべての言語用のデフォルトコアが含まれています。永続データは/var/solr（UID 8983が所有）に保存されます。

スタンドアロン Solr

EXT:solrのconfigsetをSolrインストール環境にデプロイします。

cp -r vendor/apache-solr-for-typo3/solr/Resources/Private/Solr/* $SOLR_INSTALL_DIR/server/solr/

core.propertiesファイル、solrctl、またはSolr Admin APIを使ってコアを作成します。ペイロードの形式はSolrのメジャーバージョンによって異なります（v8とv9の「v2」API）。1行のcurlコマンドはあくまで例として扱い、実際に使用するSolrのバージョンに従ってください。

# Illustrative only — confirm against your Solr admin API docs / use bin/solr or ddev solrctl for local setups
curl -sS -X POST "http://localhost:8983/solr/admin/cores?action=CREATE&name=core_en&configSet=ext_solr_14_0_0"

マネージドホスティング：Mittwald

Mittwaldは、コンテナプラットフォームを通じてマネージドSolrサービスを提供しています。Terraformモジュールを使用してください。

module "solr" {
  source         = "mittwald/solr/mittwald"
  solr_version   = "9"
  solr_core_name = "typo3"
  solr_heap      = "2g"
}

コンテナー内ではhttp://typo3-solr:8983でSolrにアクセスします。ローカルでデバッグするには、次のようにします。

mw container port-forward --port 8983

マネージドホスティング：hosted-solr.com

dkdのhosted-solr.comは、EXT:solr向けに最適化された、事前設定済みのSolrコアを提供しています。最新の料金ページによると、Smallプランは月額10,00 EURです（Solrインデックス2個、ドキュメント4.000件。VATに関する注記はサイトを参照）。コアを作成したら、提供されたホスト、ポート、パスを使ってTYPO3サイト設定で構成してください。

TYPO3 サイト設定

config/sites/<identifier>/config.yamlで設定します。

solr_enabled_read: true
solr_host_read: solr
solr_port_read: '8983'
solr_scheme_read: http
solr_path_read: /
solr_core_read: core_en

DDEVの場合は、DDEVのホスト名とHTTPSポートを使用してください。

solr_host_read: <project>.ddev.site
solr_port_read: '8984'
solr_scheme_read: https

環境設定（helhum/dotenv-connector）

Solr の接続情報をハードコードしないでください。環境ごとの設定には helhum/dotenv-connector を使用します。

composer require helhum/dotenv-connector

.env（Git で無視されます）：

SOLR_HOST=solr
SOLR_PORT=8983
SOLR_SCHEME=http
SOLR_PATH=/
SOLR_CORE_EN=core_en
SOLR_CORE_DE=core_de

.env.example（VCS にコミットします）：

SOLR_HOST=solr
SOLR_PORT=8983
SOLR_SCHEME=http
SOLR_PATH=/
SOLR_CORE_EN=core_en
SOLR_CORE_DE=core_de

config/system/additional.php でサイト設定値をプログラムから上書きするか、後処理の方法を使用します。シンプルな構成では、.env の値を維持し、環境ごとのサイト設定 YAML を生成するデプロイスクリプトから参照します。

4. EXT:tika — 必要な場合と不要な場合

EXT:tika は Apache Tika と連携し、1,000 を超えるファイル形式からメタデータの抽出、言語検出、テキスト抽出を行います。

graph TD
    Question{"Do you index files?<br/>(PDF, DOCX, XLSX)"}
    Question -->|Yes| NeedTika[Install EXT:tika + EXT:solrfal]
    Question -->|No| SkipTika[Skip -- EXT:solr handles<br/>pages and records natively]
    NeedTika --> TikaServer["Run Tika Server 3.2.3+<br/>(Docker recommended)"]

3 つのバックエンド（いずれか 1 つを選択）：

バックエンド	推奨？	セットアップ
Tika Server	はい	独立した Docker コンテナで、最新の Tika バージョンを使用します
Solr Cell	可	Solr に組み込まれた Tika を使用するため、追加のサービスは不要です
Tika App	非推奨	Web サーバーに Java が必要なため、使用しないでください

EXT:tika が必要な場合：

• EXT:solrfal によるファイルのインデックス作成（PDF、Word 文書などの内部を検索）
• FAL メタデータの自動拡充（EXIF、XMP、文書プロパティ）
• アップロードしたファイルの言語検出

必要ない場合：

• Index Queue を介してページと構造化レコード（ニュース、イベント、製品）のみをインデックス化する場合
• EXT:solr は Tika を使わずにページコンテンツとレコードフィールドをネイティブに処理します

バージョン： EXT:tika 13.1（現行の v13 リリース）には Apache Tika Server/App 3.2.3+ が必要です。v14 対応の EXT:tika は、公式の Version Matrix ではまだ提供されていません。更新情報は Packagist と GitHub で確認してください。Apache Tika と Solr のセキュリティ勧告については、Apache Solr のセキュリティ情報およびベンダーの勧告で確認してください。

ファイルのインデックス作成を完全に設定するには、SKILL-SOLRFAL.md を参照してください。

詳細リファレンス

詳細な例、長いテンプレート、トラブルシューティング用の一覧表、付録、または上記に含まれていないセクションが必要な場合は、完全ガイドをお読みください。限定的なタスクでは、このファイルを読み込まず、段階的開示に従ってスキルを利用してください。