Referência técnica/docs/referencia/ambiente-e-runtimeEtapa 3 de 7

Ambiente e runtime

Variáveis ficam no servidor e não são versionadas. Esta página registra nomes e finalidade, nunca valores reais.

Recorte da seçãoReferência do sistema

Consulte contratos, decisões e comportamentos atuais do sistema com caminhos diretos para os detalhes relacionados.

Atualizado21 de jul. de 2026

Seções8

Tags3

envruntimeproducao

Nesta página · 8 tópicos

Banco

Variável	Uso
`APP_DB_HOST`	host PostgreSQL
`APP_DB_PORT`	porta PostgreSQL
`APP_DB_NAME`	banco principal
`APP_DB_USER`	usuário da aplicação
`APP_DB_PASSWORD`	senha da aplicação
`APP_DB_SSL_MODE`	`disable`, `prefer` ou `require`
`ECOMMPANEL_DB_RUNTIME_MODE`	resolução `env`, `snapshot` ou `auto`

Alternância local de dados

O EcommPanel pode alternar a fonte de dados somente durante desenvolvimento local. O recurso é desligado por padrão, não é carregado em produção e exige security.superuser para aparecer no cabeçalho.

Variável	Uso
`PANEL_DEV_DATA_SOURCE_TOGGLE`	habilita o alternador local quando definido como `true`
`PANEL_DEV_DEFAULT_DATA_SOURCE`	fonte inicial: `local` ou `production`
`PANEL_LOCAL_DB_*`	conexão PostgreSQL isolada usada por `Dados > Local`
`APP_DB_*`	alvo de produção usado por `Dados > Produção`
`PANEL_DB_TUNNEL_*`	parâmetros do comando `npm run panel:db:tunnel`

Para selecionar produção, abra o túnel SSH no terminal local, entre como Main Admin e confirme a senha administrativa. O navegador não recebe host, usuário ou senha do banco. A troca cria uma nova sessão no banco remoto; voltar ao modo local remove essa sessão e exige novo login.

Runtime e persistência

Variável	Uso
`ECOM_RUNTIME_ROOT`	raiz externa do estado operacional
`ECOM_CONTENT_PATH`	projeções de conteúdo publicadas
`ECOM_*_PERSISTENCE_MODE`	autoridade `database` ou transição `hybrid`
`ECOMMPANEL_ALLOW_DB_DURING_BUILD`	deve permanecer desativada em build normal

E-mail

PANEL_SMTP_HOST, PANEL_SMTP_PORT, PANEL_SMTP_SECURE, PANEL_SMTP_USER, PANEL_SMTP_PASSWORD, PANEL_MAIL_FROM_EMAIL e PANEL_AUTH_BASE_URL controlam autenticação e recuperação.

Analytics e integrações

IDs de GTM/GA4, consentimento, credenciais Google e provedores externos devem ser configurados por ambiente. Nunca use chave privada em variável exposta com prefixo público do Next.js.

Origem e proxy

Variável	Uso
`APP_TRUSTED_ORIGINS`	origens públicas exatas, separadas por vírgula
`TRUSTED_PROXY_HOPS`	quantidade de proxies confiáveis lidos da direita para a esquerda

No VPS com um Nginx diretamente à frente do Node, use TRUSTED_PROXY_HOPS=1. O server block deve sobrescrever X-Real-IP e X-Forwarded-For com $remote_addr; nunca preserve uma cadeia enviada livremente pelo cliente.

Tradução

GOOGLE_SHEET_ID e GOOGLE_SERVICE_ACCOUNT_* servem apenas para inicializar tokens existentes. O uso restante e a telemetria técnica passam a ser autoritativos na tabela translation_access_tokens. Não existe senha compartilhada enviada pelo navegador.

Build

O build usa NODE_ENV=production, mas não deve consultar PostgreSQL nem escrever runtime operacional. Dados necessários para compilação precisam ser defaults seguros ou estruturas estáticas.