DocumentaçãoCommerceGuia de atualização

Concluir os pré-requisitos de atualização

Last update: Mon Jul 15 2024 00:00:00 GMT+0000 (Coordinated Universal Time)
  • Tópicos:

Criado para:

  • Experiente
  • Administrador
  • Desenvolvedor

É importante entender o que é necessário para executar o Adobe Commerce. Você deve primeiro revisar os requisitos do sistema para a versão para a qual você pretende atualizar.

Depois de revisar os requisitos do sistema, você deve concluir os seguintes pré-requisitos antes de atualizar o sistema:

  • Atualizar todo o software
  • Verifique se há um mecanismo de pesquisa compatível instalado
  • Converter formato de tabela de banco de dados
  • Definir o limite de arquivos abertos
  • Verifique se os trabalhos cron estão em execução
  • Conjunto DATA_CONVERTER_BATCH_SIZE
  • Verificar permissões do sistema de arquivos
  • Definir a raiz do diretório pub/
  • Instalar o plug-in de atualização do Composer

Atualizar todo o software

Os requisitos de sistema descrevem exatamente quais versões de software de terceiros foram testadas com versões do Adobe Commerce.

Atualize todos os requisitos e dependências do sistema em seu ambiente. Consulte PHP 7.4, PHP 8.0, PHP 8.1 e configurações PHP necessárias.

NOTE
Para projetos Pro da infraestrutura em nuvem do Adobe Commerce, você deve criar um tíquete de Suporte para instalar ou atualizar serviços em ambientes de Preparo e Produção. Indique as mudanças de serviço necessárias e inclua seus arquivos .magento.app.yaml e services.yaml atualizados e a versão do PHP no tíquete. Pode levar até 48 horas para a equipe de infraestrutura da nuvem atualizar seu projeto. Consulte Software e serviços com suporte.

Verifique se há um mecanismo de pesquisa compatível instalado

A Adobe Commerce exige que o Elasticsearch ou o OpenSearch seja instalado para usar o software.

Se estiver atualizando de 2.3.x para 2.4, você deve verificar se está usando MySQL, Elasticsearch ou uma extensão de terceiros como mecanismo de pesquisa de catálogo na instância 2.3.x. O resultado determina o que você deve fazer antes de atualizar para a versão 2.4.

Se estiver atualizando versões de patch nas linhas 2.3.x ou 2.4.x, se o Elasticsearch 7.x já estiver instalado, você poderá migrar para OpenSearch, se desejar.

Você pode usar a linha de comando ou o Administrador para determinar o mecanismo de pesquisa do catálogo:

  • Digite o comando bin/magento config:show catalog/search/engine. O comando retorna um valor de mysql, elasticsearch (que indica que o Elasticsearch 2 está configurado), elasticsearch5, elasticsearch6, elasticsearch7 ou um valor personalizado, indicando que você instalou um mecanismo de pesquisa de terceiros. Para versões anteriores à 2.4.6, use o valor elasticsearch7 para o mecanismo Elasticsearch 7 ou OpenSearch. Para a versão 2.4.6 e posterior, use o valor opensearch para o mecanismo OpenSearch.

  • No Admin, verifique o valor do campo Stores > Settings > Configuration > Catalog > Catalog > Catalog Search > Search Engine.

As seções a seguir descrevem quais ações devem ser executadas antes da atualização para a versão 2.4.0.

MySQL

A partir da versão 2.4, o MySQL não é mais um mecanismo de pesquisa de catálogo compatível. Você deve instalar e configurar o Elasticsearch ou o OpenSearch antes da atualização. Use os seguintes recursos para ajudar a orientá-lo durante esse processo:

Alguns mecanismos de pesquisa de catálogos de terceiros são executados sobre o mecanismo de pesquisa do Adobe Commerce. Entre em contato com seu fornecedor para determinar se você deve atualizar sua extensão.

MariaDB

A reindexação no MariaDB 10.4 e 10.6 leva mais tempo em comparação com as versões anteriores do MariaDB ou MySQL. Para acelerar a reindexação, recomendamos definir esses parâmetros de configuração do MariaDB:

Se você sofrer degradação de desempenho não relacionada à indexação após a atualização para MariaDB 10.6, considere habilitar a configuração --query-cache-type. Por exemplo, --query-cache-type=ON.

Antes de atualizar o Adobe Commerce em projetos de infraestrutura em nuvem, talvez também seja necessário atualizar o MariaDB (consulte práticas recomendadas de atualização do MariaDB).

Por exemplo:

  • Adobe Commerce 2.4.6 com MariaDB versão 10.5.1 ou superior
  • Adobe Commerce 2.3.5 com MariaDB versão 10.3 ou anterior

Além dessas recomendações, você deve consultar o administrador do banco de dados sobre a configuração dos seguintes parâmetros:

NOTE
Essas configurações estão disponíveis somente para implantações locais. Os clientes do Adobe Commerce na infraestrutura em nuvem não têm acesso a essas configurações.

Mecanismo de pesquisa

Você deve instalar e configurar o Elasticsearch 7.6 ou superior ou o OpenSearch 1.2 antes de atualizar para a versão 2.4.0. O Adobe não suporta mais os Elasticsearch 2.x, 5.x e 6.x. A configuração do mecanismo de pesquisa, no Guia de Configuração, descreve as tarefas que devem ser executadas após atualizar o Elasticsearch para uma versão com suporte.

Consulte Atualizando o Elasticsearch para obter instruções completas sobre como fazer backup de seus dados, detectar possíveis problemas de migração e testar atualizações antes de implantar na produção. Dependendo da sua versão atual do Elasticsearch, uma reinicialização completa do cluster pode ou não ser necessária.

O Elasticsearch exige o Java Development Kit (JDK) 1.8 ou superior. Consulte Instalar o Java Software Development Kit (JDK) para verificar qual versão do JDK está instalada.

OpenSearch

OpenSearch é uma bifurcação de código aberto do Elasticsearch 7.10.2, após a mudança de licenciamento do Elasticsearch. As seguintes versões do Adobe Commerce apresentam suporte para o OpenSearch:

  • 2.4.6 (O OpenSearch tem um módulo e configurações separados)
  • 2.4.5
  • 2.4.4
  • 2.4.3-p2
  • 2.3.7-p3

Você pode migrar do Elasticsearch para o OpenSearch somente se estiver atualizando para uma versão do Adobe Commerce listada acima (ou superior).

OpenSearch requer JDK 1.8 ou superior. Consulte Instalar o Java Software Development Kit (JDK) para verificar qual versão do JDK está instalada.

A configuração do mecanismo de pesquisa descreve as tarefas que devem ser executadas após a alteração dos mecanismos de pesquisa.

Atualizar o Elasticsearch

O suporte para o Elasticsearch 8.x foi introduzido no Adobe Commerce 2.4.6. As instruções a seguir mostram um exemplo de atualização do Elasticsearch de 7.x para 8.x:

  1. Atualize o servidor Elasticsearch 7.x para 8.x e certifique-se de que o esteja funcionando. Consulte a documentação do Elasticsearch.

  2. Habilite o campo id_field_data adicionando a seguinte configuração ao arquivo elasticsearch.yml e reiniciando o serviço Elasticsearch 8.x.

    code language-yaml 
    indices:
  id_field_data:
    enabled: true
    note info
    INFO
    Para oferecer suporte ao Elasticsearch 8.x, o Adobe Commerce 2.4.6 não permite a propriedade indices.id_field_data por padrão e usa o campo _id na propriedade docvalue_fields.

  3. No diretório raiz do seu projeto Adobe Commerce, atualize suas dependências do Composer para remover o módulo Magento_Elasticsearch7 e instalar o módulo Magento_Elasticsearch8.

    code language-bash 
    composer require magento/module-elasticsearch-8 --update-with-all-dependencies

  4. Atualize os componentes do projeto.

    code language-bash 
    bin/magento setup:upgrade

  5. Configurar Elasticsearch no Admin.

  6. Reindexe o índice do catálogo.

    code language-bash 
    bin/magento indexer:reindex catalogsearch_fulltext

  7. Excluir todos os itens dos tipos de cache ativados.

    code language-bash 
    bin/magento cache:clean

Elasticsearch de downgrade

Se você atualizar inadvertidamente a versão do Elasticsearch no servidor ou determinar que precisa fazer downgrade por qualquer outro motivo, também deverá atualizar as dependências do projeto do Adobe Commerce. Por exemplo, para fazer o downgrade do Elasticsearch 8.x para o 7.x

  1. Faça o downgrade do servidor Elasticsearch 8.x para 7.x e certifique-se de que o esteja funcionando. Consulte a documentação do Elasticsearch.

  2. No diretório raiz do seu projeto Adobe Commerce, atualize suas dependências do Composer para remover o módulo Magento_Elasticsearch8 e suas dependências do Composer, e instale o módulo Magento_Elasticsearch7.

    code language-bash 
    composer remove magento/module-elasticsearch-8

  3. Atualize os componentes do projeto.

    code language-bash 
    bin/magento setup:upgrade

  4. Configurar Elasticsearch no Admin.

  5. Reindexe o índice do catálogo.

    code language-bash 
    bin/magento indexer:reindex catalogsearch_fulltext

  6. Excluir todos os itens dos tipos de cache ativados.

    code language-bash 
    bin/magento cache:clean

Extensões de terceiros

Recomendamos que você entre em contato com o fornecedor do mecanismo de pesquisa para determinar se sua extensão é totalmente compatível com uma versão do Adobe Commerce.

Converter formato de tabela de banco de dados

Você deve converter o formato de todas as tabelas do banco de dados de COMPACT para DYNAMIC. Você também deve converter o tipo de mecanismo de armazenamento de MyISAM para InnoDB. Consulte práticas recomendadas.

Definir o limite de arquivos abertos

Definir o limite de arquivos abertos (ulimit) pode ajudar a evitar falhas de várias chamadas recursivas de cadeias de caracteres de consulta longas ou problemas com o uso do comando bin/magento setup:rollback. Esse comando é diferente para shells UNIX diferentes. Consulte seu tipo individual para obter informações específicas sobre o comando ulimit.

A Adobe recomenda definir os arquivos abertos ulimit com um valor de 65536 ou mais, mas você pode usar um valor maior, se necessário. Você pode definir o ulimit na linha de comando ou pode torná-lo uma configuração permanente para o shell do usuário.

Para definir o ulimit a partir da linha de comando:

  1. Alternar para o proprietário do sistema de arquivos.

  2. Defina o limite para 65536.

    code language-bash 
    ulimit -n 65536

Para definir o valor no seu shell Bash:

  1. Alternar para o proprietário do sistema de arquivos.

  2. Abra /home/<username>/.bashrc em um editor de texto.

  3. Adicione a seguinte linha:

    code language-bash 
    ulimit -n 65536

  4. Salve as alterações no arquivo .bashrc e saia do editor de texto.

IMPORTANT
Recomendamos que você evite definir um valor para a propriedade pcre.recursion_limit no arquivo php.ini porque isso pode resultar em reversões incompletas sem aviso de falha.

Verifique se os trabalhos cron estão em execução

O agendador de tarefas do UNIX cron é essencial para as operações diárias do Adobe Commerce. Ele agenda itens como reindexação, boletins informativos, emails e mapas de site. Vários recursos exigem pelo menos um trabalho cron em execução como proprietário do sistema de arquivos.

Para verificar se o trabalho cron está configurado corretamente, verifique o crontab inserindo o seguinte comando como proprietário do sistema de arquivos:

NOTE
O crontab é o arquivo de configuração responsável pela execução dos trabalhos cron.
crontab -l

Resultados semelhantes aos seguintes devem ser exibidos:

#~ MAGENTO START c5f9e5ed71cceaabc4d4fd9b3e827a2b
* * * * * /usr/bin/php /var/www/html/magento2/bin/magento cron:run 2>&1 | grep -v "Ran jobs by schedule" >> /var/www/html/magento2/var/log/magento.cron.log
#~ MAGENTO END c5f9e5ed71cceaabc4d4fd9b3e827a2b

Outro sintoma de que o CRON não está sendo executado é o seguinte erro no Administrador:

Para ver o erro, clique em Mensagens do Sistema na parte superior da janela da seguinte maneira:

Consulte Configurar e executar o cron para obter mais informações.

Definir DATA_CONVERTER_BATCH_SIZE

O Adobe Commerce 2.4 inclui aprimoramentos de segurança que exigem que alguns dados sejam convertidos de serializados para JSON. Essa conversão ocorre durante a atualização e pode levar muito tempo, dependendo da quantidade de dados no banco de dados.

As tabelas a seguir são as mais afetadas:

  • catalogrule
  • core_config_data
  • magento_reward_history
  • quote_payment
  • quote
  • sales_order_payment
  • sales_order
  • salesrule
  • url_rewrite

Se você tiver uma grande quantidade de dados, poderá melhorar o desempenho definindo o valor de uma variável de ambiente, DATA_CONVERTER_BATCH_SIZE. Por padrão, o valor está definido como 50,000.

Para definir a variável de ambiente:

  1. Alternar para o proprietário do sistema de arquivos.

  2. Defina a variável:

    code language-bash 
    export DATA_CONVERTER_BATCH_SIZE=100000
    note note
    NOTE
    DATA_CONVERTER_BATCH_SIZE requer memória; evite configurá-la com um valor alto (aproximadamente 1 GB) sem testá-la primeiro.

  3. Após a conclusão da atualização, é possível desfazer a definição da variável:

    code language-bash 
    unset DATA_CONVERTER_BATCH_SIZE

Verificar permissões do sistema de arquivos

Por motivos de segurança, o Adobe Commerce exige determinadas permissões no sistema de arquivos. As permissões são diferentes de propriedade. A propriedade determina quem pode executar ações no sistema de arquivos; as permissões determinam o que o usuário pode fazer.

Os diretórios no sistema de arquivos devem ser graváveis pelo grupo 🔗 do proprietário do sistema de arquivos.

Para verificar se as permissões do sistema de arquivos estão definidas corretamente, faça logon no servidor de aplicativos ou use o aplicativo gerenciador de arquivos do provedor de hospedagem.

Por exemplo, insira o seguinte comando se o aplicativo estiver instalado em /var/www/html/magento2:

ls -l /var/www/html/magento2

Saída de exemplo:

total 1028
drwxrwx---. 12 magento_user apache   4096 Jun  7 07:55 .
drwxr-xr-x.  3 root         root     4096 May 11 14:29 ..
drwxrwx---.  4 magento_user apache   4096 Jun  7 07:53 app
drwxrwx---.  2 magento_user apache   4096 Jun  7 07:53 bin
-rw-rw----.  1 magento_user apache 439792 Apr 27 21:23 CHANGELOG.md
-rw-rw----.  1 magento_user apache   3422 Apr 27 21:23 composer.json
-rw-rw----.  1 magento_user apache 425214 Apr 27 21:27 composer.lock
-rw-rw----.  1 magento_user apache   3425 Apr 27 21:23 CONTRIBUTING.md
-rw-rw----.  1 magento_user apache  10011 Apr 27 21:23 CONTRIBUTOR_LICENSE_AGREEMENT.html
-rw-rw----.  1 magento_user apache    631 Apr 27 21:23 COPYING.txt
drwxrwx---.  4 magento_user apache   4096 Jun  7 07:53 dev
-rw-rw----.  1 magento_user apache   2926 Apr 27 21:23 Gruntfile.js
-rw-rw----.  1 magento_user apache   7592 Apr 27 21:23 .htaccess
-rw-rw----.  1 magento_user apache   6419 Apr 27 21:23 .htaccess.sample
drwxrwx---.  4 magento_user apache   4096 Jun  7 07:53 lib
-rw-rw----.  1 magento_user apache  10376 Apr 27 21:23 LICENSE_AFL.txt
-rw-rw----.  1 magento_user apache  30634 Apr 27 21:23 LICENSE_EE.txt
-rw-rw----.  1 magento_user apache  10364 Apr 27 21:23 LICENSE.txt
-rw-rw----.  1 magento_user apache   4108 Apr 27 21:23 nginx.conf.sample
-rw-rw----.  1 magento_user apache   1427 Apr 27 21:23 package.json
-rw-rw----.  1 magento_user apache   1659 Apr 27 21:23 .php_cs
-rw-rw----.  1 magento_user apache    804 Apr 27 21:23 php.ini.sample
drwxrwx---.  2 magento_user apache   4096 Jun  7 07:53 phpserver
drwxrwx---.  6 magento_user apache   4096 Jun  7 07:53 pub
-rw-rw----.  1 magento_user apache   2207 Apr 27 21:23 README_EE.md
drwxrwx---.  7 magento_user apache   4096 Jun  7 07:53 setup
-rw-rw----.  1 magento_user apache   3731 Apr 27 21:23 .travis.yml
drwxrwx---.  7 magento_user apache   4096 Jun  7 07:53 update
drwxrws---. 11 magento_user apache   4096 Jun 13 16:05 var
drwxrws---. 29 magento_user apache   4096 Jun  7 07:53 vendor

Consulte o seguinte para obter uma explicação do exemplo de saída:

  • A maioria dos arquivos é -rw-rw----, que é 660
  • drwxrwx--- = 770
  • -rw-rw-rw- = 666
  • O proprietário do sistema de arquivos é magento_user

Para obter informações mais detalhadas, você pode inserir o seguinte comando:

ls -la /var/www/html/magento2/pub

Como o Adobe Commerce implanta ativos de arquivos estáticos em subdiretórios de pub, também é uma boa ideia verificar as permissões e a propriedade lá.

Para obter mais informações, consulte Permissões e propriedade do sistema de arquivos.

Definir a raiz do diretório pub/

Consulte Modificar docroot para melhorar a segurança para obter mais detalhes.

Instalar o plug-in de atualização do Composer

O plug-in Composer magento/composer-root-update-plugin resolve as alterações que devem ser feitas no arquivo composer.json do projeto raiz antes da atualização para um novo requisito de produto.

O plug-in automatiza parcialmente a atualização manual, identificando e ajudando você a resolver conflitos de dependência em vez de exigir que você os identifique e corrija manualmente.

Para instalar o plugin:

  1. Adicione o pacote ao arquivo composer.json.

    code language-bash 
    composer require magento/composer-root-update-plugin ~2.0 --no-update

  2. Atualize as dependências:

    code language-bash 
    composer update
recommendation-more-help
83a60e0e-8849-4685-a8cd-c129ecd795ea