Hoe stel je full-text zoeken in Nextcloud in met Elasticsearch 8?

De Elasticsearch-integratie van Nextcloud is in 2026 nog steeds actief, maar er is één compatibiliteitsdetail dat u moet controleren voordat u begint: de huidige app voor full-text zoeken - Elasticsearch Platform ondersteunt Elasticsearch 8, niet Elasticsearch 9. De officiële repository van het project vermeldt dat versies 26.0.0 en later alleen compatibel zijn met Elasticsearch 8. Daarnaast heeft Nextcloud 35 nu een bijbehorende Elasticsearch-platformrelease 35.0.0, gepubliceerd op 18 september 2026. Als u een bestaande server upgradet, controleer dan welke app-versie overeenkomt met uw Nextcloud-hoofdrelease voordat u de zoekindex aanpast.

Deze handleiding laat een praktische configuratie zien voor het indexeren van bestandsinhoud in Nextcloud met Elasticsearch 8. De focus ligt op de standaard drie-app-stack: het framework voor full-text zoeken, de Elasticsearch-platformconnector en de bestandsprovider. De commando's maken gebruik van de Nextcloud occCLI, omdat deze gemakkelijker te valideren en te automatiseren is dan wanneer alleen de webinterface wordt gebruikt.

Officiële referenties: Nextcloud Full text search - Elasticsearch Platform app , Nextcloud Elasticsearch platform repository , Nextcloud Full text search framework , Nextcloud Files full text search provider en Elastic's single-node Docker installation guide .

Wat de Nextcloud full-text search stack daadwerkelijk inhoudt

Nextcloud full-text search is geen op zichzelf staande app. De kernapp voor full-text search biedt het raamwerk. Een platformapp verbindt dat raamwerk met een zoekmachine, en een of meer providerapps halen de doorzoekbare inhoud eruit. Voor bestandsinhoud is de provider Full-text search - Files. Elasticsearch slaat de resulterende index op en beantwoordt zoekopdrachten.

• Volledige tekstzoekfunctie: het kernframework en de laag voor zoekorkestratie.
• Volledige tekstzoekfunctie - Elasticsearch Platform: de connector die documenten en zoekopdrachten naar Elasticsearch verzendt.
• Volledige tekstzoekfunctie - Bestanden: de provider die de bestanden van gebruikers beschikbaar stelt aan het framework voor indexering.
• Elasticsearch 8: de externe zoekmachine die de index opslaat.

De scheiding is belangrijk bij het oplossen van problemen. Een werkend Elasticsearch HTTP-eindpunt bewijst niet dat Nextcloud bestandsinhoud kan extraheren, en een ingeschakelde bestandsprovider bewijst niet dat de platformconnector Elasticsearch kan bereiken. De ingebouwde fulltextsearch:testopdracht is handig omdat deze de geconfigureerde keten controleert in plaats van slechts één component.

Voordat je begint

Je hebt beheerdersrechten nodig voor Nextcloud, shelltoegang tot de server of container waarop Nextcloud draait, en een Elasticsearch 8-instantie die vanuit die omgeving bereikbaar is. De onderstaande voorbeelden gaan uit van een Linux-server en gebruiken Docker voor Elasticsearch omdat dit de zoekservice geïsoleerd houdt. Als je al een beheerd of dedicated Elasticsearch 8-cluster gebruikt, gebruik dan in plaats daarvan het bestaande HTTPS-eindpunt.

Voor productieomgevingen mag poort 9200 niet rechtstreeks aan het openbare internet worden blootgesteld. De huidige Docker-documentatie van Elastic adviseert om de HTTP-poort te koppelen aan een beveiligde interface en de beveiligingsfuncties te behouden. Elastic documenteert ook de vereisten voor hosts, bijvoorbeeld vm.max_map_countvoor Docker-implementaties in productieomgevingen. Beschouw elk commando voor een enkele node met uitgeschakelde beveiliging als een lokale snelkoppeling, niet als een sjabloon voor productieomgevingen.

Stap 1: Installeer de drie benodigde Nextcloud-apps

Installeer en activeer vanaf de Nextcloud Apps-pagina de volgende apps: Volledige tekst zoeken , Volledige tekst zoeken - Elasticsearch Platform en Volledige tekst zoeken - Bestanden . Je kunt ze ook installeren met `npm install -cf` occ, wat vaak eenvoudiger is op servers zonder grafische interface:

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

Als uw Nextcloud-bestanden zich ergens anders bevinden, pas dan het pad aan naar occ. In de officiële Nextcloud Docker-image is het pad meestal /var/www/html/occ. Na de installatie kunt u occ app:listcontroleren of alle drie de apps onder 'Ingeschakeld' verschijnen.

Omschrijving: De Nextcloud Apps-pagina met het kernframework voor full-text zoeken, de Elasticsearch-platformconnector en de bestandsprovider ingeschakeld.

Stap 2: Start Elasticsearch 8 en controleer of Nextcloud er toegang toe heeft.

De Elasticsearch-connector vereist Elasticsearch 8 sinds versie 26.0.0 van de Nextcloud-app. Gebruik Elasticsearch 9 niet als alternatief, tenzij de officiële compatibiliteitsverklaring voor de app-versie die u gebruikt, is gewijzigd.

Voor een lokale testomgeving beschrijft Elastic een aanpak met één Docker-node. Een minimale testomgeving kan worden gestart op een privé-interface. In een productieomgeving moet authenticatie en TLS ingeschakeld blijven en moet de huidige installatiehandleiding van Elastic worden gevolgd in plaats van de beveiliging uit te schakelen.

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

De veilige standaard opstartprocedure van Elastic print het wachtwoord voor de ingebouwde elasticgebruiker en genereert HTTP TLS-certificaten. U kunt het knooppunt vervolgens verifiëren met behulp van het CA-certificaat en de inloggegevens, zoals beschreven in de officiële handleiding. Als Nextcloud zich in een andere Docker-container bevindt, houd er dan rekening mee dat 127.0.0.1dit verwijst naar de Nextcloud-container zelf, niet naar de Elasticsearch-container. Plaats beide services op een gedeeld Docker-netwerk en gebruik de Elasticsearch-servicenaam, bijvoorbeeld https://elasticsearch:9200, of routeer via een privéadres.

Omschrijving: Een terminalweergave van een Elasticsearch-service op één node die wordt gestart en gecontroleerd; voor productie is het aan te raden authenticatie en TLS ingeschakeld te houden in plaats van een onbeveiligde labconfiguratie te gebruiken.

Stap 3: Nextcloud configureren voor gebruik met Elasticsearch

Je kunt het platform configureren via de beheerdersinterface, maar de CLI-vorm is nauwkeuriger en reproduceerbaar. Nextcloud's eigen All-in-One-integratie configureert het framework door de Elasticsearch-platformklasse te selecteren en vervolgens de Elasticsearch-host en indexnaam aan de connector door te geven.

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"}'

Gebruik een host-URL die bereikbaar is vanuit het Nextcloud PHP-proces. Als uw Elasticsearch-eindpunt een privé-CA gebruikt, zorg er dan voor dat de Nextcloud-omgeving die CA vertrouwt in plaats van certificaatverificatie uit te schakelen. Vermijd het opslaan van inloggegevens in de shellgeschiedenis op gedeelde systemen; gebruik een beveiligde configuratiemethode die geschikt is voor uw implementatie.

De indexnaam moet in kleine letters zijn en specifiek voor deze Nextcloud-instantie. Een naam zoals nextcloud_indexis gemakkelijk te herkennen. Als meerdere Nextcloud-instanties één Elasticsearch-cluster delen, geef elke instantie dan een unieke indexnaam.

Omschrijving: Het beheerscherm voor full-text zoeken met Elasticsearch geselecteerd als zoekplatform en een specifieke indexnaam geconfigureerd.

Stap 4: Kies welke bestandsinhoud geïndexeerd moet worden.

De bestandsaanbieder bepaalt welke categorieën bestandsinhoud worden verzonden voor indexering. De alles-in-één-initialisatie van Nextcloud maakt het momenteel mogelijk om PDF- en Office-documenten te extraheren met dit commando:

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

De beschikbare opties voor providers kunnen per app-versie verschillen, dus controleer de huidige configuratie voordat u instellingen uit een oudere handleiding kopieert. Houd er ook rekening mee dat de kwaliteit van tekstextractie afhangt van het bronbestand. Een normale PDF met ingesloten tekst is veel gemakkelijker te indexeren dan een gescande PDF met alleen afbeeldingen. Zoeken op volledige tekst maakt slechte OCR niet automatisch nauwkeurig.

Stap 5: Test de volledige zoekconfiguratie

Voordat u een grote bibliotheek indexeert, voert u de frameworktest uit:

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

Een geslaagde test moet aantonen dat het platform bereikbaar is en dat de geconfigureerde provider/platformcombinatie kan werken. Als de test mislukt, moet de verbinding worden hersteld voordat de initiële indexering wordt gestart. Typische oorzaken zijn onder andere het gebruik localhostvan de verkeerde container, problemen met certificaatvertrouwen, authenticatiefouten, een incompatibele Elasticsearch-hoofdversie of een indexconfiguratie die door Elasticsearch wordt afgewezen.

Stap 6: Bouw de initiële index

Zodra de test slaagt, maak je de initiële index aan:

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

Op een grote server kan dit tijdrovend zijn en veel CPU, geheugen, opslag-I/O en Elasticsearch-heap verbruiken. Voer de eerste crawl uit tijdens een periode met weinig verkeer en controleer zowel de Nextcloud- als de Elasticsearch-logboeken. Het framework ondersteunt ook een formulier voor het resetten van fouten, dat door Nextcloud All-in-One wordt gebruikt tijdens de eerste installatie.

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

Reset en herbouw een goed functionerende index niet herhaaldelijk zonder reden. Lees bij upgrades eerst de release-opmerkingen van de drie zoekapps en controleer of een herindexering daadwerkelijk nodig is.

Stap 7: Houd de index actueel.

Een initiële index is slechts een momentopname. Nieuwe uploads en bewerkingen vereisen continue indexering. Het framework voor full-text zoeken bevat een fulltextsearch:liveopdracht voor continue verwerking. Als u deze gebruikt, laat deze dan uitvoeren onder een procesbeheerder of een andere servicemanager, zodat deze na fouten of herstarts van de host opnieuw wordt gestart.

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

Start geen onbeheerd voorgrondproces in een SSH-sessie en ga er niet vanuit dat het indexeren na het uitloggen doorgaat. Containerimplementaties kunnen de actieve worker als een apart, gecontroleerd proces uitvoeren; traditionele servers kunnen systemd of een supervisor gebruiken. Monitor het zoals elke andere achtergrondservice.

Stap 8: Controleer de zoekopdracht zowel via de CLI als via de Nextcloud-interface.

Nadat de eerste crawl is voltooid, zoek je naar een zin die voorkomt in een bekend document en niet alleen in de bestandsnaam. Dit bevestigt dat de extractie en indexering van de inhoud werken. Recente versies van full-text search ondersteunen ook zoeken via occ, wat handig is om een ​​probleem met de backend-indexering te scheiden van een probleem met de browser of de uniforme zoekfunctie.

Gebruik in de webinterface het zoekveld van Nextcloud en zoek naar een opvallende zin in een PDF-, DOCX- of tekstbestand waarvan u weet dat het is geïndexeerd. Als zoeken op bestandsnaam wel werkt, maar zoeken op documentinhoud niet, controleer dan de instellingen van de bestandsprovider en het type brondocument.

Omschrijving: Een succesvolle frameworktest en initiële indexering, gevolgd door een Nextcloud-zoekopdracht die geïndexeerde documenten retourneert.

Problemen oplossen die vaak voorkomen

Elasticsearch werkt met curl, maar Nextcloud kan geen verbinding maken.

Test vanuit dezelfde netwerknaamruimte als het Nextcloud PHP-proces. In Docker bewijst een succesvol verzoek vanaf de host niet dat de Nextcloud-container de Elasticsearch-service kan bereiken of oplossen. Controleer DNS, containernetwerken, firewallregels, TLS-vertrouwen en het exacte schema in de geconfigureerde URL.

De connector meldt een probleem met de Elasticsearch-versie.

Controleer de daadwerkelijke hoofdversie van Elasticsearch, niet alleen de imagetag die u wilt implementeren. De huidige officiële connectorrepository vermeldt nog steeds Elasticsearch 8-compatibiliteit voor app-versie 26.0.0 en later. Op het moment van schrijven is er een openstaand verzoek bij de ontwikkelaars van Elasticsearch 9 voor ondersteuning, dus ga er niet zomaar vanuit dat Elasticsearch 9 compatibel is.

Indexering verbruikt te veel geheugen.

Houd de Elasticsearch-heap, de geheugenlimieten van de container en het hostgeheugen tegelijkertijd in de gaten. De Docker-productiedocumentatie van Elastic verwijst ook naar instellingen op hostniveau, zoals vm.max_map_count. Als de JVM wordt afgesloten, lost het verhogen van alleen de Nextcloud PHP-geheugenlimiet het Elasticsearch-probleem niet op.

Sommige gedeelde of externe bestanden ontbreken.

Het zoekgedrag kan afhangen van de ondersteuning door de provider en de app-versie. Het Files-providerproject blijft problemen met gedeelde mappen, groepsmappen en externe opslag volgen. Als een opslagtype zich anders gedraagt ​​dan gewone lokale bestanden, reproduceer het probleem dan met een klein, gecontroleerd voorbeeld en raadpleeg de officiële probleemtracker van de provider voordat u de volledige index opnieuw opbouwt.

Hoe weet ik of de installatie voltooid is?

Een succesvolle implementatie kenmerkt zich door vier waarneembare tekenen: Elasticsearch 8 is bereikbaar vanuit Nextcloud, fulltextsearch:testslaagt voor de tests, de initiële configuratie fulltextsearch:indexwordt zonder onopgeloste fouten voltooid en het zoeken naar tekst in een bekend document levert dat bestand op voor een geautoriseerde gebruiker. Houd het index-eindpunt privé, waarborg de beveiliging van Elasticsearch in productie en upgrade de drie Nextcloud-zoekapps in lijn met uw Nextcloud-hoofdrelease.

Voor versie-specifieke details kunt u de officiële Nextcloud Elasticsearch-platformreleaselijst en de officiële Elastic Docker-richtlijnen voor productieomgevingen raadplegen . Deze bronnen zijn de meest betrouwbare plek om de compatibiliteit en hostingvereisten te controleren vóór een grote upgrade.