Compartilhar via

Configurar um aplicativo Python do Linux para o Serviço de Aplicativo do Azure

Implantar no Azure

Este artigo descreve como o Serviço de Aplicativo do Azure executa os aplicativos Python, como você pode migrar os aplicativos existentes para o Azure e como você pode personalizar o comportamento do Serviço de Aplicativo quando for necessário. Os aplicativos Python precisam ser implantados com todos os módulos pip necessários.

O mecanismo de implantação do Serviço de Aplicativo ativa automaticamente um ambiente virtual e instala dependências de um arquivo requirements.txt, pyproject.toml ou setup.py quando você implanta um repositório Git ou quando implanta um pacote zipcom automação de build habilitada.

Este artigo fornece os principais conceitos e instruções para desenvolvedores do Python que usam um contêiner interno do Linux no Serviço de Aplicativo. Se você nunca usou o Serviço de Aplicativo, primeiro conclua o início rápido do Python e o Flask, o Django ou o FastAPI com o tutorial do PostgreSQL.

Será possível usar o portal do Azure ou a CLI do Azure para executar a configuração:

Observação

O Linux é a única opção de sistema operacional para execução de aplicativos Python no Serviço de Aplicativo. Não há mais suporte para Python no Windows. No entanto, você pode criar sua própria imagem de contêiner personalizada do Windows e executá-la no Serviço de Aplicativo. Para obter mais informações, confira Usar uma imagem do Docker personalizada.

Configurar a versão do Python

  • Portal do Azure: Use a guia Configurações gerais na página Configuração, conforme descrito em Definir as configurações gerais nos contêineres do Linux.

  • CLI do Azure:

    • Mostrar a versão atual do Python usando az webapp config show:

      az webapp config show --resource-group <resource-group-name> --name <app-name> --query linuxFxVersion

      Substitua <resource-group-name> e <app-name> pelos nomes apropriados para seu aplicativo Web.

    • Defina a versão do Python usando az webapp config set:

      az webapp config set --resource-group <resource-group-name> --name <app-name> --linux-fx-version "PYTHON|3.14"

    • Mostre todas as versões do Python com suporte no Serviço de Aplicativo usando az webapp list-runtimes:

      az webapp list-runtimes --os linux | grep PYTHON

Você pode executar uma versão sem suporte do Python criando sua própria imagem de contêiner. Para obter mais informações, confira Usar uma imagem do Docker personalizada.

O que acontece com ambientes de execução obsoletos no Azure App Service?

Runtimes desatualizados são preteridos pela organização de manutenção ou têm vulnerabilidades significativas. Assim, eles são removidos da criação e configuração de páginas no portal. Quando um runtime desatualizado está oculto do portal, qualquer aplicativo que ainda esteja usando esse runtime continuará sendo executado.

Caso queira criar um aplicativo com uma versão de runtime desatualizada que não é mais mostrada no portal, use a CLI do Azure, um modelo do ARM ou o Bicep. Essas alternativas de implantação permitem criar runtimes preteridos que são removidos do portal, mas que ainda estão sendo suportados.

Se um runtime for totalmente removido da plataforma do Serviço de Aplicativo, o proprietário da assinatura do Azure receberá um aviso por email antes da remoção.

Personalizar a automação de compilação

Observação

Quando aplicativos Python são implantados com automação de build, o conteúdo é implantado e servido de /tmp/<uid>, não em /home/site/wwwroot. Você pode acessar esse diretório de conteúdo usando a variável de ambiente APP_PATH. Você deve gravar arquivos adicionais criados em runtime em um local em /home ou usando Bring Your Own Storage para persistência. Para obter mais informações sobre esse comportamento, consulte Alterações de build do Python.

O sistema de build do Serviço de Aplicativo, chamado Oryx, executa as seguintes etapas ao implantar seu aplicativo, se a configuração SCM_DO_BUILD_DURING_DEPLOYMENT do aplicativo estiver definida como 1:

  1. Execute um script personalizado de pré-compilação caso essa etapa seja especificada pela configuração PRE_BUILD_COMMAND. (O script pode, por si só, executar outros scripts Python e Node.js, comandos do Pip e do npm e ferramentas baseadas em Node como o Yarn, por exemplo, yarn install e yarn build.)

  2. Instale as dependências. O sistema de build verifica os seguintes arquivos na raiz do projeto:

    • requirements.txt: executa pip install -r requirements.txt.
    • pyproject.toml com uv.lock: usa uv.
    • pyproject.toml com poetry.lock: Usa poetry.
    • pyproject.toml: Usa poetry.
    • setup.py: Executa pip install ..

    Observação

    Se pyproject.toml estiver presente, mas uv.lock estiver ausente, o Serviço de Aplicativo usará o Poetry, mesmo que poetry.lock também esteja ausente. Para usar uv, você deve incluir uv.lock em sua implantação.

    Se nenhum desses arquivos for encontrado, o processo de build relatará o erro "Não foi possível encontrar setup.py ou requirements.txt; Não executando a instalação do pip."

  3. Se manage.py for encontrado na raiz do repositório (que indica um aplicativo Django), execute manage.py collectstatic. No entanto, caso a configuração de DISABLE_COLLECTSTATIC seja true, essa etapa será ignorada.

  4. Execute um script pós-build personalizado, se essa etapa for especificada na configuração POST_BUILD_COMMAND. (Novamente, o script pode executar outros scripts Python e Node.js, comandos do Pip e do npm e ferramentas baseadas em Node.)

Por padrão, as configurações PRE_BUILD_COMMAND, POST_BUILD_COMMAND e DISABLE_COLLECTSTATIC estarão vazias.

  • Para desabilitar a execução collectstatic ao criar aplicativos Django, defina a configuração DISABLE_COLLECTSTATIC como true.

  • Para executar os comandos de pré-compilação, defina a configuração PRE_BUILD_COMMAND para conter um comando, como o echo Pre-build command, ou um caminho para um arquivo de script relativo à raiz do projeto, como o scripts/prebuild.sh. Todos os comandos devem usar caminhos relativos à pasta raiz do projeto.

  • Para executar os comandos de pós-compilação, defina a configuração POST_BUILD_COMMAND para conter um comando, como o echo Post-build command, ou um caminho para um arquivo de script relativo à raiz do projeto, como o scripts/postbuild.sh. Todos os comandos devem usar caminhos relativos à pasta raiz do projeto.

Para obter informações sobre outras configurações que personalizam a automação de build, consulte a configuração do Oryx.

Para obter informações sobre como acessar os logs de build e implantação, consulte Logs de implantação do Access.

Para obter mais informações sobre como o Serviço de Aplicativo executa e cria aplicativos Python no Linux, confira Como o Oryx detecta e cria aplicativos Python.

Observação

As configurações PRE_BUILD_SCRIPT_PATH e POST_BUILD_SCRIPT_PATH são idênticas a PRE_BUILD_COMMAND e POST_BUILD_COMMAND, além de serem compatíveis para fins de herança.

Uma configuração chamada SCM_DO_BUILD_DURING_DEPLOYMENT, se contiver true ou 1, dispara uma compilação Oryx que acontece durante a implantação. A configuração é true quando você implanta usando o Git, o comando da CLI do Azure az webapp up, e o Visual Studio Code.

Observação

Sempre use caminhos relativos em todos os scripts de pré-build e pós-build porque o contêiner de build no qual o Oryx é executado é diferente do contêiner de runtime no qual o aplicativo é executado. Nunca confie no posicionamento exato da pasta do projeto do aplicativo dentro do contêiner (por exemplo, que a pasta foi colocada em site/wwwroot).

Migrar aplicativos existentes para o Azure

Você pode reimplantar aplicativos Web existentes no Azure da seguinte maneira:

  1. Repositório de origem. Mantenha seu código-fonte em um repositório adequado, como o GitHub, que permite configurar a implantação contínua posteriormente neste processo.

    • Seu arquivo de dependência (como requirements.txt, pyproject.toml ou setup.py) deve estar na raiz do repositório se desejar que o Serviço de Aplicativo instale automaticamente os pacotes necessários.

  2. Banco de dados. Se o aplicativo depender de um banco de dados, crie os recursos necessários no Azure também.

  3. Recursos do Serviço de Aplicativo. Crie um grupo de recursos, o plano do Serviço de Aplicativo e o aplicativo Web do Serviço de Aplicativo para hospedar seu aplicativo. Você pode criar esses recursos facilmente executando o comando az webapp up da CLI do Azure. Ou você pode criar e implantar recursos conforme mostrado no tutorial do Flask, Django ou FastAPI com PostgreSQL. Substitua os nomes do grupo de recursos, do plano do Serviço de Aplicativo e do aplicativo Web por nomes adequados para seu aplicativo.

  4. Variáveis de ambiente. se seu aplicativo exigir variáveis de ambiente, crie configurações do aplicativo do Serviço de Aplicativo equivalentes. Essas configurações do Serviço de Aplicativo aparecem para seu código como variáveis de ambiente, conforme descrito em Acessar variáveis de ambiente.

  5. Inicialização do aplicativo. Examine a seção Processo de inicialização de contêiner mais adiante neste artigo para obter informações sobre como o Serviço de Aplicativo tenta executar seu aplicativo. O Serviço de Aplicativo usa o servidor Web Gunicorn por padrão. O Gunicorn deve ser capaz de localizar o objeto do aplicativo ou pasta wsgi.py. Se precisar, você poderá Personalizar o comando de inicialização.

  6. Implantação contínua. Configure a implantação contínua do GitHub Actions, do Bitbucket ou do Azure Repos, conforme descrito no artigo Implantação contínua no Serviço de Aplicativo do Azure. Ou configure a implantação contínua do Git local, conforme descrito no artigo Implantação do Git local no Serviço de Aplicativo do Azure.

  7. Ações personalizadas. Para executar ações no contêiner do Serviço de Aplicativo que hospeda seu aplicativo, como migrações do banco de dados Django, você pode conectar-se ao contêiner usando SSH. Para obter um exemplo de como executar migrações de banco de dados do Django, consulte Tutorial: Implantar um aplicativo Web Django com PostgreSQL.

    • Ao usar a implantação contínua, você pode executar essas ações usando comandos pós-build, conforme descrito anteriormente na seção Personalizar automação de build.

Com essas etapas concluídas, você deve poder confirmar as alterações no repositório de origem e fazer com que essas atualizações sejam implantadas automaticamente no Serviço de Aplicativo.

Configurações de produção para aplicativos Django

Para um ambiente de produção como o Serviço de Aplicativo, os aplicativos do Django devem seguir as diretrizes na lista de verificação de implantação do Django.

A tabela a seguir descreverá configurações de produção relevantes para o Azure. Essas configurações serão definidas no arquivo setting.py do aplicativo.

Configuração do Django Instruções para usar no Azure
SECRET_KEY Armazene o valor em uma configuração do Serviço de Aplicativo, conforme descrito nas configurações do aplicativo access como variáveis de ambiente. Como alternativa, você pode armazenar o valor como um segredo no Azure Key Vault.
DEBUG Crie uma configuração DEBUG no Serviço de Aplicativo com o valor 0 (false) e carregue o valor como uma variável de ambiente. Em seu ambiente de desenvolvimento, crie uma variável de ambiente DEBUG com o valor 1 (true).
ALLOWED_HOSTS Na produção, o Django exigirá que você inclua a URL do aplicativo na matriz ALLOWED_HOSTS de settings.py. Você pode recuperar essa URL em runtime usando o código os.environ['WEBSITE_HOSTNAME']. O Serviço de Aplicativo definirá a variável de ambiente WEBSITE_HOSTNAME de maneira automática para a URL do aplicativo.
DATABASES Defina as configurações no Serviço de Aplicativo para a conexão de banco de dados e carregue-as como variáveis de ambiente para preencher o dicionário DATABASES. Como alternativa, você pode armazenar os valores (especialmente o nome de usuário e a senha) como segredos do Key Vault.

Servir arquivos estáticos para aplicativos Django

Se seu aplicativo Web Django incluir arquivos de front-end estáticos, primeiro siga as instruções sobre gerenciamento de arquivos estáticos na documentação do Django.

Para o Serviço de Aplicativo, faça as seguintes modificações:

  1. Considere o uso de variáveis de ambiente (para desenvolvimento local) e configurações de aplicativo (na implantação na nuvem) para definir dinamicamente as variáveis STATIC_URL e STATIC_ROOT do Django. Por exemplo:

    STATIC_URL = os.environ.get("DJANGO_STATIC_URL", "/static/")
STATIC_ROOT = os.environ.get("DJANGO_STATIC_ROOT", "./static/")

    DJANGO_STATIC_URL e DJANGO_STATIC_ROOT podem ser alterados conforme necessário para seus ambientes locais e de nuvem. Por exemplo, se o processo de build para seus arquivos estáticos os colocar em uma pasta nomeada django-static, você poderá definir DJANGO_STATIC_URL como /django-static/ para evitar o uso do padrão.

  2. Caso você tenha um script de pré-build que gera arquivos estáticos em outra pasta, inclua essa pasta na variável STATICFILES_DIRS do Django para que o processo collectstatic do Django os encontre. Por exemplo, se você executar yarn build na pasta front-end e o Yarn gerar uma pasta build/static contendo arquivos estáticos, inclua essa pasta, conforme mostrado aqui:

    FRONTEND_DIR = "path-to-frontend-folder" 
STATICFILES_DIRS = [os.path.join(FRONTEND_DIR, 'build', 'static')]

    Nesse código, FRONTEND_DIR é usado para criar um caminho para onde uma ferramenta de build como o Yarn é executada. Você pode usar novamente uma variável de ambiente e uma configuração de aplicativo, se desejar.

  3. Adicione whitenoise ao arquivo requirements.txt. O WhiteNoise (whitenoise.evans.io) é um pacote do Python que simplifica um aplicativo Django de produção para servir seus próprios arquivos estáticos. O WhiteNoise atende aos arquivos encontrados na pasta especificada pela variável Django STATIC_ROOT.

  4. No seu arquivo settings.py, adicione a seguinte linha ao WhiteNoise:

    STATICFILES_STORAGE = ('whitenoise.storage.CompressedManifestStaticFilesStorage')

  5. Modifique as listas MIDDLEWARE e INSTALLED_APPS para incluir WhiteNoise:

    MIDDLEWARE = [                                                                   
    'django.middleware.security.SecurityMiddleware',
    # Add WhiteNoise middleware after the security middleware.                             
    'whitenoise.middleware.WhiteNoiseMiddleware',
    # Other values follow.
]

INSTALLED_APPS = [
    "whitenoise.runserver_nostatic",
    # Other values follow.
]

Fornecer arquivos estáticos para aplicativos Flask

Se seu aplicativo Web Flask incluir arquivos de front-end estáticos, primeiro siga as instruções para gerenciar arquivos estáticos na documentação do Flask. Para obter um exemplo de como servir arquivos estáticos em um aplicativo Flask, consulte o aplicativo Flask de exemplo no GitHub.

Para fornecer arquivos estáticos diretamente de uma rota em seu aplicativo, você pode usar o método send_from_directory:

from flask import send_from_directory

@app.route('/reports/<path:path>')
def send_report(path):
    return send_from_directory('reports', path)

Características do contêiner

Quando implantados no Serviço de Aplicativo, os aplicativos Python são executados em um contêiner do Linux Docker definido no repositório GitHub do Serviço de Aplicativo do Python. Você pode encontrar as configurações de imagem nos diretórios específicos da versão.

Esse contêiner tem as seguintes características:

  • Os aplicativos são executados pelo servidor HTTP Gunicorn WSGI com os argumentos extras --bind=0.0.0.0 --timeout 600.

  • Por padrão, a imagem de contêiner base inclui apenas a estrutura da Web do Flask, mas o contêiner dá suporte a outras estruturas compatíveis com WSGI e compatíveis com o Python 3.6 e posterior, como o Django.

  • Para instalar outros pacotes, como o Django, crie um arquivo requirements.txt, pyproject.toml ou setup.py na raiz do projeto que especifica suas dependências diretas. O Serviço de Aplicativo instalará essas dependências de maneira automática quando você implantar o projeto.

    O arquivo de dependência deve estar na raiz do projeto ou as dependências não serão instaladas. Se esse arquivo não estiver na raiz, o processo de build relatará o erro "Não foi possível encontrar setup.py ou requirements.txt; Não executando a instalação do pip." Se você encontrar esse erro, verifique o local do arquivo de requisitos.

  • O Serviço de Aplicativo define automaticamente uma variável de ambiente nomeada WEBSITE_HOSTNAME que contém a URL do aplicativo Web, como msdocs-hello-world.azurewebsites.net. Ele também define WEBSITE_SITE_NAME, que contém o nome do seu aplicativo, como msdocs-hello-world.

  • O npm e o Node.js são instalados no contêiner de modo que você possa executar ferramentas de build baseadas em Node, como o Yarn.

Processo de inicialização do contêiner

Durante a inicialização, o Serviço de Aplicativo no contêiner do Linux executa as seguintes etapas:

  1. Use um comando de inicialização personalizada, se for fornecido.
  2. Verifique a existência de um aplicativo Django e inicie o Gunicorn para ele se for detectado.
  3. Verifique a existência de um aplicativo Flask e inicie o Gunicorn para ele se for detectado.
  4. Se nenhum outro aplicativo for encontrado, inicie um aplicativo padrão criado no contêiner.

As seções a seguir fornecem detalhes adicionais para cada opção.

Aplicativo do Django

Para aplicativos Django, o Serviço de Aplicativo procura um arquivo chamado wsgi.py no código do aplicativo e, em seguida, executa o Gunicorn usando o seguinte comando:

# <module> is the name of the folder that contains wsgi.py
gunicorn --bind=0.0.0.0 --timeout 600 <module>.wsgi

Caso queira obter um controle mais específico sobre o comando de inicialização, use um comando de inicialização personalizado, substitua o <module> pelo nome da pasta que contém o wsgi.py e adicione um argumento --chdir, caso esse módulo não esteja na raiz do projeto. Por exemplo, caso o wsgi.py esteja localizado em knboard/back-end/config na raiz do projeto, use os argumentos --chdir knboard/backend config.wsgi.

Para habilitar o log de produção, adicione os parâmetros --access-logfile e --error-logfile, conforme mostrado nos exemplos de comandos de inicialização personalizados.

Aplicativo do Flask

Para Flask, o Serviço de Aplicativo procura um arquivo chamado application.py ou app.py e inicia Gunicorn da seguinte maneira:

# If application.py
gunicorn --bind=0.0.0.0 --timeout 600 application:app

# If app.py
gunicorn --bind=0.0.0.0 --timeout 600 app:app

Se o módulo principal do seu aplicativo estiver contido em um arquivo diferente, use um nome diferente para o objeto do aplicativo. Se você quiser fornecer outros argumentos ao Gunicorn, use um comando de inicialização personalizado.

Comportamento padrão

Se o Serviço de Aplicativo não encontrar um comando personalizado, um aplicativo Django ou um aplicativo Flask, ele executará um aplicativo somente leitura padrão, localizado na pasta opt/defaultsite e mostrado na imagem a seguir.

Se você implantou o código e ainda vê o aplicativo padrão, confira Solução de problemas – O aplicativo não aparece.

Captura de tela da página da Web padrão do Serviço de Aplicativo no Linux.

Personalizar o comando de inicialização

Você pode controlar o comportamento de inicialização do contêiner fornecendo um comando de inicialização personalizado ou vários comandos em um arquivo de comandos de inicialização. Um arquivo de comando de inicialização pode usar qualquer nome escolhido, como startup.sh, startup.cmd ou startup.txt.

Todos os comandos devem usar caminhos relativos à pasta raiz do projeto.

Para especificar um comando de inicialização ou um arquivo de comandos:

  • Portal do Azure. Em Configurações no painel esquerdo da página do aplicativo, selecione Configuração e, em seguida, selecione Configurações gerais. Na caixa Comando de Inicialização, insira o texto completo do comando de inicialização ou o nome do arquivo de comando de inicialização. Depois clique em Salvar para aplicar as alterações. Confira Definir configurações gerais para contêineres do Linux.

  • CLI do Azure. Use o comando az webapp config set com o parâmetro --startup-file para definir o comando ou arquivo de inicialização:

    az webapp config set --resource-group <resource-group-name> --name <app-name> --startup-file "<custom-command>"

    Substitua <custom-command> pelo texto completo do comando de inicialização ou nome do arquivo de comandos de inicialização.

O Serviço de Aplicativo ignora todos os erros que ocorrem ao processar um arquivo ou comando de inicialização personalizado e, em seguida, continua seu processo de inicialização procurando aplicativos Django e Flask. Se você não vir o comportamento esperado, verifique se o seu comando ou arquivo de inicialização está livre de erros e se um arquivo de comando de inicialização é implantado no Serviço de Aplicativo junto com o código do aplicativo. Você também pode verificar os logs de diagnóstico para obter mais informações. E você pode verificar a página Diagnosticar e resolver problemas do aplicativo no portal do Azure.

Exemplos de comandos de inicialização

  • Argumentos do Gunicorn adicionados: o exemplo a seguir adiciona o argumento --workers=4 a uma linha de comando do Gunicorn para iniciar um aplicativo Django:

    # <module-path> is the relative path to the folder that contains the module
# that contains wsgi.py. <module> is the name of the folder that contains wsgi.py.
gunicorn --bind=0.0.0.0 --timeout 600 --workers=4 --chdir <module_path> <module>.wsgi

    Para obter mais informações, consulte Running Gunicorn. Se você estiver usando regras de dimensionamento automático para aumentar e reduzir o aplicativo Web, também deverá definir dinamicamente o número de funcionários do Gunicorn usando a variável de ambiente NUM_CORES no comando de inicialização. Por exemplo, --workers $((($NUM_CORES*2)+1)). Para obter mais informações sobre como definir o número recomendado de trabalhadores do Gunicorn, consulte Perguntas frequentes sobre o Gunicorn.

  • Habilitar o log de produção para o Django: adicione os argumentos --access-logfile '-' e --error-logfile '-' à linha de comando:

    # '-' for the log files means stdout for --access-logfile and stderr for --error-logfile.
gunicorn --bind=0.0.0.0 --timeout 600 --workers=4 --chdir <module_path> <module>.wsgi --access-logfile '-' --error-logfile '-'

    Esses logs aparecerão no fluxo de log do Serviço de Aplicativo.

    Para obter mais informações, consulte Logs do Gunicorn.

  • Módulo principal do Flask personalizado: por padrão, o Serviço de Aplicativo pressupõe que o módulo principal de um aplicativo Flask será application.py ou app.py. Se o módulo principal usar um nome diferente, você deverá personalizar o comando de inicialização. Por exemplo, se você tiver um aplicativo Flask cujo módulo principal é hello.py e o objeto do aplicativo Flask nesse arquivo se chamar myapp, este é o comando:

    gunicorn --bind=0.0.0.0 --timeout 600 hello:myapp

    Se o módulo principal estiver em uma subpasta, como site, especifique essa pasta com o argumento --chdir:

    gunicorn --bind=0.0.0.0 --timeout 600 --chdir website hello:myapp

  • Usar um servidor que não seja do Gunicorn: para usar um servidor Web diferente, como aiohttp, use o comando apropriado como o comando de inicialização ou no arquivo de comandos de inicialização:

    python3.7 -m aiohttp.web -H localhost -P 8080 package.module:init_func

Acessar configurações de aplicativos como variáveis de ambiente

As configurações do aplicativo são valores armazenados na nuvem especificamente para seu aplicativo, conforme descrito em Definir configurações de aplicativo. Essas configurações estão disponíveis para o código do aplicativo como variáveis de ambiente e acessadas por meio do padrão os.environ padrão.

Por exemplo, se você criar uma configuração de aplicativo chamada DATABASE_SERVER, o código a seguir recuperará o valor dessa configuração:

db_server = os.environ['DATABASE_SERVER']

Detectar sessão HTTPS

No Serviço de Aplicativo, a terminação TLS/SSL ocorre nos balanceadores de carga de rede, de modo que todas as solicitações HTTPS chegam ao seu aplicativo como solicitações HTTP não criptografadas. Se a lógica do aplicativo precisar verificar se as solicitações de usuário estão criptografadas, inspecione o cabeçalho X-Forwarded-Proto:

if 'X-Forwarded-Proto' in request.headers and request.headers['X-Forwarded-Proto'] == 'https':
# Do something when HTTPS is used.

Estruturas web populares permitem que você acesse as informações X-Forwarded-* em seu padrão de aplicativo padrão. Por exemplo, no Django, você pode usar SECURE_PROXY_SSL_HEADER para configurar o Django para usar o cabeçalho X-Forwarded-Proto.

Acessar registros de diagnóstico

É possível acessar os logs de console gerados de dentro do contêiner.

Para ativar o log de contêineres, execute o seguinte comando:

az webapp log config --name <app-name> --resource-group <resource-group-name> --docker-container-logging filesystem

Substitua os valores <app-name> e <resource-group-name> por nomes apropriados para seu aplicativo web.

Depois de ativar o log do contêiner, execute o seguinte comando para ver o fluxo de log:

az webapp log tail --name <app-name> --resource-group <resource-group-name>

Se os logs do console não aparecerem imediatamente, verifique novamente em 30 segundos.

Para interromper o streaming de log a qualquer momento, use o atalho de teclado Ctrl+C.

Para acessar logs no portal do Azure, selecione Monitoramento>Fluxo de log no painel esquerdo do aplicativo.

Acessar logs de implantação

Quando você implanta seu código, o Serviço de Aplicativo executa o processo de build descrito anteriormente, na seção Personalizar automação de build. Como o build é executado em um contêiner próprio, os logs de build são armazenados separadamente dos logs de diagnóstico do aplicativo.

Use as seguintes etapas para acessar os logs de implantação:

  1. Na página do portal do Azure para seu aplicativo Web, selecione Implantação>Centro de Implantação no painel esquerdo.
  2. Na guia Logs, selecione a ID de Confirmação para a confirmação mais recente.
  3. Na página Detalhes do Log exibida, selecione o link Mostrar logs... exibido ao lado de Executando build do Oryx.

Problemas de build, como dependências incorretas em seu arquivo de dependência e erros em scripts pré-build ou pós-build, aparecem nesses logs. Os erros também aparecerão se o arquivo de dependência não for encontrado na pasta raiz do projeto.

Abrir sessão SSH em um navegador

Se você quiser abrir uma sessão SSH direta com seu contêiner, seu aplicativo deverá estar em execução.

Use o comando az webapp ssh .

Se você não estiver autenticado, precisará se autenticar com sua assinatura do Azure para se conectar. Quando você é autenticado, você vê um shell no navegador em que pode executar comandos dentro de seu contêiner.

Conexão SSH

Observação

Todas as alterações feitas fora do /home diretório são armazenadas no próprio contêiner e não persistem além de uma reinicialização do aplicativo.

Para abrir uma sessão SSH remota no seu computador local, consulte Abrir a sessão SSH no shell remoto.

Quando você se conectar com sucesso à sessão SSH, deverá ver a mensagem "SSH CONNECTION ESTABLISHED", na parte inferior da janela. Se você vir erros como "SSH_CONNECTION_CLOSED" ou uma mensagem informando que o contêiner está sendo reiniciado, um erro pode estar impedindo que o contêiner do aplicativo seja iniciado. Consulte Solução de problemas para obter informações sobre como investigar possíveis problemas.

Regravações de URL

Ao implantar aplicativos Python no Serviço de Aplicativo para Linux, talvez seja necessário lidar com regravações de URL em seu aplicativo. Esse método é particularmente útil para garantir que padrões de URL específicos sejam redirecionados para os pontos de extremidade corretos sem depender das configurações externas do servidor Web. Para aplicativos Flask, você pode usar processadores de URL e middleware personalizado para conseguir isso. Em aplicativos Django, o dispatcher de URL permite o gerenciamento eficiente de regravações de URL.

Solução de problemas

De forma geral, a primeira etapa na solução de problemas é usar o diagnóstico do Serviço de Aplicativo:

  1. Na página do portal do Azure para seu aplicativo Web, selecione Diagnosticar e resolver problemas no painel esquerdo.
  2. Selecione Disponibilidade e Desempenho.
  3. Examine as informações em Logs de Aplicativos, Falha de Contêiner e Problemas de Contêiner, em que os problemas mais comuns são exibidos.

Em seguida, examine tanto os logs de implantação quanto os logs de aplicativo em busca de eventuais mensagens de erro. Esses logs geralmente identificam problemas específicos que podem impedir a implantação ou a inicialização do aplicativo. Por exemplo, o build poderá falhar se o arquivo de dependência não estiver presente na pasta raiz do projeto.

As seções a seguir fornecem diretrizes adicionais para problemas específicos.

O aplicativo não aparece

  • Você pode ver o aplicativo padrão depois de implantar seu próprio código de aplicativo. O aplicativo padrão é exibido porque você não implantou o código do aplicativo no Serviço de Aplicativo ou porque o Serviço de Aplicativo falhou ao localizar o código do aplicativo e executou o aplicativo padrão.

    • Reinicie o aplicativo, aguarde 20 segundos e verifique o aplicativo novamente.

    • Use SSH para se conectar diretamente ao contêiner do Serviço de Aplicativo e verifique se os arquivos existem em site/wwwroot. Se os arquivos não existirem, execute as seguintes etapas:

      1. Crie uma configuração de aplicativo nomeada SCM_DO_BUILD_DURING_DEPLOYMENT com um valor de 1, reimplante seu código, aguarde alguns minutos e tente acessar o aplicativo novamente. Para obter mais informações sobre como criar configurações de aplicativo, confira Configurar um aplicativo do Serviço de Aplicativo no portal do Azure.
      2. Examine o processo de implantação, verifique os logs de implantação, corrija eventuais erros e reimplante o aplicativo.

    • Se os arquivos existirem, o Serviço de Aplicativo não pôde identificar o arquivo de inicialização. Verifique se o aplicativo está estruturado como o Serviço de Aplicativo espera para o Django ou o Flask ou use um comando de inicialização personalizado.

  • Você verá a mensagem "Serviço Indisponível" no navegador. O navegador atingiu o tempo limite aguardando uma resposta do Serviço de Aplicativo. Isso indica que o Serviço de Aplicativo iniciou o servidor Gunicorn, mas o próprio aplicativo não foi iniciado. Essa condição pode indicar que os argumentos do Gunicorn estão incorretos ou que há um erro no código do aplicativo.

    • Atualize o navegador, especialmente se você estiver usando os tipos de preço mais baixos no seu plano de Serviço de Aplicativo. O aplicativo pode levar mais tempo para ser iniciado quando você usa camadas gratuitas, por exemplo, e se torna responsivo depois de atualizar o navegador.

    • Verifique se seu aplicativo está estruturado como o Serviço de Aplicativo espera para Django ou Flask ou use um comando de inicialização personalizado.

    • Examine o fluxo de log do aplicativo em busca de mensagens de erro. Os logs mostrarão eventuais erros no código do aplicativo.

Não foi possível localizar setup.py ou requirements.txt

  • O fluxo de log mostra "Não foi possível localizar setup.py ou requirements.txt; não executando pip install." O processo de build do Oryx falhou ao localizar seu arquivo requirements.txt, pyproject.toml ou setup.py.

    • Conecte-se ao contêiner do aplicativo Web por meio do SSH e verifique se o arquivo de dependência foi nomeado corretamente e existe diretamente no site/wwwroot. Se ele não existir, verifique se o arquivo existe no seu repositório e se está incluído na sua implantação. Em caso afirmativo, mova o arquivo para a raiz em uma pasta separada.

ModuleNotFoundError quando o aplicativo inicia

Se você vir um erro como ModuleNotFoundError: No module named 'example', o Python não poderá encontrar um ou mais módulos quando o aplicativo foi iniciado. Esse erro ocorre com mais frequência se você implantar o ambiente virtual com o código. Ambientes virtuais não são portáteis, portanto, um ambiente virtual não deve ser implantado com o código do aplicativo. Em vez disso, permita que o Oryx crie um ambiente virtual e instale os pacotes no aplicativo Web criando uma configuração de aplicativo, SCM_DO_BUILD_DURING_DEPLOYMENT, e definindo como 1. Essa configuração força o Oryx a instalar seus pacotes sempre que você implantar no Serviço de Aplicativo. Para obter mais informações, consulte este artigo quanto à portabilidade do ambiente virtual.

O banco de dados está bloqueado

Ao tentar executar migrações do banco de dados com um aplicativo Django, você poderá ver "sqlite3. OperationalError: o banco de dados está bloqueado." O erro indica que seu aplicativo está usando um banco de dados SQLite, para o qual o Django está configurado por padrão, em vez de usar um banco de dados de nuvem como o Banco de Dados do Azure para PostgreSQL.

Verifique a variável DATABASES no arquivo settings.py do aplicativo para garantir que ele esteja usando um banco de dados de nuvem em vez do SQLite.

Se estiver encontrando esse erro com a amostra em Tutorial: Implantar um aplicativo Web Django com PostgreSQL, verifique se você concluiu as etapas em Verificar configuções de conexão.

Outros problemas

  • As senhas não aparecem na sessão SSH quando digitadas: por motivos de segurança, a sessão SSH mantém a senha oculta à medida que você digita. No entanto, os caracteres estão sendo gravados, então digite sua senha como de costume e selecione Enter quando terminar.

  • Os comandos na sessão SSH parecem ser cortados: o editor pode não estar quebrando os comandos em palavras, mas eles ainda devem ser executados corretamente.

  • Os ativos estáticos não aparecem em um aplicativo Django: Verifique se você habilitou o módulo WhiteNoise.

  • Você verá a mensagem "A conexão SSL fatal é necessária": verifique todos os nomes de usuário e senhas usados para acessar recursos (como bancos de dados) de dentro do aplicativo.

Conteúdo relacionado

  • Last updated on