Tutoriais de VPS
Implantar Node.js na VPS: systemd, PM2, Nginx e HTTPS
Publique Node com suporte, conta limitada e backend privado usando systemd ou PM2. Configure variáveis, confiança no proxy, HTTPS, logs e memória e prepare implantações e recuperação confiáveis.

Um projeto funcionando localmente com npm start ainda precisa de supervisão, limites de memória, renovação HTTPS, logs e implantação recuperável para operar numa VPS. Este guia usa Ubuntu 24.04 e uma aplicação em 127.0.0.1:3000; também atende Express, Koa, Nest e Fastify com inicialização e encerramento adequados.
Um node app.js sem supervisor pode encerrar ao fechar a sessão e não volta sozinho após reiniciar.
| Necessidade | Mecanismo |
|---|---|
| Recuperação de falhas e boot | systemd ou PM2 |
| Domínio e HTTP/HTTPS públicos | Nginx ou Caddy |
| Renovação de certificados | Agenda Certbot ou ACME do Caddy |
| Diagnóstico | Journal, PM2 e logs do proxy |
O event loop JavaScript principal costuma aproveitar um núcleo rápido; workers e tarefas nativas podem usar mais núcleos. Usuários diários não determinam capacidade: custo de requisições, SSR, pools e I/O importam.
| Carga | Ponto de partida | Condição |
|---|---|---|
| Projeto pessoal/API pequena | 2 vCPU, 2 GB, 40 GB SSD | Swap opcional de 2 GB ajuda na pressão, sem garantir capacidade |
| Produção com SSR/build | 2–4 vCPU, 4 GB, 80 GB SSD | Meça build e execução separadamente |
| Vários processos ou banco local | 4+ vCPU, 8+ GB | Reserve para banco e sistema |
next buildevite buildpodem consumir mais recursos que atender requisições. Compile em CI ou máquina adequada se a VPS for pequena.- Deixe margem e revise
--max-old-space-size: o heap não inclui toda memória nativa e buffers. - Árvores grandes de
node_modulesprecisam de I/O adequada, não apenas espaço anunciado.
RackNerd com planos anuais e Los Angeles/San Jose, Vultr com cobrança horária/localizações e Contabo com memória/armazenamento são exemplos de seleção: confira preços, renovação, disponibilidade e desempenho reais. Produtos CN2 GIA de BandwagonHost e DMIT atendem conectividade com a China continental, podem custar mais e não garantem baixa latência mundial. Avalie também localização/rede da Hetzner; uma limitação de rota para a China não descreve todo público. Veja dimensionamento da VPS.
Prepare o sistema revisando atualizações e reinicializações:
sudo apt update && sudo apt upgrade -y
sudo apt install -y curl git build-essential ufw
sudo timedatectl set-timezone Asia/Shanghai
O comando de fuso escolhe Asia/Shanghai; selecione seu fuso IANA ou UTC em vez de aplicá-lo automaticamente. build-essential permite compilar módulos necessários em algumas versões/plataformas de bcrypt, sharp e sqlite3.
Uma opção global é NodeSource:
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs
node -v && npm -v
Instala a série 24. Revise o instalador oficial antes de dar privilégios e siga as instruções atuais do repositório.
A recomendação de setembro de 2026 mudou. Em 16 de novembro de 2026, o calendário oficial indica Node 26 LTS desde 28 de outubro de 2026, Node 24 em manutenção desde 20 de outubro de 2026 até 30 de abril de 2028, e Node 22 em manutenção até 30 de abril de 2027.
- Em implantações novas, avalie Node 26 LTS após testar dependências e módulos nativos.
- Os exemplos Node 24 atendem projetos testados em versões 24 suportadas e atualizadas.
- Planeje atualização de projetos Node 22 antes do fim do suporte; manutenção não significa inutilidade imediata.
Para desenvolvimento com versões distintas, o exemplo nvm fixado do original é:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.7/install.sh | bash
source ~/.bashrc
nvm install 24 && nvm alias default 24
v0.40.7 é referência histórica, não a mais recente; a lista oficial mostra agora v0.41.0. Verifique o instalador escolhido. systemd não carrega nvm interativo: substitua /home/deploy/.nvm/versions/node/v24.x.x/bin/node pelo binário real e revise ProtectHome. Uma instalação global mantida simplifica o serviço.
Evite root para a aplicação:
sudo useradd -r -m -d /srv/app -s /bin/bash appuser
sudo mkdir -p /srv/app/{releases,shared}
sudo chown -R appuser:appuser /srv/app
/srv/app/
├── releases/ # 每次发布的代码,按时间戳分目录
│ ├── 20260920-101500/
│ └── 20260925-090000/
├── current -> releases/20260925-090000
└── shared/
├── .env # 环境变量,不进 git
├── uploads/ # 用户上传文件,软链进 release
└── node_modules/ # 可选,跨 release 复用依赖
releases guarda versões, current aponta à ativa e shared mantém configuração/uploads. Compartilhar node_modules pode quebrar isolamento: instale por lockfile em cada versão ou entregue artefato imutável.
Para repositório privado:
sudo -u appuser ssh-keygen -t ed25519 -C "deploy@vps" -f /srv/app/.ssh/id_ed25519 -N ""
sudo -u appuser cat /srv/app/.ssh/id_ed25519.pub # 贴到仓库的 Deploy Keys
sudo -u appuser git clone [email protected]:your/repo.git /srv/app/releases/20260920-101500
Crie /srv/app/.ssh com dono appuser e modo 700 antes de ssh-keygen. Use chave dedicada somente de leitura do repositório, proteja-a e verifique a identidade do GitHub. Ela é diferente da chave de entrada usada pelo CI para implantar. Substitua repositório e datas; não sobrescreva chaves existentes.
| Recurso | systemd | PM2 |
|---|---|---|
| Dependência | Gestor do sistema | Pacote npm mantido |
| Vários processos | Unidades múltiplas/templates | Opções como -i max |
| Logs | Journal com limites | Arquivos e rotação PM2 |
| Memória | MemoryMax impõe limite; política de reinício importa | max_memory_restart verifica e reinicia, sem limite rígido |
| Recarga | systemctl reload exige ExecReload e suporte da aplicação | pm2 reload permite recarga cluster com readiness/encerramento adequados |
Use um supervisor para a mesma aplicação. Comece com um processo e aumente após conferir memória, conexões e estado compartilhado.
Em /etc/systemd/system/myapp.service:
[Unit]
Description=My Node.js App
After=network.target
[Service]
Type=simple
User=appuser
Group=appuser
WorkingDirectory=/srv/app/current
EnvironmentFile=/srv/app/shared/.env
ExecStart=/usr/bin/node --max-old-space-size=768 /srv/app/current/server.js
Restart=always
RestartSec=3
StandardOutput=journal
StandardError=journal
SyslogIdentifier=myapp
# 资源与安全限制
MemoryMax=1G
LimitNOFILE=65535
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/srv/app/shared
[Install]
WantedBy=multi-user.target
EnvironmentFileaponta ashared/.envpara preservar segredos entre versões.--max-old-space-size=768precisa de margem abaixo deMemoryMax=1Gpara buffers/memória nativa. 768 MB/1 GB não é margem universal.ProtectSystem=stricttorna grande parte do sistema somente leitura; declare caminhos graváveis comReadWritePaths. Proteja.env. Falta de caminho gravável pode causarEROFS.
A aplicação deve escutar realmente no loopback; PORT não obriga isso. Prepare uploads, logs e caches com propriedade correta.
sudo systemctl daemon-reload
sudo systemctl enable --now myapp
sudo systemctl status myapp
Esta unidade não tem ExecReload: systemctl reload falha. Use reinício testado ou desenhe recarga/blue-green real, sem prometer ausência de interrupção.
sudo npm install -g pm2@7
A série 7 não fixa versão exata; teste e fixe a aprovada. O registro mostra atualmente 7.1.2.
Configuração original em current / ecosystem.config.js:
module.exports = {
apps: [{
name: 'myapp',
script: 'server.js',
instances: 'max',
exec_mode: 'cluster',
max_memory_restart: '700M',
node_args: '--max-old-space-size=640',
env_file: '/srv/app/shared/.env',
error_file: '/srv/app/shared/logs/err.log',
out_file: '/srv/app/shared/logs/out.log',
merge_logs: true,
time: true,
listen_timeout: 10000,
kill_timeout: 5000,
}],
};
O esquema nativo PM2 não define env_file. Em Node 24/26, use --env-file do Node e cwd explícito, por exemplo em ecosystem.config.cjs:
module.exports = {
apps: [{
name: 'myapp',
cwd: '/srv/app/current',
script: 'server.js',
instances: 1,
exec_mode: 'fork',
node_args: '--env-file=/srv/app/shared/.env --max-old-space-size=640',
max_memory_restart: '700M',
error_file: '/srv/app/shared/logs/err.log',
out_file: '/srv/app/shared/logs/out.log',
time: true,
kill_timeout: 5000
}]
};
Crie logs antes de iniciar. Use .cjs quando package.json seleciona ESM. Aumente instâncias e escolha cluster após testar readiness, fechamento e memória total; PM2 não guarda sessões compartilhadas.
sudo -u appuser pm2 start ecosystem.config.js
sudo -u appuser pm2 save
sudo env PATH=$PATH:/usr/bin pm2 startup systemd -u appuser --hp /srv/app
Execute sempre como appuser, com seu diretório pessoal e caminho explícito da configuração. pm2 startup precisa gerar a unidade do usuário correto com -u appuser. Revise a unidade, salve processos e teste reinicialização.
pm2 install pm2-logrotate
pm2 set pm2-logrotate:max_size 20M
pm2 set pm2-logrotate:retain 7
Configure rotação na mesma instância PM2. Confira caminhos personalizados e ~/.pm2/logs. Cada worker tem sessões, cache e timers próprios; setInterval pode rodar uma vez por worker. Separe agendamento ou use desenho de lock distribuído.
Mantenha a aplicação em 127.0.0.1:3000 e publique 80/443:
sudo apt install -y nginx
Salve a configuração revisada em /etc/nginx/sites-available/api.example.com:
upstream myapp_backend {
server 127.0.0.1:3000;
keepalive 32;
}
server {
listen 80;
listen [::]:80;
server_name api.example.com;
client_max_body_size 20m;
access_log /var/log/nginx/api.access.log;
error_log /var/log/nginx/api.error.log warn;
location / {
proxy_pass http://myapp_backend;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Connection "";
proxy_connect_timeout 5s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;
proxy_buffering on;
}
# WebSocket / SSE
location /socket.io/ {
proxy_pass http://myapp_backend;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_read_timeout 3600s;
proxy_buffering off;
}
}
sudo ln -s /etc/nginx/sites-available/api.example.com /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
X-Forwarded-Forpreserva informações do cliente; confie somente na cadeia real do proxy. Sem tratamento, o backend pode ver127.0.0.1.app.set('trust proxy', 1)supõe um salto confiável; não use se clientes podem evitar o proxy ou injetar cabeçalhos.client_max_body_sizenormalmente parte de 1 MB; o exemplo usa 20m. Coordene limites da aplicação/CDN e segurança do proxy.- Use
proxy_buffering offna rota SSE real. WebSockets exigem upgrade; /socket.io/ não cobre outras rotas automaticamente. Acrescente protocolo/IP encaminhados ali se a aplicação depende deles. proxy_read_timeoutnormalmente mede 60s entre leituras, não duração total universal. Trabalhos longos frequentemente precisam de fila.
Caddy pode substituir Nginx:
api.example.com {
reverse_proxy 127.0.0.1:3000
}
HTTPS automático exige DNS, acesso e armazenamento persistente de certificados. Veja Caddy.
Com Nginx:
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d api.example.com --redirect --agree-tos -m [email protected]
Substitua domínio/e-mail e confira A/AAAA e portas. Verifique o agendador real do pacote/snap:
systemctl list-timers | grep certbot
sudo certbot renew --dry-run
Monitore vencimento e disponibilidade; veja renovação.
Mantenha .env em shared/:
sudo -u appuser touch /srv/app/shared/.env
sudo chmod 600 /srv/app/shared/.env
sudo chown appuser:appuser /srv/app/shared/.env
NODE_ENV=production
PORT=3000
DATABASE_URL=postgres://app:[email protected]:5432/appdb
SESSION_SECRET=换成 openssl rand -hex 32 生成的值
Substitua senhas e segredos ilustrativos. EnvironmentFile não executa shell nem interpolação arbitrária; PM2 aqui usa o leitor do Node. Confira valores sem imprimir credenciais.
- Não publique
.env;.env.examplepode documentar nomes com marcadores seguros. - Mantenha banco local/privado; veja exposição pública.
- Planeje rotação de
SESSION_SECRET: pode invalidar sessões sem transição compatível.
Ilustração de diretórios do original:
#!/usr/bin/env bash
set -euo pipefail
APP=/srv/app
RELEASE=$APP/releases/$(date +%Y%m%d-%H%M%S)
sudo -u appuser git clone --depth 1 [email protected]:your/repo.git "$RELEASE"
ln -sfn "$APP/shared/.env" "$RELEASE/.env"
ln -sfn "$APP/shared/uploads" "$RELEASE/uploads"
cd "$RELEASE"
sudo -u appuser npm ci --omit=dev
ln -sfn "$RELEASE" "$APP/current"
sudo systemctl reload myapp # 或 pm2 reload myapp
# 只保留最近 5 个版本
ls -1dt $APP/releases/* | tail -n +6 | xargs -r rm -rf
Antes de usar, corrija build/readiness, donos e recarga. Para TypeScript/SSR, instale dependências de compilação ou entregue artefato CI bloqueado. Evite compartilhar dependências mutáveis. Prepare substituição atômica do symlink no mesmo filesystem e preserve a versão ativa e anterior validada. ls/xargs não é limpeza segura com nomes arbitrários nem preserva automaticamente o rollback: selecione diretórios inativos revisados.
systemctl reload exige ExecReload e comportamento da aplicação. Escutar SIGUSR2 não ensina systemd a recarregar. Restart pode cortar requisições. Para continuidade, inicie outro backend, verifique readiness, troque tráfego do proxy e drene o anterior. Rollback também precisa considerar migrações.
set -euo pipefail e verificações explícitas devem parar um npm ci falho antes de mudar current. Confira commit e saúde reais e preserve recuperação testada.
# systemd 方式
sudo journalctl -u myapp -n 100 --no-pager
sudo journalctl -u myapp -f
# PM2 方式
pm2 logs myapp --lines 100
pm2 describe myapp
# Nginx
sudo tail -f /var/log/nginx/api.error.log
Faça diagnóstico PM2 como usuário da aplicação. Controle o journal:
sudo journalctl --vacuum-size=500M
sudo sed -i 's/^#\?SystemMaxUse=.*/SystemMaxUse=500M/' /etc/systemd/journald.conf
sudo systemctl restart systemd-journald
Isso afeta retenção do sistema inteiro; revise outros serviços. sed só altera linhas correspondentes existentes: confira a configuração efetiva ou use drop-in deliberado.
502: veja systemctl status myapp e listeners. localhost pode resolver diferente de 127.0.0.1; coordene IPv4/IPv6 e logs do proxy.
EADDRINUSE: use sudo ss -lntp 'sport = :3000'; veja conflitos de porta.
EACCES em 80: prefira proxy. sudo setcap 'cap_net_bind_service=+ep' $(which node) concede capacidade ao binário Node, amplia privilégios, pode falhar em symlinks e desaparecer após atualização. Uma política systemd limitada é outro desenho; não rode a aplicação como root.
Memória/OOM: --max-old-space-size limita heap, não todo RSS. Confira cgroup/kernel e proteja diagnósticos de heap, reservando memória para gerá-los. Swap não resolve vazamento; veja zram e swap.
EMFILE: examine LimitNOFILE do processo e fs.file-max do sistema; corrija vazamentos antes de aumentar limites. Veja logs.
name: deploy
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Deploy over SSH
uses: appleboy/ssh-action@v1
with:
host: ${{ secrets.VPS_HOST }}
username: ${{ secrets.VPS_USER }}
key: ${{ secrets.VPS_SSH_KEY }}
script: /srv/app/deploy.sh
O exemplo usa segredos de host, usuário e chave. Use chave de entrada revogável, script remoto restrito e fingerprint verificado. Fixe Actions externas em commit imutável aprovado. Serialize implantações, publique o commit/artefato esperado e confira saída do script. Limite privilégios de controle de serviço. Veja runners próprios.
Dokploy e Coolify gerenciam fluxos de implantação, mas acrescentam uma plataforma cujos dados, permissões e atualizações precisam de manutenção.
- Faça backup de bancos/uploads e teste recuperação; Git não contém todos os dados de operação.
- Configure alertas de tráfego/cotas conforme o plano.
- Verifique disponibilidade externamente e vencimento de certificados; o tempo de configuração varia.
- Confira fontes/política de
unattended-upgradese reinicializações necessárias. - Registre TTFB, RSS por worker, erros e uso do banco como referência.