共享内存容量规划

API7 网关数据面节点使用多个 NGINX 共享内存区（lua_shared_dict）在 worker 之间共享状态。大多数共享内存区用作缓存：写满后会淘汰最近最少使用的条目，节点仍可正常运行。但少数共享内存区中的数据会随部署规模增长且不会被淘汰。一旦写满，后续写入会被直接丢弃且不会显示明显错误。本文介绍需要规划容量的共享内存区、可容纳的数据量，以及如何根据实际场景调整大小。

需要规划容量的共享内存

API7 控制台会监控以下共享内存区，因为其中的数据无法通过缓存淘汰机制恢复。写满后会持续丢失数据，而不是只发生一次缓存未命中，因此问题更难排查。

共享内存区	默认值	存放内容	写满时的表现
prometheus-metrics-advanced	128 MB	每条 Prometheus 时间序列（约 1 KB）	指标停止更新，仪表盘和告警出现断点
kubernetes / nacos / consul	各 64 MB	每个已发现服务一个条目（其节点列表）	新增或变更的上游节点无法解析
api-calls-for-portal	64 MB	每个开发者门户 API 调用维度一个计数器	门户统计数据偏低
tracing_buffer	32 MB	待上报的 SkyWalking 链路追踪片段	链路追踪 Span 被丢弃

其余所有共享内存区（限流计数器、EWMA 负载均衡状态、各类缓存等）都能自行淘汰或重置，无需调整。

备注

上述默认值旨在覆盖绝大多数部署场景。仅当你的规模超出下文所述容量，或希望在小规模部署上回收内存时，才需要调整。显式设置的值始终优先于默认值。

容量参考

下列数据来自 API7 网关运行时的实际测试，表示每 MB 共享内存大约可容纳的条目数。共享内存按固定的 slab 等级分配，因此每个条目的开销会向上取整到最接近的 2 的幂边界。较长的键或较大的值跨越 slab 边界后，单个条目的开销可能大致翻倍，因此下表中的容量会呈倍数变化。

Prometheus 指标

每条时间序列（唯一的“指标 + 标签”组合）约占 1 KB：库会存储两份标签集，一份用于指标样本，另一份用于内部键索引；NGINX 会将这两个条目分别向上取整到约 512 字节的 slab。

内存区大小	约可容纳的时间序列数
64 MB	65,000
128 MB（默认）	130,000
256 MB	260,000

时间序列数量会随启用 prometheus 插件的路由和服务数量增长，还会受到标签基数与直方图分桶数的倍增影响。直方图指标是主要来源：请求延迟直方图的单个标签组合大约包含 15 个分桶，而带宽等计数器指标只会产生少量序列。高基数标签（例如按上游节点区分的标签）会使序列数量快速增长；如需限制，可使用 prometheus 插件的 disabled_labels 元数据丢弃指定标签。标签较短时，每 MB 可容纳的序列数可能增加两到三倍。共享内存区写满时，/metrics 响应也会变大：每 MB 共享内存大约对应 0.2 MB 文本，写满的 128 MB 共享内存区约产生 25 MB 文本。因此，在高基数场景中精简标签通常比单纯扩大共享内存更有效。

服务发现

每个已发现的服务以其后端节点列表的 JSON 形式存储，因此单个服务的开销随该服务的节点数增长。

每服务节点数	每 64 MB（默认）可容纳的服务数
1	170,000
5	100,000
20	31,000
100	8,000

请按注册中心内的服务数量规划 kubernetes、nacos 或 consul 内存区大小，并为节点列表最大的服务预留余量。上表是 kubernetes 的数据，它会为每个服务额外存一个小的版本标记；nacos 和 consul 每个服务只存一个条目，在低节点数时可多容纳约 1.5 倍。

开发者门户 API 调用

每个条目都是一个计数器，其键由订阅、开发者、应用、凭证、API 产品和响应状态码组合而成，大小约为 512 字节。

内存区大小	约可容纳的计数器组合数
64 MB（默认）	130,000
128 MB	260,000

活跃组合数随门户消费者数、应用数、产品数以及出现的不同响应码数量增长。计数器会周期性刷新，因此应按峰值并发基数规划，而非累计流量。

链路追踪缓冲区

该缓冲区存放排队等待上报的 SkyWalking 链路追踪片段，用于吸收采集器变慢或短暂不可达时的峰值；片段上报后即释放。

片段大小	每 32 MB（默认）可容纳的片段数
约 1 KB	16,000
约 2 KB	8,000
约 4 KB	4,000

请按采集器变慢时需要缓冲的时长规划，而非按稳态吞吐量。如果采集器健康时仍出现片段丢弃，则应调大该值。

修改默认值

可以在数据面覆盖上述共享内存区的默认值。容量使用 128m 或 1g 等字符串表示。对于 Helm 部署，请通过 helm upgrade 应用变更；对于直接管理的数据面，请编辑 config.yaml 并重启节点。共享内存区只在启动时分配，因此必须完整重启才能使新容量生效，reload 不会调整容量。

数据面配置

在数据面 config.yaml 的 nginx_config 下设置共享内存区，该配置会覆盖 config-default.yaml：

nginx_config:
  meta:
    lua_shared_dict:
      prometheus-metrics: 512m      # 对应 prometheus-metrics-advanced 内存区
  http:
    lua_shared_dict:
      tracing_buffer: 64m
      api-calls-for-portal: 128m
    custom_lua_shared_dict:
      kubernetes: 128m
      nacos: 128m
      consul: 128m

Helm

在网关 Chart values 中设置共享内存区：

apisix:
  meta:
    luaSharedDict:
      prometheus-metrics: 512m      # 对应 prometheus-metrics-advanced 内存区
  http:
    luaSharedDict:
      tracing_buffer: 64m
      api-calls-for-portal: 128m
  customLuaSharedDicts:
    - name: kubernetes
      size: 128m
    - name: nacos
      size: 128m
    - name: consul
      size: 128m

Prometheus 内存区在 meta 上下文中使用 prometheus-metrics 键配置，对应控制台中显示的 prometheus-metrics-advanced 内存区。

监控使用情况

API7 控制台会按数据面节点报告每个受监控内存区的已用容量和总容量，并在接近上限时发出告警。请结合实际流量确认容量规划，并在内存区开始丢弃数据前发现持续增长趋势。