Kong stops responding under heavy load in local development

Last edited: 8/12/2026

在本地使用 CLI 运行 Supabase 时，Kong API 网关在高负载下可能会停止响应。这通常发生在发出大量并行请求时（例如，对 Storage API 进行批量操作）：Kong 会开始终止套接字连接，并记录关于没有足够可用工作线程的错误。

🌐 When running Supabase locally with the CLI, the Kong API gateway can stop responding under heavy load. This typically happens when many parallel requests are made (for example, bulk operations against the Storage API): Kong starts terminating socket connections and logs errors about not having enough available workers.

为什么会这样 #

🌐 Why this happens

为了让本地环境更轻量，CLI 只用一个 nginx 工作进程（KONG_NGINX_WORKER_PROCESSES=1）启动 Kong。一个工作进程可以最小化 ~12 个容器组成的本地环境的内存使用，但这也限制了 Kong 可以处理的并发连接数。当正在处理的请求数量超过一个工作进程的处理能力时，Kong 就会变得无响应并断开连接。

🌐 To keep the local stack lightweight, the CLI starts Kong with a single nginx worker process (KONG_NGINX_WORKER_PROCESSES=1). A single worker minimizes memory usage across the ~12 containers that make up the local stack, but it also limits how many concurrent connections Kong can handle. When the number of in-flight requests exceeds what one worker can serve, Kong becomes unresponsive and drops connections.

怎么修好它 #

🌐 How to fix it

你可以在启动本地环境之前，通过设置KONG_NGINX_WORKER_PROCESSES环境变量来覆盖 Kong nginx 工作进程的数量。可以将其设置为具体数字，或者设置为auto让 Kong 为每个可用 CPU 分配一个工作进程：

🌐 You can override the number of Kong nginx worker processes by setting the KONG_NGINX_WORKER_PROCESSES environment variable before starting the local stack. Set it to a specific number, or to auto to let Kong allocate one worker per available CPU:

1
# Use one worker per CPU core
2
KONG_NGINX_WORKER_PROCESSES=auto supabase start
3
4
# Or pick a fixed number of workers
5
KONG_NGINX_WORKER_PROCESSES=2 supabase start

你也可以导出这个变量，这样它就会对你 shell 会话中的每条命令生效：

🌐 You can also export the variable so it applies to every command in your shell session:

1
export KONG_NGINX_WORKER_PROCESSES=auto
2
supabase start

增加工作线程数量可以让 Kong 处理更多的并行连接，但会增加内存使用。如果你不设置这个变量，CLI 会保持默认的 1 个工作线程，以尽量减少本地堆栈的内存占用。

🌐 Increasing the worker count lets Kong handle more parallel connections at the cost of higher memory usage. If you don't set the variable, the CLI keeps the default of 1 worker to minimize the local stack's memory footprint.

更改数值后，重启堆栈使其生效：

🌐 After changing the value, restart the stack for it to take effect:

1
supabase stop
2
KONG_NGINX_WORKER_PROCESSES=auto supabase start

额外资源 #

🌐 Additional resources