如何在 Nextcloud 中使用 Elasticsearch 8 設定全文搜索

Nextcloud 的 Elasticsearch 整合在 2026 年仍然有效，但在開始之前，有一項相容性細節值得注意：目前的全文搜尋 - Elasticsearch 平台應用程式支援 Elasticsearch 8，而非 Elasticsearch 9。該專案的官方程式​​碼庫指出，26.0.0 及更高版本僅相容於 Elasticsearch 8。此外，Nextcloud 35 現在也推出了與之相符的 Elasticsearch 平台版本 35.0.0，該版本於 2026 年 9 月 18 日發布。如果您要升級現有伺服器，請在修改搜尋索引之前，請確認應用程式版本與您的 Nextcloud 主要版本相符。

本指南展示了在 Nextcloud 中使用 Elasticsearch 8 為檔案內容建立索引的實用配置。它重點介紹標準的三應用堆疊：全文搜尋框架、Elasticsearch 平台連接器和檔案提供者。occ由於 Nextcloud CLI 比僅依賴 Web 介面更容易驗證和自動化，因此本指南中的命令均使用 Nextcloud CLI。

官方參考資料：Nextcloud 全文搜尋 - Elasticsearch 平台應用程式、Nextcloud Elasticsearch 平台儲存庫、Nextcloud 全文搜尋框架、Nextcloud 檔案全文搜尋提供者以及Elastic 的單節點 Docker 安裝指南。

Nextcloud全文搜尋堆疊實際包含哪些內容

Nextcloud 全文搜尋並非一個獨立的應用程式。核心全文搜尋應用程式提供框架。平台應用程式將該框架連接到搜尋引擎，一個或多個提供者應用程式提取可搜尋的內容。對於文件內容，提供者是「全文搜尋 - 文件」。 Elasticsearch 儲存搜尋結果索引並回應查詢。

• 全文搜尋：核心框架和搜尋編排層。
• 全文搜尋 - Elasticsearch 平台：將文件和查詢傳送至 Elasticsearch 的連接器。
• 全文搜尋 - 檔案：將使用者檔案揭露給框架進行索引的提供者。
• Elasticsearch 8：儲存索引的外部搜尋引擎。

在進行故障排除時，這種分離至關重要。 Elasticsearch HTTP 端點正常運作並不能證明 Nextcloud 可以擷取檔案內容，而啟用的檔案提供者也無法證明平台連接器可以存取 Elasticsearch。內建fulltextsearch:test指令的優點在於，它會檢查配置的整個鏈，而不僅僅是單一元件。

開始之前

您需要擁有 Nextcloud 的管理員權限、執行 Nextcloud 的伺服器或容器的 shell 存取權限，以及一個可從該環境存取的 Elasticsearch 8 實例。以下範例假設使用 Linux 伺服器，並使用 Docker 執行 Elasticsearch，因為它能確保搜尋服務的隔離。如果您已經執行了託管或專用的 Elasticsearch 8 集群，請使用其現有的 HTTPS 端點。

在生產環境中，請勿將 9200 連接埠直接暴露給公共網際網路。 Elastic 目前的 Docker 文件建議將 HTTP 連接埠綁定到受控介面並保留安全功能。 Elastic 也vm.max_map_count針對生產環境 Docker 部署等情況提供了主機需求。請將任何禁用安全功能的單節點命令視為本機實驗室快捷方式，而非生產環境模板。

步驟 1：安裝三個必要的 Nextcloud 應用

從 Nextcloud 應用程式頁面安裝並啟用全文搜尋、全文搜尋 - Elasticsearch 平台和全文搜尋 - 檔案。您也可以使用以下命令安裝它們occ，這在無頭伺服器上通常更簡單：

sudo -u www-data php /var/www/nextcloud/occ app:install fulltextsearch
sudo -u www-data php /var/www/nextcloud/occ app:install fulltextsearch_elasticsearch
sudo -u www-data php /var/www/nextcloud/occ app:install files_fulltextsearch

如果您的 Nextcloud 檔案位於其他位置，請將路徑變更為 `/etc/Nextcloud/` occ。在官方 Nextcloud Docker 映像中，路徑通常為 `/etc/Nextcloud/` /var/www/html/occ。安裝完成後，使用 ` npm run dev` 指令occ app:list確認所有三個應用程式都顯示在「已啟用」清單中。

圖註：Nextcloud 應用程式頁面，已啟用核心全文框架、Elasticsearch 平台連接器和檔案提供者。

步驟 2：啟動 Elasticsearch 8 並驗證 Nextcloud 是否可以存取它。

自 Nextcloud 應用 26.0.0 版本起，Elasticsearch 連接器就需要 Elasticsearch 8。除非您使用的應用程式版本的官方相容性聲明有所更改，否則請勿使用 Elasticsearch 9。

對於本機實驗室環境，Elastic 文件中介紹了一種單節點 Docker 部署方案。可以在私有介面上啟動一個最小的測試實例。在生產環境中部署時，請保持身份驗證和 TLS 啟用狀態，並遵循 Elastic 目前的安裝指南，而不是停用安全功能。

docker run --name es01   --net elastic   -p 127.0.0.1:9200:9200   -it -m 6GB   docker.elastic.co/elasticsearch/elasticsearch:<ELASTICSEARCH_8_VERSION>

Elastic 的安全性預設啟動會列印內建elastic使用者的密碼並建立 HTTP TLS 憑證。然後，您可以按照官方指南中的說明，使用 CA 憑證和憑證驗證節點。如果 Nextcloud 位於另一個 Docker 容器中，請記住，127.0.0.1指向的是 Nextcloud 容器本身，而不是 Elasticsearch 容器。將這兩個服務放在共用的 Docker 網路上，並使用 Elasticsearch 服務名稱（例如 `/etc/Elasticsearch/Nextcloud`）https://elasticsearch:9200，或透過私人位址進行路由。

圖註：啟動和檢查單節點 Elasticsearch 服務的終端視圖；對於生產環境，請保持身份驗證和 TLS 啟用狀態，而不是使用不安全的實驗室配置。

步驟 3：設定 Nextcloud 以使用 Elasticsearch

您可以在管理介面中設定平台，但 CLI 表單更加精確且可重複。 Nextcloud 自帶的 All-in-One 整合透過選擇 Elasticsearch 平台類別來配置框架，然後將 Elasticsearch 主機名稱和索引名稱傳遞給連接器。

sudo -u www-data php /var/www/nextcloud/occ fulltextsearch:configure '{"search_platform":"OCA\\FullTextSearch_Elasticsearch\\Platform\\ElasticSearchPlatform"}'

sudo -u www-data php /var/www/nextcloud/occ fulltextsearch_elasticsearch:configure '{"elastic_host":"https://elastic:YOUR_PASSWORD@elasticsearch:9200","elastic_index":"nextcloud_index"}'

使用 Nextcloud PHP 進程可存取的主機 URL。如果您的 Elasticsearch 端點使用私有 CA，請確保 Nextcloud 環境信任該 CA，而不是關閉憑證驗證。避免在共用系統上將憑證儲存在 shell 歷史記錄中；請使用適合您部署環境的受保護設定方法。

索引名稱應使用小寫字母，並且專用於此 Nextcloud 實例。例如，`<input name="Nextcloud-instance-name">` 這樣的名稱nextcloud_index易於識別。如果多個 Nextcloud 實例共用同一個 Elasticsearch 集群，請為每個實例指定一個唯一的索引名稱。

圖註：全文搜尋管理介面，已選擇 Elasticsearch 作為搜尋平台並配置了專用索引名稱。

第四步：選擇要索引的文件內容

文件提供者控制哪些類別的文件內容會被傳送到索引。 Nextcloud 的一體化初始化功能目前支援使用以下命令擷取 PDF 和 Office 文件：

sudo -u www-data php /var/www/nextcloud/occ files_fulltextsearch:configure '{"files_pdf":true,"files_office":true}'

不同應用程式版本可用的提供者選項可能有所不同，因此在從舊教學課程複製設定之前，請先檢查目前配置。另請注意，文字擷取品質取決於原始檔案。包含嵌入文字的普通 PDF 檔案比僅包含掃描影像的 PDF 檔案更容易索引。全文搜尋並不能自動彌補 OCR 辨識的不足。

步驟 5：測試完整的搜尋配置

在對大型庫進行索引之前，請執行框架測試：

sudo -u www-data php /var/www/nextcloud/occ fulltextsearch:test

成功的測試應表明平台可訪問，且配置的提供者/平台組合能夠正常運作。如果測試失敗，請在啟動初始索引之前修復連線。常見原因包括：使用了localhost錯誤的容器、憑證信任問題、驗證失敗、Elasticsearch 主版本不相容，或 Elasticsearch 拒絕了索引配置。

步驟 6：建立初始索引

測試通過後，建立初始索引：

sudo -u www-data php /var/www/nextcloud/occ fulltextsearch:index

在大型伺服器上，這可能會耗費大量時間並消耗 CPU、記憶體、儲存 I/O 和 Elasticsearch 堆記憶體。請在流量較低的時段執行首次爬取，並同時監控 Nextcloud 和 Elasticsearch 日誌。該框架還支援 Nextcloud All-in-One 在初始設定期間使用的錯誤重置表單：

sudo -u www-data php /var/www/nextcloud/occ fulltextsearch:index '{"errors":"reset"}' --no-readline

請勿無故重複重置和重建已建立的索引。升級前，請先閱讀三個搜尋應用程式的發行說明，並確認是否確實需要重新索引。

步驟 7：保持索引最新

初始索引只是一個快照。新的上傳和編輯需要持續索引。全文搜尋框架包含一個fulltextsearch:live用於持續處理的指令。如果使用該命令，請在進程管理器或其他服務管理器下執行，以便在發生故障或主機重新啟動後自動重新啟動。

sudo -u www-data php /var/www/nextcloud/occ fulltextsearch:live

不要在 SSH 會話中啟動未託管的前台進程，並假設註銷後索引會繼續運行。容器部署可以將即時工作進程作為專用的受監控進程運行；傳統伺服器可以使用 systemd 或 supervisor。像監控其他後台服務一樣監控它。

步驟 8：透過 CLI 和 Nextcloud 介面驗證搜尋功能

初始抓取完成後，搜尋出現在已知文件內部（而不僅僅是文件名中）的短語。這可以確認內容提取和索引功能是否正常運作。最新版本的全文搜尋還支援透過以下方式搜尋occ：，這有助於將後端索引問題與瀏覽器或統一搜尋問題區分開來。

在網頁介面中，使用 Nextcloud 的搜尋框，尋找已知已建立索引的 PDF、DOCX 或文字檔案中的特定短語。如果檔案名稱搜尋有效但文件正文搜尋無效，請檢查文件提供者設定和來源文件類型。

圖註：框架測試和初始索引成功，隨後在 Nextcloud 中進行搜索，傳回已索引的文件。

常見故障排除

Elasticsearch 可以用 curl 連接，但 Nextcloud 無法連接。

請在與 Nextcloud PHP 進程相同的網路命名空間中進行測試。在 Docker 中，主機發出的成功請求並不能證明 Nextcloud 容器可以解析或存取 Elasticsearch 服務。請檢查 DNS、容器網路、防火牆規則、TLS 信任以及配置 URL 中的確切協定。

連接器報告 Elasticsearch 版本問題

請檢查 Elasticsearch 的實際主版本，而不僅僅是您打算部署的鏡像標籤。目前官方的連接器倉庫仍然聲明，應用版本 26.0.0 及更高版本相容於 Elasticsearch 8。截至撰寫本文時，上游已收到對 Elasticsearch 9 的支援請求，因此不應假定 Elasticsearch 9 相容。

索引佔用過多記憶體

同時監控 Elasticsearch 堆記憶體、容器記憶體限制和主機記憶體。 Elastic 的 Docker 生產文件也提到了主機層級的設置，例如… vm.max_map_count。如果 JVM 被終止，僅增加 Nextcloud PHP 記憶體限制並不能解決 Elasticsearch 方面的問題。

缺少一些共享文件或外部文件

搜尋行為可能取決於提供者的支援情況和應用程式版本。 「文件」提供者專案會持續追蹤與共用資料夾、分組資料夾和外部儲存相關的問題。如果某種儲存類型的行為與普通本機檔案不同，請先使用一個小型可控範例重現問題，並在重建整個索引之前查看提供者的官方問題追蹤器。

如何判斷設定是否完成

一個健康的 Elasticsearch 部署有四個可觀察的標誌：Nextcloud 可以存取 Elasticsearch 8，fulltextsearch:test啟動成功，初始fulltextsearch:index配置完成且沒有未解決的錯誤，並且對已知文檔中的文本進行搜索能夠返回已授權用戶訪問的文件。請確保索引端點的私密性，在生產環境中維護 Elasticsearch 的安全性，並隨著 Nextcloud 的主要版本更新升級三個 Nextcloud 搜尋應用程式。

對於版本相關的詳細信息，請參考Nextcloud Elasticsearch 平台官方發布列表和Elastic 生產環境 Docker 官方指南。這些資源是進行重大升級前確認相容性和主機要求的最可靠途徑。