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.7

  • Fess 15.x → Fess 15.7

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.

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 enlace para descargarlos (son archivos individuales por elemento, no un único archivo ZIP).

    • fess_basic_config.bulk - Configuración básica (ajustes generales)

    • fess_config.bulk - Ajustes de rastreo, programador, etiquetas, coincidencias de clave y otra configuración

    • fess_user.bulk - Usuarios, roles y grupos

    • system.properties - Configuración del sistema

    • fess.json / doc.json - Configuración del índice (mappings)

    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) también pueden descargarse desde la misma página. No son necesarios si solo desea hacer un respaldo de la configuración.

  2. Respaldo de archivos de configuración

    Versión TAR.GZ/ZIP:

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

    Versión RPM/DEB:

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

  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/

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:

$ docker compose -f compose.yaml -f compose-opensearch3.yaml stop
$ docker run --rm -v search01_data:/data -v $(pwd):/backup ubuntu tar czf /backup/search01-data-backup.tar.gz /data
$ docker run --rm -v 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

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

Detenga Fess y OpenSearch.

Versión TAR.GZ/ZIP:

$ kill <fess_pid>
$ kill <opensearch_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

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

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

Versión TAR.GZ/ZIP

  1. Descargue y extraiga la nueva versión:

    $ wget https://github.com/codelibs/fess/releases/download/fess-15.7.0/fess-15.7.0.tar.gz
$ tar -xzf fess-15.7.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.7.0/app/WEB-INF/conf/
$ cp /path/to/old-fess/bin/fess.in.sh /path/to/fess-15.7.0/bin/

  3. 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.7.0.rpm

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

Nota

Los archivos de configuración (/etc/fess/*) se conservan automáticamente. Sin embargo, si se han agregado nuevas opciones de configuración, es necesario ajustarlas manualmente.

Versión Docker

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

    $ wget https://raw.githubusercontent.com/codelibs/docker-fess/v15.7.0/compose/compose.yaml
$ wget https://raw.githubusercontent.com/codelibs/docker-fess/v15.7.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 (Si es Necesario)

Si también actualiza OpenSearch, siga estos procedimientos.

Nota

Este procedimiento corresponde a los casos en que OpenSearch se gestiona manualmente en las versiones TAR.GZ/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.

Advertencia

Realice con cuidado las actualizaciones de versión principal de OpenSearch. Pueden surgir problemas de compatibilidad del índice.

  1. Instale la nueva versión de OpenSearch

  2. Reinstale los plugins:

    $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-fess:3.7.0
$ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-extension:3.7.0
$ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-minhash:3.7.0
$ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-configsync:3.7.0

    Nota

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

  3. Inicie OpenSearch:

    $ sudo systemctl start opensearch.service

Paso 5: Inicio de la Nueva Versión

Versión TAR.GZ/ZIP:

$ cd /path/to/fess-15.7.0
$ ./bin/fess -d

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:

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

  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.

  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

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 fess-<old-version>.rpm

O:

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

Paso 3: Restauración de Datos

Restaure desde instantánea:

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

O restaure el directorio desde el respaldo:

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

Nota

Los datos de configuración descargados desde la pantalla de administración (archivos *.bulk) pueden reimportarse desde la función de carga en la página «Información del sistema» → «Copia de seguridad» después de iniciar Fess.

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.7 es compatible con OpenSearch 3.7.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.7.0).

P: ¿Es necesario recrear el índice?

R: Generalmente no es necesario para actualizaciones de versión menor, pero se recomienda la recreación para actualizaciones de versión principal.

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: