Actualización y migración

Los componentes de Riversoft® STCP DirectLink se distribuyen como paquetes RPM en el repositorio Riversoft y se actualizan con el gestor de paquetes del sistema, dnf o yum:

La migración de la versión 8 a la versión 9 tiene un procedimiento propio, descrito en Migración de la versión 8 a la versión 9.

Buenas prácticas

• Lea las notas de la versión de todas las versiones entre la instalada y la de destino. Informan cambios de comportamiento, nuevos parámetros y procedimientos específicos.
• Actualice primero un entorno de homologación y repita las pruebas de los flujos críticos antes de actualizar producción.
• Planifique una ventana de mantenimiento y comunique a los socios cuando las transferencias no estén disponibles.
• Haga un backup de la configuración y de las bases de datos antes de cada actualización.
• Actualice a una versión de destino por vez y mantenga la misma versión en todos los servidores del entorno.
• Registre la versión anterior de cada paquete para poder revertir.

Antes de actualizar

Relevamiento

• Registre las versiones instaladas:

  rpm -q stcpgemini-api stcpgemini-portal stcpdirectlink stcpdirectlink-portal

• Verifique las versiones disponibles en el repositorio:

  dnf makecache
  dnf list --showduplicates stcpgemini-api stcpgemini-portal stcpdirectlink stcpdirectlink-portal

• Identifique las transferencias en curso y los enlaces de descarga todavía válidos.

• Defina el responsable del cambio y el plan de reversión.

Backup

• Archivos de configuración:

  Elemento	Archivo
  Riversoft STCP DirectLink	/usr/local/stcpdirectlink/configs/config.json
  Riversoft STCP DirectLink Portal	/usr/local/stcpdirectlink/static/portal/assets/configs/config.json
  Riversoft STCP Gemini API	/usr/local/stcpgemini-api/configs/config.json
  Riversoft Console Portal	/usr/local/stcpgemini-api/portal/app/configs/config.json

• Archivo de licencia (applLicense) y archivos de secretos referenciados en la configuración.

• Base de configuración y base de log, según las políticas de backup de la organización.

• Certificados y claves usados por los servicios.

Procedimiento de actualización

systemctl stop stcpdirectlink
systemctl stop stcpgemini-api

dnf clean all
dnf makecache
dnf upgrade stcpgemini-api stcpgemini-portal stcpdirectlink stcpdirectlink-portal

yum clean all
yum makecache
yum update stcpgemini-api stcpgemini-portal stcpdirectlink stcpdirectlink-portal

find /usr/local/stcpgemini-api /usr/local/stcpdirectlink -name "*.rpmnew"

systemctl start stcpgemini-api
systemctl start stcpdirectlink
systemctl status stcpgemini-api stcpdirectlink

Validación después de la actualización

• rpm -q muestra la versión de destino de cada paquete.
• systemctl status muestra running para la API y para Riversoft STCP DirectLink, sin errores en el log.
• El Riversoft Console Portal se abre y acepta el inicio de sesión.
• Riversoft STCP DirectLink Portal se abre en /portal y acepta el inicio de sesión de un usuario de prueba.
• Una carga y una descarga de prueba se completan por el portal y por la API.
• Los enlaces seguros, las notificaciones y los conectores usados en el entorno funcionan.

Reversión (rollback)

Si la validación falla y la causa no puede corregirse dentro de la ventana de mantenimiento:

1. Detenga los servicios.

2. Vuelva los paquetes a la versión anterior registrada antes de la actualización:

   dnf downgrade stcpgemini-api-<versión-anterior> stcpgemini-portal-<versión-anterior> stcpdirectlink-<versión-anterior> stcpdirectlink-portal-<versión-anterior>

   También es posible deshacer la transacción completa con dnf history undo <id>, donde <id> es el identificador de la transacción mostrado en dnf history. Con yum, use yum downgrade y yum history undo.

3. Restaure los archivos de configuración del backup.

4. Si se ejecutaron scripts de base de datos, restaure el backup de las bases.

5. Inicie los servicios y repita la validación.

Migración de la versión 8 a la versión 9

La migración de la versión 8 a la versión 9 cambia la forma de configuración y de autenticación y tiene un procedimiento propio, descrito en las secciones siguientes. Está destinada a los administradores del entorno y a los equipos responsables de las integraciones con la API. Para otras versiones, siga la actualización descrita arriba y las notas de la versión.

Qué cambia en la versión 9

En la versión 8, parte de la configuración operativa estaba en el archivo config.json. En la versión 9, la configuración se divide entre el archivo local y la base de configuración de la instancia:

La versión 9 también consolida la autenticación de la API:

Parámetros que salen del config.json

Los campos siguientes no deben copiarse del config.json de la versión 8. En la versión 9, se cargan desde la configuración de la instancia en la base de datos:

Si no se informan, el método de firma de los tokens es HS256 y la caducidad es de 3600 segundos. Sin bloqueo externo configurado, la aplicación usa bloqueo en el sistema de archivos del directorio local. Los campos de conexión con la base de configuración (cfgProvider, cfgDbHost, cfgDbPort, cfgDbName, cfgDbUser y cfgDbPswd) no cambian.

Impacto en las integraciones

Adapte los consumidores de la API antes de liberar la versión 9:

Antes de migrar

Relevamiento de la versión 8

• Identifique la instancia, el entorno y el responsable del cambio.
• Haga una copia controlada del config.json de la versión 8.
• Registre el proveedor y los datos de conexión de la base de configuración.
• Registre los servicios habilitados y los flujos críticos de carga, descarga, autenticación y SSO.
• Identifique las integraciones que envían Basic directamente a las rutas de transferencia.
• Identifique las integraciones que usan password grant, token exchange o tokens de larga duración, y los proveedores y emisores de los tokens.
• Liste los proveedores SSO habilitados y el tipo de bloqueo utilizado.
• Registre el método y la caducidad efectivos de los tokens JWT.
• Defina una ventana de indisponibilidad y el plan de retorno.

Accesos y requisitos previos

• Acceso al servidor de la aplicación, a la base de configuración y al Riversoft Console Portal.
• Backup de la base de configuración, del directorio de configuración y de los archivos de control.
• Certificados, claves y secretos disponibles en el mecanismo seguro del entorno.
• Espacio en disco y permisos del directorio de la versión 9 verificados.

Procedimiento de migración

Validación después de la migración

• El servicio se inicia sin errores de conexión con la base de configuración.
• El host usado por los clientes corresponde al configurado para la API.
• El inicio de sesión local con Basic en /auth/login funciona, incluso con MFA, cuando corresponde.
• Se emite un token con el método y la caducidad esperados; el password grant y el token exchange funcionan en los modos habilitados.
• El token se acepta en el header Authorization y la sesión del portal funciona con la cookie.
• El cierre de sesión elimina la cookie y termina el acceso a los recursos protegidos.
• Un token de suplantación válido funciona y se rechaza un identificador no registrado.
• El inicio de sesión de cada proveedor SSO habilitado funciona, y los callbacks OAuth 2.0 y SAML 2.0 llegan a la versión 9.
• La carga, los listados, la descarga autenticada, la descarga por enlace seguro y el informe funcionan.
• Se rechaza una credencial ausente o no válida, y un token válido con conexión bloqueada recibe 403.
• Las notificaciones habilitadas funcionan y los logs no muestran errores de configuración, autenticación o permisos.

Registre las evidencias (hora, instancia, versión, ruta, estado HTTP y resultado). Nunca registre tokens, cookies, contraseñas, PIN ni secretos en las evidencias.

Problemas comunes en la migración

Reversión de la migración

Ejecute la reversión cuando la versión 9 no pueda estabilizarse dentro de la ventana de cambio:

1. Detenga la versión 9 y conserve los logs del intento.
2. Restaure el archivo de configuración y el binario de la versión 8.
3. Confirme que la versión 8 apunta a la configuración y los servicios esperados e iníciela.
4. Restaure en los clientes el contrato de autenticación de la versión 8, si se modificó.
5. Valide la autenticación, la emisión de tokens, la carga, la descarga y los flujos críticos.
6. Registre las configuraciones modificadas en el Portal. Consérvelas hasta analizar la falla.

Seguridad durante la migración

• No comparta el config.json completo fuera del grupo autorizado ni registre secretos en tickets, correos o evidencias.
• Mantenga los tokens técnicos en un almacén de secretos y defina su rotación.
• Habilite solo los modos de autenticación que el entorno necesita.
• Publique el portal y la API por HTTPS para conservar la cookie Secure.
• Use tls=skip-verify en la conexión con la base de datos solo en entornos de prueba controlados. Vea Requisitos › Conexión con TLS.
• Cambie las credenciales que hayan quedado expuestas.