Tutoriales de VPS
Desplegar Node.js en una VPS: systemd, PM2, Nginx y HTTPS
Publica Node con soporte, cuenta limitada y backend privado mediante systemd o PM2. Configura variables, confianza del proxy, HTTPS, registros y memoria, y prepara despliegues y recuperación fiables.

Un proyecto que funciona localmente con npm start necesita supervisión, límites de memoria, renovación HTTPS, registros y despliegues recuperables para operar en una VPS. Esta guía usa Ubuntu 24.04 y una aplicación en 127.0.0.1:3000; sirve también para Express, Koa, Nest o Fastify con arranque y apagado adecuados.
Un node app.js sin supervisor puede terminar al cerrar la sesión y no vuelve por sí solo después de reiniciar.
| Necesidad | Mecanismo |
|---|---|
| Recuperación tras fallo y arranque | systemd o PM2 |
| Dominio público y HTTP/HTTPS | Nginx o Caddy |
| Renovación de certificados | Certbot o ACME de Caddy |
| Diagnóstico | Journal, PM2 y registros del proxy |
El bucle JavaScript principal suele beneficiarse de un núcleo rápido; workers y tareas nativas aprovechan más núcleos. Usuarios diarios no determinan capacidad: importan coste de solicitudes, SSR, conexiones e I/O.
| Carga | Punto de partida | Condición |
|---|---|---|
| Proyecto personal/API pequeña | 2 vCPU, 2 GB, 40 GB SSD | Swap opcional de 2 GB ayuda ante presión, sin garantizar capacidad |
| Producción con SSR/build | 2–4 vCPU, 4 GB, 80 GB SSD | Mide build y ejecución por separado |
| Varios procesos o base de datos local | 4+ vCPU, 8+ GB | Reserva para base de datos y sistema |
next buildyvite buildpueden consumir más que servir peticiones. Compila en CI u otro equipo adecuado si la VPS es pequeña.- Deja margen y revisa
--max-old-space-size: no limita todos los buffers y memoria nativa. - Un árbol grande de
node_modulesnecesita I/O apropiada, no solo capacidad anunciada.
RackNerd con planes anuales y ubicaciones Los Ángeles/San José, Vultr con facturación horaria y ubicaciones, y Contabo con memoria/almacenamiento son ejemplos de selección: verifica precio, renovación, disponibilidad y rendimiento reales. Productos CN2 GIA de BandwagonHost y DMIT se orientan a conectividad con China continental, pueden costar más y no garantizan menor latencia mundial. Evalúa también ubicación y red de Hetzner; una limitación de rutas hacia China no describe todas las audiencias. Consulta dimensionar VPS.
Prepara el sistema revisando actualizaciones y reinicio:
sudo apt update && sudo apt upgrade -y
sudo apt install -y curl git build-essential ufw
sudo timedatectl set-timezone Asia/Shanghai
El comando horario elige Asia/Shanghai; selecciona tu zona IANA o UTC en vez de aplicarlo automáticamente. build-essential permite compilar módulos que determinadas versiones/plataformas de bcrypt, sharp y sqlite3 necesitan.
Una opción global es NodeSource:
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs
node -v && npm -v
Instala la serie 24. Revisa el instalador oficial antes de darle privilegios y sigue las instrucciones actuales del repositorio.
La recomendación de septiembre de 2026 cambió. A 16 de noviembre de 2026, el calendario oficial indica Node 26 LTS desde el 28 de octubre de 2026, Node 24 en mantenimiento desde el 20 de octubre de 2026 hasta el 30 de abril de 2028, y Node 22 en mantenimiento hasta el 30 de abril de 2027.
- En despliegues nuevos evalúa Node 26 LTS tras probar dependencias y módulos nativos.
- Los ejemplos Node 24 sirven para proyectos probados con versiones 24 soportadas y actualizadas.
- Planifica actualizar proyectos Node 22 antes del fin de soporte; mantenimiento no significa que dejen de servir inmediatamente.
Para desarrollo con varias versiones, el ejemplo nvm fijado original es:
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 es una referencia histórica, no la última; el listado oficial muestra ahora v0.41.0. Verifica el instalador elegido. systemd no carga nvm interactivo: sustituye /home/deploy/.nvm/versions/node/v24.x.x/bin/node por el binario instalado real y revisa restricciones ProtectHome. Una ruta global mantenida simplifica los servicios.
Evita root para la aplicación:
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 contiene versiones, current apunta a la activa y shared conserva configuración/subidas. Compartir node_modules entre versiones puede romper el aislamiento: instala por lockfile o publica un artefacto inmutable.
Para el repositorio 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
Crea /srv/app/.ssh con propietario appuser y modo 700 antes de ssh-keygen. Usa una clave propia de lectura de repositorio, protégela y verifica la identidad de GitHub. Es distinta de la clave entrante que usa CI para desplegar. Sustituye repositorio y fechas; no sobrescribas claves existentes.
| Función | systemd | PM2 |
|---|---|---|
| Dependencia | Gestor del sistema | Paquete npm mantenido |
| Varios procesos | Unidades múltiples/plantillas | Opciones como -i max |
| Registros | Journal con límites | Archivos y rotación PM2 |
| Memoria | MemoryMax impone límite; importa política de reinicio | max_memory_restart comprueba y reinicia, sin ser límite duro |
| Recarga | systemctl reload exige ExecReload y soporte de aplicación | pm2 reload permite recarga cluster con readiness y cierre adecuados |
Usa un supervisor por aplicación. Empieza con un proceso y aumenta tras revisar memoria, conexiones y estado compartido.
En /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
EnvironmentFileapunta ashared/.envpara conservar secretos entre versiones.--max-old-space-size=768necesita margen bajoMemoryMax=1Gpara buffers y memoria nativa. 768 MB/1 GB no es un margen universal.ProtectSystem=stricthace gran parte del sistema de solo lectura; declara las rutas escribibles conReadWritePaths. Mantén.envprotegido. Si falta una ruta necesaria puede aparecerEROFS.
La aplicación debe escuchar realmente en loopback; PORT no lo obliga. Prepara subidas, logs y cachés con propietarios correctos.
sudo systemctl daemon-reload
sudo systemctl enable --now myapp
sudo systemctl status myapp
Esta unidad no tiene ExecReload: systemctl reload falla. Utiliza un reinicio probado o diseña recarga/blue-green reales, sin prometer cero interrupciones.
sudo npm install -g pm2@7
La serie 7 no fija una versión exacta; prueba y fija la aprobada. El registro muestra actualmente 7.1.2.
Configuración original de 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,
}],
};
El esquema nativo PM2 no define env_file. En Node 24/26 usa --env-file de Node y cwd explícito, por ejemplo en 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
}]
};
Crea logs antes de iniciar. Usa .cjs si package.json selecciona ESM. Aumenta instancias y activa cluster solo tras probar disponibilidad, cierre ordenado y memoria total; PM2 no almacena sesiones compartidas.
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
Ejecuta PM2 siempre como appuser con su directorio personal y ruta de configuración explícita. pm2 startup debe generar la unidad del usuario correcto con -u appuser. Inspecciona la unidad, guarda procesos y prueba reinicio del servidor.
pm2 install pm2-logrotate
pm2 set pm2-logrotate:max_size 20M
pm2 set pm2-logrotate:retain 7
Configura rotación en esa misma instancia PM2. Revisa rutas personalizadas y ~/.pm2/logs. Cada worker tiene sesiones, caché y temporizadores propios: setInterval puede ejecutarse por worker. Separa trabajos programados o diseña bloqueos distribuidos.
Mantén la aplicación en 127.0.0.1:3000 y publica 80/443:
sudo apt install -y nginx
Guarda la configuración revisada en /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-Forconserva información del cliente; confía solo en la cadena real de proxy. Sin tratamiento puede aparecer127.0.0.1.app.set('trust proxy', 1)presupone un salto fiable; no lo uses si se puede evitar el proxy o inyectar cabeceras.client_max_body_sizenormalmente parte de 1 MB; el ejemplo fija 20m. Coordina límites de aplicación/CDN y seguridad del proxy.- Usa
proxy_buffering offen la ruta SSE real. WebSockets necesitan upgrade; /socket.io/ no cubre automáticamente otras rutas. Añade protocolo/IP reenviados allí si se utilizan. proxy_read_timeoutnormalmente mide 60s entre lecturas, no duración total universal. Trabajos largos suelen necesitar cola.
Caddy puede reemplazar Nginx:
api.example.com {
reverse_proxy 127.0.0.1:3000
}
HTTPS automático sigue necesitando DNS, acceso y almacenamiento persistente de certificados. Consulta Caddy.
Con Nginx:
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d api.example.com --redirect --agree-tos -m [email protected]
Sustituye dominio/correo y verifica A/AAAA y puertos. Comprueba el programador real del paquete/snap:
systemctl list-timers | grep certbot
sudo certbot renew --dry-run
Monitoriza vencimiento y disponibilidad; consulta renovación.
Mantén .env bajo 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 生成的值
Sustituye contraseñas y secretos ilustrativos. EnvironmentFile no ejecuta shell ni interpolación arbitraria; PM2 aquí usa el lector de Node. Comprueba valores sin imprimir credenciales.
- No publiques
.env;.env.examplepuede documentar claves con marcadores seguros. - Mantén la base de datos local/privada; consulta exposición pública.
- Planifica rotación de
SESSION_SECRET; puede invalidar sesiones salvo transición compatible.
Ilustración de directorios del 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 usarla, corrige build/readiness, propietarios y recarga. Para TypeScript/SSR instala dependencias de compilación o despliega un artefacto CI bloqueado. No compartas dependencias mutables. Prepara reemplazo atómico de symlink en el mismo sistema de archivos y conserva versión activa y anterior validada. ls/xargs no es limpieza segura con nombres arbitrarios ni conserva automáticamente la versión necesaria: selecciona directorios inactivos revisados.
systemctl reload requiere ExecReload y comportamiento de aplicación. Escuchar SIGUSR2 no enseña a systemd cómo recargar. Restart puede cortar solicitudes. Para continuidad, inicia otro backend, verifica readiness, cambia tráfico del proxy y drena el anterior. El rollback también debe considerar migraciones.
set -euo pipefail y comprobaciones explícitas deben detener un npm ci fallido antes de cambiar current. Verifica commit y salud reales y conserva recuperación probada.
# 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
Ejecuta diagnóstico PM2 como usuario de aplicación. Controla el journal:
sudo journalctl --vacuum-size=500M
sudo sed -i 's/^#\?SystemMaxUse=.*/SystemMaxUse=500M/' /etc/systemd/journald.conf
sudo systemctl restart systemd-journald
Esto afecta retención de todo el sistema: revisa otros servicios. sed solo cambia líneas coincidentes existentes; verifica la configuración efectiva o usa un drop-in deliberado.
502: revisa systemctl status myapp y listeners. localhost puede resolver distinto de 127.0.0.1; coordina IPv4/IPv6 y registros del proxy.
EADDRINUSE: utiliza sudo ss -lntp 'sport = :3000'; consulta conflictos de puerto.
EACCES en 80: prefiere proxy. sudo setcap 'cap_net_bind_service=+ep' $(which node) concede capacidad al binario Node, amplía permisos, puede fallar en symlinks y perderse al actualizar. Una política systemd limitada es otro diseño; no ejecutes toda la app como root.
Memoria/OOM: --max-old-space-size limita heap, no todo RSS. Revisa cgroup/kernel y protege diagnósticos de heap, reservando memoria para obtenerlos. Swap no arregla fugas; consulta zram y swap.
EMFILE: comprueba LimitNOFILE del proceso y fs.file-max del sistema; arregla fugas antes de subir límites. Consulta registros.
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
El ejemplo usa secretos de host, usuario y clave. Usa una clave entrante revocable, script remoto limitado y huella verificada. Fija Actions externos a un commit inmutable aprobado. Serializa despliegues, publica el commit/artefacto esperado y comprueba salida del script. Limita privilegios para controlar servicios. Consulta runners propios.
Dokploy y Coolify gestionan flujos de despliegue, pero añaden una plataforma cuyos datos, permisos y actualizaciones debes mantener.
- Copia bases de datos y subidas y prueba recuperación; Git no incluye todo lo operativo.
- Configura alertas de tráfico y cuotas según el plan.
- Comprueba disponibilidad desde fuera y vencimiento de certificados; el tiempo de configuración varía.
- Revisa fuentes/política de
unattended-upgradesy reinicios necesarios. - Registra TTFB, RSS por worker, errores y uso del banco como referencia.