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 以获取最新开发版本）。

在 Packagist 发布稳定的 14.0 之前：

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+ 会禁用通过 configsets 中的 lib 指令加载 jar 文件。CVE-2025-24814 属于远程代码执行类问题：如果攻击者能够替换或提供 Solr 视为可信的 configset 文件，Solr 可能会从该 configset 加载攻击者控制的 JAR（包括通过 lib 指令加载），从而导致任意代码执行。更严格的默认设置会阻止从 configsets 加载此类 classpath。必须将 solr-typo3-plugin 从 /configsets/ext_solr_*/typo3lib/ 移至 Solr 服务根目录下的 /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 中设置为启动时自动初始化 cores：

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

实用的 DDEV 命令：

命令	说明
ddev solrctl apply	根据配置创建 cores
ddev solrctl wipe	删除所有 cores
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

该镜像为所有语言提供默认 cores。持久化数据存储在 /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 创建 cores。请求负载格式因 Solr 主版本而异（v8 与 v9“v2”API）——请将任何单行 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 cores。根据当前价格页面，Small 方案为 10,00 EUR/月（2 个 Solr 索引，4.000 份文档；网站上注明增值税信息）。创建 core 后，在 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（已加入 gitignore）：

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)"]

三种后端（选择一种）：

后端	是否推荐？	配置方式
Tika Server	是	独立的 Docker 容器，使用最新的 Tika 版本
Solr Cell	可以接受	使用 Solr 内置的 Tika，无需额外服务
Tika App	已弃用	需要在 Web 服务器上安装 Java，请勿使用

需要 EXT:tika 的情况：

• 通过 EXT:solrfal 对文件进行索引（搜索 PDF、Word 文档等内容）
• 自动补充 FAL 元数据（EXIF、XMP、文档属性）
• 检测上传文件的语言

不需要 EXT:tika 的情况：

• 仅通过 Index Queue 对页面和结构化记录（新闻、活动、产品）进行索引
• EXT:solr 可原生处理页面内容和记录字段，无需 Tika

版本： EXT:tika 13.1（当前的 v13 版本）要求 Apache Tika Server/App 3.2.3+。官方 Version Matrix 尚未提供兼容 v14 的 EXT:tika 版本；请关注 Packagist 和 GitHub 上的更新。有关 Apache Tika 和 Solr 的安全公告，请查阅 Apache Solr 安全信息／供应商公告。

完整的文件索引配置请参阅 SKILL-SOLRFAL.md。

详细参考

当任务需要详细示例、较长模板、故障排除矩阵、附录或上文未包含的章节时，请阅读完整指南。对于范围较窄的任务，请勿加载此文件，以便遵循渐进式披露。