Partilhar via

Visão geral do JavaScript em Aplicativos de Contêiner do Azure

Os Aplicativos de Contêiner do Azure podem executar qualquer aplicativo JavaScript em contêiner na nuvem, oferecendo opções flexíveis para como você implanta seus aplicativos.

Configuração

Os Aplicativos de Contêiner do Azure permitem simplificar a implantação de seus aplicativos JavaScript por meio de conteinerização eficaz, incluindo a configuração de variáveis de ambiente, a criação de Dockerfiles eficientes e a organização do processo de compilação do seu aplicativo.

Variáveis de ambiente

As variáveis de ambiente são cruciais para configurar seu aplicativo. Use um .env arquivo para gerenciar essas variáveis localmente e garantir que elas sejam gerenciadas com segurança na produção com um serviço como o Azure Key Vault.

O exemplo a seguir mostra como criar variáveis para seu aplicativo.

# .env
NODE_ENV=production
PORT=3000
AZURE_COSMOS_DB_ENDPOINT=https://<YOUR_COSMOSDB_RESOURCE_NAME>.documents.azure.com:443/

Contentores

Um Dockerfile bem configurado é essencial para colocar seu aplicativo em contêineres:

  • Use um Dockerfile base: Se vários projetos compartilharem uma configuração comum, você poderá criar um Dockerfile base que inclua essas etapas comuns. O Dockerfile de cada projeto pode então começar com FROM essa imagem base e adicionar configurações específicas do projeto.

  • Parametrização de argumentos de compilação: Você pode usar argumentos de compilação (ARG) em seu Dockerfile para torná-lo mais flexível. Desta forma, pode-se passar valores diferentes para esses argumentos ao criar para desenvolvimento, testes ou produção.

  • Imagem base Node.js otimizada: certifique-se de que está a utilizar uma imagem baseNode.js adequada. Considere o uso de imagens menores e otimizadas, como as variantes alpinas, para reduzir a sobrecarga.

  • Minimal Files – Copy Only Essentials: Concentre-se em copiar apenas os arquivos necessários para o seu contêiner. Crie um .dockerignore arquivo para garantir que os arquivos de desenvolvimento não sejam copiados, como .env e node_modules. Esse arquivo ajuda a acelerar as compilações nos casos em que os desenvolvedores copiaram em arquivos desnecessários.

  • Compilação separada e tempo de execução com compilações de vários estágios: use compilações de vários estágios para criar uma imagem final enxuta, separando o ambiente de compilação do ambiente de tempo de execução.

  • Pré-construir artefactos compilando e agrupando: Pré-construir os seus artefactos de aplicação (como compilar TypeScript ou agrupar JavaScript) antes de copiá-los para a fase de execução pode minimizar o tamanho da imagem, acelerar a implementação do contêiner e melhorar o desempenho de arranque a frio. A ordenação cuidadosa das instruções em seu Dockerfile também otimiza os tempos de cache e reconstrução.

  • Docker Compose para ambientes de desenvolvimento: o Docker Compose permite definir e executar aplicativos Docker de vários contêineres. Essa abordagem de vários contêineres é útil para configurar ambientes de desenvolvimento. Você pode incluir o contexto de compilação e o Dockerfile no arquivo de composição. Esse nível de encapsulamento permite que você use diferentes Dockerfiles para diferentes serviços quando necessário.

Base Dockerfile

Este arquivo serve como um ponto de partida comum para suas imagens Node.js. Você pode usá-lo com uma FROM diretiva em Dockerfiles que fazem referência a essa imagem base. Use um número de versão ou uma confirmação para oferecer suporte à versão recente e segura da imagem.

# Dockerfile.base

FROM node:22-alpine

# Set the working directory
WORKDIR /usr/src/app

# Define build arguments with default values
ARG PORT_DEFAULT=3000
ARG ENABLE_DEBUG_DEFAULT=false

# Set environment variables using the build arguments
ENV PORT=${PORT_DEFAULT}
ENV ENABLE_DEBUG=${ENABLE_DEBUG_DEFAULT}

# Copy package manifests and install dependencies
COPY package*.json ./
RUN npm install

# Expose the application and debugging ports
EXPOSE $PORT
EXPOSE 9229

# This image focuses on common steps; project-specific Dockerfiles can extend this.

Quando você passa valores usando o sinalizador --build-arg durante o processo de compilação, os valores passados substituem os valores padrão codificados em seu Dockerfile.

Por exemplo:

docker build \
  --build-arg PORT_DEFAULT=4000 \
  --build-arg ENABLE_DEBUG_DEFAULT=true \
  --tag <IMAGE>:<TAG> \
  --file Dockerfile.base .

Neste exemplo, as variáveis PORT de ambiente e ENABLE_DEBUG são definidas como valores explícitos, em vez de seus valores padrão.

As convenções de marcação de imagem de contêiner, como o uso de latest são uma convenção. Saiba mais sobre recomendações para marcação e controle de versão de imagens de contêiner.

Configurar o ambiente de desenvolvimento com o Docker Compose

O exemplo de configuração a seguir usa um Dockerfile de desenvolvimento dedicado (Dockerfile.dev), juntamente com a montagem de volumes para recarga ao vivo e sincronização de origem local.

version: "3.8"
services:
  app:
    build:
      context: .
      dockerfile: Dockerfile.base
      args:
        PORT_DEFAULT: ${PORT:-3000}
        ENABLE_DEBUG_DEFAULT: ${ENABLE_DEBUG:-false}
    ports:
      - "${PORT:-3000}:3000"
      - "9229:9229"  # Expose debug port if needed
    volumes:
      - .:/usr/src/app
      - /usr/src/app/node_modules
    environment:
      - NODE_ENV=development
      - PORT=${PORT:-3000}
      - ENABLE_DEBUG=${ENABLE_DEBUG:-false}

Para iniciar o Docker Compose com valores personalizados, você pode exportar as variáveis de ambiente na linha de comando. Por exemplo:

PORT=4000 ENABLE_DEBUG=true docker compose up

Dockerfile de produção

Este Dockerfile de vários estágios constrói o seu aplicativo e produz uma imagem de tempo de execução otimizada. Certifique-se de ter seu .dockerignore arquivo já no código-fonte para que o COPY . . comando não copie nenhum arquivo específico para o ambiente de desenvolvimento que você não precisa na produção.

# Stage 1: Builder
FROM node:22 AS build

WORKDIR /usr/src/app
COPY package*.json ./
RUN npm install
COPY . .

# Build your project (e.g., compile TypeScript or bundle JavaScript)
RUN npm run build

# Stage 2: Runtime
FROM my-base-image:latest AS runtime

WORKDIR /usr/src/app

# Copy only the compiled output and essential files from the build stage
COPY --from=build /usr/src/app/dist ./dist
COPY --from=build /usr/src/app/package*.json ./

# Install only production dependencies
RUN npm ci --omit=dev

# Copy the entrypoint script for remote debugging
COPY entrypoint.sh /usr/src/app/entrypoint.sh
RUN chmod +x /usr/src/app/entrypoint.sh

# Expose the application port (using the PORT environment variable) and the debug port (9229)
EXPOSE $PORT
EXPOSE 9229

# Use the entrypoint script to conditionally enable debugging
ENTRYPOINT ["sh", "/usr/src/app/entrypoint.sh"]

O script de ponto de entrada permite que você se conecte ao seu aplicativo de contêiner para depuração remota.

Para executar um contêiner a partir da imagem de produção criada com variáveis de ambiente personalizadas, execute:

docker run \
  --env PORT=4000 \
  --env ENABLE_DEBUG=true \
  --publish 4000:4000 \
  --publish 9229:9229 \
  <IMAGE>:<TAG>

Para compilações de produção, certifique-se de usar a tag de versão correta, que pode não ser latest. As convenções de marcação de imagem de contêiner, como o uso de latest são uma convenção. Saiba mais sobre recomendações para marcação e controle de versão de imagens de contêiner.

Implantação

Para dar suporte à integração contínua/implantação contínua (CI/CD), configure um pipeline de CI/CD usando as Ações do GitHub, o Azure DevOps ou outra ferramenta de CI/CD para automatizar o processo de implantação.

# .github/workflows/deploy.yml
name: Deploy to Azure

on:
push:
    branches:
    - main

jobs:
build-and-deploy:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v4

    - name: Set up Node.js
      uses: actions/setup-node@v4
      with:
          node-version: '22'

    - name: Install dependencies
      run: npm ci

    - name: Build the app
      run: npm run build

    - name: Log in to Azure
      uses: azure/login@v2
      with:
          creds: ${{ secrets.AZURE_CREDENTIALS }}

    - name: Deploy to Azure Container Apps
      run: |
          az containerapp up \
          --name my-container-app \
          --resource-group my-resource-group \
          --image my-image:my_tag \
          --environment my-environment \
          --cpu 1 --memory 2Gi \
          --env-vars NODE_ENV=production PORT=3000

Quando você usa o Registro do Docker, entre no Registro e envie as imagens do Docker para um registro de contêiner, como o Registro de Contêiner do Azure (ACR) ou o Docker Hub.

# Tag the image
docker tag \
  <IMAGE>:<TAG> \
  <AZURE_REGISTRY>.azurecr.io/<IMAGE>:<TAG>

# Push the image
docker push <AZURE_REGISTRY>.azurecr.io/<IMAGE>:<TAG>

Inícios a frio

Otimize sua compilação de produção incluindo apenas o código e as dependências essenciais. Para garantir que sua carga útil seja o mais enxuta possível, use uma das seguintes abordagens:

  • Compilações ou empacotadores do Docker de vários estágios: use ferramentas de compilação e agregação como Webpack ou Rollup para ajudá-lo a criar a menor carga útil possível para seu contêiner. Quando você compila e agrupa apenas o que é necessário para a produção, você ajuda a minimizar o tamanho do contêiner e ajuda a melhorar os tempos de partida a frio.

  • Gerencie dependências com cuidado: Mantenha sua node_modules pasta enxuta, incluindo apenas os pacotes necessários para executar o código de produção. Não liste dependências de desenvolvimento ou teste na secção de dependenciespackage.json. Remova todas as dependências não utilizadas e garanta que o seu arquivo de bloqueio e o package.json permaneçam consistentes.

Segurança

As considerações de segurança para desenvolvedores JavaScript que usam os Aplicativos de Contêiner do Azure incluem a proteção de variáveis de ambiente (como o uso do Cofre de Chaves do Azure), a garantia de HTTPS com gerenciamento de certificados adequado, a manutenção de dependências de up-tocom auditorias regulares e a implementação de registro e monitoramento robustos para detetar e responder rapidamente a ameaças.

Variáveis de ambiente seguro

Certifique-se de que informações confidenciais, como cadeias de conexão de banco de dados e chaves de API, sejam armazenadas com segurança. Use o Azure Key Vault para gerenciar segredos e variáveis de ambiente com segurança.

Antes de executar este comando, certifique-se de substituir os espaços reservados delimitados por <> pelos seus valores.

az keyvault secret set \
  --vault-name <KEY_VAULT_APP> \
  --name "<SECRET_NAME>" \
  --value "<CONNECTION_STRING>"

HTTPS e certificados

Certifique-se de que seu aplicativo seja servido por HTTPS. Os Aplicativos de Contêiner do Azure podem gerenciar certificados para você. Configure seu domínio e certificado personalizados no portal do Azure.

Gestão de Dependências

Atualize regularmente as suas dependências para evitar vulnerabilidades de segurança. Use ferramentas como npm audit para verificar vulnerabilidades.

npm audit

Tratamento de erros

Implemente um tratamento robusto de erros em seu aplicativo Node.js. Use middleware no Express ou no Fastify para lidar com erros normalmente.

// src/middleware/errorHandler.ts
import { Request, Response, NextFunction } from 'express';

export function errorHandler(err: any, req: Request, res: Response, next: NextFunction) {
  console.error(err.stack);
  res.status(500).send('Something broke!');
}

Desligamentos graciosos

Desligar corretamente seu aplicativo é crucial para garantir que as solicitações durante o voo sejam concluídas e os recursos liberados corretamente. Isso ajuda a evitar a perda de dados e mantém uma experiência de usuário suave durante implantações ou eventos de expansão. O exemplo a seguir demonstra uma abordagem usando Node.js e Express para lidar com sinais de desligamento normalmente.

import express from 'express';
import healthRouter from './health.js';

const app = express();

app.use(healthRouter);

const server = app.listen(process.env.PORT || 3000);

// Graceful shutdown
process.on('SIGTERM', () => {
  console.log('SIGTERM received, shutting down...');
  server.close(() => {
    console.log('Server closed');
    process.exit(0);
  });

  // Force close after 30s
  setTimeout(() => {
    console.error('Could not close connections in time, forcing shutdown');
    process.exit(1);
  }, 30000);
});

Registo

Nos Azure Container Apps, tanto as chamadas console.log como as console.error são capturadas e registradas automaticamente. Os Aplicativos de Contêiner do Azure capturam os fluxos de saída padrão (stdout) e erro padrão (stderr) do seu aplicativo e os disponibilizam no Azure Monitor e no Log Analytics.

Configurando o log em aplicativos de contêiner do Azure

Para garantir que seus logs sejam capturados e acessíveis corretamente, você precisa definir as configurações de diagnóstico para seu Aplicativo de Contêiner do Azure. A instalação é um processo de duas etapas.

  1. Habilitar configurações de diagnóstico: use a CLI do Azure para habilitar as configurações de diagnóstico para seu aplicativo de contêiner do Azure.

    Antes de executar este comando, certifique-se de substituir os espaços reservados rodeados por <> com os seus valores.

    az monitor diagnostic-settings create \
--resource /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.Web/containerApps/<CONTAINER_APP_NAME> \
--name "containerapp-logs" \
--workspace <LOG_ANALYTICS_WORKSPACE_ID> \
--logs '[{"category": "ContainerAppConsoleLogs","enabled": true}]'

  2. Aceda aos logs no portal acedendo ao seu espaço de trabalho do Log Analytics e consultando os logs.

Usando bibliotecas de log

Enquanto console.log e console.error são capturados automaticamente, o uso de uma biblioteca de registro como Winston fornece mais flexibilidade e controle sobre seu registro. Essa flexibilidade permite formatar logs, definir níveis de log e enviar logs para vários destinos, como arquivos ou serviços de registo externos.

O exemplo a seguir demonstra como configurar o Winston para armazenar logs de alta fidelidade.

// src/logger.ts
import { createLogger, transports, format } from 'winston';

const logger = createLogger({
  level: 'info',
  format: format.combine(
    format.timestamp(),
    format.json()
  ),
  transports: [
    new transports.Console(),
    new transports.File({ filename: 'app.log' })
  ]
});

export default logger;

Para usar o registrador, use a seguinte sintaxe em seu aplicativo:

import logger from './logger';

logger.info('This is an info message');
logger.error('This is an error message');

Depuração remota

Para habilitar a depuração remota, você pode usar o inspetor interno do Node. Em vez de codificar as configurações de depuração no Dockerfile, CMDvocê pode habilitar dinamicamente a depuração remota usando um shell script como ponto de entrada do contêiner.

O script a seguir verifica uma variável de ambiente (por exemplo, ENABLE_DEBUG) quando o contêiner é iniciado. Se a variável estiver definida como true, o script iniciará Node.js no modo de depuração (usando --inspect ou --inspect-brk). Caso contrário, o contêiner inicia o aplicativo normalmente.

Você pode implementar a depuração remota com as seguintes etapas:

  1. Crie um script de ponto de entrada em um arquivo nomeado entrypoint.sh na raiz do seu projeto com o seguinte conteúdo:

    #!/bin/sh
# If ENABLE_DEBUG is set to "true", start Node with debugging enabled
if [ "$ENABLE_DEBUG" = "true" ]; then
  echo "Debug mode enabled: starting Node with inspector"
  exec node --inspect=0.0.0.0:9229 dist/index.js
else
  echo "Starting Node without debug mode"
  exec node dist/index.js
fi

  2. Modifique seu Dockerfile para copiar o entrypoint.sh script no contêiner e defini-lo como o ponto de entrada. Além disso, exponha a porta de depuração, se necessário:

    # Copy the entrypoint script to the container
COPY entrypoint.sh /usr/src/app/entrypoint.sh

# Ensure the script is executable
RUN chmod +x /usr/src/app/entrypoint.sh

# Expose the debugging port (if using debug mode)
EXPOSE 9229

# Set the shell script as the container’s entrypoint
ENTRYPOINT ["sh", "/usr/src/app/entrypoint.sh"]

  3. Acione o modo de depuração definindo a variável ENABLE_DEBUG de ambiente como true. Por exemplo, usando a CLI do Azure:

    az containerapp update \
  --name <CONTAINER_APP> \
  --env-vars ENABLE_DEBUG=true

Antes de executar este comando, certifique-se de substituir os espaços reservados cercados por <> pelos seus valores.

Essa abordagem oferece uma solução flexível que permite reiniciar o contêiner no modo de depuração atualizando uma variável de ambiente na inicialização. Ele evita a necessidade de criar uma nova revisão com configurações diferentes CMD toda vez que você precisa depurar seu aplicativo.

Considerações sobre manutenção e desempenho

Para manter e otimizar o desempenho do seu aplicativo ao longo do tempo, certifique-se de gerenciar com eficiência as alterações de variáveis de ambiente, monitorar seus recursos, manter suas dependências up-toatualizadas, configurar o dimensionamento corretamente e configurar alertas de monitoramento.

Alterações na variável de ambiente

Como cada alteração nas variáveis de ambiente requer uma nova revisão implantada, faça todas as alterações nos segredos do aplicativo de uma só vez. Quando as alterações estiverem concluídas, vincule os segredos às variáveis de ambiente da revisão. Essa abordagem minimiza o número de revisões e ajuda a manter um histórico de implantação limpo.

Alocação de recursos

Monitore e ajuste a alocação de CPU e memória para seus contêineres com base nos padrões de desempenho e uso do aplicativo. O provisionamento excessivo pode levar a custos desnecessários, enquanto o subprovisionamento pode causar problemas de desempenho.

Atualizações de dependência

Atualize regularmente suas dependências para se beneficiar de melhorias de desempenho e patches de segurança. Use ferramentas como npm-check-updates para automatizar esse processo.

npm install -g npm-check-updates
ncu -u
npm install

Dimensionamento

Configure o dimensionamento automático com base na carga do aplicativo. Os Aplicativos de Contêiner do Azure dão suporte ao dimensionamento horizontal, que ajusta automaticamente o número de instâncias de contêiner com base no uso da CPU ou da memória.

O exemplo a seguir demonstra como definir uma regra de escala baseada em CPU. Antes de executar este comando, certifique-se de substituir os espaços reservados entre <> pelos seus valores.

az containerapp revision set-scale \
  --name <CONTAINER_APP> \
  --resource-group <RESOURCE_GROUP> \
  --min-replicas 1 \
  --max-replicas 10 \
  --cpu 80

Alertas de monitorização

Configure o monitoramento e os alertas para acompanhar o desempenho e a integridade do seu aplicativo. Use o Azure Monitor para criar alertas para métricas específicas, como uso da CPU, uso da memória e tempos de resposta.

Antes de executar este comando, certifique-se de substituir os espaços reservados cercados por <> pelos seus valores.

az monitor metrics alert create \
  --name "HighCPUUsage" \
  --resource-group <RESOURCE_GROUP> \
  --scopes /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.ContainerInstance/containerGroups/<CONTAINER_GROUP> \
  --condition "avg Percentage CPU > 80" \
  --description "Alert when CPU usage is above 80%"

Gestão de recursos

Use a extensão Aplicativos de Contêiner do Azure para Visual Studio Code para criar, editar e implantar rapidamente aplicativos em contêineres diretamente do Visual Studio Code.

Solução de problemas

Quando seu aplicativo enfrenta problemas de tempo de execução nos Aplicativos de Contêiner do Azure, você pode usar alertas de log, depuração remota e verificação de integridade para localizar e resolver o problema.

Registo

Habilite e configure o registo para capturar logs de aplicações. Use o Azure Monitor e o Log Analytics para coletar e analisar logs. Antes de executar estes comandos, certifique-se de substituir os marcadores de posição cercados por <> com seus valores.

  1. Crie um novo espaço de trabalho.

    az monitor log-analytics workspace create \
    --resource-group <RESOURCE_GROUP> \
    --workspace-name <WORKSPACE_NAME>

  2. Em seguida, crie uma nova configuração de espaço de trabalho.

    az monitor diagnostic-settings create \
    --resource <CONTAINER_APP> \
    --workspace <WORKSPACE_NAME> \
    --logs '[{"category": "ContainerAppConsoleLogs","enabled": true}]'

Depuração

Você usa ferramentas de depuração remota para se conectar ao contêiner em execução. Verifique se o Dockerfile expõe as portas necessárias para debugging.

# Expose the debugging port
EXPOSE 9229

Controlos sanitários

Configure verificações de integridade para monitorar a integridade do seu aplicativo. Esse recurso garante que os Aplicativos de Contêiner do Azure possam reiniciar seu contêiner se ele parar de responder.

# Azure Container Apps YAML configuration
properties:
configuration:
    livenessProbe:
    httpGet:
        path: /health
        port: 3000
    initialDelaySeconds: 30
    periodSeconds: 10

Conteúdo relacionado