Mini site de documentaçãoDeveloper Atlas

Entrada rápida para navegar arquitetura, APIs, operação e guias técnicos do projeto sem depender da estrutura do repositório.

44 notas

Procure por módulo, API, rota, fluxo operacional ou termo do projeto.

Guias técnicos/docs/guias/desenvolvimento-local-com-banco-remoto

Desenvolvimento Local com Banco Remoto

Esta nota explica como rodar o projeto localmente usando o banco PostgreSQL real da VPS, sem expor a porta do banco na internet.

Recorte da seçãoGuia orientado por fluxo

Leitura pensada para explicar responsabilidades, ordem de execução e trechos reais do código com foco no fluxo da implementação.

Atualizado19 de mar. de 2026
Seções10
Tags5
bancodesenvolvimentopostgresqlsshpainel

Objetivo

Esta nota explica como rodar o projeto localmente usando o banco PostgreSQL real da VPS, sem expor a porta do banco na internet.

Caminho recomendado

O fluxo recomendado é:

  1. manter o PostgreSQL da VPS ouvindo apenas em 127.0.0.1;
  2. abrir um túnel SSH local para essa porta;
  3. apontar o painel local para o túnel via .env.local.

Variáveis do runtime do painel

O runtime do admin aceita três modos:

  • auto: tenta usar a conexão ativa do Data Studio; se ela não estiver pronta, usa as variáveis de ambiente;
  • snapshot: usa apenas a conexão principal salva no Data Studio;
  • env: usa apenas as variáveis do .env.local.

Para desenvolvimento local com banco remoto, o modo mais previsível é:

bash
ECOMMPANEL_DB_RUNTIME_MODE=env

Script de túnel

O projeto inclui:

bash
npm run panel:db:tunnel

Antes de abrir o túnel, defina:

bash
export PANEL_DB_TUNNEL_HOST=SEU_IP_OU_HOST
export PANEL_DB_TUNNEL_USER=root
export PANEL_DB_LOCAL_PORT=55432

O script cria:

  • 127.0.0.1:55432 local
  • apontando para 127.0.0.1:5432 na VPS

Exemplo de `.env.local`

bash
ECOMMPANEL_DB_RUNTIME_MODE=env
ECOM_SITE_PERSISTENCE_MODE=database
ECOM_STOREFRONT_PERSISTENCE_MODE=database
ECOM_BLOG_PERSISTENCE_MODE=database
APP_DB_LABEL=Postgres remoto via tunel
APP_DB_HOST=127.0.0.1
APP_DB_PORT=55432
APP_DB_NAME=app_hub
APP_DB_USER=app_hub
APP_DB_PASSWORD=preencher_com_a_senha_do_app
APP_DB_SSL_MODE=disable

Se você quiser continuar desenvolvendo o blog sem depender do banco ativo:

bash
ECOM_BLOG_PERSISTENCE_MODE=files

Para a fase de transição, mantendo banco preferencial e arquivos como rede de segurança:

bash
ECOM_BLOG_PERSISTENCE_MODE=hybrid

Resultado esperado

Quando o túnel estiver aberto e as variáveis estiverem corretas:

  • o login do EcommPanel local usa a base real;
  • a lista de usuários, sessões e auditoria passa a refletir o ambiente provisionado;
  • páginas dinâmicas, rotas, template, tema, textos e mega menu também passam a usar o PostgreSQL como fonte administrativa;
  • a loja continua lendo snapshots publicados, mas esses snapshots passam a ser atualizados a partir do banco;
  • o fallback mock deixa de ser usado para autenticação.

Quando usar `auto`

Use auto quando você quiser:

  • continuar aproveitando a conexão principal registrada no Data Studio;
  • permitir que o runtime local caia para .env.local apenas quando a conexão salva ainda não estiver pronta.

Quando usar `snapshot`

Use snapshot quando:

  • a conexão principal do Data Studio já está consolidada;
  • o processo já tem a senha disponível em passwordReference;
  • você quer evitar qualquer override acidental por .env.local.

Regra de segurança

Para desenvolvimento contra VPS:

  • preferir túnel SSH;
  • não abrir a porta 5432 publicamente;
  • não salvar senhas reais em arquivos versionados.

Leitura seguinte