Procedimientos de Actualización

Esta página describe los procedimientos para actualizar Fess de versiones anteriores a la versión más reciente.

Advertencia

Notas Importantes Antes de la Actualización

• Asegúrese de hacer un respaldo antes de la actualización

• Se recomienda encarecidamente validar la actualización en un entorno de prueba con anticipación

• El servicio se detendrá durante la actualización, por lo que configure un tiempo de mantenimiento apropiado

• Dependiendo de la versión, el formato del archivo de configuración puede haber cambiado

Versiones Compatibles

Estos procedimientos de actualización son compatibles con actualizaciones entre las siguientes versiones:

• Fess 14.x → Fess 15.9

• Fess 15.x → Fess 15.9

Importante

Fess 14.x es compatible con la serie OpenSearch 2.x, mientras que Fess 15.9 es compatible con OpenSearch 3.9.0. Los plugins de OpenSearch para Fess deben coincidir exactamente con la versión de OpenSearch, por lo que si actualiza desde la versión 14.x también es obligatorio actualizar la versión principal de OpenSearch. Consulte Paso 4: Actualización de OpenSearch.

Nota

Si actualiza desde versiones más antiguas (13.x o anteriores), puede ser necesaria una actualización gradual. Para más detalles, verifique las notas de lanzamiento.

Preparación Antes de la Actualización

Verificación de Compatibilidad de Versiones

Verifique la compatibilidad entre la versión de destino de actualización y la versión actual.

• Notas de Lanzamiento

• Requisitos del Sistema - Entorno de ejecución de Fess 15.9 (versiones de Java y OpenSearch)

Planificación del Tiempo de Inactividad

La actualización requiere la detención del sistema. Planifique el tiempo de inactividad considerando lo siguiente:

• Tiempo de respaldo: 10 minutos ~ varias horas (según la cantidad de datos)

• Tiempo de actualización: 10 ~ 30 minutos

• Tiempo de verificación de funcionamiento: 30 minutos ~ 1 hora

• Tiempo de reserva: 30 minutos

Tiempo de mantenimiento recomendado: Total 2 ~ 4 horas

Paso 1: Respaldo de Datos

Antes de la actualización, haga un respaldo de todos los datos.

Respaldo de Datos de Configuración

1. Respaldo desde la pantalla de administración

   Inicie sesión en la pantalla de administración y haga clic en «Información del sistema» → «Copia de seguridad».

   En la página de Copia de seguridad se listan los siguientes datos de configuración como elementos individuales. Haga clic en cada fila para descargarlos (son archivos individuales por elemento, no un único archivo ZIP. No existe una función de descarga masiva, por lo que debe descargar los elementos necesarios uno por uno).

   • fess_basic_config.bulk - Índices de configuración (ajustes de rastreo, programador, etiquetas, coincidencias de clave, roles, autenticación web/de archivos, entre 19 índices)

   • fess_config.bulk - Además de los 19 índices anteriores, incluye 25 índices con datos de ejecución, como información de rastreo, URL con errores, registros de tareas y colas de miniaturas (25 índices en total hasta 15.8; 15.9 añade el índice tag_type, que contiene las etiquetas de usuario, hasta 26)

   • fess_user.bulk - Usuarios, roles y grupos

   • system.properties - Configuración del sistema, incluidos los ajustes generales

   • fess.json - Configuración del índice (número de shards, index.knn, etc.)

   • doc.json - Mapeo de documentos (definiciones de campos)

   Nota

   fess_config.bulk incluye el contenido de fess_basic_config.bulk. Como respaldo de configuración antes de la actualización, basta con fess_basic_config.bulk, fess_user.bulk y system.properties. Sin embargo, si el origen es 15.9 o posterior y utiliza etiquetas de usuario, descargue también fess_config.bulk: el índice tag_type, que contiene las etiquetas de usuario, no está incluido en fess_basic_config.bulk (consulte Etiqueta de usuario).

   Nota

   Los datos de registro como los registros de búsqueda y clics (search_log.ndjson, click_log.ndjson, favorite_log.ndjson, user_info.ndjson; 15.9 ofrece también chat_log.ndjson) también pueden descargarse desde la misma página. No son necesarios si solo desea hacer un respaldo de la configuración. Tenga en cuenta que estos archivos *.ndjson no se pueden restaurar cargándolos desde la página de copia de seguridad (consulte «Procedimientos de Reversión»).

2. Respaldo de archivos de configuración

   Versión ZIP:

   $ cp /path/to/fess/app/WEB-INF/conf/system.properties /backup/
   $ cp /path/to/fess/app/WEB-INF/classes/fess_config.properties /backup/
   $ cp /path/to/fess/bin/fess.in.sh /backup/
   

   Versión RPM:

   $ sudo cp /etc/fess/system.properties /backup/
   $ sudo cp /etc/fess/fess_config.properties /backup/
   $ sudo cp /etc/sysconfig/fess /backup/
   

   Versión DEB:

   $ sudo cp /etc/fess/system.properties /backup/
   $ sudo cp /etc/fess/fess_config.properties /backup/
   $ sudo cp /etc/default/fess /backup/
   

   Nota

   /etc/sysconfig/fess (versión RPM) y /etc/default/fess (versión DEB) son archivos de variables de entorno que especifican FESS_PORT, FESS_HEAP_SIZE, SEARCH_ENGINE_HTTP_URL, FESS_DICTIONARY_PATH y otros valores. En la versión ZIP, la configuración equivalente se encuentra en bin/fess.in.sh.

3. Archivos de configuración personalizados

   Si tiene archivos de configuración personalizados, también haga un respaldo de ellos:

   $ cp /path/to/fess/app/WEB-INF/classes/log4j2.xml /backup/
   $ cp /path/to/fess/lib/classes/tomcat_config.properties /backup/
   

   Nota

   app/WEB-INF/classes/log4j2.xml es la configuración de registro del proceso principal (Web) de Fess. Los procesos hijos, como el rastreador, usan archivos independientes (app/WEB-INF/env/crawler/resources/log4j2.xml, entre otros: crawler, suggest, thumbnail y chunk, 4 en total). Si los ha modificado, incluya también estos archivos en el respaldo.

Respaldo de Datos de Índice

Haga un respaldo de los datos de índice de OpenSearch.

Método 1: Usar Función de Instantánea (Recomendado)

Use la función de instantánea de OpenSearch para hacer un respaldo del índice.

Nota

Para registrar un repositorio del sistema de archivos (fs), es necesario especificar previamente el directorio de destino del respaldo en path.repo del archivo opensearch.yml de OpenSearch y reiniciar OpenSearch.

1. Configuración del repositorio:

   $ curl -X PUT "http://localhost:9200/_snapshot/fess_backup" -H 'Content-Type: application/json' -d'
   {
     "type": "fs",
     "settings": {
       "location": "/backup/opensearch/snapshots"
     }
   }'
   

2. Creación de instantánea:

   $ curl -X PUT "http://localhost:9200/_snapshot/fess_backup/snapshot_1?wait_for_completion=true"
   

3. Verificación de instantánea:

   $ curl -X GET "http://localhost:9200/_snapshot/fess_backup/snapshot_1"
   

Método 2: Respaldo de Todo el Directorio

Después de detener OpenSearch, haga un respaldo del directorio de datos.

$ sudo systemctl stop opensearch
$ sudo tar czf /backup/opensearch-data-$(date +%Y%m%d).tar.gz /var/lib/opensearch/data
$ sudo systemctl start opensearch

Respaldo de Versión Docker

Los datos de OpenSearch se almacenan en volúmenes Docker. En compose-opensearch3.yaml se definen dos volúmenes: search01_data para los datos del índice y search01_dictionary para los archivos de diccionario.

Nota

El nombre real del volumen lleva como prefijo el nombre del proyecto Compose (por defecto, el nombre del directorio donde se encuentra el archivo Compose). Para obtener el nombre exacto, ejecute:

$ docker volume ls

Detenga los contenedores y luego haga un respaldo de los volúmenes. En el -v de docker run, especifique el nombre real del volumen, incluido el prefijo:

$ docker compose -f compose.yaml -f compose-opensearch3.yaml stop
$ PROJECT=$(basename "$(pwd)")
$ docker run --rm -v ${PROJECT}_search01_data:/data -v $(pwd):/backup ubuntu tar czf /backup/search01-data-backup.tar.gz /data
$ docker run --rm -v ${PROJECT}_search01_dictionary:/data -v $(pwd):/backup ubuntu tar czf /backup/search01-dictionary-backup.tar.gz /data
$ docker compose -f compose.yaml -f compose-opensearch3.yaml start

Advertencia

Si especifica search01_data sin el prefijo en -v, Docker no hará referencia al volumen existente, sino que creará uno nuevo y vacío con el mismo nombre. El comando no producirá ningún error, pero generará un archivo comprimido vacío, por lo que puede parecer que el respaldo se realizó correctamente cuando en realidad no contiene datos.

Nota

El contenedor principal de Fess (fess01) no tiene un volumen dedicado, por lo que los únicos elementos que deben respaldarse son los dos anteriores. Sin embargo, los ajustes generales modificados desde la pantalla de administración y los plugins instalados desde ella se almacenan únicamente dentro del contenedor y se perderán si este se recrea. Persístalos especificándolos mediante FESS_JAVA_OPTS o FESS_PLUGINS en el archivo Compose.

Paso 2: Detención de la Versión Actual

Detenga Fess y OpenSearch.

La versión ZIP no incluye un script para detener el servicio. Si inició bin/fess con la opción -p, deténgalo usando el archivo PID:

$ kill $(cat /path/to/fess/fess.pid)
$ kill <opensearch_pid>

Si lo inició sin especificar -p, verifique el ID del proceso y ejecute kill manualmente (con -d solo no se crea ningún archivo PID).

Versión RPM/DEB (systemd):

$ sudo systemctl stop fess.service
$ sudo systemctl stop opensearch.service

Versión Docker:

$ docker compose -f compose.yaml -f compose-opensearch3.yaml down

Advertencia

Asegúrese de que Fess se haya detenido antes de empezar el Paso 3, y no sustituya el paquete ni los archivos de un Fess que siga en ejecución. Después de sustituir el paquete DEB de un Fess 15.8 en ejecución por el de 15.9, la pantalla de búsqueda respondió 404 hasta que se reinició Fess. Para las versiones de los paquetes, compruébelo con systemctl status fess.service.

Paso 3: Instalación de la Nueva Versión

Los procedimientos varían según el método de instalación.

Versión ZIP

1. Descargue y extraiga la nueva versión:

   $ wget https://github.com/codelibs/fess/releases/download/fess-15.9.0/fess-15.9.0.zip
   $ unzip fess-15.9.0.zip
   

   Nota

   La versión archivo de Fess se distribuye únicamente en formato ZIP (no se ofrece fess-15.9.0.tar.gz).

2. Copie la configuración de la versión antigua:

   $ cp /path/to/old-fess/app/WEB-INF/conf/system.properties /path/to/fess-15.9.0/app/WEB-INF/conf/
   $ cp /path/to/old-fess/app/WEB-INF/classes/fess_config.properties /path/to/fess-15.9.0/app/WEB-INF/classes/
   $ cp /path/to/old-fess/bin/fess.in.sh /path/to/fess-15.9.0/bin/
   

   Advertencia

   Si se copian enteros, fess_config.properties y fess.in.sh conservan sus valores antiguos, incluidos aquellos cuyo valor predeterminado cambió en 15.9: por ejemplo, los trabajos creados después usan Groovy de forma predeterminada. Antes de ejecutar las dos últimas órdenes, compare cada archivo con el de fess-15.9.0 y traslade solo los valores que haya cambiado usted. Consulte Archivos de configuración traídos de 15.8 para saber qué revisar.

3. Si tiene personalizaciones, copie también lo siguiente:

   # Configuración de Tomcat (aquí se conserva el ajuste SAML tomcat.sameSiteCookies=none)
   $ cp /path/to/old-fess/lib/classes/tomcat_config.properties /path/to/fess-15.9.0/lib/classes/
   # Plugins instalados
   $ cp -r /path/to/old-fess/app/WEB-INF/plugin/. /path/to/fess-15.9.0/app/WEB-INF/plugin/
   # Temas estáticos que haya subido usted (un directorio por tema; nunca bootstrap)
   $ cp -r /path/to/old-fess/app/themes/<your-theme> /path/to/fess-15.9.0/app/themes/
   

   Advertencia

   Sin el tomcat_config.properties de la instalación antigua, tomcat.sameSiteCookies vuelve en silencio al valor predeterminado lax y el inicio de sesión SAML deja de funcionar (consulte Si Utilizaba la Autenticación SAML (SSO)). El archivo incluido es el mismo en 15.8.0 y en 15.9, por lo que se puede copiar tal cual.

   Advertencia

   No copie log4j2.xml sobre el archivo de 15.9. El archivo de 15.9 mantiene el logger RequestLoggingFilter en warn, y un archivo copiado de 15.8 elimina ese ajuste: con el nivel de registro en DEBUG, las cabeceras de la petición (incluida Authorization) y los parámetros de la petición (incluida la contraseña escrita en el formulario de inicio de sesión) se escriben entonces en el registro. Compare los dos archivos con diff y vuelva a aplicar sobre el archivo de 15.9 solo los cambios que haya hecho usted.

   Advertencia

   No copie el directorio app/themes/ completo. También contiene bootstrap, el tema incluido con Fess, y copiarlo sobre el de 15.9 sustituye la pantalla de búsqueda de 15.9 por la versión 15.8 del tema. Copie solo los directorios de los temas que haya creado usted. Para un tema publicado por el proyecto Fess, instale en su lugar la versión para 15.9 con bin/fess-setup install theme <name> (consulte Comando fess-setup).

   Advertencia

   No copie los JSP editados desde «Diseño» en la pantalla de administración (app/WEB-INF/view/). La pantalla de búsqueda de 15.9 es un tema estático y ya no utiliza esos JSP; consulte La pantalla de búsqueda es ahora un tema estático para saber dónde van ahora esos cambios.

   Nota

   Los plugins copiados de app/WEB-INF/plugin/ se compilaron para la versión antigua. Después de copiarlos, ejecute bin/fess-setup upgrade plugins en fess-15.9.0 para sustituir cada uno por la versión compilada para 15.9; consulte Actualización de la Versión de los Plugins.

4. Verifique las diferencias de configuración y ajuste según sea necesario

Versión RPM/DEB

Instale el paquete de la nueva versión:

# RPM
$ sudo rpm -Uvh fess-15.9.0.rpm

# DEB
$ sudo dpkg -i fess-15.9.0.deb

Nota

En la versión RPM, los archivos de configuración de /etc/fess/* están registrados como %config(noreplace), por lo que se conservan durante la actualización (los nuevos archivos predeterminados se colocan junto a ellos con la extensión .rpmnew). Si se han agregado nuevas opciones de configuración, es necesario ajustarlas manualmente. Un /etc/fess/fess_config.properties que haya modificado conserva sus valores antiguos en 15.9, igual que un archivo copiado en el procedimiento ZIP; consulte Archivos de configuración traídos de 15.8.

Advertencia

En la versión DEB, los archivos de /etc/fess (como fess_config.properties y tomcat_config.properties) están registrados como conffile, igual que /etc/default/fess, /etc/init.d/fess y /usr/lib/systemd/system/fess.service. En la primera actualización desde 15.8, dpkg los trata de la siguiente manera:

• Un archivo que nunca editó se sustituye por el de 15.9 sin preguntar.

• Si editó un archivo, dpkg pregunta. Si conserva su archivo (la respuesta predeterminada, o --force-confold), el archivo de 15.9 se coloca junto a él como <nombre del archivo>.dpkg-dist. Si instala el archivo nuevo (Y o --force-confnew), su archivo se guarda como <nombre del archivo>.dpkg-old.

• dpkg -i y apt-get install -y se detienen en la primera pregunta cuando nadie puede responderla. Para una actualización desatendida, indique --force-confold (--force-confdef también evita las preguntas), por ejemplo sudo dpkg --force-confold -i fess-15.9.0.deb o sudo apt-get install -y -o Dpkg::Options::=--force-confold ./fess-15.9.0.deb.

Respalde /etc/fess antes (Paso 1) en cualquier caso. Un archivo que conserve sigue teniendo sus valores de 15.8, así que compárelo con el archivo .dpkg-dist en lugar de usarlo tal cual (consulte Archivos de configuración traídos de 15.8). Tenga en cuenta que /etc/fess/system.properties es un archivo generado en tiempo de ejecución que no forma parte del paquete, por lo que no se sobrescribe.

Versión Docker

1. Obtenga el archivo Compose de la nueva versión:

   $ wget https://raw.githubusercontent.com/codelibs/docker-fess/v15.9.0/compose/compose.yaml
   $ wget https://raw.githubusercontent.com/codelibs/docker-fess/v15.9.0/compose/compose-opensearch3.yaml
   

2. Obtenga la nueva imagen:

   $ docker compose -f compose.yaml -f compose-opensearch3.yaml pull
   

Paso 4: Actualización de OpenSearch

Fess 15.9 es compatible con OpenSearch 3.9.0. Si el OpenSearch al que se conecta es una versión anterior, actualícelo siguiendo estos procedimientos.

Nota

Este procedimiento corresponde a los casos en que OpenSearch se gestiona manualmente en las versiones ZIP y RPM/DEB. En la versión Docker, al obtener las nuevas imágenes en el Paso 3, OpenSearch y los plugins se actualizan conjuntamente, por lo que este paso no es necesario.

Importante

Fess 15.9 incluye siempre index.knn en la configuración del índice de búsqueda y content_chunk_vector (de tipo knn_vector) en el mapeo, independientemente de si se utiliza la búsqueda por vector de chunks (búsqueda semántica). Por lo tanto, el OpenSearch al que se conecta debe tener instalado el plugin k-NN.

• Viene incluido en la distribución estándar de OpenSearch y en la imagen de la versión Docker.

• No está incluido en la distribución minimal, por lo que la creación del índice fallará y |Fess| no podrá iniciarse.

• La configuración del índice también envía siempre knn.derived_source.enabled. En un OpenSearch antiguo que no reconozca esta opción, la creación del índice fallará independientemente de si el plugin k-NN está instalado.

Para más detalles, consulte los «Requisitos previos» de Búsqueda Semántica (Chunking de Contenido + Búsqueda Vectorial).

Advertencia

Realice con cuidado las actualizaciones de versión principal de OpenSearch. Pueden surgir problemas de compatibilidad del índice. Fess 14.x utiliza la serie OpenSearch 2.x, por lo que una actualización desde 14.x siempre corresponde a este caso.

Una instantánea tomada con OpenSearch 3.9.0 no se puede restaurar en OpenSearch 3.8.0 o anterior. Conserve la instantánea tomada antes de la actualización por si necesita revertirla.

1. Instale la nueva versión de OpenSearch

2. Reinstale los plugins:

   $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip
   $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-extension/3.9.0/opensearch-analysis-extension-3.9.0.zip
   $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-minhash/3.9.0/opensearch-minhash-3.9.0.zip
   $ sudo /usr/share/opensearch/bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-configsync/3.9.0/opensearch-configsync-3.9.0.zip
   

   Nota

   La versión de estos plugins debe coincidir con la versión de OpenSearch que se utiliza. Fess 15.9 es compatible con OpenSearch 3.9.0. Si las versiones no coinciden, la instalación de los plugins fallará.

   Los cuatro plugins de Fess se publican en maven.codelibs.org, por lo que se instalan mediante su URL. La forma groupId:artifactId:version de opensearch-plugin install solo busca en Maven Central.

3. Mueva el directorio de diccionarios dentro del directorio de configuración de OpenSearch

   OpenSearch 3.8.0 y versiones posteriores rechazan la creación de índices cuando los archivos de diccionario están fuera del directorio de configuración de OpenSearch. Si, siguiendo las instrucciones anteriores, configsync.config_path apunta fuera del directorio de configuración, como /var/lib/opensearch/data/config/ (/path/to/opensearch/data/config/ en la versión ZIP), Fess no puede crear sus índices y no se inicia. En la versión RPM/DEB, copie los archivos de diccionario a /etc/opensearch/dictionary/ de la siguiente manera:

   $ sudo install -d -o opensearch -g opensearch -m 0750 /etc/opensearch/dictionary
   $ sudo cp -a /var/lib/opensearch/data/config/. /etc/opensearch/dictionary/
   $ sudo chown -R opensearch:opensearch /etc/opensearch/dictionary
   

   A continuación, cambie tanto configsync.config_path en /etc/opensearch/opensearch.yml como FESS_DICTIONARY_PATH de Fess (/etc/sysconfig/fess en la versión RPM, /etc/default/fess en la versión DEB) a /etc/opensearch/dictionary/. En la versión ZIP, utilice config/dictionary/ de OpenSearch. Para más detalles, consulte Instalación en Linux (Procedimientos Detallados).

4. Inicie OpenSearch:

   $ sudo systemctl start opensearch.service
   

Paso 5: Inicio de la Nueva Versión

Versión ZIP:

$ cd /path/to/fess-15.9.0
$ ./bin/fess -d -p /path/to/fess-15.9.0/fess.pid

Nota

Si especifica -p, se crea un archivo PID que permite detener el servicio la próxima vez con kill $(cat /path/to/fess-15.9.0/fess.pid).

Versión RPM/DEB:

$ sudo systemctl start opensearch.service
$ sudo systemctl start fess.service

Versión Docker:

$ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d

Paso 6: Verificación de Funcionamiento

1. Verificación de registros

   Verifique que no haya errores.

   Versión ZIP:

   $ tail -f /path/to/fess/logs/fess.log
   

   Versión RPM/DEB:

   $ sudo tail -f /var/log/fess/fess.log
   

   Versión Docker:

   $ docker compose -f compose.yaml -f compose-opensearch3.yaml logs -f fess01
   

   Nota

   En el mismo directorio de registros también se generan fess-crawler.log (procesamiento de rastreo), audit.log (autenticación y operaciones de administración) y searchlog.log (solicitudes de búsqueda).

2. Acceso a la interfaz Web

   Acceda a http://localhost:8080/ desde el navegador.

3. Inicio de sesión en la pantalla de administración

   Acceda a http://localhost:8080/admin e inicie sesión con la cuenta de administrador.

4. Verificación de la versión

   En la pantalla de administración, haga clic en «Información del sistema» → «Información de configuración» y verifique que fess.version que se muestra en «Propiedades del sistema» corresponda a la nueva versión.

5. Verificación de funcionamiento de búsqueda

   Ejecute una búsqueda en la pantalla de búsqueda y verifique que se devuelvan resultados normalmente.

Paso 7: Recreación del Índice (Recomendado)

Para actualizaciones de versión principal, se recomienda recrear el índice.

Nota

Los pasos siguientes vuelven a ejecutar el rastreo; no actualizan el mapeo del índice (definiciones de campos). Si necesita una reindexación que actualice el mapeo — por ejemplo, para habilitar recién la búsqueda por vector de chunks (búsqueda semántica) —, ejecute por separado la «Reindexación» en «Información del sistema» → «Mantenimiento» en la interfaz de administración. Consulte Migración desde la versión 15.7 o anterior (Búsqueda Semántica (Chunking de Contenido + Búsqueda Vectorial)) para más detalles.

Si sigue usando un índice de documentos creado con 15.8 o anterior, consulte también Aplicar los nuevos campos y la normalización de kana a un índice de documentos existente.

Advertencia

OpenSearch 3.9.0 rechaza entradas de diccionario que 15.8 aceptaba, como la misma entrada de mapping guardada dos veces o un token de kuromoji que contiene un espacio. Con una entrada así, la «Reindexación» no crea el nuevo índice de documentos: fess.log solo dice Failed to create index y el índice antiguo sigue atendiendo las búsquedas. Descargue el diccionario en «Sistema» → «Diccionario», elimine las líneas duplicadas o no válidas, cárguelo de nuevo y ejecute otra vez la «Reindexación». Consulte Solicitudes que la API ahora rechaza para ver las entradas que 15.9 ya no guarda.

1. Verifique los programas de rastreo existentes

2. Ejecute «Default Crawler» desde «Sistema» → «Programador»

3. Espere hasta que se complete el rastreo

4. Verifique los resultados de búsqueda

Advertencia

Dado que la reindexación reconstruye el índice con el nuevo mapeo, fallará en un OpenSearch sin el plugin k-NN. Consulte las notas del Paso 4.

Actualización de 15.8 a 15.9

Si actualiza desde 15.8, los cambios siguientes no son retrocompatibles. Si actualiza desde 15.7 o anterior, también se aplican a usted: lea todas las secciones desde «Eliminación del OpenSearch integrado» hasta «Aplicar los nuevos campos y la normalización de kana a un índice de documentos existente» (el OpenSearch integrado, el motor de scripting, los plugins de S3 y SSO, el trabajo Index Exporter, etc.) y, después, «Migración Específica de 15.9» al final de esta página.

Eliminación del OpenSearch integrado

Hasta 15.8, iniciar bin/fess sin definir SEARCH_ENGINE_HTTP_URL hacía que Fess ejecutara un nodo OpenSearch dentro de su propia JVM. Esa configuración desaparece en 15.9: el motor de búsqueda es siempre un servidor independiente.

bin/fess.in.sh ahora establece SEARCH_ENGINE_HTTP_URL=http://localhost:9200 de forma predeterminada. Fess no se inicia si no hay ningún OpenSearch accesible. bin/fess-setup install opensearch instala uno (solo Linux y Windows; OpenSearch no publica una versión para macOS, así que utilice Homebrew o Docker en ese caso).

Fess también necesita que FESS_DICTIONARY_PATH coincida con configsync.config_path en el opensearch.yml de ese OpenSearch; sin ello, Fess no puede crear sus índices. El bin/fess.in.sh de 15.9 (bin\fess.in.bat en Windows) la establece por sí mismo cuando opensearch/ dentro del directorio de Fess contiene exactamente un OpenSearch instalado por bin/fess-setup install opensearch. Para cualquier otro OpenSearch, establézcala tal como se describe en Instalación en Linux (Procedimientos Detallados) o Instalación en Windows (Procedimientos Detallados).

También se han eliminado:

• el directorio es/ (es/modules, es/plugins y es/data)

• -Dfess.es.dir y SEARCH_ENGINE_HOME

• bin/module.xml y bin/plugin.xml

• los valores de reserva de las antiguas claves de configuración elasticsearch.*

Un motor anterior a OpenSearch 3 también detiene el inicio, mientras que 15.8 registraba un error y continuaba. Esas versiones no implementan la ordenación _shard_doc de la que dependen todas las operaciones que recorren el conjunto completo de resultados, y por HTTP una petición así se queda colgada en lugar de fallar.

Advertencia

Los datos de índice de una instalación integrada no se pueden conservar. Construya un nuevo servidor OpenSearch externo, traslade la configuración con la página de copia de seguridad de la administración y vuelva a rastrear. La copia de seguridad incluye la configuración de rastreo, los usuarios y los registros; no contiene los documentos rastreados.

Nota

Dos cosas que debe saber al restaurar una copia de seguridad de 15.8 en el nuevo servidor 15.9:

• Los trabajos solo se restauran si son más recientes que los del servidor. Por eso los trabajos incluidos que nunca editó en 15.8 conservan su versión JavaScript de 15.9. Un trabajo que editó o creó en 15.8 vuelve con el motor de scripts con el que se guardó, que es groovy en un trabajo incluido, y sin el plugin fess-script-groovy falla con groovy is not found. Instale el plugin o pase esos trabajos a JavaScript; ambas opciones se describen en El motor de scripting integrado pasa de Groovy a JavaScript.

• Las contraseñas y los secretos almacenados en la autenticación web, la configuración de rastreo y la configuración de almacenes de datos están cifrados con app.cipher.key. Defina el valor de la instalación antigua en el fess_config.properties del nuevo servidor, como se describe en Archivos de configuración traídos de 15.8; de lo contrario, no se pueden descifrar.

El rastreador de Playwright pasa a un plugin

El rastreador de Playwright, y los ejecutables de Node.js que utiliza, ya no forman parte de la distribución. En fess-15.8.0.zip (457,1 MiB), el paquete de controladores de Playwright que contenía los ejecutables de Node.js ocupaba 204,3 MiB.

Si alguna configuración de rastreo indica el cliente de Playwright, por ejemplo con client.crawlerClients=playwright:http://.* en sus parámetros de configuración, instale tanto el plugin como Node.js. El plugin también puede instalarse desde la página Sistema > Plugin de la pantalla de administración. bin/fess.in.sh detecta Node.js y establece PLAYWRIGHT_NODEJS_PATH.

$ bin/fess-setup install plugin fess-crawler-playwright
$ bin/fess-setup install nodejs

Sin el plugin, esa configuración se sigue rastreando, pero con el cliente HTTP normal, de modo que el texto que solo genera JavaScript no se indexa. El trabajo de rastreo termina igualmente con éxito y no se registra ninguna URL con errores. En cada rastreo, fess-crawler.log registra una advertencia por cada configuración de rastreo, con el nombre del plugin y las dos órdenes anteriores.

El plugin fess-thumbnail-playwright, que genera miniaturas de páginas HTML con Playwright, también se ejecuta sobre Node.js. Si lo utiliza, instale Node.js con bin/fess-setup install nodejs; la misma instalación sirve a ambos plugins.

Si no utiliza ni el rastreador de Playwright ni el plugin fess-thumbnail-playwright, no hay nada que hacer.

Google Cloud Storage pasa a un plugin

El SDK de Google Cloud Storage ya no forma parte de la distribución, por lo que el rastreo de gcs:// y el tipo de almacenamiento gcs provienen ahora del plugin fess-storage-gcs. Instálelo desde la página Sistema > Plugin de la pantalla de administración o con la orden siguiente.

$ bin/fess-setup install plugin fess-storage-gcs

gcs también ha salido del valor distribuido de crawler.file.protocols, que ahora es file,smb,smb1,ftp; el plugin lo vuelve a añadir al instalarse. Hasta entonces, una configuración de rastreo de archivos cuya ruta empieza por gcs: se registra como advertencia y no recupera nada. Una instalación que se actualiza conserva su propio crawler.file.protocols, por lo que la ruta se sigue aceptando pero ningún cliente de rastreo la atiende; en una instalación nueva gcs: no es un protocolo configurado, así que la pantalla de administración rechaza guardar la ruta y una ruta guardada antes se lee como ruta de archivo local. La página de almacenamiento también registra una advertencia y muestra el fallo como un error con el nombre del plugin que hay que instalar, donde antes solo mostraba una lista de archivos vacía.

Si no utiliza Google Cloud Storage, no hay nada que hacer. Amazon S3 y el almacenamiento compatible con S3, como MinIO, han pasado a un plugin de la misma manera; consulte la sección siguiente.

Amazon S3 pasa a un plugin

El SDK de AWS ya no forma parte de la distribución, por lo que el rastreo de s3:// y los tipos de almacenamiento s3 y s3_compat provienen ahora del plugin fess-storage-s3. Instálelo desde la página Sistema > Plugin de la pantalla de administración o con la orden siguiente.

$ bin/fess-setup install plugin fess-storage-s3

s3 también ha salido del valor distribuido de crawler.file.protocols, que ahora es file,smb,smb1,ftp; el plugin lo vuelve a añadir al instalarse. storage.type sigue teniendo el valor predeterminado auto, que se resuelve como S3 cuando no hay ningún punto final configurado, así que la página de almacenamiento de la pantalla de administración no funciona hasta que se instala el plugin, aunque nunca haya indicado s3 explícitamente. Sus valores storage.* se conservan, porque están en WEB-INF/conf/system.properties, y un crawler.file.protocols existente tampoco se sustituye en la actualización.

Si no utiliza Amazon S3 ni almacenamiento compatible con S3 como MinIO, no hay nada que hacer.

La autenticación SSO pasa a plugins

Ninguno de los cuatro autenticadores SSO forma parte ya de la distribución; cada valor de sso.type proviene ahora de su propio plugin, que incluye la biblioteca de identidad que necesita: saml de fess-sso-saml, spnego de fess-sso-spnego, entraid (y el antiguo aad) de fess-sso-entraid y oic de fess-sso-oidc. Fíjese en el último par: el plugin se llama fess-sso-oidc mientras que el valor de sso.type sigue siendo oic, el único lugar en el que ambos difieren. Instale el que utilice desde la página Sistema > Plugin de la pantalla de administración o con la orden siguiente.

$ bin/fess-setup install plugin fess-sso-saml

Sus valores de configuración se conservan, porque sso.type y las claves saml.*, spnego.*, entraid.*, aad.* y oic.* están en WEB-INF/conf/system.properties. Además, «Sistema» → «General» de la pantalla de administración sigue ofreciendo los cuatro tipos y sigue mostrando sus ajustes, porque un plugin no puede proporcionar un JSP, así que nada en esa pantalla indica que falte un plugin.

Hasta que se instala el plugin, una petición a /sso/ se redirige de vuelta a la página de inicio de sesión, que informa de que el inicio de sesión SSO ha fallado, y nadie puede iniciar sesión mediante SSO. 15.9 registra en fess.log una advertencia con el nombre del componente que ha buscado y el del plugin que lo proporciona, donde hasta 15.8 no se registraba nada en ningún nivel.

El plugin oic es más estricto que el autenticador de 15.8. oic.token.server.url debe ser HTTPS (http solo para localhost, 127.x.x.x y ::1), se comprueban los claims aud y exp del ID Token, y iss se comprueba cuando se define la nueva clave oic.issuer. Para más detalles, consulte Configuración de SSO con OpenID Connect.

En 15.8, oic.token.server.url podía ser una URL http de cualquier host. En 15.9, http hacia el nombre de un servicio de Docker Compose (como http://keycloak:8080/...) o un nombre de host interno se rechaza, aunque apunte a la misma máquina. El inicio de sesión falla y fess.log registra una advertencia que empieza por Failed to process the OpenID Connect callback: oic.token.server.url must be https. Cambie el endpoint de token a una URL HTTPS antes de actualizar.

Además, defina oic.issuer con el valor issuer del documento Discovery del OP. Si no se define, iss no se comprueba y se registra una advertencia en el primer inicio de sesión tras el arranque. Definir oic.issuer no relaja la regla de HTTPS.

Si no utiliza SSO, es decir, si sso.type es none o no está definido, no hay nada que hacer.

El motor de scripting integrado pasa de Groovy a JavaScript

Hasta 15.8 el motor de scripting integrado era Groovy y job.default.script tenía el valor predeterminado groovy. En 15.9 el motor integrado es JavaScript y el valor predeterminado es javascript. Groovy ya no está integrado: lo proporciona el plugin fess-script-groovy, que debe estar instalado para que un scriptType con valor groovy se pueda resolver.

Una actualización no cambia el motor almacenado con cada ajuste, y un ajuste guardado antes de 15.9 que no registra ningún motor cuenta como groovy. Sin el plugin, deja de funcionar lo siguiente:

• Los trabajos programados guardados como groovy. Esto incluye los trabajos que creó el propio 15.8: Default Crawler, Suggest Indexer, Config Reloader, Log Aggregator, Doc Purger y los demás trabajos incluidos están guardados como groovy, y al iniciarse 15.9 solo añade los trabajos incluidos que todavía no existen, así que no los modifica. Cada uno de ellos falla cada vez que se ejecuta según su programación, de modo que Default Crawler deja de rastrear. La mayoría de los trabajos incluidos tienen desactivado «Registro», por lo que sus fallos no aparecen en el registro de trabajos, sino solo como advertencias Failed to execute job en fess.log.

• Las configuraciones de rastreo web y de archivos con scripts de campo (field.script.<nombre del campo>) en «Parámetro de configuración». Todos los documentos de una configuración así fallan con una ScriptEngineException y se registran como URL con errores, mientras que el propio trabajo de rastreo termina correctamente.

• Las configuraciones de almacén de datos con un «Script». Los valores que no son solo un nombre de parámetro no se pueden evaluar; consulte Descripción General de los Conectores de Almacén de Datos.

• Las reglas de impulso de documentos. Una regla así no impulsa nada.

• Los mapeos de rutas cuyo «Reemplazo» empieza por groovy:. Un mapeo así no se aplica y las URL quedan sin cambios.

Después del primer inicio, busque en fess.log una advertencia que empiece por Settings use the script engine groovy, which is not registered. Fess comprueba los ajustes anteriores una vez al iniciarse e indica, para cada tipo, cuántos usan un motor que ningún plugin proporciona. También menciona job.default.script cuando un fess_config.properties traído de 15.8 sigue indicando groovy; en ese caso, los trabajos creados después de la actualización también usan Groovy (consulte Archivos de configuración traídos de 15.8). Resuélvalo de una de estas dos maneras:

• Instale el plugin y reinicie Fess. Los scripts de Groovy almacenados se ejecutan entonces sin cambios y la advertencia deja de registrarse. El plugin también puede instalarse desde «Sistema» → «Plugin» en la pantalla de administración.

  $ bin/fess-setup install plugin fess-script-groovy
  

• Pase cada ajuste a JavaScript. Primero reescriba la sintaxis que solo acepta Groovy y después seleccione JavaScript:

  • Trabajos programados: en «Sistema» → «Programador», cambie «Tipo de ejecución» a javascript. Los scripts de los trabajos incluidos son JavaScript válido tal como están, con dos excepciones: Thumbnail Purger usa el literal long de Groovy 1000L, que JavaScript rechaza (escriba 1000), e Index Exporter necesita el cambio descrito en El trabajo Index Exporter hace referencia a un paquete eliminado. Un literal de array de JavaScript se convierte automáticamente en un String[] de Java, por lo que se omiten las conversiones as String[] de la forma Groovy:

    return container.getComponent("crawlJob").logLevel("info").webConfigIds(["1", "2"]).fileConfigIds(["1"]).dataConfigIds([]).execute(executor);
    

  • Configuraciones de rastreo web y de archivos: añada config.script.type=javascript a «Parámetro de configuración».

  • Configuraciones de almacén de datos: añada script_type=javascript a «Parámetro».

  • Reglas de impulso de documentos: cambie «Tipo de Script» a javascript.

  • Mapeos de rutas: empiece el «Reemplazo» por javascript: en lugar de groovy:.

  • job.default.script: establézcalo en javascript en un fess_config.properties traído de 15.8.

crawler.default.script se ha eliminado

crawler.default.script ya no existe en fess_config.properties. Elimínelo de su configuración; un valor que permanezca con ese nombre no tiene ningún efecto.

El protocolo de rastreo storage se ha eliminado

storage ya no se admite en crawler.file.protocols; el valor incluido es file,smb,smb1,ftp. Utilice s3 en su lugar y cambie a una ruta s3: cualquier configuración de rastreo de archivos cuya ruta empiece por storage:. s3 necesita el plugin fess-storage-s3.

El trabajo Index Exporter hace referencia a un paquete eliminado

15.9 ya no incluye las clases org.opensearch; los constructores de consultas que usan los scripts de los trabajos están ahora en org.codelibs.fesen.opensearch. El script que 15.8 guardó para el trabajo Index Exporter hace referencia a org.opensearch.index.query.QueryBuilders, y la actualización no lo sustituye, así que el trabajo falla incluso con fess-script-groovy instalado. El trabajo se distribuye desactivado y sin programación, por lo que solo le afecta si lo ejecuta. Ábralo en «Sistema» → «Programador» y cambie el paquete de su script por el de 15.9:

return new org.codelibs.fess.job.IndexExportJob().query(org.codelibs.fesen.opensearch.index.query.QueryBuilders.matchAllQuery()).execute()

Cambie de la misma manera cualquier script propio que haga referencia a org.opensearch.index.query. Consulte Función de Exportación de Índice para ver más ejemplos de consultas.

Archivos de configuración traídos de 15.8

El procedimiento ZIP del Paso 3 copia fess_config.properties y bin/fess.in.sh de la instalación antigua, y una actualización RPM conserva un /etc/fess/fess_config.properties que haya modificado (el archivo de 15.9 se coloca junto a él como fess_config.properties.rpmnew). Una actualización DEB hace lo mismo cuando conserva su versión al responder la pregunta (el archivo de 15.9 se coloca junto a él como fess_config.properties.dpkg-dist). En ambos casos, 15.9 funciona después con los valores de 15.8, incluidos aquellos cuyo valor distribuido cambió en 15.9. Revise al menos las claves siguientes.

Clave	15.8.0	15.9	Efecto de conservar el valor de 15.8
job.default.script	groovy	javascript	Los trabajos creados en «Sistema» → «Programador» usan groovy de forma predeterminada y fallan sin el plugin fess-script-groovy.
job.template.script	Forma Groovy con as String[]	Forma JavaScript	Un trabajo creado a partir de una configuración de rastreo recibe un script de Groovy.
crawler.file.protocols	file,smb,smb1,ftp,storage,s3,gcs	file,smb,smb1,ftp	Una ruta que empieza por s3: o gcs: se sigue aceptando sin su plugin y se omite con una advertencia al rastrear. storage ya no se admite.
search_engine.http.url	http://localhost:9201	http://localhost:9200	Se usa cuando SEARCH_ENGINE_HTTP_URL no está definido, como en un bin/fess.in.sh copiado de 15.8 en el que no lo definió. Fess busca entonces OpenSearch en el puerto 9201, el del OpenSearch integrado que 15.9 eliminó.
jvm.crawler.options, jvm.thumbnail.options	-Djcifs.smb.client.*, -Djcifs.smb1.smb.client.*	-Djcifs.client.*	Los tiempos de espera de SMB siguen con los valores predeterminados de jcifs; consulte Los tiempos de espera de SMB usan los nombres de propiedad de jcifs 3.
response.headers	Incluye la fila text/html=Content-Security-Policy: reflected-xss block	Fila eliminada	La página de inicio de sesión, la interfaz de administración y las demás páginas que Fess genera por sí mismo se envían con una cabecera Content-Security-Policy: reflected-xss block que ningún navegador reconoce, y la consola del navegador registra Unrecognized Content-Security-Policy directive 'reflected-xss'. La cabecera no restringe nada. Elimine la fila, como se describe a continuación.
app.encrypt.property.pattern	.*password|.*key|.*token|.*secret	.*password|.*passphrase|.*key|.*token|.*secret	Un parámetro cuyo nombre termina en passphrase (por ejemplo, ssh.passphrase de una configuración de almacén de datos) se guarda en texto plano. Un valor guardado antes sigue en texto plano hasta que se vuelve a guardar el ajuste con el patrón de 15.9.
index.backup.log.targets	click_log.ndjson,favorite_log.ndjson,search_log.ndjson,user_info.ndjson	chat_log.ndjson,click_log.ndjson,favorite_log.ndjson,search_log.ndjson,user_info.ndjson	La página «Información del sistema» → «Copia de seguridad» no ofrece chat_log.ndjson.
index.export.exclude.fields	cache	cache,tag	El campo tag, que contiene las etiquetas de usuario, ya no se excluye de los archivos que escribe el trabajo Index Exporter.
crawler.default.script, theme.allowed.archive.extensions, theme.assets.cache.max.age, theme.assets.precompressed, rag.chat.message.max.length, supported.uploaded.js.extentions, supported.uploaded.css.extentions, supported.uploaded.media.extentions, supported.uploaded.files, online.help.name.design	Presentes	Eliminadas	Ningún efecto; elimínelas.

El valor distribuido de response.headers contiene, de 15.0 a 15.8, la fila text/html=Content-Security-Policy: reflected-xss block. reflected-xss era una directiva de un borrador temprano de Content-Security-Policy que los navegadores ya no reconocen, por lo que la cabecera no restringe nada y solo añade el error a la consola. 15.9 ya no distribuye la fila (las filas X-XSS-Protection y X-Frame-Options no cambian), pero un response.headers traído de 15.8 la conserva. Elimine solo esa fila de response.headers en fess_config.properties. El \n\ al final de cada fila continúa el valor en la línea siguiente, así que al borrar la línea completa las demás quedan intactas:

text/html=Content-Security-Policy: reflected-xss block\n\

Si define response.headers con -Dfess.config.response.headers, elimine la misma entrada de ese valor.

A un bin/fess.in.sh copiado de 15.8 también le faltan dos cosas que sí tiene el archivo de 15.9. Deja SEARCH_ENGINE_HTTP_URL sin definir salvo que lo haya definido usted, mientras que 15.9 define http://localhost:9200, y no busca el Node.js instalado con bin/fess-setup install nodejs, por lo que los plugins de Playwright no encuentran Node.js a menos que defina PLAYWRIGHT_NODEJS_PATH.

En lugar de copiar cualquiera de los dos archivos entero, parta del archivo distribuido con 15.9 y vuelva a aplicar los valores que haya cambiado. diff los muestra:

$ diff /path/to/old-fess/app/WEB-INF/classes/fess_config.properties /path/to/fess-15.9.0/app/WEB-INF/classes/fess_config.properties
$ diff /path/to/old-fess/bin/fess.in.sh /path/to/fess-15.9.0/bin/fess.in.sh

En una actualización RPM, compare de la misma manera /etc/fess/fess_config.properties con /etc/fess/fess_config.properties.rpmnew, y en una actualización DEB con /etc/fess/fess_config.properties.dpkg-dist. Un fess_config.properties que nunca editó se sustituye por el archivo de 15.9 en una actualización DEB (consulte el Paso 3), así que se parte de los valores de 15.9.

app.cipher.key es el único valor que debe trasladar aunque 15.9 no lo haya cambiado. Es la clave que cifra las contraseñas y los secretos almacenados en los parámetros de la autenticación web, de las configuraciones de rastreo y de las configuraciones de almacenes de datos. Si la nueva instalación funciona con una clave distinta de la que los guardó, porque tomó el fess_config.properties incluido o restauró una copia de seguridad en un servidor nuevo, no se pueden descifrar: fess-crawler.log registra una CipherFailureException y un rastreo que incluya una configuración así puede no indexar nada.

Nota

Fess 15.9 también guarda el password de la autenticación web y de archivos cifrado con app.cipher.key, por lo que fess_basic_config.bulk y fess_config.bulk de una copia de seguridad contienen los valores cifrados. Al restaurar en otra instalación, traslade la misma app.cipher.key; con una clave distinta, los rastreos que usan estas credenciales fallan con un error. Una copia de seguridad creada antes de 15.9 las contiene en texto sin cifrar y sigue funcionando (consulte Copia de Seguridad).

Los tiempos de espera de SMB usan los nombres de propiedad de jcifs 3

jcifs, la biblioteca que Fess utiliza para rastrear servidores de archivos SMB, cambió el nombre de sus propiedades en la versión 3: jcifs.smb.client.* pasó a ser jcifs.client.*, y los nombres separados jcifs.smb1.smb.client.* para SMB1 se unificaron en las mismas propiedades. Hasta 15.8, jvm.crawler.options y jvm.thumbnail.options seguían pasando los nombres antiguos, que jcifs ignora, por lo que los rastreos SMB se ejecutaban con los valores predeterminados de jcifs. 15.9 pasa los nombres nuevos:

-Djcifs.client.responseTimeout=30000
-Djcifs.client.soTimeout=35000
-Djcifs.client.connTimeout=60000
-Djcifs.client.sessionTimeout=60000

Por tanto, los tiempos de espera de conexión y de sesión surten efecto por primera vez y pasan del valor predeterminado de jcifs de 35 segundos a 60 segundos: un rastreo espera ahora hasta 60 segundos a un servidor SMB que no responde. Los tiempos de espera de respuesta y de socket coinciden con los valores predeterminados de jcifs, así que no cambian.

Si cambió estos tiempos de espera, cambie sus nombres en ambas opciones. Con los nombres antiguos tampoco tenían efecto en 15.8. Un fess_config.properties traído de 15.8 conserva los nombres antiguos y, con ellos, los valores predeterminados de jcifs.

Se han eliminado cuatro propiedades sin efecto

Las siguientes claves ya no existen en fess_config.properties. Fess nunca las leyó de ese archivo, así que un valor que permanezca con estos nombres sigue sin tener efecto.

• theme.allowed.archive.extensions

• theme.assets.cache.max.age

• theme.assets.precompressed

• rag.chat.message.max.length

El límite que establece rag.chat.message.max.length sigue funcionando, pero se lee como propiedad del sistema: defínalo en app/WEB-INF/conf/system.properties o con -Dfess.system.rag.chat.message.max.length, como se describe en Configuración de la funcionalidad de modo de búsqueda IA.

La pantalla de búsqueda es ahora un tema estático

La pantalla de búsqueda la sirve el tema estático bootstrap, incluido con Fess, salvo que se seleccione otro tema. Esto se aplica a /, /search, /advance, /help, /profile, /cache, /chat y a las páginas de error. Hasta 15.8, estas páginas eran JSP salvo que se hubiera configurado un tema predeterminado.

El cambio también se produce al actualizar. Una instalación 15.8 que nunca configuró un tema predeterminado no tiene theme.default en system.properties, así que después de la actualización muestra el tema estático; no se escribe nada en la configuración ni se registra nada. No existe ninguna configuración que recupere la pantalla de búsqueda JSP. Si había configurado un tema predeterminado en 15.8, esa configuración se conserva; instale la versión para 15.9 del tema (bin/fess-setup install theme <name>), porque un tema predeterminado que nombra un tema no instalado recurre a bootstrap con una advertencia en fess.log.

Si modificó los JSP, el CSS o las imágenes de la pantalla de búsqueda, mediante «Diseño de página» en la pantalla de administración o en un plugin de tema JAR, esos cambios ya no se muestran. Aplíquelos en un tema estático: copie el tema incluido y modifique la copia, como se describe en Personalización del Tema Incluido, o instale un tema publicado desde «Sistema» > «Tema» en la pantalla de administración o con bin/fess-setup install theme <name>. Un aspecto distinto por host virtual es ahora un tema estático con el nombre del host virtual; consulte Host Virtual.

También desaparecieron estas dos funciones:

• La pantalla de inicio de sesión por host virtual. Hasta 15.8, al guardar «Sistema» > «General» se copiaban los JSP, incluida la pantalla de inicio de sesión, en WEB-INF/view/<nombre del host virtual>/, y se podían editar por host virtual. 15.9 ya no crea esas copias. La pantalla de inicio de sesión (/login/) sigue siendo un JSP, pero todos los hosts virtuales muestran el mismo, el de WEB-INF/view/admin/login/. Los JSP copiados anteriormente no se utilizan.

• Los plugins de tema JAR (fess-theme-*). Si instala uno, solo se coloca como un JAR de propósito general del tipo jar y no cambia ninguna pantalla. Los JAR que queden se pueden eliminar en la página «Sistema» > «Plugin» o con bin/fess-setup remove plugin <name> (consulte Guía de Desarrollo de Temas).

Si en 15.8 mostraba campos propios en los resultados de búsqueda JSP, añada los mismos campos a query.additional.api.response.fields además de a query.additional.response.fields. El tema estático obtiene los resultados de búsqueda de /api/v2/search. query.additional.response.fields solo añade los campos que se obtienen del motor de búsqueda, y esta API incluye en la respuesta únicamente los campos enumerados en query.additional.api.response.fields (consulte Configuración de Búsqueda Avanzada). Modifique también el tema para que muestre esos campos.

Lo que ven los clientes

Ahora los errores se muestran en el mismo lugar, en la URL solicitada y con el código de estado HTTP real. Un navegador (una solicitud cuyo encabezado Accept incluye text/html) recibe la página de error del tema; cualquier otro cliente recibe un cuerpo text/plain de una línea (por ejemplo Not Found. para 404). Hasta 15.8, la mayoría de los errores respondían con una redirección 302 a una página /error/... que a su vez devolvía 200. Revise la monitorización, las comprobaciones de estado y los clientes que siguen los encabezados Location o esperan URL /error/.

Solicitud	Hasta 15.8	15.9
/go/ sin un parámetro, o para un documento que no existe	200, o 302 a /error/	400 o 404
/thumbnail/ sin un parámetro, para un documento desconocido o sin miniatura	200 o 302	400 o 404
/sso/metadata y /sso/logout cuando el tipo de SSO configurado no los gestiona	302 a /error/badrequest/	400
/api/v1/*, /json y cualquier URL desconocida	302 a /error/notfound/	404
Una excepción no capturada, también en la API de administración	302 a /error/systemerror/	500 con el cuerpo System Error. (no JSON)
Las propias /error/notfound/, /error/badrequest/, /error/systemerror/	200	404, 400, 500

Con login.required=true, las páginas de búsqueda ya no redirigen a un usuario anónimo. Devuelven 200 con el tema, que pide al usuario que inicie sesión, y en su lugar se rechazan los datos que hay detrás: todos los endpoints de /api/v2/ salvo /health, /auth/* y /ui/config, incluido /api/v2/search, responden 401 hasta que el usuario inicia sesión. /go/, /thumbnail/ y /osdd siguen redirigiendo al inicio de sesión. Una comprobación que espera una redirección para una solicitud anónima a / debe comprobar en su lugar que /api/v2/search devuelve 401.

La pantalla de búsqueda también busca a través de /api/v2/search, así que una búsqueda se registra cuando se llama a esa API, no cuando se solicita /search. Un cliente que no ejecuta JavaScript recibe la página sin resultados.

El HTML de la pantalla de búsqueda lleva X-Frame-Options: DENY y un Content-Security-Policy con frame-ancestors 'none', por lo que ninguna otra página puede mostrarlo en un marco. La pantalla de búsqueda JSP de la 15.8 enviaba X-Frame-Options: SAMEORIGIN (el valor por defecto de response.headers) y podía mostrarse en un iframe de una página del mismo origen. Si incrustaba la pantalla de búsqueda en un iframe del mismo origen, establezca theme.index.frame.ancestors en fess_config.properties (por defecto 'none') en 'self'. Para incrustarla desde otro origen, indique ese origen (consulte Guía de Desarrollo de Temas).

Se ha eliminado el editor de diseño de página

[Sistema > Diseño de página] ya no forma parte de la pantalla de administración, por lo que los archivos JSP, CSS e imágenes de la pantalla de búsqueda ya no se pueden editar desde allí. Para cambiar el aspecto de la pantalla de búsqueda, utilice un tema estático (consulte Personalización del Tema Incluido).

También se han eliminado las siguientes claves de fess_config.properties. Un valor que permanezca con estos nombres no se utiliza.

• supported.uploaded.js.extentions

• supported.uploaded.css.extentions

• supported.uploaded.media.extentions

• supported.uploaded.files

• online.help.name.design

Los roles admin-design y admin-design-view ya no otorgan ningún permiso. Un usuario que solo tenga estos roles llega a la pantalla de búsqueda, y no a la de administración, al iniciar sesión.

api.access.token.required se ha eliminado

api.access.token.required ya no existe en fess_config.properties. Un valor que permanezca con ese nombre no tiene ningún efecto, incluso en un fess_config.properties conservado de la 15.8. Con true, rechazaba toda solicitud a la API de un usuario que no hubiera iniciado sesión. Como la pantalla de búsqueda ahora busca a través de /api/v2/search, además habría mostrado a los usuarios anónimos una pantalla de búsqueda sin resultados.

Una instalación que lo tenía en true responde ahora a las solicitudes a la API de usuarios anónimos con los roles de invitado, igual que en la pantalla de búsqueda. Para impedir que los usuarios anónimos busquen, establezca login.required=true. Los tokens de acceso funcionan como antes: una solicitud con un token de acceso registrado recibe los permisos de ese token, y una solicitud con un token no registrado o caducado se rechaza.

Solicitudes que la API ahora rechaza

La 15.9 rechaza las siguientes solicitudes, que la 15.8 aceptaba. Revise los clientes y scripts que escribió para la 15.8. La API de administración responde a un rechazo con HTTP 400 y status 1 en el cuerpo.

Solicitud	Hasta 15.8	15.9
/api/v2/search con facet.field o facet.query y un facet.size de 0 o menos, o un facet.size o facet.minDocCount que no es un entero	200, pero con un resultado vacío: record_count es 0 y partial es true	400 (invalid_request). facet.size debe ser 1 o más
track_total_hits=false. Con query.track.total.hits en false, afecta a todas las búsquedas	200, pero sin resultados	Se rechaza la búsqueda (/api/v2/search responde 400 con invalid_request). true y los enteros positivos funcionan como antes
Una entrada de los diccionarios mapping o kuromoji que repite una existente, creada o actualizada mediante la API de administración	Se guarda. Después falla la carga del diccionario, lo que puede dejar la búsqueda sin servicio	400
Una entrada del diccionario kuromoji cuyo token contiene un espacio, o cuyos segmentation y reading tienen un número distinto de partes separadas por espacios, creada o actualizada mediante la API de administración	Se guarda. La carga del diccionario falla del mismo modo	400
DELETE /api/admin/searchlist/doc/{doc_id} que no elimina nada: un doc_id que no existe, o un valor que no es un doc_id, como el _id que muestra la lista de documentos	200 (status 0); el documento no se elimina	400
Un nombre de rol o de grupo en roles o groups de un usuario de la API de administración	Se guarda, pero el nombre no actúa como rol. Con algunos nombres falla la lectura del usuario	400. Indique el ID del rol o del grupo (el id que devuelven GET /api/admin/role/settings y GET /api/admin/group/settings)
Un usuario de la API de administración cuya contraseña incumple la política de contraseñas (por ejemplo password.min.length, por defecto 8); una creación sin contraseña; un confirm_password distinto de password	Se guarda; el usuario puede iniciar sesión con esa contraseña	400

Las filas de /api/v2/documents/all ya no llevan score. Hasta la 15.8 cada documento tenía su puntuación de búsqueda; la 15.9 recorre todo el resultado con un point in time y search_after, que no produce puntuación. /json?type=scroll y /api/v1/documents/all de los plugins de las API antiguas se comportan igual. Un script que lea score debe tolerar que falte.

Las subidas de archivos de la API de administración (los seis diccionarios, badword, elevateword y storage) se aceptan con POST. La documentación de la 15.8 indicaba PUT, pero un PUT con multipart/form-data nunca entrega el archivo, así que tanto en la 15.8 como en la 15.9 falla con el error de validación de que el archivo es obligatorio. Los endpoints PUT siguen existiendo; utilice POST para las subidas.

search_engine.type=cloud está obsoleto

La versión 15.9 añade el valor vanilla a search_engine.type para un OpenSearch puro sin los plugins de CodeLibs (consulte Tipo de motor de búsqueda). cloud pasa a ser un alias obsoleto de vanilla: sigue funcionando, pero Fess registra una advertencia al iniciarse. Cámbielo a vanilla cuando la instalación ya se ejecute con la 15.9. aws sigue funcionando como antes.

• vanilla requiere la 15.9. Fess 15.8 y anteriores no reconocen el valor, así que mantenga cloud mientras todavía pueda volver a la 15.8.

• Las definiciones de índice de aws y cloud se leen ahora de fess_indices/_vanilla/. Los directorios fess_indices/_aws/ y fess_indices/_cloud/ incluidos ya no existen, y un directorio fess_indices/_aws/ o fess_indices/_cloud/ que usted haya añadido ya no se lee. Traslade sus cambios a fess_indices/_vanilla/. Los índices ya existentes no se modifican.

• La configuración de sugerencias que la 15.8 guardó en el motor de búsqueda se migra automáticamente; no tiene que hacer nada.

El almacén de datos CSV interpreta los campos entrecomillados

El plugin fess-ds-csv de 15.9 interpreta las comillas de forma predeterminada. Un campo como "Yamada, Taro" es una sola columna, mientras que el plugin de 15.8.0 lo dividía en la coma. Después de bin/fess-setup upgrade plugins, revise las configuraciones de almacén de datos que leen archivos CSV con campos entrecomillados. Para mantener el comportamiento de 15.8, añada quote_disabled=true a «Parámetros»; consulte Conector CSV, que también describe qué ocurre con una comilla sin pareja.

Aplicar los nuevos campos y la normalización de kana a un índice de documentos existente

Al iniciarse, 15.9 añade campos nuevos a los índices de configuración, de registros y de usuarios. En el índice de documentos añade únicamente el campo tag (keyword), que contiene las etiquetas de usuario; el resto del mapeo y la configuración de análisis no cambian. Si sigue usando un índice de documentos creado con 15.8 o anterior, los siguientes cambios de 15.9 no tienen efecto.

• Propietario y último modificador de un archivo (owner, last_modifier): campos nuevos que indexan los rastreos del sistema de archivos, SMB y FTP. El índice de documentos existente no los define, por lo que el primer valor rastreado los mapea dinámicamente como text y las búsquedas como owner:alice o facet.field=owner no funcionan como se espera.

• ETag (etag): el campo en el que el rastreador guarda el ETag de una página rastreada, que 15.9 devuelve como If-None-Match para no volver a obtener una página sin cambios. El índice de documentos existente tampoco lo define, por lo que se mapea dinámicamente como text en lugar del keyword no indexado incluido. Las peticiones condicionales siguen funcionando con ese mapeo.

• Normalización de variantes de kana y de guiones escritos en lugar de la marca de vocal larga (por ejemplo, サ―バ－ se trata como la misma palabra que サーバー): las reglas están en la configuración de análisis del índice de documentos y en el diccionario mapping.txt, por lo que un índice existente no las recibe.

Para aplicar ambos, habilite «Actualizar alias» y «Restablecer diccionarios» en «Información del sistema» → «Mantenimiento» en la interfaz de administración y ejecute la «Reindexación». La reindexación copia los documentos existentes a un índice nuevo, por lo que no es necesario volver a rastrear.

Advertencia

«Restablecer diccionarios» sobrescribe los diccionarios del lado de OpenSearch con los archivos de diccionario incluidos. Si ha editado sinónimos u otros diccionarios en «Diccionario» de la interfaz de administración, descárguelos antes y vuelva a aplicarlos después de la reindexación: elimine las entradas duplicadas o no válidas de los archivos descargados (consulte el Paso 7), cárguelos y, después, haga clic en [Recargar] en «Recargar índice de documentos» en «Información del sistema» → «Mantenimiento». Hasta que lo haga, los analizadores del índice de documentos siguen usando los diccionarios incluidos y un sinónimo restaurado no coincide, por mucho que espere. Un diccionario que se aplica al indexar también requiere volver a rastrear los documentos; consulte Aplicar los cambios de diccionario.

Nota

Los archivos indexados con 15.8 o anterior no tienen valores de propietario ni de último modificador. El rastreo incremental no vuelve a obtener los archivos sin cambios, así que, para añadir los valores, deshabilite temporalmente «Comprobar fecha de última modificación» en «Sistema» → «General» y rastree.

Migración Específica de 15.9

Si actualiza desde la versión 15.7 o anterior a la 15.9, es posible que deba realizar las siguientes tareas según las funciones que utilice.

Si Utilizaba la Búsqueda Semántica

El plugin fess-webapp-semantic-search, que proporcionaba la búsqueda semántica en las versiones 15.7 y anteriores, ya no es necesario (y queda obsoleto) porque se integró en el núcleo en la versión 15.9. Debe eliminar el plugin, eliminar -Dfess.semantic_search.* y -Drank.fusion.searchers=default,semantic, y separar el antiguo ingest pipeline. Consulte Migración desde la versión 15.7 o anterior (Búsqueda Semántica (Chunking de Contenido + Búsqueda Vectorial)) para conocer el procedimiento.

Si Utilizaba el Modo de Búsqueda con IA (Chat RAG)

A partir de la versión 15.9, la función del modo de búsqueda con IA (chat RAG) se separó en plugins independientes, como fess-llm-ollama, fess-llm-openai y fess-llm-gemini. Instale el plugin correspondiente al proveedor que utilice desde «Sistema» → «Plugin» en la pantalla de administración. La versión 15.9 añade además fess-llm-bedrock para Amazon Bedrock.

Si Utilizaba SPNEGO (Autenticación Integrada de Windows)

A partir de la versión 15.9, un inicio de sesión SPNEGO se rechaza cuando el reino Kerberos del principal del cliente difiere del reino del servidor. Si sus usuarios inician sesión desde un dominio secundario de un árbol de dominios de AD o desde un bosque de confianza, indique esos reinos, separados por comas, en spnego.allowed.realms desde «Sistema» → «General» en la pantalla de administración o en app/WEB-INF/conf/system.properties. De lo contrario, los usuarios que podían iniciar sesión hasta la versión 15.7 son rechazados con Kerberos realm is not allowed. Consulte Configuración de SSO con Auth Integrada de Windows para conocer más detalles.

Además, en la versión 15.9 los valores predeterminados definidos en el código de spnego.allow.unsecure.basic y spnego.allow.localhost cambiaron de true a false. Una instalación en la que estas claves no estén presentes en app/WEB-INF/conf/system.properties adopta el comportamiento más estricto al actualizar. En particular, con spnego.allow.unsecure.basic=false la biblioteca SPNEGO solo ofrece la autenticación básica en las peticiones en las que HttpServletRequest#isSecure() devuelve true, por lo que, detrás de un proxy inverso que termina TLS y reenvía la petición por HTTP, los clientes que antes recurrían a la autenticación básica ya no pueden iniciar sesión. En ese caso, establezca tomcat.secure=true en tomcat_config.properties; consulte Configuración de SSO con Auth Integrada de Windows para conocer más detalles.

Advertencia

Un valor predeterminado definido en el código solo se aplica mientras la clave está ausente, y «Sistema» → «General» de la pantalla de administración escribe todas las claves spnego.* cada vez que se guarda. Por lo tanto, una instalación en la que alguna vez se pulsó Actualizar en esa pantalla con la versión 15.7 sigue teniendo almacenados spnego.allow.unsecure.basic=true y spnego.allow.localhost=true, y actualizar a 15.9 no la refuerza: mantiene el comportamiento permisivo de forma silenciosa y 15.9 solo registra una advertencia en fess.log al inicializar SPNEGO. Abra «Sistema» → «General» (o edite system.properties) y desactive ambas opciones de forma deliberada. spnego.allow.localhost=true es la más peligrosa de las dos: la biblioteca SPNEGO autentica las peticiones procedentes del mismo host como el usuario del sistema operativo del servidor, sin ninguna verificación de Kerberos, lo que resulta inseguro detrás de un proxy inverso situado en el mismo host.

Si Utilizaba la Autenticación SAML (SSO)

A partir de la versión 15.9, Fess vincula cada respuesta SAML al identificador de la AuthnRequest que envió, por lo que el SSO iniciado por el IdP (no solicitado) ya no funciona. Un inicio de sesión que comienza en un icono de Fess dentro de un portal del IdP, como el panel de Okta o el portal «Mis aplicaciones» de Microsoft Entra ID, no tiene ninguna AuthnRequest con la que emparejarse y se rechaza. Hasta la versión 15.7 funcionaba porque Fess devolvía al IdP la respuesta que no podía emparejar y el IdP entregaba de inmediato una aserción solicitada. Si coloca un icono en el lado del IdP, haga que apunte al endpoint /sso/ de Fess para que el inicio de sesión lo inicie el SP.

Además, el IdP devuelve la aserción mediante un POST entre sitios, por lo que tomcat.sameSiteCookies debe establecerse en none en tomcat_config.properties. Con el valor predeterminado lax que se incluye, la cookie de sesión no se envía en esa petición y el inicio de sesión SAML no puede completarse. Este archivo se encuentra en lib/classes/ en el paquete ZIP y en /etc/fess/ en los paquetes DEB/RPM, y es necesario reiniciar Fess tras el cambio. Los navegadores solo aceptan none en una cookie que además tenga el atributo Secure, por lo que Fess debe servirse mediante HTTPS. Hasta la versión 15.7, esta configuración incorrecta no producía un error claro, sino un bucle interminable de redirecciones al IdP, así que compruebe el ajuste incluso en un sitio que parecía funcionar; en la versión 15.9 falla una sola vez en lugar de entrar en bucle. Consulte Configuración de SSO con autenticación SAML para conocer más detalles.

Si Utilizaba Microsoft Entra ID (Azure AD)

A partir de la versión 15.9, el modo de respuesta solicitado al endpoint de autorización es query por defecto, en lugar de form_post. Hasta la versión 15.7 el callback se devolvía como un POST entre sitios, y con el valor por defecto de Fess tomcat.sameSiteCookies = lax la cookie de sesión no se envía en esa petición, por lo que era necesario tomcat.sameSiteCookies = none. Si estableció none únicamente por ese motivo, puede volver al valor por defecto. Para mantener el comportamiento anterior, establezca entraid.response.mode=form_post y conserve tomcat.sameSiteCookies = none. Los navegadores solo aceptan none en una cookie que además tenga el atributo Secure, por lo que esa vía también exige servir Fess mediante HTTPS.

A partir de la versión 15.9, Fess también resuelve la pertenencia a grupos y roles del usuario en segundo plano una vez completado el inicio de sesión, en lugar de bloquear el inicio de sesión a la espera de Microsoft Graph. Hasta que la resolución termina — o si no se completa del todo —, el usuario solo tiene su propio permiso a nivel de usuario y lo que aporten entraid.default.groups y entraid.default.roles. Si no se ha configurado ninguno de los dos —el valor por defecto que se incluye—, una búsqueda hecha en esa ventana no devuelve ningún documento, porque una configuración de rastreo creada con los valores por defecto que se incluyen concede {role}guest y un usuario con la sesión iniciada no tiene ese rol. Mientras la resolución está en curso, la pantalla de búsqueda lo indica, y muestra otro mensaje distinto si no se completó del todo: la resolución solo se considera correcta si han tenido éxito tanto la consulta de pertenencias directas como el recorrido de los grupos anidados. La resolución se reintenta cada vez que se renueva el token de acceso, y un éxito posterior hace desaparecer el mensaje, por lo que un fallo no es definitivo en una sesión que dura más que el token; para reintentarlo de inmediato, cierre la sesión y vuelva a iniciarla. Consulte Configuración de SSO con Entra ID para conocer más detalles.

Una consecuencia de resolver en segundo plano: hasta que la resolución llega, los roles resueltos del usuario todavía no se conocen. Por eso, un administrador es redirigido a la pantalla de búsqueda en lugar de al panel de administración, y si abre una página del panel de administración durante esa ventana vuelve a la pantalla de búsqueda. La ventana dura hasta aproximadamente un segundo de retardo de planificación más las propias llamadas a Microsoft Graph — una para las pertenencias directas y luego una más por cada uno de esos grupos para recorrer los grupos anidados, emitidas una tras otra con la caché fría —, por lo que crece con el número de grupos a los que pertenece el usuario. En esa ventana el acceso solo se deniega, nunca se concede, y no hace falta ninguna configuración para superarla: la autorización se evalúa de nuevo en cada petición de la misma sesión, así que una vez terminada la resolución las pantallas de administración se abren con normalidad, sin volver a iniciar sesión.

Advertencia

No acorte esa ventana poniendo el rol de administrador de Fess en entraid.default.roles. Esa propiedad es un valor global único que Fess aplica a todos los usuarios de Entra ID al iniciar sesión y vuelve a aplicar en cada resolución posterior, por lo que concedería a todos los usuarios del inquilino permisos permanentes de administrador de Fess.

Si Utiliza LDAP / Active Directory

A partir de 15.9, el nombre de permiso de un grupo o rol es el valor del RDN de la entrada y no un fragmento del texto del DN. Por tanto, un grupo cuyo CN contiene un carácter que el DN escapa –la coma es el caso habitual– obtiene un nombre de permiso distinto al de 15.7.

DN de la entrada del grupo	Nombre de permiso hasta 15.7	Nombre de permiso en 15.9
CN=Sales\, EMEA,CN=Users,...	2Sales	2Sales, EMEA
CN=Sales\, APAC,CN=Users,...	2Sales	2Sales, APAC

Hasta 15.7, varios grupos que coincidían hasta la coma se reducían a un mismo nombre de permiso, de modo que los miembros de Sales, EMEA y Sales, APAC podían leer los documentos del otro grupo y los del grupo Sales. En 15.9 cada uno obtiene su propio nombre de permiso y ese acceso entre grupos no se produce.

A cambio, los documentos indexados con el nombre de permiso antiguo dejan de ser visibles para los miembros de ese grupo. Si la configuración de permisos de un rastreo contiene un nombre de permiso antiguo, actualícelo al nuevo y vuelva a rastrear (o reindexar). Si no utiliza ningún grupo cuyo CN contenga una coma u otro carácter escapado, ningún nombre de permiso cambia.

Cambio en ldap.role.search.user.enabled

Hasta 15.7, el permiso derivado del nombre de usuario (role.search.user.prefix seguido del nombre de usuario) se concedía incluso con ldap.role.search.user.enabled=false. A partir de 15.9 la opción surte efecto y el permiso no se concede cuando está desactivada.

En una instalación que la tenga en false, los usuarios pierden tras la actualización el permiso que lleva su propio nombre, por lo que los documentos asignados a un usuario concreto dejan de aparecer para ese usuario. Para mantener el comportamiento anterior, restaure el valor predeterminado true.

Si Había Modificado las Claves de Configuración de /api/v2

En 15.8.0, cuatro claves de configuración perdieron su prefijo api.v2.. Sus valores, valores predeterminados y comportamiento no cambian, pero no se conserva ningún alias retrocompatible: una configuración que permanezca con su nombre antiguo se ignora sin ninguna advertencia y se aplica el valor predeterminado incluido.

Hasta 15.7	15.8.0 en adelante	Valor predeterminado
api.v2.chat.stream.keepalive.interval.ms	api.chat.stream.keepalive.interval.ms	15000
api.v2.param.max.length	api.param.max.length	1000
api.v2.param.max.array.size	api.param.max.array.size	100
api.v2.click.max.rt	api.click.max.timestamp	9999999999999

Si estableció alguna de ellas en fess_config.properties o como argumento de JVM -Dfess.config.<clave>, cámbieles el nombre. Solo se ven afectadas las configuraciones explícitas; una instalación que nunca las modificó no requiere ninguna acción.

La primera clave controla con qué frecuencia se envía una trama de keep-alive mientras POST /api/v2/chat/stream espera al modelo, por lo que el modo de búsqueda con IA es donde se nota una configuración perdida. La última clave también se renombró por precisión: limita el valor rt que puede llevar un registro de clic, que es una marca de tiempo y no un tiempo de respuesta.

Actualización de la Versión de los Plugins

Los plugins instalados en app/WEB-INF/plugin/ deben reemplazarse por los correspondientes a la versión de Fess. bin/fess-setup upgrade plugins lo hace para todos los plugins instalados: instala la versión compilada para este Fess y elimina la anterior. Después, reinicie Fess. A continuación, bin/fess-setup check informa sobre OpenSearch, sus plugins y los plugins de Fess instalados, y termina con el código 1 cuando algo va mal. No lee bin/fess.in.sh, /etc/sysconfig/fess ni /etc/default/fess, así que, cuando OpenSearch no está en http://localhost:9200, indique --url o defina SEARCH_ENGINE_HTTP_URL en el shell que lo ejecuta; de lo contrario, informa de que el motor no es accesible.

$ bin/fess-setup upgrade plugins
$ bin/fess-setup check

upgrade plugins solo trata los plugins que ya están instalados. Instale con bin/fess-setup install plugin, como se indica en las secciones anteriores, los plugins que sustituyen a partes eliminadas de la distribución en 15.9, como fess-script-groovy.

Si utiliza FESS_PLUGINS en la versión Docker, actualice la parte de la versión, por ejemplo a fess-ds-wikipedia:15.9.0.

Procedimientos de Reversión

Si la actualización falla, puede revertir con los siguientes procedimientos.

Paso 1: Detención de la Nueva Versión

$ sudo systemctl stop fess.service
$ sudo systemctl stop opensearch.service

Paso 2: Restauración de la Versión Antigua

Restaure los archivos de configuración y datos desde el respaldo.

Para versión RPM/DEB:

$ sudo rpm -Uvh --oldpackage --nodeps fess-<old-version>.rpm

O:

$ sudo dpkg -i fess-<old-version>.deb

Nota

--nodeps es necesario para el RPM. El paquete 15.8.0 requiere los usuarios y grupos fess y opensearch, y sin esa opción rpm rechaza la reversión con Failed dependencies: group(fess) is needed by fess-15.8.0.

Advertencia

El paquete DEB 15.8.0 no registra /etc/fess/* como conffile, por lo que dpkg -i sobrescribe los archivos que haya editado, como /etc/fess/fess_config.properties, sin conservar una copia. Restáurelos desde el respaldo que hizo en el Paso 1.

Paso 3: Restauración de Datos

Restaure desde instantánea. OpenSearch debe estar en ejecución y Fess detenido:

1. Inicie OpenSearch:

   $ sudo systemctl start opensearch.service
   

2. Una instantánea no se puede restaurar sobre un índice que existe, así que elimine antes todos los índices de Fess, incluidos los creados después de la actualización (por ejemplo, con la reindexación) y el índice configsync que crea el plugin de OpenSearch. Si elimina solo los índices que están en la instantánea, un índice creado por la reindexación se queda, fess.search apunta a dos índices y 15.8.0 no se inicia:

   $ curl "http://localhost:9200/_cat/indices/fess*,configsync?h=index"
   $ curl -X DELETE "http://localhost:9200/<index name>"
   

   Ejecute la segunda orden para cada índice que liste la primera.

3. Restaure la instantánea:

   $ curl -X POST "http://localhost:9200/_snapshot/fess_backup/snapshot_1/_restore?wait_for_completion=true"
   

Nota

El directorio de diccionarios debe existir como antes (configsync.config_path, con los archivos de diccionario). En una máquina que lo haya perdido, la restauración termina, pero los índices que usan los diccionarios se quedan en rojo.

O restaure el directorio desde el respaldo (use el nombre del archivo que creó en el Paso 1):

$ sudo systemctl stop opensearch
$ sudo rm -rf /var/lib/opensearch/data/*
$ sudo tar xzf /backup/opensearch-data-<YYYYMMDD>.tar.gz -C /
$ sudo systemctl start opensearch

En la versión Docker, vuelva al archivo Compose de la versión anterior y restaure el contenido de los volúmenes:

$ docker compose -f compose.yaml -f compose-opensearch3.yaml down
$ PROJECT=$(basename "$(pwd)")
$ docker run --rm -v ${PROJECT}_search01_data:/data -v $(pwd):/backup ubuntu \
    sh -c "rm -rf /data/* && tar xzf /backup/search01-data-backup.tar.gz -C /"
$ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d

Nota

Los datos de configuración descargados desde la pantalla de administración pueden reimportarse desde la función de carga en la página «Información del sistema» → «Copia de seguridad» después de iniciar Fess. Solo se pueden cargar archivos *.bulk, archivos *.properties que comiencen con system, archivos *.xml que comiencen con gsa, archivos *.json que comiencen con fess y archivos *.json que comiencen con doc, y solo un archivo por operación. Los archivos *.ndjson, como los registros de búsqueda, no se aceptan y producen un error.

Advertencia

Cargar fess.json y doc.json sobrescribe los propios archivos de definición de índice incluidos con Fess. Si después de la actualización carga la versión antigua de fess.json o doc.json, se perderán la configuración y el mapeo del índice de la nueva versión. No los cargue salvo con fines de reversión.

Nota

El archivo system.properties cargado se lee únicamente en memoria y no se escribe en disco. Por lo tanto, su contenido se pierde al reiniciar Fess. Para restaurarlo de forma fiable, coloque directamente el archivo respaldado en su ubicación correspondiente (app/WEB-INF/conf/ en la versión ZIP, /etc/fess/ en la versión RPM/DEB) antes de iniciar el servicio.

Nota

La importación se ejecuta de forma asíncrona y la pantalla solo muestra que se inició el proceso. Para confirmar si realmente se completó con éxito, consulte fess.log.

Paso 4: Inicio y Verificación del Servicio

$ sudo systemctl start opensearch.service
$ sudo systemctl start fess.service

Verifique el funcionamiento y confirme que volvió a la normalidad.

Preguntas Frecuentes

P: ¿Se puede actualizar sin tiempo de inactividad?

R: La actualización de Fess requiere la detención del servicio. Para minimizar el tiempo de inactividad, considere:

• Verificar los procedimientos con anticipación en un entorno de prueba

• Hacer el respaldo con anticipación

• Asegurar suficiente tiempo de mantenimiento

P: ¿Es necesario actualizar también OpenSearch?

R: Cada versión de Fess requiere una versión específica de OpenSearch. Fess 15.9 es compatible con OpenSearch 3.9.0. Los plugins de OpenSearch para Fess, como opensearch-analysis-fess, deben coincidir exactamente con la versión de OpenSearch; por lo tanto, si actualiza OpenSearch, actualice también los plugins a la versión correspondiente (3.9.0).

Tenga en cuenta que Fess 15.9 requiere el plugin k-NN y siempre envía knn.derived_source.enabled en la configuración del índice. Con un OpenSearch antiguo, la creación de nuevos índices fallará, por lo que en la práctica es necesario actualizar OpenSearch. Para más detalles, consulte el Paso 4.

P: ¿Es necesario recrear el índice?

R: Para una actualización de versión menor de Fess (15.x → 15.9) en la que no se utilice la búsqueda por vector de chunks, generalmente no es necesario. El índice existente puede seguir utilizándose tal cual, y como content_chunker.enabled y otras opciones similares están deshabilitadas de forma predeterminada, el comportamiento no cambia.

En los siguientes casos sí es necesario recrear el índice y reindexar:

• Si habilita recién la búsqueda por vector de chunks (búsqueda semántica): el índice existente no adopta el nuevo mapeo, por lo que la reindexación es obligatoria. Para más detalles, consulte Migración desde la versión 15.7 o anterior (Búsqueda Semántica (Chunking de Contenido + Búsqueda Vectorial)).

• Si actualiza desde 14.x: dado que OpenSearch pasa de la serie 2.x a la 3.x (actualización de versión principal), se recomienda recrear el índice.

• Si usa la búsqueda por propietario o la normalización de kana con un índice de documentos creado con 15.8 o anterior: se necesita una reindexación. Consulte Aplicar los nuevos campos y la normalización de kana a un índice de documentos existente.

Advertencia

Las operaciones que crean un índice nuevo (incluida la reindexación) fallarán en un OpenSearch sin el plugin k-NN. Consulte las notas del Paso 4.

P: Después de la actualización, no se muestran los resultados de búsqueda

R: Verifique lo siguiente:

1. Verifique que OpenSearch esté en ejecución

2. Verifique que exista el índice (curl http://localhost:9200/_cat/indices)

3. Vuelva a ejecutar el rastreo

Próximos Pasos

Una vez completada la actualización:

• Inicio, Detención y Configuración Inicial - Verificación de inicio y configuración inicial

• Configuración de Seguridad - Revisión de configuración de seguridad

• Búsqueda Semántica (Chunking de Contenido + Búsqueda Vectorial) - Configuración y pasos de migración de la búsqueda por vector de chunks (búsqueda semántica)

• Verifique las notas de lanzamiento para nuevas funciones