Atualizar versão do Commerce
Você pode atualizar a base de código do Adobe Commerce para uma versão mais recente. Antes de atualizar seu projeto, verifique os requisitos de sistema no guia Instalação para obter os requisitos de versão de software mais recentes.
Dependendo da configuração do seu projeto, suas tarefas de atualização podem incluir o seguinte:
- Serviços de atualização — como MariaDB (MySQL), OpenSearch, RabbitMQ e Redis — para compatibilidade com novas versões do Adobe Commerce.
- Converta um arquivo de gerenciamento de configuração mais antigo.
- Atualize o arquivo
.magento.app.yaml
com novas configurações para ganchos e variáveis de ambiente. - Atualize extensões de terceiros para a versão mais recente com suporte.
- Atualize o arquivo
.gitignore
.
Staging
e Production
..magento.app.yaml
e do services.yaml
e informe a versão do PHP no tíquete. Para alterações de autoatendimento na versão, extensões ou configurações do ambiente do PHP, consulte configurações do PHP em Configuração do aplicativo.Atualizar a partir de versões anteriores
Se você estiver iniciando uma atualização de uma versão do Commerce anterior à versão 2.1, algumas restrições na base de código do Adobe Commerce poderão afetar sua capacidade de atualizar para uma versão específica das Ferramentas ECE ou de atualizar para a próxima versão do Commerce com suporte. Use a tabela a seguir para determinar o melhor caminho:
Consulte as notas de versão de 2002.0.9 e versões posteriores de 2002.0.x.
ece-tools
, será necessário executar uma atualização única para o projeto em nuvem, a fim de remover pacotes obsoletos. Se você usa atualmente o pacote ece-tools
e precisa atualizá-lo, consulte Atualizar o pacote ECE-Tools.Gerenciamento de configuração
Versões anteriores do Adobe Commerce, como 2.1.4 ou posterior a 2.2.x ou posterior, usavam um arquivo config.local.php
para o Gerenciamento de configuração. O Adobe Commerce versão 2.2.0 e posterior usa o arquivo config.php
, que funciona exatamente como o arquivo config.local.php
, mas tem definições de configuração diferentes que incluem uma lista de módulos habilitados e opções de configuração adicionais.
Ao atualizar de uma versão mais antiga, você deve migrar o arquivo config.local.php
para usar o arquivo config.php
mais recente. Use as etapas a seguir para fazer backup do arquivo de configuração e criar um.
Para criar um config.php
arquivo temporário:
-
Crie uma cópia do arquivo
config.local.php
e nomeie-a comoconfig.php
. -
Adicione este arquivo à pasta
app/etc
do seu projeto. -
Adicione e confirme o arquivo na ramificação.
-
Envie o arquivo para a ramificação de integração.
-
Continue com o processo de atualização.
config.php
e gerar um arquivo novo e completo. Você só pode excluir este arquivo para substituí-lo desta vez. Após gerar um novo arquivo config.php
completo, você não pode excluir o arquivo para gerar um novo. Consulte Gerenciamento de configuração e implantação de pipeline.Verificar dependências do Zend Framework Composer
Ao atualizar de 2.2.x para 2.3.x ou posterior, verifique se as dependências do Zend Framework foram adicionadas à propriedade autoload
do arquivo composer.json
para dar suporte ao Laminas. Este plug-in suporta novos requisitos para o Zend Framework, que migrou para o projeto Laminas. Consulte Migration of Zend Framework to the Laminas Project no Magento DevBlog.
Para verificar a auto-load:psr-4
configuração:
-
Na estação de trabalho local, altere para o diretório do projeto.
-
Confira a ramificação de integração.
-
Abra o arquivo
composer.json
em um editor de texto. -
Verifique a seção
autoload:psr-4
para a implementação do gerenciador de plug-in Zend para dependência de controladores.code language-json "autoload": { "psr-4": { "Magento\\Framework\\": "lib/internal/Magento/Framework/", "Magento\\Setup\\": "setup/src/Magento/Setup/", "Magento\\": "app/code/Magento/", "Zend\\Mvc\\Controller\\": "setup/src/Zend/Mvc/Controller/" }, }
-
Se a dependência Zend estiver ausente, atualize o arquivo
composer.json
:-
Adicione a seguinte linha à seção
autoload:psr-4
.code language-json "Zend\\Mvc\\Controller\\": "setup/src/Zend/Mvc/Controller/"
-
Atualize as dependências do projeto.
code language-bash composer update
-
Adicionar, confirmar e enviar alterações de código.
code language-bash git add -A
code language-bash git commit -m "Add Zend plugin manager implementation for controllers dependency for Laminas support"
code language-bash git push origin <branch-name>
-
Mescle as alterações no ambiente de preparo e, em seguida, na produção.
-
Arquivos de configuração
Antes de atualizar o aplicativo, você deve atualizar os arquivos de configuração do projeto para levar em conta as alterações nas configurações padrão do Adobe Commerce na infraestrutura em nuvem ou no aplicativo. Os padrões mais recentes podem ser encontrados no repositório GitHub da magento-cloud.
.magento.app.yaml
Sempre examine os valores contidos no arquivo .magento.app.yaml para a sua versão instalada, pois ele controla a maneira como o aplicativo é criado e implantado na infraestrutura de nuvem. O exemplo a seguir é para a versão 2.4.7 e usa o Composer 2.7.2. A propriedade build: flavor:
não é usada para o Composer 2.x; consulte Instalando e usando o Composer 2.
Para atualizar o .magento.app.yaml
arquivo:
-
Na estação de trabalho local, altere para o diretório do projeto.
-
Abra e edite o arquivo
magento.app.yaml
. -
Atualize as opções do PHP.
code language-yaml type: php:8.3 build: flavor: none dependencies: php: composer/composer: '2.7.2'
-
Modifique os comandos
build
edeploy
da propriedadehooks
.code language-yaml hooks: # We run build hooks before your application has been packaged. build: | set -e composer install php ./vendor/bin/ece-tools run scenario/build/generate.xml php ./vendor/bin/ece-tools run scenario/build/transfer.xml # We run deploy hook after your application has been deployed and started. deploy: | php ./vendor/bin/ece-tools run scenario/deploy.xml # We run post deploy hook to clean and warm the cache. Available with ECE-Tools 2002.0.10. post_deploy: | php ./vendor/bin/ece-tools run scenario/post-deploy.xml
-
Adicione as variáveis de ambiente a seguir ao final do arquivo.
Para o Adobe Commerce 2.2.x a 2.3.x-
code language-yaml variables: env: CONFIG__DEFAULT__PAYPAL_ONBOARDING__MIDDLEMAN_DOMAIN: 'payment-broker.magento.com' CONFIG__STORES__DEFAULT__PAYMENT__BRAINTREE__CHANNEL: 'Magento_Enterprise_Cloud_BT' CONFIG__STORES__DEFAULT__PAYPAL__NOTATION_CODE: 'Magento_Enterprise_Cloud'
Para o Adobe Commerce 2.4.x-
code language-yaml variables: env: CONFIG__DEFAULT__PAYPAL_ONBOARDING__MIDDLEMAN_DOMAIN: 'payment-broker.magento.com' CONFIG__STORES__DEFAULT__PAYPAL__NOTATION_CODE: 'Magento_Enterprise_Cloud'
-
Salve o arquivo. Não confirme ou envie alterações para o ambiente remoto ainda.
-
Continue com o processo de atualização.
composer.json
Antes de atualizar, sempre verifique se as dependências no arquivo composer.json
são compatíveis com a versão do Adobe Commerce.
Para atualizar o arquivo composer.json
para o Adobe Commerce versão 2.4.4 e posterior:
-
Adicionar o seguinte
allow-plugins
à seçãoconfig
:code language-json "config": { "allow-plugins": { "dealerdirect/phpcodesniffer-composer-installer": true, "laminas/laminas-dependency-plugin": true, "magento/*": true } },
-
Adicionar o seguinte plug-in à seção
require
:code language-json "require": { "magento/composer-root-update-plugin": "^2.0.3" },
-
Adicionar o seguinte componente à seção
extra:component_paths
:code language-json "extra": { "component_paths": { "tinymce/tinymce": "lib/web/tiny_mce_5" }, },
-
Salve o arquivo. Não confirme ou envie alterações para sua ramificação ainda.
-
Continue com o processo de atualização.
Backup do projeto
Recomendamos criar um backup do seu projeto antes de uma atualização. Use as etapas a seguir para fazer backup dos ambientes de integração, de preparo e de produção.
Para fazer backup do banco de dados e do código do ambiente de integração:
-
Crie um backup local do banco de dados remoto.
code language-bash magento-cloud db:dump
note note NOTE O comando magento-cloud db:dump
executa o comando mysqldump com o sinalizador--single-transaction
, que permite fazer backup do banco de dados sem bloquear as tabelas. -
Faça backup do código e da mídia.
code language-bash php bin/magento setup:backup --code [--media]
Opcionalmente, você pode omitir
[--media]
se tiver um grande número de arquivos estáticos que já estão no controle do código-fonte.
Para fazer backup do banco de dados do ambiente de Preparo ou Produção antes de implantar:
-
Use o SSH para fazer logon no ambiente remoto.
-
Criar um despejo de banco de dados. Para escolher um diretório de destino para o despejo do banco de dados, use a opção
--dump-directory
.code language-bash vendor/bin/ece-tools db-dump
A operação de despejo cria um arquivo morto
dump-<timestamp>.sql.gz
no diretório do projeto remoto. Consulte Fazer backup do banco de dados.
Atualização de aplicativo
Examine as informações das versões de serviço para obter os requisitos de versão de software mais recentes antes de atualizar seu aplicativo.
Para atualizar a versão do aplicativo:
-
Na estação de trabalho local, altere para o diretório do projeto.
-
Defina a versão de atualização usando a sintaxe de restrição de versão.
code language-bash composer require "magento/magento-cloud-metapackage":">=CURRENT_VERSION <NEXT_VERSION" --no-update
note note NOTE Você deve usar a sintaxe de restrição de versão para atualizar o pacote ece-tools
com êxito. Você pode localizar a restrição de versão no arquivocomposer.json
da versão do modelo de aplicativo que você está usando para a atualização. -
Atualize o projeto.
code language-bash composer update
-
Adicionar, confirmar e enviar alterações de código.
code language-bash git add -A
code language-bash git commit -m "Upgrade"
code language-bash git push origin <branch-name>
git add -A
é necessário para adicionar todos os arquivos alterados ao controle do código-fonte devido à forma como o Composer realiza marshaling nos pacotes base. Os arquivos de marshaling decomposer install
ecomposer update
do pacote base (magento/magento2-base
emagento/magento2-ee-base
) para a raiz do pacote.Os arquivos que o Composer empacota pertencem à nova versão do Adobe Commerce, para substituir a versão desatualizada desses mesmos arquivos. Atualmente, o empacotamento está desativado no Adobe Commerce, portanto, você deve adicionar os arquivos empacotados ao controle do código-fonte.
-
Aguarde a conclusão da implantação.
-
Verifique a atualização em seu ambiente de integração, preparo ou produção usando SSH para fazer logon e verificar a versão.
code language-bash php bin/magento --version
Criar um arquivo config.php
Como mencionado em Gerenciamento de configuração, após a atualização, você deve criar um arquivo config.php
atualizado. Conclua todas as alterações adicionais de configuração por meio do Administrador no ambiente de integração.
Para criar um arquivo de configuração específico do sistema:
-
No terminal, use um comando SSH para gerar o arquivo
/app/etc/config.php
para o ambiente.code language-bash ssh <SSH-URL> "<Command>"
Por exemplo, para Pro, para executar o
scd-dump
na ramificaçãointegration
:code language-bash ssh <project-id-integration>@ssh.us.magentosite.cloud "php vendor/bin/ece-tools config:dump"
-
Transfira o arquivo
config.php
para suas estações de trabalho locais usandorsync
ouscp
. Você só pode adicionar este arquivo à ramificação localmente.code language-bash rsync <SSH-URL>:app/etc/config.php ./app/etc/config.php
-
Adicionar, confirmar e enviar alterações de código.
code language-bash git add app/etc/config.php && git commit -m "Add system-specific configuration" && git push origin master
Isso gera um arquivo
/app/etc/config.php
atualizado com uma lista de módulos e definições de configuração.
config.php
. Depois que este arquivo for adicionado ao seu código, você deve não excluí-lo. Se precisar remover ou editar configurações, edite o arquivo manualmente.Atualizar extensões
Revise suas páginas de extensão e módulo de terceiros no Marketplace ou outros sites da empresa e verifique o suporte para o Adobe Commerce e o Adobe Commerce na infraestrutura em nuvem. Se for necessário atualizar extensões e módulos de terceiros, a Adobe recomenda trabalhar em uma nova ramificação de integração com as extensões desativadas.
Para verificar e atualizar suas extensões:
-
Crie uma ramificação na estação de trabalho local.
-
Desative as extensões conforme necessário.
-
Quando disponível, baixar atualizações de extensão.
-
Instale a atualização conforme documentado pela documentação de terceiros.
-
Ative e teste a extensão.
-
Adicione, confirme e envie as alterações de código para o remoto.
-
Encaminhar e testar no ambiente de integração.
-
Encaminhar para o ambiente de preparo para testar em um ambiente de pré-produção.
A Adobe recomenda que você atualize seu ambiente de Produção antes, incluindo as extensões atualizadas em seu processo de inicialização do site.
Solução de problemas de atualização
Se a atualização falhar, você receberá uma mensagem de erro no navegador indicando que não é possível acessar sua loja ou o painel Administrador:
There has been an error processing your request
Exception printing is disabled by default for security reasons.
Error log record number: <error-number>
Para resolver o erro:
-
Na estação de trabalho local, altere para o diretório do projeto.
-
Use o SSH para fazer logon no ambiente remoto.
code language-bash magento-cloud ssh
-
Abra o arquivo
./app/var/report/<error number>
. -
Examine os logs e determine a origem do problema.
-
Adicionar, confirmar e enviar alterações de código.
code language-bash git add -A && git commit -m "Fixed deployment failure" && git push origin <branch-name>