Tutoriais de VPS
PostgreSQL 18 na VPS: Docker, TLS, PgBouncer e recuperação
Implante PostgreSQL 18 com Docker, TLS/SCRAM e PgBouncer. Confira permissões e volumes, ajuste conexões e teste backups e recuperação isolada.

Este guia configura PostgreSQL na VPS com Ubuntu 24.04, PostgreSQL 18, Compose, TLS/SCRAM e PgBouncer. Inclui acesso privado, usuários, pool, recursos, backups, recuperação e migrações. Contêiner saudável não comprova recuperação nem alta disponibilidade.
Revisão de versões em 16 de novembro de 2026: PostgreSQL 18.7 foi lançado em 12 de novembro. Os exemplos originais mantêm 18.6 como referência; troque cada postgres:18.6-bookworm, inclusive nas consultas de proprietário, por tag/digest 18.7 verificado antes do deploy. PgBouncer 1.26.1 corrige CVE-2026-107350, que afeta de 1.17.0 a 1.26.0. A versão original 1.25.2 já não atende: use 1.26.1 ou versão posterior suportada e corrigida. Leia as notas do PostgreSQL e o histórico do PgBouncer.
PostgreSQL 18 saiu em setembro de 2025 com I/O assíncrono, UUIDv7, colunas geradas virtuais e checksums padrão em novos clusters. Fixe patch 18.x suportado, sem latest.
- Aplicação/banco compartilham host ou rede privada e custos adequados.
- Você precisa controlar extensões, ajustes e backups.
- O projeto precisa de SQL, transações, JSONB, busca ou extensões geográficas suportadas.
- A equipe consegue manter atualizações, monitoramento, recuperação e incidentes.
Serviço gerenciado pode atender melhor failover/PITR ou pouca capacidade operacional. Host/disco/datacenter continuam sendo um domínio único de falha.
| Uso | Referência | Disco | Nota |
|---|---|---|---|
| Desenvolvimento/leve | 2 vCPU, 4 GB | 60 GB NVMe | Conexões conservadoras com aplicações compartilhadas |
| Produção pequena | 4 vCPU, 8 GB | 120 GB NVMe+ | Pool e margem medida |
| Carga maior | 8 vCPU, 16 GB+ | Armazenamento dedicado | Considerar separar aplicação/banco |
Reserve 2-3 vezes o tamanho atual para WAL, índices, temporários, backups e migração. Use fio em arquivos de teste descartáveis e meça IOPS sustentadas. Swap ajuda emergências, sem substituir RAM.
| Porta | Função | Publicação |
|---|---|---|
5432/TCP | PostgreSQL | Somente 127.0.0.1 do host |
6432/TCP | PgBouncer | Somente 127.0.0.1 |
22/TCP | SSH | Chaves e origem restrita |
Use rede privada ou túnel verificado; não abra 5432 pública. Aplicações em contêiner precisam da rota Docker/privada real, não do próprio loopback. Veja exposição de bancos.
Instale Docker/Compose suportados pelo repositório oficial:
sudo apt update
sudo apt full-upgrade -y
sudo apt install -y ca-certificates curl openssl jq
docker --version
docker compose version
Planeje atualizações/reinício do host. Como administrador autorizado:
sudo install -d -m 0750 -o "$USER" -g "$USER" \
/opt/postgres18/{conf,initdb,secrets,tls,backups}
cd /opt/postgres18
umask 077
openssl rand -hex 32 > secrets/postgres_superuser_password
openssl rand -hex 32 > secrets/app_db_password
chmod 600 secrets/*
Proteja secrets/, chaves e backups fora do Git. Root/administradores Docker ainda leem segredos de arquivo.
Distribua ca.crt com segurança e acrescente hostname privado real ao SAN. Crie /opt/postgres18/tls/openssl.cnf:
[req]
distinguished_name = dn
prompt = no
req_extensions = server_ext
[dn]
CN = postgres
[server_ext]
subjectAltName = DNS:postgres,DNS:localhost,IP:127.0.0.1
keyUsage = critical,digitalSignature,keyEncipherment
extendedKeyUsage = serverAuth
cd /opt/postgres18/tls
openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes \
-subj "/CN=PostgreSQL Internal CA" \
-keyout ca.key -out ca.crt
openssl req -newkey rsa:3072 -sha256 -nodes \
-config openssl.cnf -keyout server.key -out server.csr
openssl x509 -req -sha256 -days 825 \
-in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
-extfile openssl.cnf -extensions server_ext \
-out server.crt
chmod 600 ca.key server.key
chmod 644 ca.crt server.crt
sudo chown 999:999 server.key server.crt
Preserve ca.key protegido para assinatura/renovação, sem montar no banco. Confira UID/GID de postgres na imagem, sem presumir sempre 999. server.key só deve ser legível pelo usuário adequado.
Crie /opt/postgres18/conf/postgresql.conf:
listen_addresses = '*'
port = 5432
ssl = on
ssl_cert_file = '/run/postgres-tls/server.crt'
ssl_key_file = '/run/postgres-tls/server.key'
ssl_ca_file = '/run/postgres-tls/ca.crt'
ssl_min_protocol_version = 'TLSv1.2'
password_encryption = 'scram-sha-256'
shared_preload_libraries = 'pg_stat_statements'
max_connections = 100
shared_buffers = '2GB'
effective_cache_size = '5GB'
work_mem = '16MB'
maintenance_work_mem = '512MB'
checkpoint_timeout = '15min'
max_wal_size = '4GB'
min_wal_size = '1GB'
wal_compression = on
random_page_cost = 1.1
effective_io_concurrency = 200
track_io_timing = on
log_checkpoints = on
log_connections = on
log_disconnections = on
log_lock_waits = on
log_min_duration_statement = 1000
deadlock_timeout = '1s'
timezone = 'UTC'
São referências para host dedicado de 8 GB. shared_buffers perto de 25% é início; work_mem pode multiplicar por nós/workers/consultas. Com aplicações compartilhadas, reduza shared_buffers para perto de 1 GB e meça memória total, manutenção e limite do contêiner de 6 GB.
Crie /opt/postgres18/conf/pg_hba.conf:
local all postgres peer
local all all scram-sha-256
hostssl all all 0.0.0.0/0 scram-sha-256
hostssl all all ::0/0 scram-sha-256
hostnossl all all 0.0.0.0/0 reject
hostnossl all all ::0/0 reject
hostssl exige TLS TCP. CIDRs amplos ainda precisam de publicação restrita e contêineres confiáveis; limite sub-redes ao separar hosts. TLS/senha não autorizam qualquer origem.
Crie /opt/postgres18/initdb/01-app.sh:
#!/usr/bin/env bash
set -Eeuo pipefail
app_password="$(<"${APP_DB_PASSWORD_FILE}")"
psql -v ON_ERROR_STOP=1 \
--username "${POSTGRES_USER}" \
--dbname "${POSTGRES_DB}" \
--set=app_password="${app_password}" <<'EOSQL'
SELECT format('CREATE ROLE appuser LOGIN PASSWORD %L', :'app_password')
WHERE NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'appuser')
\gexec
SELECT 'CREATE DATABASE app OWNER appuser'
WHERE NOT EXISTS (SELECT 1 FROM pg_database WHERE datname = 'app')
\gexec
REVOKE ALL ON DATABASE app FROM PUBLIC;
EOSQL
psql -v ON_ERROR_STOP=1 \
--username "${POSTGRES_USER}" \
--dbname app \
-c 'CREATE EXTENSION IF NOT EXISTS pg_stat_statements;'
chmod 700 /opt/postgres18/initdb/01-app.sh
Complete proprietário antes de iniciar: script 700 do usuário de deploy não pode ser executado por postgres. Esse usuário também precisa ler o segredo da aplicação. Ajuste proprietário ao UID/GID real, travessia de initdb e leitura da configuração sem segredos. Para Debian, adapte:
cd /opt/postgres18
pg18_uid=$(docker run --rm --entrypoint id postgres:18.6-bookworm -u postgres)
pg18_gid=$(docker run --rm --entrypoint id postgres:18.6-bookworm -g postgres)
sudo chown "$pg18_uid:$pg18_gid" initdb/01-app.sh secrets/app_db_password
sudo chmod 700 initdb/01-app.sh
sudo chmod 400 secrets/app_db_password
sudo chmod 755 initdb
sudo chmod 644 conf/postgresql.conf conf/pg_hba.conf
Depois de alterar o proprietário, o usuário de deploy não pode ler o segredo com modo 400. Execute os comandos seguintes que leem credenciais em uma sessão root autorizada (sudo -i, depois volte a /opt/postgres18) ou adapte a leitura com sudo; não abra os arquivos para todos. Inicialização só atua em cluster vazio; depois use ALTER ROLE e atualize aplicação/pool, sem apenas trocar arquivos.
Crie /opt/postgres18/compose.yml:
name: postgres18
services:
postgres:
image: postgres:18.6-bookworm
environment:
POSTGRES_USER: postgres
POSTGRES_DB: postgres
POSTGRES_PASSWORD_FILE: /run/secrets/postgres_superuser_password
APP_DB_PASSWORD_FILE: /run/secrets/app_db_password
command:
- postgres
- -c
- config_file=/etc/postgresql/postgresql.conf
- -c
- hba_file=/etc/postgresql/pg_hba.conf
ports:
- "127.0.0.1:5432:5432"
volumes:
- postgres-data:/var/lib/postgresql
- ./conf/postgresql.conf:/etc/postgresql/postgresql.conf:ro
- ./conf/pg_hba.conf:/etc/postgresql/pg_hba.conf:ro
- ./initdb:/docker-entrypoint-initdb.d:ro
- ./tls/ca.crt:/run/postgres-tls/ca.crt:ro
- ./tls/server.crt:/run/postgres-tls/server.crt:ro
- ./tls/server.key:/run/postgres-tls/server.key:ro
secrets:
- postgres_superuser_password
- app_db_password
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres -d postgres"]
interval: 10s
timeout: 5s
retries: 10
start_period: 30s
shm_size: 1gb
mem_limit: 6g
restart: unless-stopped
logging:
driver: json-file
options:
max-size: 20m
max-file: "5"
secrets:
postgres_superuser_password:
file: ./secrets/postgres_superuser_password
app_db_password:
file: ./secrets/app_db_password
volumes:
postgres-data:
Desde 18, PGDATA tem subdiretório versionado: monte /var/lib/postgresql. Não copie mecanicamente /var/lib/postgresql/data nem apague cluster aparentemente perdido. Veja Compose.
cd /opt/postgres18
docker compose config --quiet
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 postgres
docker compose exec --user postgres postgres \
psql -U postgres -d postgres -c 'SELECT version();'
docker compose exec --user postgres postgres \
psql -U postgres -d postgres -c 'SHOW ssl; SHOW data_checksums; SHOW shared_preload_libraries;'
docker compose exec --user postgres postgres \
psql -U postgres -d app -c '\dx pg_stat_statements'
Confira versão, TLS, checksums e extensão. Teste usuário da aplicação:
sudo apt install -y postgresql-client
APP_DB_PASSWORD="$(<secrets/app_db_password)" \
PGPASSWORD="${APP_DB_PASSWORD}" \
psql "host=127.0.0.1 port=5432 dbname=app user=appuser sslmode=verify-full sslrootcert=/opt/postgres18/tls/ca.crt" \
-c 'SELECT current_user, current_database(), ssl FROM pg_stat_ssl WHERE pid = pg_backend_pid();'
ssl deve ser t. Evite segredos no histórico e execute unset APP_DB_PASSWORD PGPASSWORD. pg_isready não testa permissões nem idade dos backups.
O pool reduz pressão quando max_connections enche. Instale pelo APT oficial PostgreSQL e confirme 1.26.1 ou posterior com as correções necessárias. Pare se o repositório oferecer apenas a versão original vulnerável 1.25.2:
sudo apt install -y postgresql-common
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
sudo apt update
sudo apt install -y pgbouncer
pgbouncer --version
Crie /etc/pgbouncer/pgbouncer.ini:
[databases]
app = host=127.0.0.1 port=5432 dbname=app
[pgbouncer]
listen_addr = 127.0.0.1
listen_port = 6432
unix_socket_dir = /var/run/postgresql
auth_type = scram-sha-256
auth_file = /etc/pgbouncer/userlist.txt
pool_mode = transaction
max_client_conn = 300
default_pool_size = 20
min_pool_size = 5
reserve_pool_size = 5
reserve_pool_timeout = 3
max_prepared_statements = 200
server_tls_sslmode = verify-full
server_tls_ca_file = /etc/pgbouncer/ca.crt
admin_users = postgres
stats_users = postgres
ignore_startup_parameters = extra_float_digits
log_connections = 1
log_disconnections = 1
O arquivo protegido de senhas permite SCRAM no backend:
cd /opt/postgres18
APP_DB_PASSWORD="$(<secrets/app_db_password)"
printf '"appuser" "%s"\n' "${APP_DB_PASSWORD}" > secrets/pgbouncer-userlist.txt
unset APP_DB_PASSWORD
sudo install -m 0640 -o postgres -g postgres \
secrets/pgbouncer-userlist.txt /etc/pgbouncer/userlist.txt
sudo install -m 0644 -o root -g root \
tls/ca.crt /etc/pgbouncer/ca.crt
sudo systemctl restart pgbouncer
sudo systemctl enable pgbouncer
sudo systemctl status --no-pager pgbouncer
Proteja o arquivo. admin_users/stats_users não criam conta autenticada: acrescente usuário de controle dedicado ao auth_file e listas quando precisar de console, sem dar credenciais administrativas às aplicações.
Conecte a 127.0.0.1:6432/app pela rota privada. transaction pode afetar estado de sessão, temporários ou SET entre transações; use session quando necessário. Prepared statements depende da versão/configuração. Confira descritores ao aumentar max_client_conn.
APP_DB_PASSWORD="$(</opt/postgres18/secrets/app_db_password)" \
PGPASSWORD="${APP_DB_PASSWORD}" \
psql -h 127.0.0.1 -p 6432 -U appuser -d app \
-c 'SELECT current_user, now();'
unset APP_DB_PASSWORD PGPASSWORD
O TLS configurado é para backend; cliente-pool local não tem TLS aqui. Configure antes de conexões entre hosts.
Use pg_dump diário e papéis/configuração; cargas maiores podem exigir pg_basebackup, WAL e PITR. Não copie volume ativo como backup consistente.
cd /opt/postgres18
backup_time="$(date -u +%Y%m%dT%H%M%SZ)"
docker compose exec -T --user postgres postgres \
pg_dump -U postgres -d app -Fc \
> "backups/app-${backup_time}.dump"
docker compose exec -T --user postgres postgres \
pg_dumpall -U postgres --globals-only \
> "backups/globals-${backup_time}.sql"
sha256sum "backups/app-${backup_time}.dump" \
"backups/globals-${backup_time}.sql" \
> "backups/SHA256SUMS-${backup_time}"
Valide cada saída antes de aceitar arquivos/hashes. Proteja hashes de senhas dos papéis. Preserve cópia local breve, externa regional e independente/offline, com permissões mínimas, versões/bloqueio e downloads testados. Dumps diários não dão recuperação contínua.
Execute só depois de mudar para instância/projeto separado e compatível. Restaure papéis/extensões necessários por globals revisados; confirme arquivo e hashes. Não execute dropdb final antes de testar dados de negócio:
cd /opt/postgres18
latest_dump="$(find backups -name 'app-*.dump' -type f -print | sort | tail -1)"
docker compose exec -T --user postgres postgres \
createdb -U postgres -O appuser app_restore_test
docker compose exec -T --user postgres postgres \
pg_restore -U postgres -d app_restore_test \
--clean --if-exists < "${latest_dump}"
docker compose exec --user postgres postgres \
psql -U postgres -d app_restore_test \
-c "SELECT count(*) FROM pg_tables WHERE schemaname NOT IN ('pg_catalog', 'information_schema');"
docker compose exec -T --user postgres postgres \
dropdb -U postgres app_restore_test
Confira linhas exatas, extensões, sequências, permissões e conexão real. Registre tempo e ponto de recuperação, sem afetar produção.
Monitore CPU, RAM/swap, espaço/latência, conexões, transações, locks, WAL/réplicas e idade dos backups:
SELECT state, count(*)
FROM pg_stat_activity
GROUP BY state
ORDER BY count(*) DESC;
SELECT query, calls, total_exec_time, mean_exec_time, rows
FROM pg_stat_statements
ORDER BY total_exec_time DESC
LIMIT 20;
Corrija vazamentos/transações ociosas e teste pool antes de aumentar max_connections de 100 para 1000. EXPLAIN (ANALYZE, BUFFERS) executa consultas: use com cuidado. Melhore índices/SQL sem atribuir tudo a shared_buffers.
18.x normalmente não exige pg_upgrade. Troque tag/digest deliberadamente e faça backup/testes antes de:
cd /opt/postgres18
: "先完成备份和恢复抽查"
docker compose pull postgres
docker compose up -d postgres
docker compose exec --user postgres postgres \
psql -U postgres -d postgres -c 'SELECT version();'
18 para 19 exige pg_upgrade ou migração lógica testada. O diretório versionado PGDATA não migra automaticamente.
Confira proprietário de server.key, adaptando 999 quando diferente:
sudo chown 999:999 /opt/postgres18/tls/server.key
sudo chmod 600 /opt/postgres18/tls/server.key
docker compose restart postgres
Pare escritas, confira volumes/projeto e /var/lib/postgresql. Preserve originais e inspecione cópia somente leitura antes de inicializar.
Examine pg_stat_activity e SHOW POOLS; com conta autorizada. Corrija ciclo das conexões antes de aumentar default_pool_size ou max_connections.
Confira SAN, sslrootcert, CA e relógio. Corrija verify-full, sem usar sslmode=disable.
O serviço fica em 127.0.0.1. O túnel aponta para PgBouncer 6432:
ssh -N -L 15432:127.0.0.1:6432 user@your-vps
Use 127.0.0.1:15432 local e TLS adequado ao listener do pool. Veja conexão.
- Patch 18.x exato suportado, sem
latest. - Volume no
/var/lib/postgresqlcorreto. - 5432/6432 em loopback ou privado restrito.
- PostgreSQL TCP TLS/SCRAM, aplicação sem superusuário.
- PgBouncer corrigido e modo compatível.
- Memória/conexões medidas.
- Backups externos com restauração isolada registrada.
- Patches/migrações com manutenção e recuperação.
- Alertas de disco, conexões, consultas, locks, WAL e backups.
Teste carga real e reinício/recuperação controlados antes dos dados de produção.