# 适用于 TYPO3 的 Apache Solr > **兼容性：** TYPO3 v13.4 LTS（当前）和 v14.x（当 EXT:solr 14.0 发布时）。 EXT：solr 13.1 目标为 TYPO3 13.4。 “task/14LTS_compatibility”开发分支正在积极开发中。本技能中的所有自定义 PHP 代码都使用 TYPO3 v14 约定（PHP 8.2+、`#[AsEventListener]`、构造函数提升）。 > **TYPO3 API First：** 在创建自定义实现之前，始终使用 TYPO3 的内置 API 和 EXT:solr 的 TypoScript/PSR-14 事件。不要重新发明 EXT:solr 已经提供的功能。 ## 来源该技能基于以下权威来源： 1. [EXT:solr 文档]() 2. [EXT:tika 文档]() 3. [版本矩阵]() 4. [GitHub：TYPO3-Solr/ext-solr]() 5. [GitHub：v14 开发分支]() 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.8 起）矢量/语义搜索。图LR 子图typo3 [TYPO3 CMS] 编辑者[编辑者创建/编辑内容] 监控[监控检测变化] 队列[索引队列] 调度器[调度工作者] 插件[搜索插件] 结束子图 solr [Apache Solr 服务器] 核心[Solr核心] 架构[架构/配置集] 结束编辑器 --> 监视器监控-->队列队列 --> 调度程序调度程序-->|HTTP POST 文档|核心插件 -->|HTTP GET 查询|核心核心 --> 插件 ### 文档生命周期序列图参与者 E 作为编辑参与者 T 为 TYPO3 参与者M作为监控者参与者 Q 作为索引队列参与者S作为调度者参与者 Solr 作为 Solr 服务器 E->>T：创建/编辑记录 T->>M：DataHandler 触发 PSR-14 事件 M->>Q：添加/更新队列项关于问题的注释：tx_solr_indexqueue_item S->>Q：对待处理项目进行民意调查 Q->>S：将项目返回到索引 S->>Solr：POST 文档（JSON） Solr-->>S：200 好 S->>Q：将项目标记为已索引 ### 组件概述组件|套餐 |目的|必需的？ ---|---|---|--- **外部：solr** | `apache-solr-for-typo3/solr` |核心搜索集成 |是的 **外部：蒂卡** | `apache-solr-for-typo3/tika` |从文件中提取文本/元数据 |仅用于文件索引 **EXT：solrfal** |资金延期 | FAL 文件索引到 Solr |仅用于文件索引 **外部：solrconsole** |资金延期 |后台管理控制台 |可选 **EXT：solrdebugtools** |资金延期 |查询调试、评分分析 |可选（推荐用于开发） ## 2\.版本兼容性矩阵延伸：solr |打字3 |阿帕奇·索尔 |配置集| PHP |延伸：提卡 | EXT：索尔法尔 ---|---|---|---|---|---|--- **13.1** | **13.4** | **9.10.1** | `ext_solr_13_1_0` | 8.2 - 8.4 | 8.2 - 8.4 13.1 | 13.1 13.0 12.1 | 12.1 12.4 | 12.4 9.10.1 | `ext_solr_12_1_0` | 8.1 - 8.3 | 8.1 - 8.3 12.1 | 12.1 12.0 ### TYPO3 v14 准备情况 EXT：solr **还**尚未发布稳定的 v14 版本。活跃的开发发生在 [`task/14LTS_compatibility`]() 分支上（最后更新于 2026 年 2 月 17 日）。 **开发分支中的 v14 关键更改：** * Fluid v5 ViewHelper 兼容性 * TSFE 删除：`FrontendEnvironment/Tsfe` 重构为 `FrontendSimulation/FrontendAwareEnvironment` * 删除了 `ext_emconf.php`（仅限 Composer） * 已处理 TCA `searchFields` 弃用 * 通过 `registerPlugin()` 而不是 `addPiFlexFormValue()` 注册 FlexForm * 新配置集：`ext_solr_14_0_0` **使用开发分支进行测试：** 作曲家需要 apache-solr-for-typo3/solr:dev-task/14LTS_compatibility > **警告：** 该分支尚未完成。不要在生产中使用。 ### CVE-2025-24814 迁移 Apache Solr 9.8.0+ 禁止通过配置集中的“lib”指令加载“jar”文件。必须将“solr-typo3-plugin”从 Solr 服务器根目录下的“/configsets/ext_solr_*/typo3lib/”移动到“/typo3lib/”。 Docker 用户：pull 镜像 v13.0.1+——迁移自动运行。 ## 3\.安装与设置 ### 作曲家作曲家需要 apache-solr-for-typo3/solr ### DDEV 设置推荐的本地开发设置使用 [ddev-typo3-solr]() 插件： ddev 插件获取 ddev/ddev-typo3-solr ddev 重新启动配置`.ddev/typo3-solr/config.yaml`：配置：'vendor/apache-solr-for-typo3/solr/Resources/Private/Solr/solr.xml' typo3lib：'供应商/apache-solr-for-typo3/solr/资源/私人/Solr/typo3lib' 配置集： - 名称：'ext_solr_13_1_0' 路径：'供应商/apache-solr-for-typo3/solr/Resources/Private/Solr/configsets/ext_solr_13_1_0' 核心： - 名称：'core_en' 架构：'english/schema.xml' - 名称：'core_de' 架构：“德语/schema.xml” 在`.ddev/config.yaml`中启动时自动初始化核心：挂钩：启动后： - 执行主机：ddev solrctl 应用 **有用的 DDEV 命令：** 命令 |描述 ---|--- `ddev solrctl 应用` |从配置创建核心 `ddev solrctl 擦除` |删除所有核心 `ddev solr 版本` |检查 Solr 版本 `ddev 启动：8984` |打开 Solr 管理 UI `ddev 日志 -stypo3-solr` |查看Solr日志 ### Docker（生产）服务：索尔：图片：typo3solr/ext-solr：13.1 端口： - “8983:8983” 卷： - solr 数据：/var/solr 重新启动：除非停止卷： solr 数据：司机：本地该映像附带了所有语言的默认核心。持久数据存储在“/var/solr”（由 UID 8983 拥有）。 ### 独立 Solr 将配置集从 EXT:solr 部署到您的 Solr 安装中： cp -r 供应商/apache-solr-for-typo3/solr/资源/私人/Solr/* $SOLR_INSTALL_DIR/server/solr/ 通过“core.properties”文件或 REST API 创建核心： curl -X POST http://localhost:8983/api/cores -H '内容类型：application/json' -d '{ “创建”：{ “名称”：“core_en”， “configSet”：“ext_solr_13_1_0”， "schema": "english/schema.xml", "instanceDir": "核心/core_en", “dataDir”：“/var/solr/data/core_en” } }' ### 托管托管：Mittwald Miittwald 通过其容器平台提供托管 Solr 服务。使用 Terraform 模块：模块“solr”{ 来源=“米特瓦尔德/solr/米特瓦尔德” solr_版本=“9” solr_core_name =“typo3” solr_heap =“2g” } 通过容器内的“http://solr:8983”访问 Solr。对于本地调试： MW集装箱端口转发--端口8983 ### 托管：hosted-solr.com dkd 的 [hosted-solr.com]() 提供针对 EXT:solr 优化的预配置 Solr 核心。计划起价为 10 欧元/月（2 个索引，4000 个文档）。创建核心后，使用提供的主机、端口和路径在 TYPO3 站点配置中对其进行配置。 ### TYPO3 站点配置在 `config/sites//config.yaml` 中： solr_enabled_read：真 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: <项目>.ddev.site solr_port_read: '8984' solr_scheme_read：https ### 环境配置 (helhum/dotenv-connector) 切勿对 Solr 连接详细信息进行硬编码。使用 [helhum/dotenv-connector]() 进行每个环境配置：作曲家需要 helhum/dotenv-connector `.env`（gitignored）： 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，用于从约 1200 种文件格式中提取元数据、语言检测和文本提取。图解TD 问题{“您索引文件吗？
（PDF、DOCX、XLSX）”} 问题-->|是| NeedTika[安装 EXT:tika + EXT:solrfal] 问题-->|否| SkipTika[跳过 -- EXT:solr 本地处理
页面和记录] NeedTika --> TikaServer["运行 Tika Server 3.2.2+
(推荐使用 Docker)"] **三个后端（选择一个）：** 后端|受到推崇的？ |设置 ---|---|--- **蒂卡服务器** |是的 |独立 Docker 容器，最新 Tika 版本 **Solr Cell** |可以接受|使用 Solr 内置的 Tika，无需额外服务 **蒂卡应用程序** |已弃用 |需要在网络服务器上使用 Java，请勿使用 **当您需要分机时：tika：** * 通过 EXT:solrfal 进行文件索引（在 PDF、Word 文档等内部搜索） * 自动 FAL 元数据丰富（EXIF、XMP、文档属性） * 上传文件的语言检测 **当你不需要它时：** * 仅通过索引队列索引页面和结构化记录（新闻、事件、产品） * EXT:solr 原生处理页面内容和记录字段，无需 Tika **版本：** EXT：tika 13.1。需要 Tika 服务器 **3.2.2+**（CVE-2025-54988 修复）。有关完整的文件索引设置，请参阅 [SKILL-SOLRFAL.md]()。 ## 5\.配置集和架构配置集定义 Solr 如何处理和索引文本。 EXT：solr 在“Resources/Private/Solr/configsets/ext_solr_13_1_0/”处提供配置集。 ### 结构 ext_solr_13_1_0/ ├── 会议/ │ ├── solrconfig.xml │ ├── 英语/ │ │ └── schema.xml │ ├── 德语/ │ │ └── schema.xml │ └── ...（其他语言） └──typo3lib/ # 自 Solr 9.8 起移至服务器根目录每种语言都有自己的“schema.xml”以及特定于语言的分析器（词干分析器、停用词）。 ### 动态字段类型使用动态字段后缀添加自定义字段而不修改架构：后缀 |类型 |多|示例 ---|---|---|--- `_stringS` |字符串（未分析）|没有 | `category_stringS` `_stringM` |字符串（未分析）|是的 | `tags_stringM` `_textS` |文本（分析）|没有 | `描述文本S` `_textM` |文本（分析）|是的 | `keywords_textM` `_intS` |整数 |没有 | `year_intS` `_floatS` |浮动|没有 | `price_floatS` `_dateS` |日期 |没有 | `发布日期S` `_boolS` |布尔 |没有 | `active_boolS` 完整参考：[动态字段附录]() ### 网站哈希策略自 EXT:solr 13.0 起，默认站点哈希策略从 **基于域**（已弃用）更改为 **基于站点标识符**。在扩展设置中配置： * `siteHashStrategy = 1`（站点标识符，**默认和推荐**） * `siteHashStrategy = 0`（域，已弃用，在 13.1.x+ 中删除）如果从 12.x 升级，切换策略后必须重新索引。 ## 6\.索引队列配置索引队列是将 TYPO3 记录获取到 Solr 的中心机制。图LR 子图监控【记录监控】编辑[已创建/编辑的记录] 事件[PSR-14数据更新事件] 结束子图队列【索引队列】项目[“tx_solr_indexqueue_item”] 结束子图处理[处理] Worker[调度器：索引队列Worker] Solr[Solr服务器] 结束编辑-->事件事件 --> 项目工人-->|民意调查|项目工人-->|POST文档|索尔 ### 页数页面索引是开箱即用的。无需额外配置。页面索引器将渲染的页面内容发送到 Solr。 ### 自定义记录通过 TypoScript 对任何 TYPO3 记录表建立索引。 EXT:news 的完整示例：插件.tx_solr.index.queue { 新闻 = 1 新闻{ 类型 = tx_news_domain_model_news 字段{ 摘要=预告片作者=作者作者电子邮件字符串S = 作者电子邮件标题=标题内容 = SOLR_CONTENT 内容{ c对象 = COA c对象{ 10 = 文本 10 { 字段 = 正文不修剪包裹 = || | } } } 类别_字符串M = SOLR_RELATION 类别_字符串M { 本地字段 = 类别多值 = 1 } 关键字 = SOLR_MULTIVALUE 关键词{ 字段=关键字 } Tags_stringM = SOLR_RELATION 标签_字符串M { 本地字段 = 标签多值 = 1 } 网址=文本网址{ typolink.parameter = {$plugin.tx_news.settings.detailPid} typolink.additionalParams = &tx_news_pi1[controller]=新闻&tx_news_pi1[action]=detail&tx_news_pi1[news]={field:uid} typelink.additionalParams.insertData = 1 打字链接.returnLast = url } } 附件{ 字段=相关文件 } } } ### 内容对象对象|目的 ---|--- `SOLR_内容` |从字段内容中去除 HTML/RTE `SOLR_RELATION` |解析关系（类别、标签等），支持 `multiValue = 1` `SOLR_MULTIVALUE` |将逗号分隔的字段拆分为多个值 ### Siteroot 之外的记录要对存储在站点树外部的 sysfolder 中的记录建立索引：插件.tx_solr.index.queue.news { 附加页面 ID = 45,48 } 在扩展设置中启用监控：“启用对 siteroot 之外的记录的跟踪”。 ### 监控 EXT：solr 通过 PSR-14 事件检测记录更改。两种模式： * **立即**（默认）：在 DataHandler 操作期间直接处理更改 * **延迟** ：更改在 `tx_solr_eventqueue_item` 中排队并由调度程序任务（“事件队列工作线程”）处理通过扩展设置进行配置：“monitoringType”。 ## 7\.搜索配置 ### 基本设置插件.tx_solr { 启用 = 1 搜索{ 目标页 = 42 初始化WithEmptyQuery = 1 显示初始空查询结果 = 0 可信字段 = url keepExistingParametersForNewSearches = 1 } } ### 刻面插件.tx_solr.search { 刻面 = 1 刻面{ 刻面{ 内容类型{ 标签=内容类型字段=类型 } 类别{ 标签=类别字段=类别_字符串M } 年{ 标签=年份字段=year_intS 类型 = 查询组查询组{ 2026 { 查询 = [2026-01-01T00:00:00Z 至 2026-12-31T23:59:59Z] } 2025 { 查询 = [2025-01-01T00:00:00Z 至 2025-12-31T23:59:59Z] } 2024 { 查询 = [2024-01-01T00:00:00Z 至 2024-12-31T23:59:59Z] } } } } } } **方面类型：** `options` （默认）、`queryGroup`、`hierarchy`、`dateRange`、`numericRange`。 ### 建议/自动完成插件.tx_solr { 建议=1 建议{ 建议数量 = 10 suggestField = 拼写显示热门结果 = 1 顶部结果数 = 5 其他TopResultsFields = url,类型 } } 内置建议使用 devbridge/jQuery-Autocomplete 库。对于无 jQuery 的方法，请参阅 [SKILL-FRONTEND.md]()。 ### 排序、突出显示、拼写检查插件.tx_solr.search { 排序 = 1 排序{ 默认顺序 = asc 选项{ 相关性{ 领域=相关性标签=相关性 } 标题{ 字段 = 排序标题标签=标题 } 创建了{ 字段=已创建标签 = 日期 } } } 结果{ 结果突出显示 = 1 结果突出显示 { 片段大小 = 200 换行 = <标记>| } } 拼写检查 = 1 } ### 路由增强器 SEO 友好的搜索 URL：路线增强器： Solr搜索：类型：SolrFacetMaskAndCombineEnhancer 扩展键：solr 索尔：类型：扩展库扩展：Solr 插件：pi_结果路线： - 路线路径：'/search/{q}' _controller: '搜索::结果' _参数：问：问 ## 8\.流体模板和前端 ### 模板路径插件.tx_solr { 查看{ templateRootPaths.10 = EXT:my_ext/Resources/Private/Templates/Solr/ partialRootPaths.10 = EXT:my_ext/Resources/Private/Partials/Solr/ layoutRootPaths.10 = EXT:my_ext/Resources/Private/Layouts/Solr/ } } ### 关键模板模板|目的 ---|--- `模板/搜索/Results.html` |主搜索结果页面 `模板/搜索/Form.html` |搜索表格 `Partials/Result/Document.html` |单个结果项 `Partials/Facets/OptionsFacet.html` |选项构面渲染 `Partials/Facets/QueryGroupFacet.html` |查询组方面将默认模板从 EXT:solr 复制到您的扩展路径并修改它们。 ## 9\. PSR-14 事件参考 ### 监控事件活动 |被解雇时 ---|--- `VersionSwappedEvent` |版本已交换（工作区发布） `记录移动事件` |一条记录被移动 `RecordGarbageCheckEvent` |触发垃圾检查 `记录删除事件` |一条记录被删除 `PageMovedEvent` |页面已移动 `ContentElementDeletedEvent` |内容元素被删除 ### 数据更新处理事件活动 |被解雇时 ---|--- `处理完成事件` |数据更新处理完成 `DelayedProcessingQueuingFinishedEvent` |更新在事件队列中排队（延迟模式） `DelayedProcessingFinishedEvent` |延迟处理完成（调度程序） ### 索引事件活动 |被解雇时 ---|--- `BeforePageDocumentIsProcessedForIndexingEvent` |处理页面文档之前（添加额外文档） `AfterPageDocumentIsCreatedForIndexingEvent` |创建页面文档后（替换/替换） `BeforeDocumentIsProcessedForIndexingEvent` |在处理非页面记录文档之前 `BeforeDocumentsAreIndexedEvent` |在将文档发送到 Solr 之前（添加自定义字段） ### 其他活动活动 |被解雇时 ---|--- `AfterFacetIsParsedEvent` | Facet组件修改 `AfterUriIsProcessedEvent` |在搜索上下文中构建 URI `AfterSiteHashHasBeenDeterminedForSiteEvent` |覆盖计算的站点哈希值 ### 示例：向文档添加自定义字段（v14 样式） getDocuments() as $document) { $document->addField('custom_score_floatS', $this->calculateScore($document)); } } 私有函数calculateScore(\ApacheSolrForTypo3\Solr\System\Solr\Document\Document $document): float { 返回匹配 ($document->getField('type')['value'] ?? '') { '页面' => 1.0, 'tx_news_domain_model_news' => 0.8, 默认=> 0.5， }; } } **v13 后备**（如果 `#[AsEventListener]` 不可用）：在 `Services.yaml` 中注册： MyVendor\MyExt\EventListener\EnrichSolrDocuments：标签： - 名称：事件监听器标识符：'my-ext/enrich-solr-documents' ## 10\.独立索引器（自定义数据）对于外部数据或 RecordIndexer 不够用时： siteRepository->getSiteByRootPageId($rootPageId); $connection = $this->connectionManager->getConnectionByPageId($rootPageId, $language); $文档= []; foreach ($rows 作为 $row) { $文档 = 新文档(); $document->setField('id', 'external_' . $row['uid']); $document->setField('variantId', 'external_' . $row['uid']); $document->setField('type', 'external_record'); $document->setField('appKey', 'EXT:solr'); $document->setField('access', ['r:0']); $document->setField('site', $site->getDomain()); $document->setField('siteHash', $site->getSiteHash()); $document->setField('uid', $row['uid']); $document->setField('pid', $rootPageId); $document->setField('标题', $row['标题']); $document->setField('内容', $row['内容']); $document->setField('url', $row['url']); $文档[] = $文档； } $connection->getWriteService()->addDocuments($documents); } 公共函数clearIndex(string $type = 'external_record'): void { $connections = $this->connectionManager->getAllConnections(); foreach ($connections 作为 $connection) { $connection->getWriteService()->deleteByType($type); } } } ### CLI 命令包装器 fetchExternalData(); $io->info(sprintf('索引 %d 条记录...', count($rows))); $this->索引器->索引($rows); $io->success('完成。'); 返回命令::成功； } 私有函数 fetchExternalData(): 数组 { // 实现数据获取逻辑返回[]； } } ## 11\. LLM 和矢量搜索（Solr 服务器本机） Apache Solr 9.8+ 包含用于语义/向量搜索的本机 LLM 模块。这在 **Solr 服务器端** \-- EXT:solr 查询结果。图LR 子图索引[索引时间] 文本[文档文本] URP["TextToVectorUpdateProcessor"] API1["嵌入API
(OpenAI、Mistral等)"] Vector1[密集向量] SolrIdx["Solr 索引
(DenseVectorField)"] 结束子图查询【查询时间】查询[用户查询文本] QP["knn_text_to_vector 解析器"] API2[“嵌入API”] Vector2[查询向量] KNN["KNN 搜索"] 结果[排名结果] 结束文本 --> URP --> API1 --> Vector1 --> SolrIdx 查询 --> QP --> API2 --> Vector2 --> KNN --> 结果 SolrIdx -.->|相似性|克尼恩 ### 先决条件 * Apache Solr **9.8+** 启用了“llm”模块 * 外部嵌入 API 帐户（OpenAI、Mistral AI、Cohere 或 HuggingFace） ### 架构：DenseVectorField 添加到您的架构（或使用自定义配置集）： <字段名称=“向量”类型=“knn_vector”索引=“true”存储=“true”/> `vectorDimension` 必须与您的嵌入模型匹配（例如，OpenAI `text-embedding-3-small` = 1536 维）。 ### 模型配置在`solrconfig.xml`中注册查询解析器：上传模型定义：卷曲-XPUT 'http://localhost:8983/solr/core_en/schema/text-to-vector-model-store' \ --data-binary @model.json -H '内容类型：application/json' `model.json`（OpenAI 示例）： { "class": "dev.langchain4j.model.openai.OpenAiEmbeddingModel", “名称”：“openai-嵌入”， “参数”：{ "baseUrl": "https://api.openai.com/v1", "apiKey": "sk-...", "modelName": "text-embedding-3-small", “超时”：60， “最大重试次数”：3 } } 支持的提供商：OpenAI、Mistral AI、Cohere、HuggingFace。有关所有参数，请参阅 [LangChain4j 嵌入模型]()。 ### 用向量索引在`solrconfig.xml`中添加更新处理器链： <处理器类=“solr.llm.textvectorization.update.processor.TextToVectorUpdateProcessorFactory”> _text_ 矢量 openai-embed **双通道策略**（建议用于生产）：首先正常索引文档，然后在第二通道中使用向量进行丰富，以避免因缓慢的 API 调用而阻塞索引管道。 ### 查询 **语义搜索**（文本输入，矢量输出）： ?q={!knn_text_to_vector model=openai-embed f=vector topK=10}客户投诉处理 **原始向量搜索：** ?q={!knn f=向量 topK=10}[0.1, 0.2, 0.3, ...] **阈值搜索**（相似度以上的所有文档）： ?q={!向量相似度 f=向量 minReturn=0.7}[0.1, 0.2, 0.3, ...] **混合搜索**（BM25 + 向量重新排序）： ?q=客户投诉 &rq={!rerank reRankQuery=$rqq reRankDocs=50 reRankWeight=2} &rqq={!knn_text_to_vector model=openai-embed f=vector topK=50}客户投诉 ### 预过滤将矢量搜索与传统过滤器相结合： ?q={!knn_text_to_vector model=openai-embed f=vector topK=10 preFilter=type:pages}搜索查询 ### EXT：solr 集成 EXT：solr 13.1 具有初始向量搜索支持。对于自定义集成，请在“BeforeDocumentsAreIndexedEvent”上使用 PSR-14 事件侦听器，通过您自己的嵌入服务调用将矢量数据添加到文档中。 > **注意：** EXT:solr 中的完整原生矢量搜索支持（索引队列 -> 矢量字段、矢量结果的流体模板）仍在不断发展。监视 [GitHub 存储库]() 的更新。 ### 用例使用案例|方法 ---|--- **智能站点搜索** | `knn_text_to_vector` 查找语义相似的内容 **类似内容** |给定文档向量，找到 K 个最近邻 **多语言桥梁** |嵌入可以跨语言匹配 **常见问题匹配** |尽管措辞不同，但将用户问题与常见问题解答相匹配 **RAG 准备** |使用 Solr 作为 LLM 支持的问答的检索层 **文件发现** |结合solrfal + Tika：对文档进行语义搜索 ## 12\.调试与故障排除本节是诊断和修复 EXT:solr 问题的核心参考。如果您是 EXT:solr 的新手，请从下面的分步指南开始，然后再跳转到参考部分。 ### 分步故障排除指南（初学者）如果搜索不起作用并且您**不知道从哪里开始**，请按顺序执行以下步骤。每个步骤都解释了您要检查的**内容**、**在哪里**找到它以及**结果意味着什么**。 ** ** #### 第 1 步：了解架构在调试之前，先了解 EXT:solr 的工作原理。 **四个部分**必须全部工作： ┌──────────────────┐ ┐──────────────┐ ┌──────────────┐ ┌──────────────┐ │ 1. 连接 │────▶│ 2. 索引 │────▶│ 3. Solr Core │────▶│ 4. 前端 │ │ TYPO3 ↔ Solr │ │ Queue+Worker │ │ 文档 │ │ Search+Fluid │ └──────────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ * **连接** ：TYPO3 必须知道 Solr 在哪里运行（主机、端口、核心名称） * **索引** ：TYPO3 必须通过索引队列和调度程序任务将您的内容（页面、新闻等）发送到 Solr * **Solr Core** ：Solr 服务器存储文档并使其可搜索 * **Frontend** ：搜索插件将查询发送到 Solr 并通过 Fluid 模板呈现结果这四个部分中的任何一个出现问题都会中断搜索。以下步骤从左到右检查每个部分。 ** ** #### 步骤 2：Solr 是否可达？（连接检查） **位置：** TYPO3 后端 → 管理工具 → 报告 → 状态报告 **您看到的内容：** 状态检查列表。查找有关“Solr”的条目： * **全绿色** ✅ = Solr 可达，连接正常 → 转到步骤 3 * **红色/黄色** ⚠️ = Solr 无法访问 → 首先修复连接 **如果是红色——需要检查的事项：** 打开站点配置文件 `config/sites//config.yaml` 并验证这些设置： solr_enabled_read：真 solr_host_read: solr # Solr 运行的主机名 solr_port_read: '8983' # 端口（独立端口为 8983，DDEV 为 8984） solr_scheme_read: http # http 或 https（DDEV 使用 https） solr_path_read: / # 通常只是 / solr_core_read: core_en # 必须与 Solr 中的实际核心名称匹配 **对于 DDEV 用户：** solr_host_read：<您的项目>.ddev.site solr_port_read: '8984' solr_scheme_read：https **从终端快速测试：** # DDEV：测试 Solr 是否响应 ddev 执行curl -s http://solr:8983/solr/core_en/admin/ping # 预期：{"status":"OK"} # 如果“连接被拒绝”：Solr 容器未运行 → ddev restart **修复后：** 始终单击 EXT:solr 后端模块中的“初始化连接”（Web → 搜索 → 概述选项卡）。 ** ** #### 步骤 3：内容在索引队列中吗？（索引检查） **位置：** TYPO3 后端 → Web → 搜索 → “索引队列”选项卡 **您看到的内容：** 显示记录类型（页面、新闻等）和计数的表格。你所看到的|这意味着什么 |该怎么办 ---|---|--- **表是空的** | Solr 尚未排队任何内容 |您需要初始化队列（见下文） **计数 > 0 的项目，错误 = 0** |内容已排队并建立索引 |转到步骤 4 **错误数 > 0** |某些记录索引失败 |阅读错误消息（见下文） **如果队列为空：** 1. 检查根页面中是否包含 EXT:solr TypoScript 模板： * 后端 → Web → 模板模块 → 根页面 → “包含”选项卡 * 您必须在列表中看到“搜索 - 基本配置” * 如果缺少，请添加它：单击“包含静态（来自扩展）”并选择“搜索 - 基本配置 (solr)” 2.初始化队列： * 转到网页→搜索→“索引队列”选项卡 * 选择要索引的记录类型的复选框（例如“页面”） * 单击“将所选内容放入队列” * 表格现在应该显示计数 **如果项目有错误：** “错误”列告诉您出了什么问题。常见错误：错误信息 |这意味着什么 |修复 ---|---|--- “无法解析主机” | Solr 服务器无法访问 |返回步骤 2 “文档缺少强制 uniqueKey 字段：id”|该文档没有 ID |检查您的 TypoScript 字段映射 “内存不足错误”| PHP 或 Solr 内存不足 |增加调度程序的“内存限制” “HTTP 404”| Solr 核心不存在 |检查核心名称，运行“ddev solrctl apply” ** ** #### 步骤 4：文档是否已到达 Solr？（Solr 检查）即使队列没有显示错误，文档也可能尚未发送到 Solr。队列仅填充待办事项列表——**调度程序任务**实际上发送它们。 **检查Scheduler任务是否存在：** * 后端→系统→调度程序 * 查找名为“Index Queue Worker”的任务（类：`ApacheSolrForTypo3\Solr\Task\IndexQueueWorkerTask`） * 如果不存在：创建它（添加任务→选择“Index Queue Worker”→保存） * 如果存在：检查“上次执行”——最近是否运行过？ **现在手动运行它：** * 单击 Index Queue Worker 任务旁边的“播放”按钮 **验证文档是否在 Solr 中：** 打开 Solr 管理用户界面： * DDEV：运行 `ddev launch :8984` （在浏览器中打开） * 生产：导航到“http://your-solr-host:8983/solr/” 在 Solr 管理界面中： 1. 从下拉列表中选择您的核心（例如“core_en”） 2.点击左侧菜单“查询” 3. 将 `q` 保留为 `*:*` （表示“所有文档”） 4. 点击“执行查询” 5. 检查响应中的“numFound”：发现数量 |这意味着什么 |该怎么办 ---|---|--- **0** |根本没有文件 |调度程序任务未运行，或索引无提示地失败 → 启用日志记录（请参阅下面的 12.0 第 2 层） **> 0** | Solr 中存在文档 |转到步骤 5 **在 Solr Admin 中运行的有用查询：** # 每种类型有多少个文档？ q=*:*&rows=0&facet=true&facet.field=type # 显示 5 页文档及其关键字段 q=*:*&fq=类型:页数&行=5&fl=uid,标题,url,siteHash # 搜索特定术语 q=您的搜索词&fl=uid,标题,分数 ** ** #### 步骤 5：前端是否显示结果？（前端检查） **其中：** 打开前端带有搜索插件的页面，输入您知道 Solr 中存在的搜索词。你所看到的|这意味着什么 |该怎么办 ---|---|--- **“搜索当前不可用”** |插件无法连接到 Solr |返回第2步——前端的连接问题 **搜索有效，但 0 个结果** |查询运行但未找到任何内容 |检查站点哈希、访问字段（见下文） **结果出现但错误** |找到文件，但内容/顺序错误 |检查字段映射、提升（见下文） **结果显示正确** ✅ |一切正常！ |完成 **如果 0 结果，即使 Solr 有文档：** 最常见的原因是**站点哈希不匹配**。 EXT：solr为每个文档添加一个`siteHash`以防止跨站污染。如果索引期间的哈希值与搜索期间的哈希值不同，则不会显示任何结果。检查 Solr 管理： # 索引中存在哪些 siteHash 值？ q=*:*&rows=0&facet=true&facet.field=siteHash 与 EXT:solr 期望的进行比较：打开扩展设置（管理工具 → 设置 → 扩展配置 → solr）并选中 `siteHashStrategy`。从 EXT:solr 13.0 开始，默认值为 **site-identifier** （不是域）。如果哈希值不匹配：**重新索引**（后端 → Web → 搜索 → 索引队列 → 清除并重新排队所有）。 **导致 0 个结果的其他原因：** * `plugin.tx_solr.search.targetPage`指向错误的页面→将其设置为包含搜索插件的页面UID * TypoScript 中某处 `plugin.tx_solr.enabled` 为 `0` → 检查覆盖 * 访问限制：文档上的“access”字段与前端用户不匹配 → 在 Solr Admin 中使用“q=*:*&fl=uid,title,access”进行测试 ** ** #### 第 6 步：其他问题 - 启用日志记录如果上述步骤没有解决问题，**启用日志记录**以查看 EXT:solr 的具体作用： **1\.添加 TypoScript 日志记录**（仅在根页面上，仅用于开发/登台）：插件.tx_solr.logging { 调试输出 = 1 例外 = 1 索引 = 1 查询.rawGet = 1 查询.queryString = 1 查询.searchWords = 1 } **2\.将日志写入文件**（在`config/system/additional.php`中）： $GLOBALS['TYPO3_CONF_VARS']['LOG']['ApacheSolrForTypo3']['Solr']['writerConfiguration'] = [ \Psr\Log\LogLevel::DEBUG => [ \TYPO3\CMS\Core\Log\Writer\FileWriter::class => [ 'logFile' => \TYPO3\CMS\Core\Core\Environment::getVarPath() 。 '/log/solr.log', ], ], ]; **3\.观看日志文件：** # DDEV ddev exec tail -f var/log/solr.log # 然后触发操作：运行调度程序，或者在前端进行搜索 **在日志中查找什么：** * `[ERROR]` 行 → 这些行准确地告诉您失败的原因 * `Solr raw GET: http://...` → 发送到 Solr 的确切 URL（将其粘贴到浏览器中进行测试） * `响应：0 个结果` → Solr 回答但什么也没找到（站点哈希？访问？错误的字段？） **4\.另请检查：** 管理工具 → 日志模块（按组件“ApacheSolrForTypo3”过滤） ** ** #### 第 7 步：仍然卡住？升级路径如果以上六个步骤都不能解决问题： 1. **在 Slack 中询问：** [TYPO3 Slack #ext-solr]() \-- 维护者 (dkd) 在此活跃 2. **搜索 GitHub 问题：** [TYPO3-Solr/ext-solr/issues]() \-- 您的问题可能已经被报告 3. **dkd支持：** [专业支持]() \--来自扩展维护者的付费支持 4. **收集错误报告信息：** Solr 版本、EXT:solr 版本、PHP 版本、TYPO3 版本、日志中的错误消息、Solr Admin 查询结果 ** ** ### 12.0 如何获取调试数据在修复任何问题之前，您需要**查看** EXT:solr 正在做什么。调试数据共有六层，从快速检查到深度检查：图解TD subgraph fast [“1.快速检查（无需配置）”] 报告[“TYPO3 报告模块”] 后端[“EXT：solr后端模块”] SolrUI["Solr 管理用户界面"] 结束 subgraph config ["2.启用调试输出"] TSLog["TypoScript 日志记录。*"] FileLog["FileWriter → var/log/solr.log"] 调试工具[“EXT：solrdebugtools”] 结束子图深度[“3.深度检查”] SolrDebug["Solr debugQuery=true"] DB["tx_solr_* 表上的 SQL"] CLI["CLI 卷曲到 Solr API"] 结束报告 --> TSLog 后端 --> TSLog SolrUI --> Solr调试 TSLog --> 文件日志文件日志 --> 数据库调试工具 --> SolrDebug #### 第 1 层：快速检查（零配置） **TYPO3 报告模块**（管理工具 -> 报告 -> 状态报告）： * 显示连接状态、配置集匹配、每种语言的核心可用性 * 如果这里有任何红色/黄色的东西，请在进一步调试之前修复它 **EXT：solr后端模块**（Web -> 搜索）： * **概览选项卡**：每个站点和语言的连接状态 * **索引队列选项卡**：按类型记录计数、错误计数、最后索引时间戳 * **“索引字段”选项卡**：Solr 架构中具有类型和存储/索引标志的所有字段 * **停用词/同义词选项卡**：Solr 核心上的当前配置 **Solr 管理 UI**（DDEV：`ddev launch :8984`，生产：`http://host:8983/solr/`）： * **仪表板** ：JVM 内存、Solr 版本、正常运行时间 * **核心选择器**（下拉菜单）：选择您想要检查的核心 * **查询选项卡**：直接针对核心运行查询 * **模式浏览器**：检查字段类型、存储/索引标志、样本值 * **分析选项卡**：粘贴文本以查看 Solr 如何对其进行标记和词干 #### 第 2 层：启用 TypoScript 调试日志记录添加到您的**根页面 TypoScript 设置**（仅限开发/登台）：插件.tx_solr.logging { 调试输出 = 1 例外 = 1 索引 = 1 索引.indexQueueInitialization = 1 索引.pageIndexed = 1 索引.队列.新闻 = 1 查询.rawGet = 1 查询.rawPost = 1 查询.queryString = 1 查询.searchWords = 1 } 设置|它记录什么 ---|--- `调试输出` |将调试信息写入 TYPO3 开发日志 `例外` | Solr 通信的完整异常堆栈跟踪 `索引` |索引期间发送到 Solr 的每个文档 `indexing.indexQueueInitialization` |哪些表被初始化到队列中 `indexing.pageIndexed` |索引后的每个页面（URL、字段、响应） `indexing.queue.<名称>` |每个配置的日志记录（例如“queue.news”、“queue.events”） `query.rawGet` |发送到 Solr 的确切 HTTP GET URL `query.rawPost` | POST 正文发送到 Solr（用于复杂查询） `query.queryString` |解析后的 Solr 查询字符串 `query.searchWords` |处理后的用户搜索输入 **输出到哪里？** 默认情况下，输出到 TYPO3 日志系统。要获取文件，您可以“tail -f”： // 配置/系统/additional.php $GLOBALS['TYPO3_CONF_VARS']['LOG']['ApacheSolrForTypo3']['Solr']['writerConfiguration'] = [ \Psr\Log\LogLevel::DEBUG => [ \TYPO3\CMS\Core\Log\Writer\FileWriter::class => [ 'logFile' => \TYPO3\CMS\Core\Core\Environment::getVarPath() 。 '/log/solr.log', ], ], ]; 然后观看直播： # DDEV ddev exec tail -f var/log/solr.log # 独立尾-f /var/www/html/var/log/solr.log **另请检查 TYPO3 系统日志：** 管理工具 -> 日志模块，按组件“ApacheSolrForTypo3”过滤。 #### 第三层：Solr debugQuery（分数解释）在 Solr 管理 UI -> 查询选项卡中，添加 `debugQuery=true` 以查看文档排名的**原因**： q=typo3 solr&debugQuery=true&fl=uid,标题,分数响应包括“调试”部分： { “调试”：{ “rawquerystring”：“typo3 solr”， “查询字符串”：“typo3 solr”， "parsedquery": "(标题:typo3 | 内容:typo3) (标题:solr | 内容:solr)", "QParser": "ExtendedDismaxQParser", “解释”：{ "4f547484...": "\n7.256 = 总和:\n 3.628 = 权重(标题:typo3) ...\n 3.628 = 权重(标题:solr) ..." }, “时间”：{ “时间”：2.0， “准备”：{“时间”：1.0}， “过程”：{“时间”：1.0} } } } 调试响应中的关键字段：领域|它告诉你什么 ---|--- `解析查询` | Solr 如何解释您的搜索词（哪些字段、运算符） `解释一下` |每个文档的分数细分：哪些字段匹配、TF-IDF/BM25 权重 `时机` |每个阶段的查询执行时间（准备、处理） `原始查询字符串` |解析前的原始查询 **阅读解释输出：** 每行显示一个分数部分。更高=更相关。寻找： * 哪些**字段**贡献最大（标题与内容） * 应用 **Boost** 值 * **coord**（协调）是否惩罚部分匹配 #### 第 4 层：EXT：solrdebugtools（资金扩展） [EXT:solrdebugtools]() 向前端添加可视化调试： * **Debug\Query ViewHelper** ：在前端显示 Solr 查询、解析的查询和计时 * **解释显示**：每个结果分数细分为饼图 * **查询参数** ：查看发送到 Solr 的所有参数在开发过程中添加到您的 Fluid 模板中：这会直接在搜索结果页面中呈现一个调试面板，显示完整的 Solr 请求和响应。 #### 第 5 层：CLI 卷曲到 Solr API 完全绕过 TYPO3 并直接与 Solr 对话： # Ping（Solr 还活着吗？） ddev 执行curl -s http://solr:8983/solr/core_en/admin/ping | python3 -m json.工具 # 文档总数 ddev exec curl -s 'http://solr:8983/solr/core_en/select?q=*:*&rows=0' | python3 -m json.工具 # 通过调试进行搜索 ddev exec curl -s 'http://solr:8983/solr/core_en/select?q=test&debugQuery=true&fl=uid,title,score&wt=json' | python3 -m json.工具 # 通过uid检查特定文档 ddev exec curl -s 'http://solr:8983/solr/core_en/select?q=uid:42&fl=*' | python3 -m json.工具 # 列出索引中所有字段名 ddev exec curl -s 'http://solr:8983/solr/core_en/admin/luke?numTerms=0&wt=json' | python3 -m json.tool | grep '“名字”' # 按类型划分的文档计数 ddev exec curl -s 'http://solr:8983/solr/core_en/select?q=*:*&rows=0&facet=true&facet.field=type' | python3 -m json.工具 # 检查存在哪些 siteHash 值 ddev exec curl -s 'http://solr:8983/solr/core_en/select?q=*:*&rows=0&facet=true&facet.field=siteHash' | python3 -m json.工具 # 分析术语如何标记化（对于字段类型“文本”） ddev exec curl -s 'http://solr:8983/solr/core_en/analysis/field?analysis.fieldname=content&analysis.fieldvalue=TYPO3+Content+Management&wt=json' | python3 -m json.工具 **来自主机**（将 `ddev exec curl -s http://solr:8983` 替换为 `curl -sk https://.ddev.site:8984`）。 #### 第 6 层：数据库级检查查询 TYPO3 数据库以查看 EXT:solr 认为的状态是什么： -- 每个类型/配置有多少个项目，有多少个有错误？选择项目类型、索引配置、 COUNT(*) 总计， SUM(CASE WHEN indexed > 0 THEN 1 ELSE 0 END) 作为索引， SUM(CASE WHEN 错误 != '' THEN 1 ELSE 0 END) 作为错误， SUM(CASE WHEN Changed > Indexed THEN 1 ELSE 0 END) 已过时来自 tx_solr_indexqueue_item 按 item_type、indexing_configuration 分组； -- 显示实际的错误信息选择 uid、item_type、item_uid、LEFT(errors, 200) 作为 error_preview 来自 tx_solr_indexqueue_item 哪里错误！= '' 按 uid DESC 限制 20 排序； -- 最后一次成功的索引运行是什么时候？ SELECT MAX(FROM_UNIXTIME(indexed)) 作为last_indexed 来自 tx_solr_indexqueue_item WHERE 索引 > 0； -- 为特定页面存储的站点哈希值是什么？选择 uid、标题、slug 从页面其中 uid = 1； -- 然后检查：站点哈希来自config.yaml中的站点标识符 #### 综合起来：调试工作流程图解TD 问题[“出了点问题”] 问题 --> 报告["1.检查报告模块"] 报告-->|红色|连接[“修复连接(12.2)”] 报告-->|绿色| Queue["2.查看后端模块中的索引队列"] 队列-->|空| Init["初始化队列，检查TypoScript"] 队列-->|错误| SQL["3.从数据库读取错误消息"] 队列-->|确定| SolrAdmin["4.直接查询Solr Admin"] SolrAdmin -->|没有文档| Scheduler["运行调度程序，检查索引日志"] SolrAdmin -->|文档存在|前端["5.检查前端TypoScript"] 前端-->|没有结果| TS["启用查询日志记录，检查 siteHash"] 前端-->|错误结果| Debug["6.debugQuery=true,检查评分"] 调度程序 --> Log["启用索引日志记录，tail solr.log"] ### 12.1 从哪里开始：诊断流程图图解TD 开始[“Solr 有问题吗？”] 开始 --> A{"报告模块：
全绿色？"} A -->|否| Fix1["修复连接配置
(参见12.2)"] 一个-->|是| B{“索引队列：
存在项目？”} B -->|否| Fix2["初始化队列
(见12.3)"] B -->|是| C{"项目有
错误？"} C -->|是| Fix3["检查错误消息
(见12.3)"] C -->|否| D{"Solr Admin:
文档存在吗？"} D -->|否| Fix4["运行调度程序worker
(参见12.3)"] D -->|是| E{“前端显示
结果？”} E -->|否| Fix5["检查 TypoScript，
站点哈希值（参见 12.4）"] E -->|是|完成[“工作！”] **第 1 步：** 检查 TYPO3 报告模块（管理工具 -> 报告 -> 状态报告）。所有与 Solr 相关的检查都必须是绿色的。 **第 2 步：** 打开 Solr 管理 UI。 DDEV：`ddev 启动：8984`。生产：`https://your-host:8983/solr/`。 **第3步：** EXT：solr后端模块->“索引队列”选项卡。物品是否已排队？有错误吗？ ### 12.2 连接问题 **“搜索当前不可用”** \-- 完整清单： 1. 验证站点配置值：`solr_host_read`、`solr_port_read`、`solr_scheme_read`、`solr_path_read` 2. 任何配置更改后，单击 EXT:solr 后端模块中的“初始化连接” 3. 从 CLI 测试： # DDEV 容器内部 ddev 执行curl -s http://solr:8983/solr/core_en/admin/ping # 来自主机 curl -sk https://<项目>.ddev.site:8984/solr/core_en/admin/ping 4. **DDEV 网络：** 在容器内部，可以通过主机名“solr”在端口“8983”上访问 Solr。在主机上，使用带有 HTTPS 的“.ddev.site:8984”。 5. **防火墙：** 确保端口 8983（或 DDEV 的 8984）已打开 6. **HTTPS：** DDEV 使用自签名证书。将 `solr_scheme_read: https` 与 DDEV 结合使用。 ### 12.3 索引问题 #### 索引队列中没有任何内容 * **TypoScript 未加载：** 检查根页面上的模板模块。 EXT：必须包含 solr 静态模板。 * **队列未初始化：** 后端模块 -> “索引队列”选项卡 -> 选择记录类型 -> 单击“队列所选内容” * **缺少配置：** 每个表必须存在 `plugin.tx_solr.index.queue.[table] = 1` * **siteroot 之外的记录：** 设置 `additionalPageIds` 并在扩展设置中启用“跟踪 siteroot 之外的记录” #### 队列中但未索引的项目 * **调度程序未运行：** 必须配置并执行“Index Queue Worker”调度程序任务 * **检查错误：** 检查 `errors` 列：选择 item_type、错误、COUNT(*) 作为 cnt 来自 tx_solr_indexqueue_item 哪里错误！= '' 按项目类型分组，错误； * **强制 webroot：** 如果 TYPO3 无法自动检测 Web 根目录（CLI 上下文），请在计划程序任务设置中配置“强制 webroot” * **内存：** 大内容可能会超过 PHP `memory_limit`。增加调度程序进程。 #### 项目已编入索引但内容错误/缺失 * **在 Solr 管理 UI 中检查实际文档**： q=*:*&fq=类型:tx_news_domain_model_news&rows=5&fl=uid,标题,内容,url,siteHash * **字段映射：** 验证 `plugin.tx_solr.index.queue.[table].fields` TypoScript 与您的 Solr 架构字段匹配 * **内容中的 HTML：** 使用 `SOLR_CONTENT` 从 RTE 字段中去除 HTML * **关系为空：** 将“SOLR_RELATION”与“multiValue = 1”一起用于类别/标签字段 #### 重新索引 1. **软重新索引：** 后端模块 -> 清除队列 -> 重新队列 -> 运行调度程序任务 2. **强制重新索引：** 针对特定配置的计划程序任务“强制重新索引站点” 3. **核选项**（仅限 DDEV）：`TRUNCATE tx_solr_indexqueue_item;` 然后通过后端模块重新初始化 ### 12.4 搜索/查询问题 #### 前端没有结果图LR 插件["搜索插件
(流体)"] --> TS["TypoScript Config"] TS --> SolrQ["Solr 查询
(HTTP GET)"] SolrQ --> 响应["Solr 响应
(JSON)"] 响应 --> 渲染[“流体渲染”] * **targetPage:** `plugin.tx_solr.search.targetPage` 必须指向包含搜索插件的页面 * **禁用：** 检查 `plugin.tx_solr.enabled` 未设置为 `0` * **站点哈希不匹配：** 使用错误站点哈希索引的文档不会出现。在 Solr 管理中测试： q=YOUR_TERM&fq=siteHash:YOUR_EXPECTED_HASH * **访问限制：** 文档有一个“访问”字段。确保前端用户组匹配。 #### 错误结果/不良相关性 * **debugQuery:** 在 Solr Admin 中，运行 `q=YOUR_TERM&debugQuery=true` 以查看分数细分 * **EXT:solrdebugtools:** 安装调试\查询 ViewHelper、解释功能和分数饼图 * **Boosting：** 配置字段权重：插件.tx_solr.search.query { boostFunction = recip(ms(现在,已创建),3.16e-11,1,1) boostQuery = 类型：页^2.0 } #### 刻面未显示 * `plugin.tx_solr.search.faceting = 1` 缺失 * 字段未建立索引（检查动态字段后缀是否与架构匹配） * 需要 `initializeWithEmptyQuery = 1` 在任何搜索之前显示构面 * Facet 字段在索引文档中的值为零 ### 12.5 日志深入探讨 > 有关完整的日志记录设置（TypoScript 配置、FileWriter、`tail -f`），请参阅上面的 **12.0 Layer 2**。 **每个索引队列配置的选择性日志记录：** 您可以仅为一项配置启用日志记录以减少噪音：插件.tx_solr.logging { 索引 = 0 索引.队列.事件 = 1 } 这仅记录“事件”队列处理，而不记录“新闻”或“页面”。 **每个文档的索引日志包含的内容：** [DEBUG] 索引文档：tx_news_domain_model_news:42 字段：标题=我的活动，内容=...（截断），url=/events/my-event Solr 响应：{"responseHeader":{"status":0,"QTime":3}} 如果索引失败，您将看到 Solr 错误响应： [错误] tx_news_domain_model_news 索引失败：42 错误：文档缺少强制 uniqueKey 字段：id **查询日志包含的内容：** [调试] Solr 查询：q=test+search&fq=siteHash:abc123&fl=*,score [调试] Solr 原始 GET：http://solr:8983/solr/core_en/select?q=test+search&... [DEBUG] 搜索词：[“测试”、“搜索”] [调试] 响应：3 毫秒内 15 个结果 > **警告：** 禁用生产日志记录。日志数据快速增长并影响性能。从“additional.php”中删除“plugin.tx_solr.logging”配置和“writerConfiguration”。 ### 12.6 Solr 管理 UI 作为调试工具 > 请参阅 **12.0 第 5 层**，了解所有这些查询的 CLI `curl` 等效项。关键诊断查询（在 Solr Admin -> Query 选项卡中运行）：查询 |目的 ---|--- `q=*:*&行=0` |文件总数 `q=*:*&fq=type:pages&rows=5&fl=uid,标题,url,siteHash` |检查索引页面 `q=*:*&fq=类型:tx_news_domain_model_news&fl=uid,标题,内容` |检查自定义记录 `q=YOUR_TERM&debugQuery=true` |分数解释（参见 12.0 第 3 层读取输出） `q=*:*&facet=true&facet.field=type&rows=0` |文档类型分布 `q=*:*&fq=siteHash:YOUR_HASH&rows=0` |每个站点的文档哈希值 **其他有用的查询：** # 通过UID和类型查找特定记录 q=*:*&fq=uid:42&fq=类型:tx_news_domain_model_news&fl=* # 检查文档中存在哪些字段（所有字段） q=*:*&行=1&fl=* # 比较索引的两个配置 q=*:*&fq=indexing_configuration:新闻&行=0 q=*:*&fq=indexing_configuration:事件&行=0 # 查找内容为空的文档 q=*:*&fq=-内容:[* TO *]&fl=uid,标题,类型 # 检查访问字段（前端用户限制） q=*:*&fl=uid,标题,访问&行=10 **核心管理：** 在架构更改后重新加载核心（核心管理 -> 重新加载按钮，或通过 API：`curl http://solr:8983/solr/admin/cores?action=RELOAD&core=core_en`）。 **分析屏幕：** 测试文本如何标记化和词干化。在 Solr Admin -> Analysis 中，选择字段类型（例如“文本”），将文本粘贴到“字段值（索引）”框中，然后单击“分析值”。这显示了每个处理步骤：字符过滤器、标记器、标记过滤器（小写、停用词、词干）。 ### 12.7 数据库级调试 > 有关完整的 SQL 查询手册，请参阅 **12.0 第 6 层**。快速参考： -- 概述：队列中有什么？选择项目类型、索引配置、 COUNT(*) 总计， SUM(CASE WHEN 错误！= '' THEN 1 ELSE 0 END) 作为错误来自 tx_solr_indexqueue_item 按 item_type、indexing_configuration 分组； ——出了什么问题？ SELECT uid、item_type、item_uid、错误、更改、索引来自 tx_solr_indexqueue_item 哪里错误！= '' 限制 20； -- 事件队列（延迟监听模式）从 tx_solr_eventqueue_item 选择* 按 tstamp DESC LIMIT 20 排序； -- 需要重新索引的项目 SELECT uid、item_type、item_uid、已更改、已索引来自 tx_solr_indexqueue_item 更改位置 > 已索引限制 20； -- 重置错误以重试索引更新 tx_solr_indexqueue_item SET 错误 = '' WHERE 错误 != ''; ### 12.8 常见问题快速参考症状|可能的原因 |修复 ---|---|--- “搜索当前不可用” | Solr 连接配置错误 |检查站点配置，初始化连接任何查询都没有结果 |站点哈希不匹配 |检查`siteHashStrategy`，重新索引空索引队列| TypoScript 未加载到根页面 |包括 EXT:solr 静态模板队列项目从未编入索引 |调度程序任务未运行 |创建“索引队列工作者”任务队列中的项目有错误 |索引失败（内存、URL）|检查数据库中的“错误”列刻面不可见 | `faceting = 0` 或空字段 |启用分面，检查字段是否有值建议不要工作 | `suggest = 0` 或缺少 jQuery |启用建议，检查JS包含结果内容错误 |字段映射不正确 |修复 TypoScript `fields` 配置访问受限页面丢失 |未设置“linkAccessRestrictedPages” |添加 `config.typolinkLinkAccessRestrictedPages = 1` 记录的 URL 生成失败 |未配置`detailPid` |设置正确的详情页ID Docker：`/var/solr` 上的权限被拒绝 |卷所有权错误 |确保 UID 8983 拥有该卷 DDEV：端口 8984 无法访问 |插件未安装或 Solr 已关闭 | `ddev 插件获取 ddev/ddev-typo3-solr && ddev restart` 配置集版本不匹配 |部署了错误的配置集 |重新部署匹配的“ext_solr_13_1_0” Jar 加载错误 (Solr 9.8+) |需要 CVE-2025-24814 迁移 |将 `typo3lib/` 移至服务器根目录，或拉取 Docker 13.0.1+ 蒂卡：连接超时 | Tika 服务器未运行或端口错误 |检查 Docker 容器，在扩展设置中测试连接语言核心缺失 |语言没有核心 |使用匹配的语言模式创建核心 ## 13\.测试 ### 功能测试设置 importCSVDataSet(__DIR__ . '/Fixtures/news_records.csv'); $this->indexQueue('新闻'); $searchResult = $this->searchInSolr('测试新闻标题'); self::assertGreaterThan(0, $searchResult->getResultCount()); } } ### 测试自定义事件监听器 setField('类型', '页面'); $event = $this->createMock(BeforeDocumentsAreIndexedEvent::class); $event->method('getDocuments')->willReturn([$document]); $listener = new EnrichSolrDocuments(); $监听器($事件); self::assertNotNull($document->getField('custom_score_floatS')); } } ## 14\.最佳实践 ### 生产清单 * 部署正确的配置集版本（`ext_solr_13_1_0`） * 配置 Solr JVM 内存 (`SOLR_JAVA_MEM=-Xms512m -Xmx1g`) * Solr 不可公开访问（防火墙、反向代理） * 调度程序任务“Index Queue Worker”定期运行 * 在生产中禁用日志记录 * Solr数据量备份 * 应用了 CVE 补丁（Solr 9.8.0+ jar 迁移） * `siteHashStrategy = 1`（站点标识符） ### 安全 * Solr 绝不能公开访问。使用防火墙规则或绑定到“127.0.0.1” * 如果需要远程访问，请使用带有身份验证的反向代理（nginx/Apache） * 监控 [Apache Solr 安全建议]() * 保持 Tika 服务器更新（CVE-2025-54988：需要 3.2.2+） ### 性能 * **提交策略：** 使用 `autoSoftCommit` （1-5 秒）实现近乎实时，使用 `autoCommit` （15-60 秒）实现持久性 * **缓存预热：** 在`solrconfig.xml`中配置`newSearcher`和`firstSearcher`事件 * **分段合并：** 在 Solr Admin 中监控分段计数，在非高峰期间考虑“优化” ### 多站点/多语言 * 每种语言一个 Solr 核心（例如 `core_en`、`core_de`），具有特定于语言的模式 * 每个 TYPO3 站点在站点配置 YAML 中配置自己的 Solr 连接 * 使用 `siteHash` 来隔离每个站点的文档 ### 环境配置使用 helhum/dotenv-connector 来管理每个环境的 Solr 凭证： * 每个环境（本地、临时、生产）的“.env”文件，包含“SOLR_HOST”、“SOLR_PORT”等。 * 切勿在提交给 VCS 的站点配置 YAML 中硬编码连接详细信息 * 使用占位符值提交`.env.example` ## 15\.数据库结构表|目的 ---|--- `tx_solr_indexqueue_item` |排队等待索引的项目（类型、uid、错误、时间戳） `tx_solr_indexqueue_indexing_property` |每个队列项目的附加索引属性 `tx_solr_last_searches` |最近执行的搜索词 `tx_solr_statistics` |搜索统计信息（术语、结果计数、时间戳） `tx_solr_eventqueue_item` |延迟监控模式的事件队列 `tx_solr_indexqueue_item` 中的关键列：专栏 |类型 |目的 ---|---|--- `项目类型` | varchar |表名称（例如“pages”、“tx_news_domain_model_news”） `item_uid` |整数 |记录UID `索引配置` | varchar | TypoScript 配置名称 `改变了` |整数 |记录上次更改的时间戳 `索引` |整数 |记录上次索引的时间戳 `错误` |文字|上次索引尝试的错误消息 ## 常见问题/常见食谱 ### 一张表，两个索引配置（例如来自 EXT:news 的新闻 + 事件）常见模式：EXT:news 安装一次，但有两个目的 - 经典新闻文章和活动日历（或产品公告、新闻稿等）。您希望它们在搜索中作为**单独的方面值**。 **步骤1：同一个表的两个索引队列配置** 使用“additionalWhereClause”按类别、类型字段或 sysfolder PID 拆分记录：插件.tx_solr.index.queue { # 配置1：经典新闻文章新闻 = 1 新闻{ 类型 = tx_news_domain_model_news extraWhereClause =categories.uid IN (1,2,3) 字段{ 标题=标题内容 = SOLR_CONTENT 内容.cObject = COA 内容.cObject { 10 = 文本 10.字段=正文 } 类别_字符串M = SOLR_RELATION 类别_字符串M { 本地字段 = 类别多值 = 1 } 网址=文本网址{ typolink.parameter = {$plugin.tx_news.settings.detailPid} typolink.additionalParams = &tx_news_pi1[controller]=新闻&tx_news_pi1[action]=detail&tx_news_pi1[news]={field:uid} typelink.additionalParams.insertData = 1 打字链接.returnLast = url } # 自定义字段以区分方面新闻类型_字符串S = TEXT newstype_stringS.value = 新闻 } } # 配置2：事件（同一张表，不同记录）事件 = 1 事件{ 类型 = tx_news_domain_model_news extraWhereClause =categories.uid IN (4,5,6) 字段{ 标题=标题内容 = SOLR_CONTENT 内容.cObject = COA 内容.cObject { 10 = 文本 10.字段=正文 } 类别_字符串M = SOLR_RELATION 类别_字符串M { 本地字段 = 类别多值 = 1 } # 特定于事件的字段 eventdate_dateS = 日期时间 eventlocation_stringS = TEXT 事件位置_字符串S { 字段=预告片 } 网址=文本网址{ typolink.parameter = {$plugin.tx_news.settings.detailPid} typolink.additionalParams = &tx_news_pi1[controller]=新闻&tx_news_pi1[action]=detail&tx_news_pi1[news]={field:uid} typelink.additionalParams.insertData = 1 打字链接.returnLast = url } 新闻类型_字符串S = TEXT newstype_stringS.value = 事件 } } } **替代分割策略**（仅使用一种）：战略| `附加WhereClause` |何时使用 ---|---|--- 按类别 | `categories.uid IN (4,5,6)` |新闻与事件的不同类别树通过系统文件夹 | `pid IN (50,51)` |新闻和事件存储在单独的系统文件夹中按类型字段 | `tx_news_domain_model_news.type = 1` | EXT:新闻类型字段区分记录类型按标签 | `tags.uid = 10` |用特定标签标记 **第 2 步：自定义字段上的分面** 插件.tx_solr.search.faceting { 刻面{ 新闻类型{ 标签=内容类型字段 = newstype_stringS } } } 这将“新闻 (42)”和“事件 (15)”显示为方面选项。 **第 3 步：初始化两个队列配置** 在 EXT:solr 后端模块 -> Index Queue 选项卡中，“新闻”和“事件”都显示为单独的索引配置。选择两者并单击“排队所选内容”。 **内部工作原理：** 每个配置都使用“indexing_configuration = 'news'”或“indexing_configuration = 'events'”创建自己的“tx_solr_indexqueue_item”条目。调度程序工作线程处理两者。在 Solr 中，文档具有“type = tx_news_domain_model_news”（表名称），但“newstype_stringS”字段有所不同。 > **提示：** 如果您希望 Solr `type` 字段本身不同（例如，`type = news` 与 `type = events`），您可以在字段配置中覆盖它：`type = TEXT` / `type.value = events`。请注意，这会影响其他基于类型的过滤。 ### 每个配置有不同的详细信息页面 URL 当新闻和事件有单独的详细信息页面时：插件.tx_solr.index.queue.news.fields.url { 打字链接.参数= 42 # ... } 插件.tx_solr.index.queue.events.fields.url { 打字链接.参数 = 55 # ... } ### 一张表中的三个或更多配置模式可扩展——您可以根据需要为同一个表创建任意数量的索引队列配置。每个都有自己的名称、“additionalWhereClause”、字段映射和详细信息页面 URL。 ## 相关技能 * **typo3-datahandler** ：触发Solr索引的数据库操作 * **typo3-seo** ：补充 Solr 搜索的 SEO 配置 * **ai-search-optimization** ：AEO/GEO 用于 AI 搜索可见性 * **typo3-content-blocks** ：可以索引的内容元素 * **typo3-testing** ：TYPO3 扩展的测试模式 ## 参考文献 ### 官方文档 * [EXT:solr 文档]() * [EXT:tika 文档]() * [版本矩阵]() * [动态字段参考]() * [tx_solr.search 参考]() * [tx_solr.index 参考]() * [tx_solr.suggest 参考]() * [扩展设置]() * [PSR-14 事件]() * [索引（开发）]() * [索引队列]() * [Facets]() * [自动建议]() * [AJAX 结果]() * [自定义前端]() * [流体结构]() * [调度程序任务]() * [常见问题解答]() ### GitHub 存储库 * [EXT:solr]() * [EXT:tika]() * [TYPO3-Solr 组织]() * [v14 开发分支]() * [Docker 镜像]() ### Apache Solr 服务器 * [参考指南]() * [密集向量搜索]() * [文本到向量（LLM模块）]() * [Solr 模块]() * [LLM API Javadoc]() * [教程：向量]() ### 商业和托管 * [typo3-solr.com]() * [变更日志 EXT:solr]() * [变更日志 EXT:solrfal]() * [hosted-solr.com]() * [hosted-solr.com 定价]() * [dkd 企业支持]() * [dkd 研讨会]() ### DDEV * [ddev-typo3-solr 插件]() * [DDEV 插件目录]() ### 米特瓦尔德 * [Solr 文档]() ### 环境配置 * [helhum/dotenv-connector]() * [Packagist]() * [TYPO3环境配置]() ### 社区 * [TYPO3 Slack #ext-solr]() * [GitHub 问题]() * [TYPO3 扩展 (TER)]() ### 博客和教程 * [Sease：神经搜索]() * [Sease：KNN 基准]() * [Sease：语义搜索文本到向量]() * [Sease: SeededKnnVectorQuery (Solr 10)]() * [LangChain4j 嵌入模型]() ## 制作人员及归属 * **dkd Internet Service GmbH** 用于开发和维护 EXT:solr、EXT:tika 和 TYPO3-Solr 生态系统 * **Apache Software Foundation** 适用于 Apache Solr 和 Apache Tika * **b13** 用于维护 ddev-typo3-solr 插件 * **Helmut Hummel (helhum)** 用于 dotenv 连接器 * **Mittwald** 用于托管 Solr 托管文档

Typo3 Solr

包含技能