Escalado

Réplicas, límites de CPU y memoria y autoescalado de una aplicación, en el servidor que la ejecuta.

Qué requiere licencia

Fijar usted mismo las réplicas y los límites en su propia máquina está disponible en todos los planes. Solo la automatización requiere licencia:

Escalado manual

sh0 scale <app> <réplicas> arranca o detiene contenedores para que la aplicación funcione con el número de réplicas pedido; --status muestra la configuración (salida real):

$ sh0 scale my-api 2
my-api: scaled 1 -> 2 replica(s)

$ sh0 scale my-api --status
Scaling status for my-api:
  Current replicas:   2
  Min replicas:       1
  Max replicas:       1
  Autoscaling:        disabled
  CPU threshold:      80%
  Memory threshold:   80%
  LB policy:          round_robin
  Cooldown:           300s

Por la API:

curl -X POST https://panel.example.com/api/v1/apps/<app-id>/scale \
  -H "Authorization: Bearer $SH0_TOKEN" -H "Content-Type: application/json" \
  -d '{"replicas":2}'

La API acepta de 1 a 50 réplicas; la CLI rechaza más de 10 («Replicas must be between 1 and 10»). Escalar requiere el rol developer en el proyecto de la aplicación.

Límites de CPU y memoria

Cada contenedor de aplicación funciona con una cuota de CPU y un límite de memoria. Cámbielos con PUT /api/v1/apps/<id>/resources (respuesta real):

$ curl -X PUT https://panel.example.com/api/v1/apps/<app-id>/resources \
    -H "Authorization: Bearer $SH0_TOKEN" -H "Content-Type: application/json" \
    -d '{"cpu_limit":500,"memory_limit":256}'
{"data":{"app_id":"<app-id>","autoscale_cpu_threshold":80,"autoscale_enabled":false,"autoscale_memory_threshold":80,"cooldown_seconds":300,"cpu_limit":500,"created_at":"2026-10-02 02:55:05","current_replicas":2,"id":"4930c97a-d6ab-44ac-bfd0-368d2c6ac4cd","last_scale_at":null,"lb_policy":"round_robin","max_replicas":1,"memory_limit":256,"min_replicas":1,"updated_at":"2026-10-02 02:55:05"}}

• cpu_limit se expresa en milinúcleos (1000 = un núcleo), memory_limit en MB. Un campo omitido no cambia; 0 lo restablece al valor predeterminado.
• Valores predeterminados cuando no se fija nada: 512 MB de memoria y la mitad de los núcleos de la máquina para la CPU (como mínimo 0,5 núcleos).
• Los límites vienen de la máquina: CPU de 100 milinúcleos hasta el número de núcleos, memoria de 64 MB hasta la RAM de la máquina. Fuera de ellos, el error da las cifras reales, por ejemplo:
• Los nuevos límites se aplican a los contenedores creados después: vuelva a desplegar la aplicación para que el contenedor en marcha los reciba.

{"error":{"code":"VALIDATION_ERROR","message":"memory_limit must be between 64 and 7751 MB (this machine has 7751 MB of RAM), or 0 to reset"}}

Autoescalado

Con una licencia Business, sh0 ajusta el número de réplicas según el uso de CPU y memoria. Cree la configuración una vez:

curl -X POST https://panel.example.com/api/v1/apps/<app-id>/scaling \
  -H "Authorization: Bearer $SH0_TOKEN" -H "Content-Type: application/json" \
  -d '{"min_replicas":1,"max_replicas":4,"target_cpu_percent":70,"target_memory_percent":80,"cooldown_seconds":300,"enabled":true}'

• min_replicas, max_replicas -- de 1 a 50, el máximo no inferior al mínimo. Ambos valen 1 por defecto.
• target_cpu_percent, target_memory_percent -- de 10 a 100, 80 por defecto.
• cooldown_seconds -- de 60 a 3600, 300 por defecto: ninguna nueva acción antes de ese plazo tras la anterior.
• lb_policy -- round_robin (predeterminado), least_conn o random.
• cpu_limit, memory_limit -- opcionales, mismo significado y mismos límites que arriba.

Una configuración existe en cuanto se han fijado límites, y un segundo POST se rechaza («Scaling config already exists for this app. Use PATCH to update.»). Modifíquela con PATCH /api/v1/apps/<id>/scaling/update, con todos los campos opcionales. Sin licencia Business, el rechazo es un 403 con el código LICENSE_REQUIRED.

Cómo decide el autoescalador

• El autoescalador se ejecuta cada 30 segundos (sh0 serve --autoscale-interval; 0 lo desactiva) y lee las métricas de CPU y memoria de la aplicación de los dos últimos minutos.
• Hacia arriba cuando la media de CPU o la de memoria supera su objetivo.
• Hacia abajo cuando ambas medias están por debajo de la mitad de su objetivo, con al menos 10 muestras de cada una.
• Una réplica cada vez, dentro de los límites, y nunca durante el periodo de enfriamiento.
• El plan se comprueba en cada pasada: si la licencia vence, el escalado automático se detiene.

Balanceo de carga

Todas las réplicas están detrás de los mismos dominios: Caddy les reparte las solicitudes según lb_policy. Dentro de la red del proyecto, el alias de la aplicación (my-api.internal) resuelve a cada réplica.

Limitaciones

• Un solo servidor. Las réplicas se ejecutan en el servidor que aloja la aplicación; aportan paralelismo de CPU y resistencia ante un fallo, no más máquina.
• Montajes. Las réplicas añadidas con sh0 scale arrancan sin los volúmenes montados de la aplicación. No escale una aplicación que escribe en un volumen.
• Estado. Las solicitudes de un mismo usuario pueden llegar a réplicas distintas: mantenga sesiones y archivos subidos fuera del contenedor (base de datos, Redis, almacenamiento de objetos).
• Bases de datos. Los servidores de bases de datos tienen sus propios ajustes de recursos; esta página trata de las aplicaciones.