From 09285693d1cf65c1bd7699242024a6e373ef3d65 Mon Sep 17 00:00:00 2001 From: ci-check Date: Tue, 27 Oct 2026 09:17:39 +0800 Subject: [PATCH 1/2] docs: size sessions.residentMaxBytes for concurrent large sessions (#4893) The permanent compress-refusal path already tells users to raise sessions.residentMaxBytes above ~weight+otherBytes, but the main docs never gave concurrency-scenario sizing advice. Add it to the sessions table row and the Detail paragraph, en+zh mirrored. --- CONFIGURATION.md | 4 ++-- CONFIGURATION.zh-CN.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/CONFIGURATION.md b/CONFIGURATION.md index cd922567c8..dbf762d6e8 100644 --- a/CONFIGURATION.md +++ b/CONFIGURATION.md @@ -201,7 +201,7 @@ This index is generated from `website/config-reference/*.yaml` — edit the seed | `sessions.max` | number | 256 | BILI_MAX_SESSIONS | In-memory session table cap (LRU eviction of idle sessions). | | `sessions.warmMax` | number | 0 | BILI_SESSION_WARM_MAX | Bounded startup (#2803/#3050): max most-recently-saved sessions hydrated at boot before listening; older state reloads on demand. Default 0 (no eager warm set — first touch pays one on-demand load; set 8 to restore the eager behavior). Capped by sessions.max. | | `sessions.warmMaxBytes` | number | 67108864 | BILI_SESSION_WARM_MAX_BYTES | Decoded-byte budget for the boot warm set (#2803). Counts decoded size, not compressed on-disk bytes, so zstd archives cannot sneak past the RAM bound. A single file over the budget is never warmed. | -| `sessions.residentMaxBytes` | number | 536870912 | BILI_SESSION_RESIDENT_MAX_BYTES | Soft target for estimated resident session bytes (#2803). Active/in-flight state stays pinned above it; when over target, idle state discharges back to disk as requests complete. | +| `sessions.residentMaxBytes` | number | 536870912 | BILI_SESSION_RESIDENT_MAX_BYTES | Soft target for estimated resident session bytes (#2803). Active/in-flight state stays pinned above it; when over target, idle state discharges back to disk as requests complete. If several large sessions stay open at once, size it above their combined weight (e.g. seven ~136 MiB sessions want ≥1 GiB): a saturated pool evicts idle sessions and every touch of one pays a synchronous cold load that can block the event loop for seconds (#4893); the permanent compress-refusal log names the value to raise it above. | | `sessions.gc.enabled` | boolean | false | BILI_SESSION_GC | Opt-in garbage collection of stale persisted sessions (user data is never pruned silently without this flag). | | `sessions.gc.maxAgeDays` | number | 7 | BILI_SESSION_GC_MAX_AGE_DAYS | GC age threshold in days. | | `sessions.gc.maxTokens` | number | 1000000 | BILI_SESSION_GC_MAX_TOKENS | GC token-size threshold per session record. | @@ -947,7 +947,7 @@ Since #2030 every pure-behavior knob has a config-file key alongside its env var - **Type:** `{ max?: number; gc?: { enabled?: boolean; maxAgeDays?: number; maxTokens?: number; intervalMs?: number } }` - **Default:** `{ max: 256, gc: { enabled: false, maxAgeDays: 7, maxTokens: 1000000, intervalMs: 3600000 } }` - **Status:** ACTIVE -- **Description:** `max` caps in-memory sessions with LRU eviction (twin `BILI_MAX_SESSIONS`; disk remains the source of truth). `warmMax`/`warmMaxBytes` bound the boot warm cache and `residentMaxBytes` the idle-residency target (#2803 bounded startup: boot hydrates only the most recent warm set, everything else reloads on demand; active/in-flight state is never evicted). `gc` controls stale-session-file cleanup (twins `BILI_SESSION_GC*`) — **opt-in**, because session files are user data: compressed sessions are never deleted, deletions are audit-logged, and the age + lossless-size gates apply. Details in the [env table](#config-file-keys-for-environment-knobs-2030). +- **Description:** `max` caps in-memory sessions with LRU eviction (twin `BILI_MAX_SESSIONS`; disk remains the source of truth). `warmMax`/`warmMaxBytes` bound the boot warm cache and `residentMaxBytes` the idle-residency target (#2803 bounded startup: boot hydrates only the most recent warm set, everything else reloads on demand; active/in-flight state is never evicted). Size `residentMaxBytes` above the combined weight of your concurrently-open large sessions (#4893) — under a saturated pool every touch of an evicted session pays a multi-second synchronous cold load. `gc` controls stale-session-file cleanup (twins `BILI_SESSION_GC*`) — **opt-in**, because session files are user data: compressed sessions are never deleted, deletions are audit-logged, and the age + lossless-size gates apply. Details in the [env table](#config-file-keys-for-environment-knobs-2030). ### `plugin` diff --git a/CONFIGURATION.zh-CN.md b/CONFIGURATION.zh-CN.md index 0bb8498f59..21178b5867 100644 --- a/CONFIGURATION.zh-CN.md +++ b/CONFIGURATION.zh-CN.md @@ -201,7 +201,7 @@ | `sessions.max` | number | 256 | BILI_MAX_SESSIONS | 内存会话表上限(空闲会话 LRU 逐出)。 | | `sessions.warmMax` | number | 0 | BILI_SESSION_WARM_MAX | 有界启动(#2803/#3050):启动监听前预热加载的最近保存会话数上限,更早的状态按需重新加载。默认 0(不预热——首次访问按需加载一次;设 8 恢复预热行为)。受 sessions.max 封顶。 | | `sessions.warmMaxBytes` | number | 67108864 | BILI_SESSION_WARM_MAX_BYTES | 启动预热集的解码字节预算(#2803)。按解码后大小计而非磁盘压缩字节,zstd 归档无法绕过内存上限;单文件超预算则永不预热。 | -| `sessions.residentMaxBytes` | number | 536870912 | BILI_SESSION_RESIDENT_MAX_BYTES | 驻留会话估算字节的软目标(#2803)。活跃/在途状态始终固定保留;超过目标时,空闲状态随请求完成回写磁盘释放。 | +| `sessions.residentMaxBytes` | number | 536870912 | BILI_SESSION_RESIDENT_MAX_BYTES | 驻留会话估算字节的软目标(#2803)。活跃/在途状态始终固定保留;超过目标时,空闲状态随请求完成回写磁盘释放。若同时保持多个大会话打开,请按它们的合计权重上调(例如七个 ~136 MiB 会话需要 ≥1 GiB):池子饱和时空闲会话被逐出,每次触碰都要付一次同步冷加载,可阻塞事件循环数秒(#4893);压缩永久拒绝的日志会给出应上调到的具体值。 | | `sessions.gc.enabled` | boolean | false | BILI_SESSION_GC | 过期持久化会话的可选垃圾回收(未开启时用户数据绝不被悄悄清理)。 | | `sessions.gc.maxAgeDays` | number | 7 | BILI_SESSION_GC_MAX_AGE_DAYS | GC 年龄阈值(天)。 | | `sessions.gc.maxTokens` | number | 1000000 | BILI_SESSION_GC_MAX_TOKENS | GC 单会话记录的 token 大小阈值。 | @@ -947,7 +947,7 @@ - **类型:** `{ max?: number; gc?: { enabled?: boolean; maxAgeDays?: number; maxTokens?: number; intervalMs?: number } }` - **默认:** `{ max: 256, gc: { enabled: false, maxAgeDays: 7, maxTokens: 1000000, intervalMs: 3600000 } }` - **状态:** ACTIVE -- **说明:** `max` 以 LRU 淘汰约束内存会话数(对应 `BILI_MAX_SESSIONS`;磁盘仍是事实来源)。`warmMax`/`warmMaxBytes` 约束启动预热缓存、`residentMaxBytes` 约束空闲常驻目标(#2803 有界启动:启动只预热最近的热集,其余按需重载;活跃/in-flight 状态永不被逐出)。`gc` 控制陈旧会话文件清理(对应 `BILI_SESSION_GC*`)—— **显式开启**,因为会话文件是用户数据:压缩过的会话永不删除、每次删除都审计记录、年龄 + 无损尺寸双闸门同时满足才删。详见[环境变量表](#环境变量的配置键对照-2030)。 +- **说明:** `max` 以 LRU 淘汰约束内存会话数(对应 `BILI_MAX_SESSIONS`;磁盘仍是事实来源)。`warmMax`/`warmMaxBytes` 约束启动预热缓存、`residentMaxBytes` 约束空闲常驻目标(#2803 有界启动:启动只预热最近的热集,其余按需重载;活跃/in-flight 状态永不被逐出)。若同时保持多个大会话,把 `residentMaxBytes` 设到它们合计权重之上(#4893)——池子饱和时每次触碰被逐出的会话都是一次数秒级同步冷加载。`gc` 控制陈旧会话文件清理(对应 `BILI_SESSION_GC*`)—— **显式开启**,因为会话文件是用户数据:压缩过的会话永不删除、每次删除都审计记录、年龄 + 无损尺寸双闸门同时满足才删。详见[环境变量表](#环境变量的配置键对照-2030)。 ### `plugin` From bcdf0f9e1576ecb9180457da2f4204a2762ccdf8 Mon Sep 17 00:00:00 2001 From: ci-check Date: Tue, 27 Oct 2026 09:44:52 +0800 Subject: [PATCH 2/2] docs: source the #4893 residentMaxBytes sizing guidance from the config seed The hand-edited table rows in CONFIGURATION.md/.zh-CN.md were overwritten by tools/gen-config-docs.mjs generate (docs-sync gate), because the wording never reached the seed of record in website/config-reference/process.yaml. Move the #4893 concurrency-sizing guidance into sessions.residentMaxBytes desc_en/desc_zh so regeneration reproduces the intended rows byte-for-byte. --- website/config-reference/process.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/config-reference/process.yaml b/website/config-reference/process.yaml index 29d83428a2..3411bbabc2 100644 --- a/website/config-reference/process.yaml +++ b/website/config-reference/process.yaml @@ -365,8 +365,8 @@ entries: default: "536870912" env: BILI_SESSION_RESIDENT_MAX_BYTES group: process - desc_en: "Soft target for estimated resident session bytes (#2803). Active/in-flight state stays pinned above it; when over target, idle state discharges back to disk as requests complete." - desc_zh: "驻留会话估算字节的软目标(#2803)。活跃/在途状态始终固定保留;超过目标时,空闲状态随请求完成回写磁盘释放。" + desc_en: "Soft target for estimated resident session bytes (#2803). Active/in-flight state stays pinned above it; when over target, idle state discharges back to disk as requests complete. If several large sessions stay open at once, size it above their combined weight (e.g. seven ~136 MiB sessions want ≥1 GiB): a saturated pool evicts idle sessions and every touch of one pays a synchronous cold load that can block the event loop for seconds (#4893); the permanent compress-refusal log names the value to raise it above." + desc_zh: "驻留会话估算字节的软目标(#2803)。活跃/在途状态始终固定保留;超过目标时,空闲状态随请求完成回写磁盘释放。若同时保持多个大会话打开,请按它们的合计权重上调(例如七个 ~136 MiB 会话需要 ≥1 GiB):池子饱和时空闲会话被逐出,每次触碰都要付一次同步冷加载,可阻塞事件循环数秒(#4893);压缩永久拒绝的日志会给出应上调到的具体值。" - key: sessions.gc.enabled type: boolean default: "false"