diff --git a/de/15.9/config/datastore/ds-database.rst b/de/15.9/config/datastore/ds-database.rst index df7621f2..9e69cf7d 100644 --- a/de/15.9/config/datastore/ds-database.rst +++ b/de/15.9/config/datastore/ds-database.rst @@ -34,38 +34,47 @@ Voraussetzungen Plugin-Installation ------------------- -Methode 1: JAR-Datei direkt platzieren +Methode 1: Installation über die Administrationsoberfläche -:: +1. "System" -> "Plugins" öffnen +2. JAR-Datei hochladen +3. |Fess| neu starten - # Herunterladen von Maven Central - wget https://repo1.maven.org/maven2/org/codelibs/fess/fess-ds-db/X.X.X/fess-ds-db-X.X.X.jar +Methode 2: JAR-Datei direkt platzieren - # Platzieren - cp fess-ds-db-X.X.X.jar $FESS_HOME/app/WEB-INF/lib/ - # oder - cp fess-ds-db-X.X.X.jar /usr/share/fess/app/WEB-INF/lib/ +:: -Methode 2: Installation über die Administrationsoberfläche + # Herunterladen aus dem CodeLibs-Repository + wget https://maven.codelibs.org/release/org/codelibs/fess/fess-ds-db/X.X.X/fess-ds-db-X.X.X.jar -1. "System" -> "Plugins" öffnen -2. JAR-Datei hochladen -3. |Fess| neu starten + # Platzieren (dasselbe Verzeichnis, in das auch über die Administrationsoberfläche installiert wird) + cp fess-ds-db-X.X.X.jar $FESS_HOME/app/WEB-INF/plugin/ + # oder + cp fess-ds-db-X.X.X.jar /usr/share/fess/app/WEB-INF/plugin/ JDBC-Treiber-Installation -------------------------- -Platzieren Sie den JDBC-Treiber für die Zieldatenbank im Classpath von |Fess| (Verzeichnis ``app/WEB-INF/lib/``): +Der JDBC-Treiber ist nicht im Plugin enthalten. Beschaffen Sie den Treiber für Ihre Datenbank separat und platzieren Sie ihn selbst. + +Das Datenspeicher-Crawling läuft im Crawler-Prozess, daher muss der Treiber im **Classpath des Crawler-Prozesses** liegen. Eines der folgenden Verzeichnisse ist geeignet: + +- ``app/WEB-INF/lib/`` +- ``app/WEB-INF/env/crawler/lib/`` :: # Beispiel: MySQL-Treiber - cp mysql-connector-j-8.x.x.jar $FESS_HOME/app/WEB-INF/lib/ + cp mysql-connector-j-9.x.x.jar $FESS_HOME/app/WEB-INF/lib/ # oder - cp mysql-connector-j-8.x.x.jar /usr/share/fess/app/WEB-INF/lib/ + cp mysql-connector-j-9.x.x.jar /usr/share/fess/app/WEB-INF/lib/ Starten Sie |Fess| neu, um den Treiber zu laden. +.. note:: + Fehlt der Treiber, schlägt das Crawling mit der Meldung + ``The JDBC driver ... is not on the crawler classpath.`` fehl. + Konfiguration ============= @@ -137,7 +146,10 @@ Parameterliste - Datenbank-Passwort * - ``fetch_size`` - Nein - - JDBC-Fetch-Größe. Für MySQL-Streaming-Resultsets kann ``MIN_VALUE`` angegeben werden + - JDBC-Fetch-Größe. ``MIN_VALUE`` weist MySQL an, das Resultset zeilenweise zu lesen; andere Treiber lehnen negative Werte ab, und das Crawling wird nach einer Warnung mit dem Standardwert des Treibers fortgesetzt. Negative oder nicht numerische Werte werden gemeldet und ignoriert + * - ``query_timeout`` + - Nein + - Query-Timeout in Sekunden. ``0`` bedeutet keine Begrenzung (JDBC-Standard). Ohne Angabe des Parameters wird kein Timeout gesetzt * - ``default_mimetype`` - Nein - Standard-MIME-Typ für die Inhaltsextraktion aus BLOB- und Binärspalten @@ -157,6 +169,12 @@ Parameterliste - Nein - Skript-Engine-Typ. Standard: groovy +.. note:: + Hängt eine Query, gibt das Stoppen des Jobs den Crawler-Thread nicht frei. + Die Stopp-Anforderung wird nur zwischen den Zeilen geprüft und kann daher einen + Aufruf, der im Treiber blockiert, nicht unterbrechen. Setzen Sie ``query_timeout`` + für Queries, die lange laufen können. + Skript-Einstellungen -------------------- @@ -172,19 +190,49 @@ Ordnen Sie die SQL-Spaltennamen den Index-Feldern zu: Verfügbare Felder: - ```` - Ergebnisspalten der SQL-Query (direkt über den Spaltenbezeichner zugänglich, ohne Präfix wie ``data.``) +- ``crawlingConfig`` - die Datenspeicher-Konfiguration +- ``crawlingContext`` - der Crawling-Kontext; ``crawlingContext.doc`` enthält das gerade erzeugte Dokument .. note:: Die Spaltennamen müssen mit den Spaltenbezeichnern (Aliasnamen) in der ``SELECT``-Klausel übereinstimmen. Bei Aggregatfunktionen oder Ausdrücken vergeben Sie mit ``AS`` einen expliziten Aliasnamen (Beispiel: ``COUNT(*) AS total``). +.. note:: + Die Groß-/Kleinschreibung der Spaltenbezeichner unterscheidet sich je nach Datenbank. + PostgreSQL wandelt nicht in Anführungszeichen gesetzte Bezeichner in Kleinbuchstaben um, + H2 in Großbuchstaben, und MySQL liefert sie wie deklariert. Ein Name, der nicht aufgelöst + werden kann, lässt das Feld unbesetzt, statt einen Fehler auszulösen - vergeben Sie daher + mit ``AS`` einen expliziten Aliasnamen, wenn Portabilität wichtig ist. + +.. warning:: + Skripte können auf die **gesamte Parameterzuordnung des Datenspeichers** zugreifen, nicht + nur auf die Ergebnisspalten der SQL-Query. ``driver``, ``url``, ``username``, ``password`` + und ``sql`` sind alle als gleichnamige Variablen sichtbar, sodass eine Spalte unbeabsichtigt + überdeckt werden kann oder ein Parameterwert dort erscheint, wo eine fehlende Spalte + erwartet wurde. Existieren beide, gewinnt der Wert der Spalte. + Laden von BLOB- und Binärdaten ============================== -Spalten vom Typ BLOB, CLOB, NCLOB, Byte-Array oder Binär-Stream werden automatisch -einer Inhaltsextraktion unterzogen (derselbe Extraktor wie beim Datei-Crawling) und als -Text indiziert. Spalten vom Array-Typ werden in leerzeichengetrennte Zeichenketten -umgewandelt. NULL-Werte werden zu leeren Zeichenketten. +Binärspalten (BLOB, ``BYTEA``, Byte-Array, Binär-Stream) werden einer Inhaltsextraktion +unterzogen - derselbe Extraktor wie beim Datei-Crawling - und als Text indiziert. + +CLOB, NCLOB und Zeichen-Streams durchlaufen **keinen** Extraktor. Sie werden unverändert als +Text gelesen; die unten beschriebenen MIME-Typ-Hinweise gelten für sie nicht. + +Spalten vom Array-Typ werden zu ihren mit Leerzeichen verbundenen Elementen. NULL-Werte +werden zu leeren Zeichenketten. + +.. note:: + Ob eine BLOB-Spalte als ``java.sql.Blob`` oder als Byte-Array ankommt, entscheidet der + JDBC-Treiber - MySQL und PostgreSQL liefern ein Byte-Array. Beide werden auf dieselbe + Weise extrahiert. + +.. note:: + CLOB und NCLOB werden vollständig und ohne Größenbegrenzung in den Speicher gelesen. + Bei sehr großen Textspalten sollten Sie im SQL mit ``SUBSTRING`` oder Ähnlichem kürzen. + Für den Weg über den Extraktor gilt die maximale Inhaltslänge des Crawlers. Damit Text aus BLOB- und Binär-Streams korrekt extrahiert werden kann, muss der Datentyp (MIME-Typ) bestimmt werden. Die folgende Prioritätsreihenfolge wird verwendet: @@ -229,6 +277,17 @@ Methode zum Abrufen nur der aktualisierten Datensätze: # Bereichsangabe nach ID sql=SELECT * FROM articles WHERE id > 10000 +.. warning:: + Die Query auf diese Weise einzuschränken macht aus dem Crawling noch kein + inkrementelles Crawling. Wenn ein Crawl endet, löscht |Fess| die Dokumente dieser + Datenspeicher-Konfiguration, die nicht Teil des soeben gelaufenen Crawls waren - eine + gefilterte Query lässt also nur die passenden Zeilen im Index zurück. + + Fügen Sie ``delete_old_docs=false`` zu den Datenspeicher-Parametern hinzu, um die von + früheren Crawls indexierten Dokumente zu behalten. Aus der Datenbank gelöschte Zeilen + werden dann allerdings auch nicht mehr aus dem Index entfernt; führen Sie deshalb + regelmäßig ein vollständiges Crawling durch. + URL-Generierung --------------- @@ -245,6 +304,13 @@ Die Dokument-URL wird im Skript generiert: # In der Datenbank gespeicherte URL verwenden url=url +.. warning:: + ``url=url`` tut nur dann das Erwartete, wenn das ``SELECT``-Ergebnis eine Spalte mit dem + Bezeichner ``url`` enthält. Ohne eine solche Spalte wird der gleichnamige + Datenspeicher-Parameter - also die **JDBC-Verbindungs-URL** - zur Dokument-URL. Vergeben + Sie einen Aliasnamen für die Spalte, etwa ``SELECT page_url AS url``, oder benennen Sie sie + im Skript, etwa ``url=page_url``. + Multibyte-Zeichenunterstützung ============================== @@ -277,10 +343,33 @@ Schutz der Datenbank-Anmeldedaten Empfohlene Methoden: -1. Umgebungsvariablen verwenden -2. Verschlüsselungsfunktion von |Fess| verwenden +1. Automatische Verschlüsselung nutzen + + Der Wert eines Parameters, dessen Name auf ``app.encrypt.property.pattern`` passt + (Standard ``.*password|.*key|.*token|.*secret``), wird beim Speichern über die + Administrationsoberfläche verschlüsselt und mit dem Präfix ``{cipher}`` abgelegt. + ``password`` passt auf dieses Muster und wird daher nicht im Klartext gespeichert, + wenn es über die Administrationsoberfläche gesetzt wird. + +2. Umgebungsvariablen verwenden + + Eine Umgebungsvariable, deren Name mit ``FESS_ENV_`` beginnt, wird innerhalb eines + Datenspeicher-Parameters als ``${Variablenname}`` expandiert: + + :: + + password=${FESS_ENV_DB_PASSWORD} + + Welche Namen expandiert werden, steuert ``crawler.data.env.param.key.pattern`` + (Standard ``^FESS_ENV_.*``). + 3. Nur-Lese-Benutzer verwenden +.. note:: + Das Anheben von ``org.codelibs.fess.ds`` auf DEBUG legt keine Anmeldedaten offen: Die Werte + von Parametern, die auf ``app.encrypt.property.pattern`` passen, sowie in der JDBC-URL + eingebettete Anmeldedaten werden im Log maskiert. + Prinzip der minimalen Rechte ----------------------------- @@ -345,21 +434,23 @@ Skript: Fehlerbehebung ============== +Schlägt ein Crawling fehl, gibt die Meldung im Log an, welcher Schritt fehlgeschlagen ist. + JDBC-Treiber nicht gefunden ---------------------------- -**Symptom**: ``ClassNotFoundException`` oder ``No suitable driver`` +**Symptom**: ``The JDBC driver ... is not on the crawler classpath.`` **Lösung**: -1. Überprüfen Sie, ob der JDBC-Treiber in ``lib/`` platziert ist -2. Überprüfen Sie, ob der Klassenname des Treibers korrekt ist +1. Überprüfen Sie, ob der JDBC-Treiber in ``app/WEB-INF/lib/`` oder ``app/WEB-INF/env/crawler/lib/`` platziert ist +2. Überprüfen Sie, ob der in ``driver`` angegebene Klassenname korrekt ist 3. Starten Sie |Fess| neu Verbindungsfehler ----------------- -**Symptom**: ``Connection refused`` oder Authentifizierungsfehler +**Symptom**: ``Failed to connect to .`` **Zu überprüfen**: @@ -371,7 +462,7 @@ Verbindungsfehler Query-Fehler ------------ -**Symptom**: ``SQLException`` oder SQL-Syntaxfehler +**Symptom**: ``Failed to execute the query.`` **Zu überprüfen**: @@ -379,6 +470,27 @@ Query-Fehler 2. Überprüfen Sie, ob die Spaltennamen korrekt sind 3. Überprüfen Sie, ob die Tabellennamen korrekt sind +Fehlende Parameter +------------------ + +**Symptom**: ``The driver parameter is required.``, ``The url parameter is required.`` oder ``The sql parameter is required.`` + +Ein erforderlicher Parameter ist nicht gesetzt. Überprüfen Sie das Parameterfeld. + +Nur einzelne Zeilen schlagen fehl +--------------------------------- + +Eine fehlgeschlagene Zeile bricht das Crawling nicht ab; sie wird unter "System" -> "Fehlerhafte URL" +protokolliert. Verwendet wird die Dokument-URL, sofern die Skripte eine erzeugt haben, und +``datastore:///``, wenn nicht. + +Dokumente erscheinen nicht in den Suchergebnissen +------------------------------------------------- + +1. Überprüfen Sie, ob die Skripte ``url``, ``title`` und ``content`` setzen +2. Überprüfen Sie, ob die Groß-/Kleinschreibung der Spaltenbezeichner mit der in den Skripten verwendeten übereinstimmt (siehe "Skript-Einstellungen") +3. Überprüfen Sie die Anzahl der Dokumente im Protokoll des Crawl-Jobs + Weiterführende Informationen ============================ diff --git a/en/15.9/config/datastore/ds-database.rst b/en/15.9/config/datastore/ds-database.rst index 7e79fbbc..17a6068a 100644 --- a/en/15.9/config/datastore/ds-database.rst +++ b/en/15.9/config/datastore/ds-database.rst @@ -35,38 +35,47 @@ Prerequisites Plugin Installation ------------------- -Method 1: Place the JAR file directly +Method 1: Install from the admin console -:: +1. Open "System" -> "Plugin" +2. Upload the JAR file +3. Restart |Fess| - # Download from Maven Central - wget https://repo1.maven.org/maven2/org/codelibs/fess/fess-ds-db/X.X.X/fess-ds-db-X.X.X.jar +Method 2: Place the JAR file directly - # Place the file - cp fess-ds-db-X.X.X.jar $FESS_HOME/app/WEB-INF/lib/ - # or - cp fess-ds-db-X.X.X.jar /usr/share/fess/app/WEB-INF/lib/ +:: -Method 2: Install from the admin console + # Download from the CodeLibs repository + wget https://maven.codelibs.org/release/org/codelibs/fess/fess-ds-db/X.X.X/fess-ds-db-X.X.X.jar -1. Open "System" -> "Plugin" -2. Upload the JAR file -3. Restart |Fess| + # Place the file, in the same directory the admin console installs into + cp fess-ds-db-X.X.X.jar $FESS_HOME/app/WEB-INF/plugin/ + # or + cp fess-ds-db-X.X.X.jar /usr/share/fess/app/WEB-INF/plugin/ Installing JDBC Drivers ----------------------- -Place the JDBC driver compatible with your target database in the |Fess| classpath (``app/WEB-INF/lib/`` directory): +The JDBC driver is not bundled with the plugin. Obtain the driver for your database separately and place it yourself. + +Data store crawling runs in the crawler process, so the driver has to be on the **crawler process classpath**. Either of these directories works: + +- ``app/WEB-INF/lib/`` +- ``app/WEB-INF/env/crawler/lib/`` :: # Example: MySQL driver - cp mysql-connector-j-8.x.x.jar $FESS_HOME/app/WEB-INF/lib/ + cp mysql-connector-j-9.x.x.jar $FESS_HOME/app/WEB-INF/lib/ # or - cp mysql-connector-j-8.x.x.jar /usr/share/fess/app/WEB-INF/lib/ + cp mysql-connector-j-9.x.x.jar /usr/share/fess/app/WEB-INF/lib/ After placing the JDBC driver, restart |Fess| to load it. +.. note:: + When the driver is missing, the crawl fails with + ``The JDBC driver ... is not on the crawler classpath.`` + Configuration ============= @@ -138,7 +147,10 @@ Parameter List - Database password * - ``fetch_size`` - No - - JDBC fetch size. Set to ``MIN_VALUE`` for MySQL streaming result sets + - JDBC fetch size. ``MIN_VALUE`` asks MySQL to read the result set one row at a time; other drivers reject a negative value, and the crawl continues with the driver default after a warning. A negative or non-numeric value is reported and ignored + * - ``query_timeout`` + - No + - Query timeout in seconds. ``0`` means no limit, which is the JDBC default. No timeout is set when the parameter is absent * - ``default_mimetype`` - No - Default MIME type used when extracting content from BLOB or binary columns @@ -158,6 +170,11 @@ Parameter List - No - Script engine type. Default: groovy +.. note:: + Stopping the job does not release the crawler thread while a query is hanging. + The stop request is only checked between rows, so it cannot interrupt a call + blocked inside the driver. Set ``query_timeout`` for queries that may run long. + Script Configuration -------------------- @@ -173,18 +190,48 @@ Map SQL column names to index fields: Available fields: - ```` - SQL query result columns (accessed directly by the column label name; no prefix such as ``data.`` is used) +- ``crawlingConfig`` - the data store configuration +- ``crawlingContext`` - the crawling context; ``crawlingContext.doc`` holds the document being built .. note:: Column names must match the column labels (aliases) in the ``SELECT`` clause. When using aggregate functions or expressions, assign an explicit alias with ``AS`` (e.g., ``COUNT(*) AS total``). +.. note:: + Column label casing differs between databases. PostgreSQL folds unquoted + identifiers to lower case, H2 folds them to upper case, and MySQL reports them + as declared. A name that does not resolve leaves the field unset rather than + raising an error, so assign an explicit alias with ``AS`` when portability + matters. + +.. warning:: + Scripts can reference the **entire data store parameter map**, not only the SQL + result columns. ``driver``, ``url``, ``username``, ``password`` and ``sql`` are + all visible as variables of the same name, so a column can be shadowed + unintentionally, or a parameter value can appear where a missing column was + expected. When both exist, the column value wins. + Loading BLOB/Binary Data ======================== -Columns of type BLOB, CLOB, NCLOB, byte array, or binary stream are automatically passed through the -content extraction process (the same extractor used for file crawling) and ingested as text. -Array-type columns are converted to space-separated strings. NULL values become empty strings. +Binary columns (BLOB, ``BYTEA``, byte array, binary stream) are passed through the content +extraction process - the same extractor used for file crawling - and ingested as text. + +CLOB, NCLOB and character streams are **not** passed through an extractor. They are read as +text as they are, and the MIME type hints described below do not apply to them. + +Array-type columns become their elements joined with spaces. NULL values become empty strings. + +.. note:: + Whether a BLOB column arrives as ``java.sql.Blob`` or as a byte array is decided by + the JDBC driver - MySQL and PostgreSQL return a byte array. Both are extracted the + same way. + +.. note:: + CLOB and NCLOB are read into memory whole, with no size limit. For very large text + columns, consider truncating in SQL with ``SUBSTRING`` or similar. The extractor path + does honour the crawler's maximum content length. To correctly extract text from BLOB or binary streams, the data type (MIME type) must be determined. The following priority order is used: @@ -229,6 +276,16 @@ Methods to retrieve only updated records: # Specify range by ID sql=SELECT * FROM articles WHERE id > 10000 +.. warning:: + Narrowing the query this way does not turn the crawl into an incremental one. + When a crawl finishes, |Fess| deletes the documents of this data store + configuration that were not part of the crawl that just ran, so a filtered + query leaves only the matching rows in the index. + + Add ``delete_old_docs=false`` to the data store parameters to keep the + documents indexed by earlier crawls. Rows deleted from the database are then + no longer removed from the index either, so run a full crawl periodically. + URL Generation -------------- @@ -245,6 +302,12 @@ Generate document URLs in the script: # Use URL stored in database url=url +.. warning:: + ``url=url`` only does what it looks like when the ``SELECT`` result has a column + labelled ``url``. With no such column, the data store parameter of the same name - + the **JDBC connection URL** - becomes the document URL. Alias the column, as in + ``SELECT page_url AS url``, or name it in the script, as in ``url=page_url``. + Multi-byte Character Support ============================= @@ -277,10 +340,32 @@ Protecting Database Credentials Recommended methods: -1. Use environment variables -2. Use |Fess| encryption features +1. Rely on automatic encryption + + A parameter whose name matches ``app.encrypt.property.pattern`` (default + ``.*password|.*key|.*token|.*secret``) is encrypted when saved from the admin + console and stored with a ``{cipher}`` prefix. ``password`` matches that pattern, + so it is not stored in cleartext when set from the admin console. + +2. Use environment variables + + An environment variable whose name starts with ``FESS_ENV_`` is expanded inside a + data store parameter as ``${variable name}``: + + :: + + password=${FESS_ENV_DB_PASSWORD} + + Which names are expanded is controlled by ``crawler.data.env.param.key.pattern`` + (default ``^FESS_ENV_.*``). + 3. Use read-only users +.. note:: + Raising ``org.codelibs.fess.ds`` to DEBUG does not expose credentials: the values of + parameters matching ``app.encrypt.property.pattern``, and credentials embedded in the + JDBC URL, are masked in the log. + Principle of Least Privilege ----------------------------- @@ -345,21 +430,23 @@ Script: Troubleshooting =============== +When a crawl fails, the log message identifies which step failed. + JDBC Driver Not Found --------------------- -**Symptom**: ``ClassNotFoundException`` or ``No suitable driver`` +**Symptom**: ``The JDBC driver ... is not on the crawler classpath.`` **Resolution**: -1. Verify that the JDBC driver is placed in ``lib/`` -2. Verify that the driver class name is correct +1. Verify that the JDBC driver is placed in ``app/WEB-INF/lib/`` or ``app/WEB-INF/env/crawler/lib/`` +2. Verify that the class name given in ``driver`` is correct 3. Restart |Fess| Connection Errors ----------------- -**Symptom**: ``Connection refused`` or authentication errors +**Symptom**: ``Failed to connect to .`` **Check**: @@ -371,7 +458,7 @@ Connection Errors Query Errors ------------ -**Symptom**: ``SQLException`` or SQL syntax errors +**Symptom**: ``Failed to execute the query.`` **Check**: @@ -379,6 +466,27 @@ Query Errors 2. Verify that column names are correct 3. Verify that table names are correct +Missing Parameters +------------------ + +**Symptom**: ``The driver parameter is required.``, ``The url parameter is required.`` or ``The sql parameter is required.`` + +A required parameter is not set. Check the parameter field. + +Only Some Rows Fail +------------------- + +A row that fails does not stop the crawl; it is recorded under "System" -> "Failure URL". +The document URL is used when the scripts produced one, and +``datastore:///`` when they did not. + +Documents Do Not Appear in Search Results +----------------------------------------- + +1. Verify that the scripts set ``url``, ``title`` and ``content`` +2. Verify that the column label casing matches what the scripts use (see "Script Configuration") +3. Check the document count in the crawl job log + Reference Information ===================== diff --git a/es/15.9/config/datastore/ds-database.rst b/es/15.9/config/datastore/ds-database.rst index 9bbd1959..929340c0 100644 --- a/es/15.9/config/datastore/ds-database.rst +++ b/es/15.9/config/datastore/ds-database.rst @@ -35,38 +35,47 @@ Requisitos Previos Instalacion del Plugin ---------------------- -Metodo 1: Colocar el archivo JAR directamente +Metodo 1: Instalar desde la consola de administracion -:: +1. Abrir "Sistema" -> "Plugins" +2. Subir el archivo JAR +3. Reiniciar |Fess| - # Descargar desde Maven Central - wget https://repo1.maven.org/maven2/org/codelibs/fess/fess-ds-db/X.X.X/fess-ds-db-X.X.X.jar +Metodo 2: Colocar el archivo JAR directamente - # Colocar el archivo - cp fess-ds-db-X.X.X.jar $FESS_HOME/app/WEB-INF/lib/ - # o bien - cp fess-ds-db-X.X.X.jar /usr/share/fess/app/WEB-INF/lib/ +:: -Metodo 2: Instalar desde la consola de administracion + # Descargar desde el repositorio de CodeLibs + wget https://maven.codelibs.org/release/org/codelibs/fess/fess-ds-db/X.X.X/fess-ds-db-X.X.X.jar -1. Abrir "Sistema" -> "Plugins" -2. Subir el archivo JAR -3. Reiniciar |Fess| + # Colocar el archivo (el mismo directorio en el que instala la consola de administracion) + cp fess-ds-db-X.X.X.jar $FESS_HOME/app/WEB-INF/plugin/ + # o bien + cp fess-ds-db-X.X.X.jar /usr/share/fess/app/WEB-INF/plugin/ Instalacion del Controlador JDBC --------------------------------- -Coloque el controlador JDBC correspondiente a la base de datos de destino en el classpath de |Fess| (directorio ``app/WEB-INF/lib/``): +El controlador JDBC no se incluye en el plugin. Obtenga por separado el controlador correspondiente a su base de datos y coloquelo usted mismo. + +El rastreo del almacen de datos se ejecuta en el proceso del rastreador, por lo que el controlador debe estar en el **classpath del proceso del rastreador**. Sirve cualquiera de estos directorios: + +- ``app/WEB-INF/lib/`` +- ``app/WEB-INF/env/crawler/lib/`` :: # Ejemplo: Controlador MySQL - cp mysql-connector-j-8.x.x.jar $FESS_HOME/app/WEB-INF/lib/ + cp mysql-connector-j-9.x.x.jar $FESS_HOME/app/WEB-INF/lib/ # o bien - cp mysql-connector-j-8.x.x.jar /usr/share/fess/app/WEB-INF/lib/ + cp mysql-connector-j-9.x.x.jar /usr/share/fess/app/WEB-INF/lib/ Despues de colocar el controlador JDBC, reinicie |Fess| para cargarlo. +.. note:: + Cuando falta el controlador, el rastreo falla con el mensaje + ``The JDBC driver ... is not on the crawler classpath.`` + Metodo de Configuracion ======================= @@ -138,7 +147,10 @@ Lista de Parametros - Contrasena de la base de datos * - ``fetch_size`` - No - - Tamano de recuperacion JDBC. Para resultados en streaming con MySQL, especifique ``MIN_VALUE`` + - Tamano de recuperacion JDBC. ``MIN_VALUE`` indica a MySQL que lea el conjunto de resultados fila a fila; otros controladores rechazan los valores negativos y el rastreo continua con el valor predeterminado del controlador tras emitir una advertencia. Los valores negativos o no numericos se notifican y se ignoran + * - ``query_timeout`` + - No + - Tiempo de espera de la consulta en segundos. ``0`` significa sin limite (el valor predeterminado de JDBC). Si el parametro no se especifica, no se establece ningun tiempo de espera * - ``default_mimetype`` - No - Tipo MIME predeterminado utilizado al extraer contenido de columnas BLOB o binarias @@ -158,6 +170,12 @@ Lista de Parametros - No - Tipo de motor de scripts. Predeterminado: groovy +.. note:: + Si una consulta se queda bloqueada, detener el trabajo no libera el hilo del rastreador. + La solicitud de parada solo se comprueba entre filas, por lo que no puede interrumpir una + llamada bloqueada dentro del controlador. Establezca ``query_timeout`` para las consultas + que puedan tardar mucho. + Configuracion de Script ------------------------ @@ -173,19 +191,50 @@ Mapee los nombres de columnas SQL a campos del indice: Campos disponibles: - ```` - Columnas de resultado de la consulta SQL (se accede directamente por el nombre de la etiqueta de columna; no se usa prefijo como ``data.``) +- ``crawlingConfig`` - la configuracion del almacen de datos +- ``crawlingContext`` - el contexto del rastreo; ``crawlingContext.doc`` contiene el documento que se esta construyendo .. note:: Los nombres de columna deben coincidir con la etiqueta de columna (alias) de la clausula ``SELECT``. Cuando se usen funciones de agregacion o expresiones, asigne un alias explicito con ``AS`` (ej. ``COUNT(*) AS total``). +.. note:: + El uso de mayusculas y minusculas en las etiquetas de columna varia segun la base de datos. + PostgreSQL convierte a minusculas los identificadores sin comillas, H2 los convierte a + mayusculas y MySQL los devuelve tal como se declararon. Un nombre que no se resuelve deja el + campo sin asignar en lugar de generar un error, asi que asigne un alias explicito con ``AS`` + cuando la portabilidad sea importante. + +.. warning:: + Los scripts pueden referenciar **todo el mapa de parametros del almacen de datos**, no solo + las columnas de resultado de la consulta SQL. ``driver``, ``url``, ``username``, ``password`` + y ``sql`` son visibles como variables con el mismo nombre, por lo que una columna puede + quedar ocultada de forma involuntaria, o el valor de un parametro puede aparecer donde se + esperaba una columna inexistente. Cuando existen ambos, prevalece el valor de la columna. + Carga de Datos BLOB o Binarios ================================ -Las columnas de tipo BLOB, CLOB, NCLOB, arrays de bytes y flujos binarios se procesan -automaticamente mediante el extractor de contenido (el mismo que se usa en el rastreo de -archivos) y se incorporan como texto. Las columnas de tipo array se convierten en cadenas -separadas por espacios. Los valores NULL se convierten en cadenas vacias. +Las columnas binarias (BLOB, ``BYTEA``, arrays de bytes y flujos binarios) se procesan +mediante el extractor de contenido (el mismo que se usa en el rastreo de archivos) y se +incorporan como texto. + +CLOB, NCLOB y los flujos de caracteres **no** pasan por ningun extractor. Se leen tal cual +como texto, y las indicaciones de tipo MIME descritas a continuacion no se les aplican. + +Las columnas de tipo array se convierten en sus elementos unidos por espacios. Los valores +NULL se convierten en cadenas vacias. + +.. note:: + Que una columna BLOB llegue como ``java.sql.Blob`` o como array de bytes lo decide el + controlador JDBC: MySQL y PostgreSQL devuelven un array de bytes. Ambos se extraen de la + misma manera. + +.. note:: + CLOB y NCLOB se leen enteros en memoria, sin limite de tamano. Para columnas de texto muy + grandes, considere truncarlas en el SQL con ``SUBSTRING`` o similar. La ruta que pasa por + el extractor si respeta la longitud maxima de contenido del rastreador. Para extraer correctamente el texto de datos BLOB o flujos binarios, es necesario determinar el tipo de dato (tipo MIME). La determinacion sigue el siguiente orden de @@ -231,6 +280,17 @@ Metodo para obtener solo registros actualizados: # Especificar rango por ID sql=SELECT * FROM articles WHERE id > 10000 +.. warning:: + Restringir la consulta de esta manera no convierte el rastreo en incremental. Cuando + un rastreo termina, |Fess| elimina los documentos de esta configuración del almacén + de datos que no formaron parte del rastreo que acaba de ejecutarse, de modo que una + consulta filtrada deja en el índice únicamente las filas coincidentes. + + Añada ``delete_old_docs=false`` a los parámetros del almacén de datos para conservar + los documentos indexados por rastreos anteriores. Las filas eliminadas de la base de + datos dejan entonces de eliminarse también del índice, así que ejecute periódicamente + un rastreo completo. + Generacion de URLs ------------------- @@ -247,6 +307,13 @@ Las URLs de documentos se generan en el script: # Usar URL almacenada en la base de datos url=url +.. warning:: + ``url=url`` solo hace lo que parece cuando el resultado de ``SELECT`` tiene una columna + etiquetada como ``url``. Si no existe esa columna, el parametro del almacen de datos con el + mismo nombre, es decir, la **URL de conexion JDBC**, se convierte en la URL del documento. + Asigne un alias a la columna, como en ``SELECT page_url AS url``, o indiquela en el script, + como en ``url=page_url``. + Soporte de Caracteres Multibyte ================================ @@ -279,10 +346,33 @@ Proteccion de Credenciales de Base de Datos Metodos recomendados: -1. Usar variables de entorno -2. Usar la funcion de cifrado de |Fess| +1. Aprovechar el cifrado automatico + + El valor de un parametro cuyo nombre coincide con ``app.encrypt.property.pattern`` + (predeterminado ``.*password|.*key|.*token|.*secret``) se cifra al guardarlo desde la + consola de administracion y se almacena con el prefijo ``{cipher}``. ``password`` coincide + con ese patron, por lo que no se almacena en texto plano cuando se establece desde la + consola de administracion. + +2. Usar variables de entorno + + Una variable de entorno cuyo nombre empieza por ``FESS_ENV_`` se expande dentro de un + parametro del almacen de datos como ``${nombre de la variable}``: + + :: + + password=${FESS_ENV_DB_PASSWORD} + + Que nombres se expanden lo controla ``crawler.data.env.param.key.pattern`` + (predeterminado ``^FESS_ENV_.*``). + 3. Usar usuarios de solo lectura +.. note:: + Subir ``org.codelibs.fess.ds`` a DEBUG no expone las credenciales: los valores de los + parametros que coinciden con ``app.encrypt.property.pattern``, y las credenciales incrustadas + en la URL JDBC, se enmascaran en el registro. + Principio de Minimo Privilegio -------------------------------- @@ -347,21 +437,23 @@ Script: Solucion de Problemas ====================== +Cuando un rastreo falla, el mensaje del registro identifica que paso ha fallado. + Controlador JDBC No Encontrado -------------------------------- -**Sintoma**: ``ClassNotFoundException`` o ``No suitable driver`` +**Sintoma**: ``The JDBC driver ... is not on the crawler classpath.`` **Solucion**: -1. Verifique que el controlador JDBC este colocado en ``lib/`` -2. Verifique que el nombre de la clase del controlador sea correcto +1. Verifique que el controlador JDBC este colocado en ``app/WEB-INF/lib/`` o ``app/WEB-INF/env/crawler/lib/`` +2. Verifique que el nombre de clase indicado en ``driver`` sea correcto 3. Reinicie |Fess| Error de Conexion ------------------ -**Sintoma**: ``Connection refused`` o error de autenticacion +**Sintoma**: ``Failed to connect to .`` **Verifique**: @@ -373,7 +465,7 @@ Error de Conexion Error de Consulta ------------------ -**Sintoma**: ``SQLException`` o error de sintaxis SQL +**Sintoma**: ``Failed to execute the query.`` **Verifique**: @@ -381,6 +473,27 @@ Error de Consulta 2. Verifique que los nombres de columna sean correctos 3. Verifique que los nombres de tabla sean correctos +Parametros Faltantes +--------------------- + +**Sintoma**: ``The driver parameter is required.``, ``The url parameter is required.`` o ``The sql parameter is required.`` + +Falta un parametro obligatorio. Revise el campo de parametros. + +Solo Fallan Algunas Filas +-------------------------- + +Una fila que falla no detiene el rastreo; queda registrada en "Sistema" -> "URL con Errores". +Se usa la URL del documento cuando los scripts la generaron, y +``datastore:///`` cuando no. + +Los Documentos No Aparecen en los Resultados de Busqueda +--------------------------------------------------------- + +1. Verifique que los scripts establezcan ``url``, ``title`` y ``content`` +2. Verifique que el uso de mayusculas y minusculas de las etiquetas de columna coincida con el que usan los scripts (vease "Configuracion de Script") +3. Revise el numero de documentos en el registro del trabajo de rastreo + Informacion de Referencia ========================== diff --git a/fr/15.9/config/datastore/ds-database.rst b/fr/15.9/config/datastore/ds-database.rst index ca26051c..19cd1bec 100644 --- a/fr/15.9/config/datastore/ds-database.rst +++ b/fr/15.9/config/datastore/ds-database.rst @@ -35,38 +35,47 @@ Prérequis Installation du plugin ---------------------- -Méthode 1 : Déposer le fichier JAR directement +Méthode 1 : Installer depuis l'interface d'administration -:: +1. Ouvrir « Système » → « Plugins » +2. Téléverser le fichier JAR +3. Redémarrer |Fess| - # Téléchargement depuis Maven Central - wget https://repo1.maven.org/maven2/org/codelibs/fess/fess-ds-db/X.X.X/fess-ds-db-X.X.X.jar +Méthode 2 : Déposer le fichier JAR directement - # Déploiement - cp fess-ds-db-X.X.X.jar $FESS_HOME/app/WEB-INF/lib/ - # ou - cp fess-ds-db-X.X.X.jar /usr/share/fess/app/WEB-INF/lib/ +:: -Méthode 2 : Installer depuis l'interface d'administration + # Téléchargement depuis le dépôt CodeLibs + wget https://maven.codelibs.org/release/org/codelibs/fess/fess-ds-db/X.X.X/fess-ds-db-X.X.X.jar -1. Ouvrir « Système » → « Plugins » -2. Téléverser le fichier JAR -3. Redémarrer |Fess| + # Déploiement (le même répertoire que celui utilisé par l'interface d'administration) + cp fess-ds-db-X.X.X.jar $FESS_HOME/app/WEB-INF/plugin/ + # ou + cp fess-ds-db-X.X.X.jar /usr/share/fess/app/WEB-INF/plugin/ Installation du pilote JDBC ---------------------------- -Placez le pilote JDBC adapté à la base de données cible dans le répertoire ``app/WEB-INF/lib/`` du classpath de |Fess| : +Le pilote JDBC n'est pas fourni avec le plugin. Procurez-vous séparément le pilote adapté à votre base de données et déposez-le vous-même. + +Le crawl de DataStore s'exécute dans le processus du crawler ; le pilote doit donc se trouver dans le **classpath du processus du crawler**. L'un ou l'autre de ces répertoires convient : + +- ``app/WEB-INF/lib/`` +- ``app/WEB-INF/env/crawler/lib/`` :: # Exemple : pilote MySQL - cp mysql-connector-j-8.x.x.jar $FESS_HOME/app/WEB-INF/lib/ + cp mysql-connector-j-9.x.x.jar $FESS_HOME/app/WEB-INF/lib/ # ou - cp mysql-connector-j-8.x.x.jar /usr/share/fess/app/WEB-INF/lib/ + cp mysql-connector-j-9.x.x.jar /usr/share/fess/app/WEB-INF/lib/ Une fois le pilote JDBC déposé, redémarrez |Fess| pour le charger. +.. note:: + Lorsque le pilote est absent, le crawl échoue avec le message + ``The JDBC driver ... is not on the crawler classpath.`` + Méthode de configuration ======================== @@ -138,7 +147,10 @@ Liste des paramètres - Mot de passe de la base de données * - ``fetch_size`` - Non - - Taille de fetch JDBC. Pour le streaming de résultats MySQL, spécifiez ``MIN_VALUE`` + - Taille de fetch JDBC. ``MIN_VALUE`` demande à MySQL de lire le jeu de résultats ligne par ligne ; les autres pilotes rejettent une valeur négative, et le crawl se poursuit avec la valeur par défaut du pilote après un avertissement. Une valeur négative ou non numérique est signalée puis ignorée + * - ``query_timeout`` + - Non + - Délai d'expiration de la requête, en secondes. ``0`` signifie aucune limite (valeur par défaut de JDBC). Si le paramètre est absent, aucun délai n'est défini * - ``default_mimetype`` - Non - Type MIME par défaut utilisé lors de l'extraction du contenu des colonnes BLOB/binaires @@ -158,6 +170,12 @@ Liste des paramètres - Non - Type du moteur de script. Par défaut : groovy +.. note:: + Si une requête reste bloquée, arrêter le job ne libère pas le thread du crawler. + La demande d'arrêt n'est vérifiée qu'entre deux lignes : elle ne peut donc pas interrompre + un appel bloqué à l'intérieur du pilote. Définissez ``query_timeout`` pour les requêtes + susceptibles d'être longues. + Configuration du script ----------------------- @@ -173,19 +191,51 @@ Mappez les noms de colonnes SQL vers les champs d'index : Champs disponibles : - ```` - Colonnes du résultat de la requête SQL (accès direct par le nom de colonne. Aucun préfixe tel que ``data.`` n'est ajouté) +- ``crawlingConfig`` - la configuration du DataStore +- ``crawlingContext`` - le contexte du crawl ; ``crawlingContext.doc`` contient le document en cours de construction .. note:: Le nom de colonne doit correspondre au libellé de colonne (alias) de la clause ``SELECT``. Pour les fonctions d'agrégation ou les expressions, utilisez explicitement ``AS`` pour définir un alias (ex. : ``COUNT(*) AS total``). +.. note:: + La casse des libellés de colonne varie selon la base de données. PostgreSQL convertit les + identifiants non entourés de guillemets en minuscules, H2 les convertit en majuscules et + MySQL les renvoie tels qu'ils ont été déclarés. Un nom qui ne peut pas être résolu laisse + le champ non renseigné au lieu de provoquer une erreur : définissez donc explicitement un + alias avec ``AS`` lorsque la portabilité est importante. + +.. warning:: + Les scripts peuvent référencer **l'ensemble des paramètres du DataStore**, et pas seulement + les colonnes du résultat SQL. ``driver``, ``url``, ``username``, ``password`` et ``sql`` + sont tous visibles sous forme de variables portant le même nom : une colonne peut donc être + masquée involontairement, ou la valeur d'un paramètre peut apparaître là où une colonne + absente était attendue. Lorsque les deux existent, la valeur de la colonne l'emporte. + Chargement de données BLOB/binaires ===================================== -Les colonnes de type BLOB, CLOB, NCLOB, tableau d'octets ou flux binaire sont automatiquement -soumises au traitement d'extraction de contenu (le même extracteur que pour le crawl de fichiers) -et intégrées sous forme de texte. Les colonnes de type tableau sont converties en chaîne séparée -par des espaces. Les valeurs NULL deviennent des chaînes vides. +Les colonnes binaires (BLOB, ``BYTEA``, tableau d'octets, flux binaire) sont soumises au +traitement d'extraction de contenu - le même extracteur que pour le crawl de fichiers - et +intégrées sous forme de texte. + +Les CLOB, NCLOB et flux de caractères ne passent **pas** par un extracteur. Ils sont lus tels +quels sous forme de texte, et les indications de type MIME décrites ci-dessous ne s'appliquent +pas à eux. + +Les colonnes de type tableau deviennent leurs éléments joints par des espaces. Les valeurs NULL +deviennent des chaînes vides. + +.. note:: + Le fait qu'une colonne BLOB arrive sous forme de ``java.sql.Blob`` ou de tableau d'octets + dépend du pilote JDBC - MySQL et PostgreSQL renvoient un tableau d'octets. Les deux sont + extraits de la même manière. + +.. note:: + Les CLOB et NCLOB sont lus intégralement en mémoire, sans limite de taille. Pour des colonnes + de texte très volumineuses, envisagez de les tronquer en SQL avec ``SUBSTRING`` ou équivalent. + Le chemin passant par l'extracteur respecte, lui, la taille maximale de contenu du crawler. Pour extraire correctement du texte depuis des BLOB ou des flux binaires, il est nécessaire de déterminer le type de données (type MIME). La priorité de détermination est la suivante : @@ -230,6 +280,18 @@ Méthode pour récupérer uniquement les enregistrements mis à jour : # Spécification de plage par ID sql=SELECT * FROM articles WHERE id > 10000 +.. warning:: + Restreindre la requête de cette manière ne transforme pas le crawl en crawl + incrémental. À la fin d'un crawl, |Fess| supprime les documents de cette + configuration du DataStore qui ne faisaient pas partie du crawl qui vient de + s'exécuter : une requête filtrée ne laisse donc dans l'index que les lignes + correspondantes. + + Ajoutez ``delete_old_docs=false`` aux paramètres du DataStore pour conserver les + documents indexés par les crawls précédents. Les lignes supprimées de la base de + données ne sont alors plus retirées de l'index non plus : exécutez donc + périodiquement un crawl complet. + Génération d'URL ---------------- @@ -246,6 +308,13 @@ L'URL du document est générée par le script : # Utilisation de l'URL stockée dans la base de données url=url +.. warning:: + ``url=url`` ne fait ce à quoi on s'attend que si le résultat du ``SELECT`` comporte une + colonne portant le libellé ``url``. En l'absence d'une telle colonne, c'est le paramètre du + DataStore de même nom - autrement dit l'**URL de connexion JDBC** - qui devient l'URL du + document. Définissez un alias pour la colonne, comme dans ``SELECT page_url AS url``, ou + indiquez-la dans le script, comme dans ``url=page_url``. + Prise en charge des caractères multi-octets ============================================ @@ -278,10 +347,33 @@ Protection des identifiants de base de données Méthodes recommandées : -1. Utiliser des variables d'environnement -2. Utiliser la fonctionnalité de chiffrement de |Fess| +1. S'appuyer sur le chiffrement automatique + + La valeur d'un paramètre dont le nom correspond à ``app.encrypt.property.pattern`` + (par défaut ``.*password|.*key|.*token|.*secret``) est chiffrée lors de l'enregistrement + depuis l'interface d'administration et stockée avec le préfixe ``{cipher}``. ``password`` + correspond à ce motif : il n'est donc pas stocké en clair lorsqu'il est défini depuis + l'interface d'administration. + +2. Utiliser des variables d'environnement + + Une variable d'environnement dont le nom commence par ``FESS_ENV_`` est développée à + l'intérieur d'un paramètre du DataStore sous la forme ``${nom de la variable}`` : + + :: + + password=${FESS_ENV_DB_PASSWORD} + + Les noms développés sont déterminés par ``crawler.data.env.param.key.pattern`` + (par défaut ``^FESS_ENV_.*``). + 3. Utiliser un utilisateur en lecture seule +.. note:: + Passer ``org.codelibs.fess.ds`` en DEBUG n'expose pas les identifiants : les valeurs des + paramètres correspondant à ``app.encrypt.property.pattern``, ainsi que les identifiants + intégrés dans l'URL JDBC, sont masqués dans le journal. + Principe du moindre privilège ------------------------------ @@ -346,21 +438,23 @@ Script : Dépannage ========= +Lorsqu'un crawl échoue, le message du journal indique quelle étape a échoué. + Pilote JDBC introuvable ----------------------- -**Symptôme** : ``ClassNotFoundException`` ou ``No suitable driver`` +**Symptôme** : ``The JDBC driver ... is not on the crawler classpath.`` **Solution** : -1. Vérifiez que le pilote JDBC est placé dans ``lib/`` -2. Vérifiez que le nom de classe du pilote est correct +1. Vérifiez que le pilote JDBC est placé dans ``app/WEB-INF/lib/`` ou ``app/WEB-INF/env/crawler/lib/`` +2. Vérifiez que le nom de classe indiqué dans ``driver`` est correct 3. Redémarrez |Fess| Erreur de connexion -------------------- -**Symptôme** : ``Connection refused`` ou erreur d'authentification +**Symptôme** : ``Failed to connect to .`` **Points à vérifier** : @@ -372,7 +466,7 @@ Erreur de connexion Erreur de requête ----------------- -**Symptôme** : ``SQLException`` ou erreur de syntaxe SQL +**Symptôme** : ``Failed to execute the query.`` **Points à vérifier** : @@ -380,6 +474,27 @@ Erreur de requête 2. Vérifiez que les noms de colonnes sont corrects 3. Vérifiez que les noms de tables sont corrects +Paramètres manquants +-------------------- + +**Symptôme** : ``The driver parameter is required.``, ``The url parameter is required.`` ou ``The sql parameter is required.`` + +Un paramètre obligatoire n'est pas défini. Vérifiez le champ des paramètres. + +Seules certaines lignes échouent +-------------------------------- + +Une ligne en échec n'interrompt pas le crawl : elle est enregistrée sous « Système » → +« URL en échec ». L'URL du document est utilisée lorsque les scripts en ont produit une, et +``datastore:///`` dans le cas contraire. + +Les documents n'apparaissent pas dans les résultats de recherche +---------------------------------------------------------------- + +1. Vérifiez que les scripts définissent ``url``, ``title`` et ``content`` +2. Vérifiez que la casse des libellés de colonne correspond à celle utilisée par les scripts (voir « Configuration du script ») +3. Vérifiez le nombre de documents dans le journal du job de crawl + Informations de référence ========================== diff --git a/ja/15.9/config/datastore/ds-database.rst b/ja/15.9/config/datastore/ds-database.rst index f125307f..9ad52488 100644 --- a/ja/15.9/config/datastore/ds-database.rst +++ b/ja/15.9/config/datastore/ds-database.rst @@ -35,38 +35,47 @@ JDBC対応のすべてのデータベースに対応しています。主な例: プラグインのインストール ------------------------ -方法1: JARファイルを直接配置 +方法1: 管理画面からインストール -:: +1. 「システム」→「プラグイン」を開く +2. JARファイルをアップロード +3. |Fess| を再起動 - # Maven Centralからダウンロード - wget https://repo1.maven.org/maven2/org/codelibs/fess/fess-ds-db/X.X.X/fess-ds-db-X.X.X.jar +方法2: JARファイルを直接配置 - # 配置 - cp fess-ds-db-X.X.X.jar $FESS_HOME/app/WEB-INF/lib/ - # または - cp fess-ds-db-X.X.X.jar /usr/share/fess/app/WEB-INF/lib/ +:: -方法2: 管理画面からインストール + # CodeLibsリポジトリからダウンロード + wget https://maven.codelibs.org/release/org/codelibs/fess/fess-ds-db/X.X.X/fess-ds-db-X.X.X.jar -1. 「システム」→「プラグイン」を開く -2. JARファイルをアップロード -3. |Fess| を再起動 + # 配置（管理画面からのインストール先と同じディレクトリ） + cp fess-ds-db-X.X.X.jar $FESS_HOME/app/WEB-INF/plugin/ + # または + cp fess-ds-db-X.X.X.jar /usr/share/fess/app/WEB-INF/plugin/ JDBCドライバーのインストール ---------------------------- -接続先データベースに対応したJDBCドライバーを |Fess| のクラスパス（ ``app/WEB-INF/lib/`` ディレクトリ）に配置します: +JDBCドライバーはプラグインに含まれていません。接続先データベースに対応したドライバーを別途入手して配置してください。 + +データストアクロールはクローラープロセスで実行されるため、ドライバーは **クローラープロセスのクラスパス** に置く必要があります。次のいずれかのディレクトリが該当します: + +- ``app/WEB-INF/lib/`` +- ``app/WEB-INF/env/crawler/lib/`` :: # 例: MySQLドライバー - cp mysql-connector-j-8.x.x.jar $FESS_HOME/app/WEB-INF/lib/ + cp mysql-connector-j-9.x.x.jar $FESS_HOME/app/WEB-INF/lib/ # または - cp mysql-connector-j-8.x.x.jar /usr/share/fess/app/WEB-INF/lib/ + cp mysql-connector-j-9.x.x.jar /usr/share/fess/app/WEB-INF/lib/ JDBCドライバーを配置したら |Fess| を再起動して読み込みます。 +.. note:: + ドライバーが見つからない場合、クロールは + ``The JDBC driver ... is not on the crawler classpath.`` というメッセージで失敗します。 + 設定方法 ======== @@ -138,7 +147,10 @@ PostgreSQLの例: - データベースパスワード * - ``fetch_size`` - いいえ - - JDBCフェッチサイズ。MySQLのストリーミング結果セットには ``MIN_VALUE`` を指定 + - JDBCフェッチサイズ。``MIN_VALUE`` はMySQLで結果セットを1行ずつ読み込ませるための指定で、他のドライバーは負の値を受け付けません（警告を出してドライバー既定値で継続します）。負の値や数値以外は警告を出して無視されます + * - ``query_timeout`` + - いいえ + - クエリのタイムアウト（秒）。``0`` は無制限（JDBCの既定）。未指定の場合はタイムアウトを設定しません * - ``default_mimetype`` - いいえ - BLOB・バイナリ列のコンテンツ抽出時に使用するデフォルトMIMEタイプ @@ -158,6 +170,12 @@ PostgreSQLの例: - いいえ - スクリプトエンジンの種類。デフォルト: groovy +.. note:: + クエリがハングした場合、ジョブを停止してもクローラースレッドは解放されません。 + ジョブの停止は行と行の間でしか判定されないため、ドライバー内部でブロックしている + 呼び出しには効きません。長時間実行の可能性があるクエリには ``query_timeout`` + を設定してください。 + スクリプト設定 -------------- @@ -173,19 +191,48 @@ SQLの列名をインデックスフィールドにマッピングします: 利用可能なフィールド: - ```` - SQLクエリの結果列（カラムラベル名で直接アクセスします。\ ``data.`` のような接頭辞は付きません） +- ``crawlingConfig`` - データストア設定 +- ``crawlingContext`` - クロール中のコンテキスト。``crawlingContext.doc`` で構築中のドキュメントを参照できます .. note:: 列名は ``SELECT`` 句のカラムラベル（別名）と一致させる必要があります。 集計関数や式を使用する場合は ``AS`` で明示的に別名を付けてください （例: ``COUNT(*) AS total``）。 +.. note:: + カラムラベルの大文字・小文字はデータベースによって異なります。PostgreSQLは + 引用符で囲まない識別子を小文字に、H2は大文字に変換し、MySQLは宣言どおりに + 返します。スクリプトで参照した名前が解決できない場合、そのフィールドは + 何も設定されずに終わります（エラーにはなりません）。移植性を重視する場合は + ``AS`` で明示的に別名を付けてください。 + +.. warning:: + スクリプトからは、SQLの結果列だけでなく **データストアパラメーター全体** が + 同名の変数として参照できます。``driver`` ・ ``url`` ・ ``username`` ・ + ``password`` ・ ``sql`` なども変数として見えるため、これらと同じ名前の列を + 意図せず上書きしたり、逆に列が無いときにパラメーターの値が入り込んだり + します。同名の列がある場合は列の値が優先されます。 + BLOB・バイナリデータの取り込み ============================== -BLOB、CLOB、NCLOB、バイト配列、バイナリストリームなどの列は、自動的に -コンテンツ抽出処理（ファイルクロールと同じ抽出器）にかけられ、テキストとして -取り込まれます。配列型の列はスペース区切りの文字列に変換されます。NULL値は -空文字列になります。 +バイナリ列（BLOB・ ``BYTEA`` ・バイト配列・バイナリストリーム）は、コンテンツ抽出処理 +（ファイルクロールと同じ抽出器）にかけられ、テキストとして取り込まれます。 + +一方、CLOB・NCLOB・文字ストリームは **抽出器を通らず** 、文字列としてそのまま +読み込まれます。MIMEタイプの指定（後述）はこれらには適用されません。 + +配列型の列は要素をスペースで連結した文字列になります。NULL値は空文字列になります。 + +.. note:: + 同じBLOB列でも、JDBCドライバーによって ``java.sql.Blob`` を返すものと + バイト配列を返すものがあります（MySQLとPostgreSQLはバイト配列）。 + どちらの場合も同じように抽出されます。 + +.. note:: + CLOB・NCLOBはサイズ上限なしでメモリに読み込まれます。非常に大きな + テキスト列を扱う場合は、SQL側で ``SUBSTRING`` などを使って切り詰めることを + 検討してください。抽出器を通る経路にはクローラーの最大サイズ設定が適用されます。 BLOBやバイナリストリームから正しくテキストを抽出するには、データの種類（MIMEタイプ）を 判定する必要があります。判定には次の優先順位が使われます: @@ -230,6 +277,17 @@ SQLはそのままデータベースに送信されます（パラメーター # IDによる範囲指定 sql=SELECT * FROM articles WHERE id > 10000 +.. warning:: + このようにクエリを絞り込んでも、差分クロールになるわけではありません。 + クロールが完了すると、|Fess| は今回のクロールに含まれなかった + このデータストア設定のドキュメントをインデックスから削除するため、 + 条件に一致した行だけがインデックスに残ります。 + + 以前のクロールで登録したドキュメントを残す場合は、データストアパラメーターに + ``delete_old_docs=false`` を追加してください。この場合、データベースから削除された + 行に対応するドキュメントもインデックスから削除されなくなるため、定期的に + 全件クロールを実行してください。 + URLの生成 --------- @@ -246,6 +304,13 @@ URLの生成 # データベースに格納されたURLを使用 url=url +.. warning:: + ``url=url`` は、``SELECT`` の結果に ``url`` というラベルの列がある場合にのみ + 意図どおりに動きます。該当する列が無いと、同名のデータストアパラメーター、 + すなわち **JDBC接続URL** がドキュメントのURLとして設定されます。 + 列名が異なる場合は ``SELECT page_url AS url`` のように別名を付けるか、 + ``url=page_url`` のようにスクリプト側で列名を指定してください。 + マルチバイト文字対応 ==================== @@ -278,9 +343,31 @@ PostgreSQLは通常UTF-8がデフォルトです。必要に応じて: 推奨される方法: -1. 環境変数を使用 -2. |Fess| の暗号化機能を使用 -3. 読み取り専用ユーザーを使用 +1. 自動暗号化を利用する + + ``app.encrypt.property.pattern`` （デフォルト ``.*password|.*key|.*token|.*secret`` ） + に一致するパラメーター名の値は、管理画面から保存すると自動的に暗号化され、 + ``{cipher}`` 接頭辞付きで保存されます。``password`` はこのパターンに一致するため、 + 管理画面から設定していれば平文では保存されません。 + +2. 環境変数を使用する + + ``FESS_ENV_`` で始まる環境変数は、データストアパラメーターの中で + ``${環境変数名}`` として展開されます: + + :: + + password=${FESS_ENV_DB_PASSWORD} + + 展開対象となる環境変数名のパターンは ``crawler.data.env.param.key.pattern`` + （デフォルト ``^FESS_ENV_.*`` ）で設定します。 + +3. 読み取り専用ユーザーを使用する + +.. note:: + ``org.codelibs.fess.ds`` のログレベルをDEBUGにしても、パスワードなど + ``app.encrypt.property.pattern`` に一致するパラメーターの値と、JDBC接続URLに + 埋め込まれた資格情報はマスクされて出力されます。 最小権限の原則 -------------- @@ -346,21 +433,23 @@ PostgreSQLは通常UTF-8がデフォルトです。必要に応じて: トラブルシューティング ====================== +クロールが失敗したときは、まずログのメッセージで原因を切り分けます。 + JDBCドライバーが見つからない ---------------------------- -**症状**: ``ClassNotFoundException`` または ``No suitable driver`` +**症状**: ``The JDBC driver ... is not on the crawler classpath.`` **解決方法**: -1. JDBCドライバーが ``lib/`` に配置されているか確認 -2. ドライバーのクラス名が正しいか確認 +1. JDBCドライバーが ``app/WEB-INF/lib/`` または ``app/WEB-INF/env/crawler/lib/`` に配置されているか確認 +2. ``driver`` に指定したクラス名が正しいか確認 3. |Fess| を再起動 接続エラー ---------- -**症状**: ``Connection refused`` または認証エラー +**症状**: ``Failed to connect to .`` **確認事項**: @@ -372,7 +461,7 @@ JDBCドライバーが見つからない クエリエラー ------------ -**症状**: ``SQLException`` やSQLシンタックスエラー +**症状**: ``Failed to execute the query.`` **確認事項**: @@ -380,6 +469,27 @@ JDBCドライバーが見つからない 2. 列名が正しいか確認 3. テーブル名が正しいか確認 +設定漏れ +-------- + +**症状**: ``The driver parameter is required.`` ・ ``The url parameter is required.`` ・ ``The sql parameter is required.`` + +必須パラメーターが設定されていません。パラメーター欄を確認してください。 + +一部の行だけ失敗する +-------------------- + +行単位の失敗はクロールを中断せず、「システム」→「障害URL」に記録されます。 +スクリプトがURLを生成できていればそのURLで、生成前に失敗した場合は +``datastore://<データストア設定ID>/<行番号>`` として記録されます。 + +検索結果に出てこない +-------------------- + +1. スクリプトで ``url`` と ``title`` ・ ``content`` が設定されているか確認 +2. カラムラベルの大文字・小文字がスクリプトと一致しているか確認（「スクリプト設定」を参照） +3. クロールジョブのログでドキュメント数を確認 + 参考情報 ======== diff --git a/ko/15.9/config/datastore/ds-database.rst b/ko/15.9/config/datastore/ds-database.rst index e1460382..7ddc928f 100644 --- a/ko/15.9/config/datastore/ds-database.rst +++ b/ko/15.9/config/datastore/ds-database.rst @@ -35,38 +35,47 @@ JDBC 호환 모든 데이터베이스를 지원합니다. 주요 예: 플러그인 설치 ------------- -방법1: JAR 파일을 직접 배치 +방법1: 관리 화면에서 설치 -:: +1. "시스템" → "플러그인"을 엽니다 +2. JAR 파일을 업로드 +3. |Fess| 를 재시작 - # Maven Central에서 다운로드 - wget https://repo1.maven.org/maven2/org/codelibs/fess/fess-ds-db/X.X.X/fess-ds-db-X.X.X.jar +방법2: JAR 파일을 직접 배치 - # 배치 - cp fess-ds-db-X.X.X.jar $FESS_HOME/app/WEB-INF/lib/ - # 또는 - cp fess-ds-db-X.X.X.jar /usr/share/fess/app/WEB-INF/lib/ +:: -방법2: 관리 화면에서 설치 + # CodeLibs 리포지토리에서 다운로드 + wget https://maven.codelibs.org/release/org/codelibs/fess/fess-ds-db/X.X.X/fess-ds-db-X.X.X.jar -1. "시스템" → "플러그인"을 엽니다 -2. JAR 파일을 업로드 -3. |Fess| 를 재시작 + # 배치（관리 화면에서 설치되는 디렉터리와 동일） + cp fess-ds-db-X.X.X.jar $FESS_HOME/app/WEB-INF/plugin/ + # 또는 + cp fess-ds-db-X.X.X.jar /usr/share/fess/app/WEB-INF/plugin/ JDBC 드라이버 설치 ------------------ -연결 대상 데이터베이스에 맞는 JDBC 드라이버를 |Fess| 의 클래스패스（ ``app/WEB-INF/lib/`` 디렉터리）에 배치합니다: +JDBC 드라이버는 플러그인에 포함되어 있지 않습니다. 연결 대상 데이터베이스에 맞는 드라이버를 별도로 입수하여 배치하십시오. + +데이터스토어 크롤링은 크롤러 프로세스에서 실행되므로, 드라이버는 **크롤러 프로세스의 클래스패스** 에 배치해야 합니다. 다음 디렉터리 중 하나가 해당됩니다: + +- ``app/WEB-INF/lib/`` +- ``app/WEB-INF/env/crawler/lib/`` :: # 예: MySQL 드라이버 - cp mysql-connector-j-8.x.x.jar $FESS_HOME/app/WEB-INF/lib/ + cp mysql-connector-j-9.x.x.jar $FESS_HOME/app/WEB-INF/lib/ # 또는 - cp mysql-connector-j-8.x.x.jar /usr/share/fess/app/WEB-INF/lib/ + cp mysql-connector-j-9.x.x.jar /usr/share/fess/app/WEB-INF/lib/ JDBC 드라이버를 배치한 후 |Fess| 를 재시작하여 로드합니다. +.. note:: + 드라이버를 찾을 수 없는 경우, 크롤링은 + ``The JDBC driver ... is not on the crawler classpath.`` 메시지와 함께 실패합니다. + 설정 방법 ========= @@ -138,7 +147,10 @@ PostgreSQL 예: - 데이터베이스 비밀번호 * - ``fetch_size`` - 아니요 - - JDBC 페치 크기. MySQL의 스트리밍 결과 세트에는 ``MIN_VALUE`` 를 지정 + - JDBC 페치 크기. ``MIN_VALUE`` 는 MySQL에서 결과 세트를 한 행씩 읽게 하기 위한 지정이며, 다른 드라이버는 음수 값을 받아들이지 않습니다（경고를 출력하고 드라이버 기본값으로 계속합니다）. 음수 값이나 숫자가 아닌 값은 경고를 출력하고 무시됩니다 + * - ``query_timeout`` + - 아니요 + - 쿼리 타임아웃（초）. ``0`` 은 무제한（JDBC 기본값）. 미지정 시 타임아웃을 설정하지 않습니다 * - ``default_mimetype`` - 아니요 - BLOB·바이너리 열의 콘텐츠 추출 시 사용할 기본 MIME 타입 @@ -158,6 +170,12 @@ PostgreSQL 예: - 아니요 - 스크립트 엔진의 종류. 기본값: groovy +.. note:: + 쿼리가 멈춘 경우, 작업을 중지해도 크롤러 스레드는 해제되지 않습니다. + 중지 요청은 행과 행 사이에서만 확인되므로, 드라이버 내부에서 블록된 호출에는 + 효과가 없습니다. 장시간 실행될 가능성이 있는 쿼리에는 ``query_timeout`` 을 + 설정하십시오. + 스크립트 설정 ------------- @@ -173,19 +191,47 @@ SQL 열 이름을 인덱스 필드에 매핑합니다: 사용 가능한 필드: - ```` - SQL 쿼리 결과의 열（컬럼 라벨명으로 직접 접근합니다. ``data.`` 와 같은 접두사는 붙지 않습니다） +- ``crawlingConfig`` - 데이터스토어 설정 +- ``crawlingContext`` - 크롤링 중의 컨텍스트. ``crawlingContext.doc`` 로 생성 중인 문서를 참조할 수 있습니다 .. note:: 열 이름은 ``SELECT`` 절의 컬럼 라벨（별칭）과 일치시켜야 합니다. 집계 함수나 식을 사용하는 경우 ``AS`` 로 명시적으로 별칭을 붙여 주세요 （예: ``COUNT(*) AS total``）. +.. note:: + 컬럼 라벨의 대소문자는 데이터베이스마다 다릅니다. PostgreSQL은 따옴표로 감싸지 않은 + 식별자를 소문자로, H2는 대문자로 변환하며, MySQL은 선언한 그대로 반환합니다. + 스크립트에서 참조한 이름을 해석할 수 없는 경우, 해당 필드는 오류 없이 설정되지 않은 + 상태로 남습니다. 이식성이 중요한 경우에는 ``AS`` 로 명시적으로 별칭을 붙여 주세요. + +.. warning:: + 스크립트에서는 SQL 결과 열뿐만 아니라 **데이터스토어 파라미터 전체** 를 같은 이름의 + 변수로 참조할 수 있습니다. ``driver`` ・ ``url`` ・ ``username`` ・ ``password`` ・ + ``sql`` 등도 변수로 보이기 때문에, 같은 이름의 열이 의도치 않게 가려지거나, 반대로 + 열이 없을 때 파라미터 값이 들어갈 수 있습니다. 같은 이름의 열이 있는 경우에는 열의 + 값이 우선합니다. + BLOB·바이너리 데이터 취득 ========================== -BLOB, CLOB, NCLOB, 바이트 배열, 바이너리 스트림 등의 열은 자동으로 -콘텐츠 추출 처리（파일 크롤링과 동일한 추출기）에 적용되어 텍스트로 -취득됩니다. 배열형 열은 공백으로 구분된 문자열로 변환됩니다. NULL 값은 -빈 문자열이 됩니다. +바이너리 열（BLOB・ ``BYTEA`` ・바이트 배열・바이너리 스트림）은 콘텐츠 추출 처리 +（파일 크롤링과 동일한 추출기）에 적용되어 텍스트로 취득됩니다. + +한편 CLOB・NCLOB・문자 스트림은 **추출기를 거치지 않고** 문자열로 그대로 읽힙니다. +MIME 타입 지정（후술）은 이들에는 적용되지 않습니다. + +배열형 열은 요소를 공백으로 연결한 문자열이 됩니다. NULL 값은 빈 문자열이 됩니다. + +.. note:: + 같은 BLOB 열이라도 JDBC 드라이버에 따라 ``java.sql.Blob`` 을 반환하는 것과 바이트 + 배열을 반환하는 것이 있습니다（MySQL과 PostgreSQL은 바이트 배열）. 어느 쪽이든 + 동일하게 추출됩니다. + +.. note:: + CLOB・NCLOB은 크기 제한 없이 메모리에 읽어 들입니다. 매우 큰 텍스트 열을 다루는 + 경우에는 SQL 측에서 ``SUBSTRING`` 등을 사용하여 잘라내는 것을 검토하십시오. + 추출기를 거치는 경로에는 크롤러의 최대 크기 설정이 적용됩니다. BLOB나 바이너리 스트림에서 올바르게 텍스트를 추출하려면 데이터의 종류（MIME 타입）를 판별해야 합니다. 판별에는 다음 우선순위가 사용됩니다: @@ -230,6 +276,15 @@ SQL은 그대로 데이터베이스에 전송됩니다（파라미터 바인딩 # ID로 범위 지정 sql=SELECT * FROM articles WHERE id > 10000 +.. warning:: + 이렇게 쿼리를 좁혀도 차분 크롤링이 되는 것은 아닙니다. 크롤링이 끝나면 |Fess| 는 방금 + 실행한 크롤링에 포함되지 않은 이 데이터스토어 설정의 문서를 삭제하므로, 필터를 건 쿼리는 + 조건에 일치하는 행만 인덱스에 남기게 됩니다. + + 이전 크롤링에서 인덱싱한 문서를 유지하려면 데이터스토어 파라미터에 + ``delete_old_docs=false`` 를 추가하십시오. 그러면 데이터베이스에서 삭제된 행도 더 이상 + 인덱스에서 제거되지 않으므로, 정기적으로 전체 크롤링을 실행하십시오. + URL 생성 -------- @@ -246,6 +301,13 @@ URL 생성 # 데이터베이스에 저장된 URL 사용 url=url +.. warning:: + ``url=url`` 은 ``SELECT`` 결과에 ``url`` 이라는 라벨의 열이 있는 경우에만 의도대로 + 동작합니다. 해당하는 열이 없으면 같은 이름의 데이터스토어 파라미터, 즉 + **JDBC 연결 URL** 이 문서의 URL로 설정됩니다. 열 이름이 다른 경우에는 + ``SELECT page_url AS url`` 과 같이 별칭을 붙이거나, ``url=page_url`` 과 같이 + 스크립트 측에서 열 이름을 지정하십시오. + 다국어 문자 지원 ================ @@ -278,10 +340,32 @@ PostgreSQL은 보통 UTF-8이 기본입니다. 필요한 경우: 권장 방법: -1. 환경 변수 사용 -2. |Fess| 의 암호화 기능 사용 +1. 자동 암호화 이용 + + ``app.encrypt.property.pattern`` （기본값 ``.*password|.*key|.*token|.*secret`` ）에 + 일치하는 파라미터 이름의 값은 관리 화면에서 저장하면 자동으로 암호화되어 + ``{cipher}`` 접두사가 붙은 상태로 저장됩니다. ``password`` 는 이 패턴에 일치하므로, + 관리 화면에서 설정했다면 평문으로 저장되지 않습니다. + +2. 환경 변수 사용 + + ``FESS_ENV_`` 로 시작하는 환경 변수는 데이터스토어 파라미터 안에서 + ``${환경 변수명}`` 으로 전개됩니다: + + :: + + password=${FESS_ENV_DB_PASSWORD} + + 전개 대상이 되는 환경 변수 이름의 패턴은 ``crawler.data.env.param.key.pattern`` + （기본값 ``^FESS_ENV_.*`` ）으로 설정합니다. + 3. 읽기 전용 사용자 사용 +.. note:: + ``org.codelibs.fess.ds`` 의 로그 레벨을 DEBUG로 설정해도, 비밀번호 등 + ``app.encrypt.property.pattern`` 에 일치하는 파라미터의 값과 JDBC 연결 URL에 + 포함된 인증 정보는 마스킹되어 출력됩니다. + 최소 권한 원칙 -------------- @@ -346,21 +430,23 @@ PostgreSQL은 보통 UTF-8이 기본입니다. 필요한 경우: 문제 해결 ========= +크롤링이 실패했을 때는 먼저 로그의 메시지로 원인을 구분합니다. + JDBC 드라이버를 찾을 수 없음 ----------------------------- -**증상**: ``ClassNotFoundException`` 또는 ``No suitable driver`` +**증상**: ``The JDBC driver ... is not on the crawler classpath.`` **해결 방법**: -1. JDBC 드라이버가 ``lib/`` 에 배치되어 있는지 확인 -2. 드라이버의 클래스명이 올바른지 확인 +1. JDBC 드라이버가 ``app/WEB-INF/lib/`` 또는 ``app/WEB-INF/env/crawler/lib/`` 에 배치되어 있는지 확인 +2. ``driver`` 에 지정한 클래스명이 올바른지 확인 3. |Fess| 재시작 연결 오류 --------- -**증상**: ``Connection refused`` 또는 인증 오류 +**증상**: ``Failed to connect to .`` **확인 사항**: @@ -372,7 +458,7 @@ JDBC 드라이버를 찾을 수 없음 쿼리 오류 --------- -**증상**: ``SQLException`` 또는 SQL 구문 오류 +**증상**: ``Failed to execute the query.`` **확인 사항**: @@ -380,6 +466,27 @@ JDBC 드라이버를 찾을 수 없음 2. 열 이름이 올바른지 확인 3. 테이블 이름이 올바른지 확인 +설정 누락 +--------- + +**증상**: ``The driver parameter is required.`` ・ ``The url parameter is required.`` ・ ``The sql parameter is required.`` + +필수 파라미터가 설정되어 있지 않습니다. 파라미터 란을 확인하십시오. + +일부 행만 실패함 +---------------- + +행 단위의 실패는 크롤링을 중단시키지 않으며, "시스템" → "장애 URL"에 기록됩니다. +스크립트가 URL을 생성했다면 그 URL로, 생성 전에 실패한 경우에는 +``datastore://<데이터스토어 설정 ID>/<행 번호>`` 로 기록됩니다. + +검색 결과에 나오지 않음 +----------------------- + +1. 스크립트에서 ``url`` ・ ``title`` ・ ``content`` 가 설정되어 있는지 확인 +2. 컬럼 라벨의 대소문자가 스크립트와 일치하는지 확인（「스크립트 설정」 참조） +3. 크롤링 작업의 로그에서 문서 수를 확인 + 참고 정보 ========= diff --git a/zh-cn/15.9/config/datastore/ds-database.rst b/zh-cn/15.9/config/datastore/ds-database.rst index 1632242d..1e2e3310 100644 --- a/zh-cn/15.9/config/datastore/ds-database.rst +++ b/zh-cn/15.9/config/datastore/ds-database.rst @@ -35,38 +35,47 @@ 插件安装 -------- -方法1：直接放置JAR文件 +方法1：从管理界面安装 -:: +1. 打开"系统"→"插件" +2. 上传JAR文件 +3. 重启 |Fess| - # 从Maven Central下载 - wget https://repo1.maven.org/maven2/org/codelibs/fess/fess-ds-db/X.X.X/fess-ds-db-X.X.X.jar +方法2：直接放置JAR文件 - # 放置 - cp fess-ds-db-X.X.X.jar $FESS_HOME/app/WEB-INF/lib/ - # 或 - cp fess-ds-db-X.X.X.jar /usr/share/fess/app/WEB-INF/lib/ +:: -方法2：从管理界面安装 + # 从CodeLibs仓库下载 + wget https://maven.codelibs.org/release/org/codelibs/fess/fess-ds-db/X.X.X/fess-ds-db-X.X.X.jar -1. 打开"系统"→"插件" -2. 上传JAR文件 -3. 重启 |Fess| + # 放置（与从管理界面安装时的目录相同） + cp fess-ds-db-X.X.X.jar $FESS_HOME/app/WEB-INF/plugin/ + # 或 + cp fess-ds-db-X.X.X.jar /usr/share/fess/app/WEB-INF/plugin/ JDBC驱动程序安装 ---------------- -将对应连接数据库的JDBC驱动程序放置在 |Fess| 的类路径（ ``app/WEB-INF/lib/`` 目录）中： +JDBC驱动程序未包含在插件中。请另行获取对应连接数据库的驱动程序并自行放置。 + +数据存储爬取在爬虫进程中执行，因此驱动程序必须位于 **爬虫进程的类路径** 中。以下任一目录均可： + +- ``app/WEB-INF/lib/`` +- ``app/WEB-INF/env/crawler/lib/`` :: # 示例：MySQL驱动程序 - cp mysql-connector-j-8.x.x.jar $FESS_HOME/app/WEB-INF/lib/ + cp mysql-connector-j-9.x.x.jar $FESS_HOME/app/WEB-INF/lib/ # 或 - cp mysql-connector-j-8.x.x.jar /usr/share/fess/app/WEB-INF/lib/ + cp mysql-connector-j-9.x.x.jar /usr/share/fess/app/WEB-INF/lib/ 放置JDBC驱动程序后，重启 |Fess| 以加载驱动程序。 +.. note:: + 找不到驱动程序时，爬取将以 + ``The JDBC driver ... is not on the crawler classpath.`` 消息失败。 + 设置方法 ======== @@ -138,7 +147,10 @@ PostgreSQL示例： - 数据库密码 * - ``fetch_size`` - 否 - - JDBC获取大小。MySQL流式结果集请指定 ``MIN_VALUE`` + - JDBC获取大小。``MIN_VALUE`` 用于让MySQL逐行读取结果集，其他驱动程序不接受负值（将输出警告并以驱动程序默认值继续）。负值或非数值将输出警告并被忽略 + * - ``query_timeout`` + - 否 + - 查询超时时间（秒）。``0`` 表示无限制（JDBC默认值）。未指定该参数时不设置超时 * - ``default_mimetype`` - 否 - 提取BLOB/二进制列内容时使用的默认MIME类型 @@ -158,6 +170,11 @@ PostgreSQL示例： - 否 - 脚本引擎类型。默认值：groovy +.. note:: + 查询挂起时，即使停止作业也不会释放爬虫线程。 + 停止请求只在行与行之间进行判断，因此对在驱动程序内部阻塞的调用无效。 + 对于可能长时间执行的查询，请设置 ``query_timeout``。 + 脚本设置 -------- @@ -173,19 +190,44 @@ PostgreSQL示例： 可用字段： - ```` - SQL查询的结果列（直接使用列标签名称访问，不带 ``data.`` 等前缀） +- ``crawlingConfig`` - 数据存储配置 +- ``crawlingContext`` - 爬取过程中的上下文。可通过 ``crawlingContext.doc`` 引用正在构建的文档 .. note:: 列名需与 ``SELECT`` 子句中的列标签（别名）一致。 使用聚合函数或表达式时，请用 ``AS`` 明确指定别名 （例：``COUNT(*) AS total``）。 +.. note:: + 列标签的大小写因数据库而异。PostgreSQL会将未加引号的标识符转换为小写， + H2会转换为大写，而MySQL则按声明原样返回。若脚本中引用的名称无法解析， + 该字段将保持未设置状态（不会报错）。若重视可移植性，请用 ``AS`` 明确指定别名。 + +.. warning:: + 脚本不仅可以引用SQL的结果列，还可以将 **整个数据存储参数** 作为同名变量引用。 + ``driver`` 、 ``url`` 、 ``username`` 、 ``password`` 、 ``sql`` 等也会作为变量可见， + 因此可能会意外遮蔽同名的列，或者在列不存在时混入参数的值。 + 当存在同名的列时，以列的值优先。 + BLOB/二进制数据的导入 ===================== -BLOB、CLOB、NCLOB、字节数组、二进制流等列将自动经过 -内容提取处理（与文件爬取使用相同的提取器），以文本形式 -导入。数组类型的列将转换为空格分隔的字符串。NULL值将 -变为空字符串。 +二进制列（BLOB、 ``BYTEA`` 、字节数组、二进制流）会经过内容提取处理 +（与文件爬取使用相同的提取器），以文本形式导入。 + +另一方面，CLOB、NCLOB和字符流 **不会经过提取器** ，而是直接按字符串读取。 +下述MIME类型的指定对它们不适用。 + +数组类型的列将变为以空格连接各元素的字符串。NULL值将变为空字符串。 + +.. note:: + 即使是同样的BLOB列，不同的JDBC驱动程序有的返回 ``java.sql.Blob`` ，有的返回字节数组 + （MySQL和PostgreSQL返回字节数组）。两者的提取方式相同。 + +.. note:: + CLOB、NCLOB会不受大小限制地全部读入内存。处理非常大的文本列时， + 请考虑在SQL端使用 ``SUBSTRING`` 等进行截断。经过提取器的路径则会应用 + 爬虫的最大内容长度设置。 要从BLOB或二进制流中正确提取文本，需要判断数据类型（MIME类型）。 判断时使用以下优先顺序： @@ -230,6 +272,13 @@ SQL将原样发送到数据库（不进行参数绑定）： # 按ID范围指定 sql=SELECT * FROM articles WHERE id > 10000 +.. warning:: + 像这样缩小查询范围并不会让爬取变成增量抓取。爬取结束后， |Fess| 会删除该数据存储配置中 + 未包含在本次爬取内的文档，因此使用了过滤条件的查询会使索引中只剩下匹配的行。 + + 若要保留此前爬取已建立索引的文档，请在数据存储参数中添加 ``delete_old_docs=false``。 + 这样一来，数据库中已删除的行也不会再从索引中移除，因此请定期执行全量爬取。 + URL生成 ------- @@ -246,6 +295,12 @@ URL生成 # 使用存储在数据库中的URL url=url +.. warning:: + 只有当 ``SELECT`` 的结果中存在标签为 ``url`` 的列时， ``url=url`` 才会按预期工作。 + 若不存在对应的列，则同名的数据存储参数，即 **JDBC连接URL** 会被设置为文档的URL。 + 若列名不同，请像 ``SELECT page_url AS url`` 那样指定别名，或像 ``url=page_url`` + 那样在脚本中指定列名。 + 多字节字符支持 ============== @@ -278,10 +333,30 @@ PostgreSQL通常默认使用UTF-8。如有需要： 推荐方法： -1. 使用环境变量 -2. 使用 |Fess| 的加密功能 +1. 利用自动加密 + + 与 ``app.encrypt.property.pattern`` （默认值 ``.*password|.*key|.*token|.*secret`` ） + 匹配的参数名，其值在从管理界面保存时会自动加密，并以 ``{cipher}`` 前缀保存。 + ``password`` 与该模式匹配，因此只要是从管理界面设置的，就不会以明文保存。 + +2. 使用环境变量 + + 以 ``FESS_ENV_`` 开头的环境变量，会在数据存储参数中以 ``${环境变量名}`` 的形式展开： + + :: + + password=${FESS_ENV_DB_PASSWORD} + + 展开对象的环境变量名模式通过 ``crawler.data.env.param.key.pattern`` + （默认值 ``^FESS_ENV_.*`` ）设置。 + 3. 使用只读用户 +.. note:: + 即使将 ``org.codelibs.fess.ds`` 的日志级别设为DEBUG，密码等与 + ``app.encrypt.property.pattern`` 匹配的参数值，以及嵌入在JDBC连接URL中的认证信息， + 也会被掩码后输出。 + 最小权限原则 ------------ @@ -346,21 +421,23 @@ PostgreSQL通常默认使用UTF-8。如有需要： 故障排除 ======== +爬取失败时，请先根据日志中的消息判断原因。 + 找不到JDBC驱动程序 ------------------ -**症状**：``ClassNotFoundException`` 或 ``No suitable driver`` +**症状**：``The JDBC driver ... is not on the crawler classpath.`` **解决方法**： -1. 确认JDBC驱动程序是否放置在 ``lib/`` 中 -2. 确认驱动程序类名是否正确 +1. 确认JDBC驱动程序是否放置在 ``app/WEB-INF/lib/`` 或 ``app/WEB-INF/env/crawler/lib/`` 中 +2. 确认 ``driver`` 中指定的类名是否正确 3. 重启 |Fess| 连接错误 -------- -**症状**：``Connection refused`` 或认证错误 +**症状**：``Failed to connect to .`` **检查项**： @@ -372,7 +449,7 @@ PostgreSQL通常默认使用UTF-8。如有需要： 查询错误 -------- -**症状**：``SQLException`` 或SQL语法错误 +**症状**：``Failed to execute the query.`` **检查项**： @@ -380,6 +457,27 @@ PostgreSQL通常默认使用UTF-8。如有需要： 2. 确认列名是否正确 3. 确认表名是否正确 +参数缺失 +-------- + +**症状**：``The driver parameter is required.`` 、 ``The url parameter is required.`` 、 ``The sql parameter is required.`` + +必填参数未设置。请确认参数栏。 + +仅部分行失败 +------------ + +单行的失败不会中断爬取，而是记录到"系统"→"故障URL"中。 +如果脚本已经生成了URL，则以该URL记录；如果在生成之前失败，则记录为 +``datastore://<数据存储配置ID>/<行号>`` 。 + +文档未出现在搜索结果中 +---------------------- + +1. 确认脚本中是否设置了 ``url`` 、 ``title`` 、 ``content`` +2. 确认列标签的大小写是否与脚本一致（参见"脚本设置"） +3. 在爬取作业的日志中确认文档数 + 参考信息 ========