Atualização e migração

Os componentes do Riversoft® STCP DirectLink são distribuídos como pacotes RPM no repositório Riversoft e são atualizados pelo gerenciador de pacotes do sistema, dnf ou yum:

A migração da versão 8 para a versão 9 tem procedimento próprio, descrito em Migração da versão 8 para a versão 9.

Boas práticas

• Leia as notas de versão de todas as versões entre a instalada e a de destino. Elas informam mudanças de comportamento, novos parâmetros e procedimentos específicos.
• Atualize primeiro um ambiente de homologação e repita os testes dos fluxos críticos antes de atualizar a produção.
• Planeje uma janela de manutenção e comunique os parceiros quando houver indisponibilidade das transferências.
• Faça backup da configuração e dos bancos de dados antes de cada atualização.
• Atualize uma versão de destino por vez e mantenha a mesma versão em todos os servidores do ambiente.
• Registre a versão anterior de cada pacote para poder fazer a reversão.

Antes de atualizar

Levantamento

• Registre as versões instaladas:

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

• Confira as versões disponíveis no repositório:

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

• Identifique as transferências em andamento e os links de download ainda válidos.

• Defina o responsável pela mudança e o plano de reversão.

Backup

• Arquivos de configuração:

  Item	Arquivo
  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

• Arquivo de licença (applLicense) e arquivos de segredos referenciados na configuração.

• Banco de configuração e banco de log, conforme as políticas de backup da organização.

• Certificados e chaves usados pelos serviços.

Procedimento de atualização

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

Validação após a atualização

• rpm -q mostra a versão de destino de cada pacote.
• systemctl status mostra running para a API e para o Riversoft STCP DirectLink, sem erros no log.
• O Riversoft Console Portal abre e aceita o login.
• O Riversoft STCP DirectLink Portal abre em /portal e aceita o login de um usuário de teste.
• Um upload e um download de teste são concluídos pelo portal e pela API.
• Os links seguros, as notificações e os conectores usados no ambiente funcionam.

Reversão (rollback)

Se a validação falhar e a causa não puder ser corrigida dentro da janela de manutenção:

1. Pare os serviços.

2. Volte os pacotes para a versão anterior registrada antes da atualização:

   dnf downgrade stcpgemini-api-<versão-anterior> stcpgemini-portal-<versão-anterior> stcpdirectlink-<versão-anterior> stcpdirectlink-portal-<versão-anterior>

   Também é possível desfazer a transação inteira com dnf history undo <id>, em que <id> é o identificador da transação mostrado em dnf history. Com yum, use yum downgrade e yum history undo.

3. Restaure os arquivos de configuração do backup.

4. Se scripts de banco tiverem sido executados, restaure o backup dos bancos de dados.

5. Inicie os serviços e repita a validação.

Migração da versão 8 para a versão 9

A migração da versão 8 para a versão 9 muda a forma de configuração e de autenticação e tem procedimento próprio, descrito nas seções a seguir. Ela é destinada aos administradores do ambiente e às equipes responsáveis pelas integrações com a API. Para outras versões, siga a atualização descrita acima e as notas de versão.

O que muda na versão 9

Na versão 8, parte da configuração operacional ficava no arquivo config.json. Na versão 9, a configuração passa a ser dividida entre o arquivo local e o banco de configuração da instância:

A versão 9 também consolida a autenticação da API:

Parâmetros que saem do config.json

Os campos abaixo não devem ser copiados do config.json da versão 8. Na versão 9, eles são carregados da configuração da instância no banco:

Quando não informados, o método de assinatura dos tokens é HS256 e a expiração é de 3600 segundos. Sem lock externo configurado, a aplicação usa lock em sistema de arquivos no diretório local. Os campos de conexão com o banco de configuração (cfgProvider, cfgDbHost, cfgDbPort, cfgDbName, cfgDbUser e cfgDbPswd) não mudam.

Impacto nas integrações

Adeque os consumidores da API antes de liberar a versão 9:

Antes de migrar

Levantamento da versão 8

• Identifique a instância, o ambiente e o responsável pela mudança.
• Faça uma cópia controlada do config.json da versão 8.
• Registre o provider e os dados de conexão do banco de configuração.
• Registre os serviços habilitados e os fluxos críticos de upload, download, autenticação e SSO.
• Identifique as integrações que enviam Basic diretamente às rotas de transferência.
• Identifique as integrações que usam password grant, token exchange ou token de longa duração, e os provedores e emissores dos tokens.
• Liste os provedores SSO habilitados e o tipo de lock utilizado.
• Registre o método e a expiração efetivos dos tokens JWT.
• Defina uma janela de indisponibilidade e o plano de retorno.

Acessos e pré-requisitos

• Acesso ao servidor da aplicação, ao banco de configuração e ao Riversoft Console Portal.
• Backup do banco de configuração, do diretório de configuração e dos arquivos de controle.
• Certificados, chaves e segredos disponíveis no mecanismo seguro do ambiente.
• Espaço em disco e permissões do diretório da versão 9 conferidos.

Procedimento de migração

Validação após a migração

• O serviço inicia sem erro de conexão com o banco de configuração.
• O host usado pelos clientes corresponde ao configurado para a API.
• O login local com Basic em /auth/login funciona, inclusive com MFA, quando aplicável.
• Um token é emitido com o método e a expiração esperados; password grant e token exchange funcionam nos modos habilitados.
• O token é aceito no header Authorization e a sessão do portal funciona pelo cookie.
• O logout remove o cookie e encerra o acesso aos recursos protegidos.
• O token de impersonação válido funciona e um identificador não registrado é rejeitado.
• O login de cada provedor SSO habilitado funciona, e os callbacks OAuth 2.0 e SAML 2.0 chegam à versão 9.
• Upload, listagens, download autenticado, download por link seguro e relatório funcionam.
• Credencial ausente ou inválida é rejeitada, e um token válido com conexão bloqueada recebe 403.
• As notificações habilitadas funcionam e os logs não apresentam erros de configuração, autenticação ou permissão.

Registre as evidências (horário, instância, versão, rota, status HTTP e resultado). Nunca registre token, cookie, senha, PIN ou segredo nas evidências.

Problemas comuns na migração

Reversão da migração

Execute a reversão quando a versão 9 não puder ser estabilizada dentro da janela de mudança:

1. Interrompa a versão 9 e preserve os logs da tentativa.
2. Restaure o arquivo de configuração e o binário da versão 8.
3. Confirme que a versão 8 aponta para a configuração e os serviços esperados e inicie-a.
4. Restaure nos clientes o contrato de autenticação da versão 8, se ele tiver sido alterado.
5. Valide autenticação, emissão de token, upload, download e os fluxos críticos.
6. Registre as configurações alteradas no Portal. Preserve esses cadastros até a análise da falha.

Segurança durante a migração

• Não compartilhe o config.json completo fora do grupo autorizado nem registre segredos em chamados, e-mails ou evidências.
• Mantenha os tokens técnicos em cofre de segredos e defina a rotação.
• Habilite somente os modos de autenticação necessários ao ambiente.
• Publique o portal e a API por HTTPS para preservar o cookie Secure.
• Use tls=skip-verify na conexão com o banco somente em ambientes controlados de teste. Veja Requisitos › Conexão com TLS.
• Troque as credenciais que tenham sido expostas.