diff --git a/docs/configuration.ja.md b/docs/configuration.ja.md index 80a4e18ec4..e06c4ef236 100644 --- a/docs/configuration.ja.md +++ b/docs/configuration.ja.md @@ -216,7 +216,7 @@ | `sessions.max` | number | 256 | BILI_MAX_SESSIONS | メモリ内セッションテーブル上限 (アイドルセッションの LRU 退避)。 | | `sessions.warmMax` | number | 0 | BILI_SESSION_WARM_MAX | 有界な起動 (#2803/#3050): リスニング前に起動時に水合される最大最近保存セッション数; 古い状態はオンデマンドで再ロードされる。デフォルト 0 (急激なウォームセットなし — 最初のタッチが 1 回のオンデマンドロードを支払う; 急激な動作を復元するには 8 を設定)。sessions.max で上限が設定される。 | | `sessions.warmMaxBytes` | number | 67108864 | BILI_SESSION_WARM_MAX_BYTES | 起動ウォームセットのデコード済みバイト予算 (#2803)。ディスク上の圧縮バイトではなくデコード済みサイズをカウントするため、zstd アーカイブが RAM 境界をすり抜けることはない。予算を超える単一のファイルは決してウォームされない。 | -| `sessions.residentMaxBytes` | number | 4294967296 | BILI_SESSION_RESIDENT_MAX_BYTES | 推定リザident セッションバイトのソフトターゲット (#2803; #5779 で 512 MiB から 4 GiB に引き上げ — 単一のセッションは通常 512 MiB を超え、より小さい予算に対して永遠にピンポンしていた)。アクティブ/進行中の状態はそれより上にピン留めされる; ターゲット超過時、アイドル状態はリクエスト完了時にディスクへ排出される。メモリが少ないマシンではこれを下げる。 | +| `sessions.residentMaxBytes` | number | 4294967296 | BILI_SESSION_RESIDENT_MAX_BYTES | 推定リザident セッションバイトのソフトターゲット (#2803; #5779 で 512 MiB から 4 GiB に引き上げ — 単一のセッションは通常 512 MiB を超え、より小さい予算に対して永遠にピンポンしていた)。アクティブ/進行中の状態はそれより上にピン留めされる; ターゲット超過時、アイドル状態はリクエスト完了時にディスクへ排出される。複数の大容量セッションを同時に開いたままにする場合は、それらの合計重さより大きく設定してください (例: 約 136 MiB のセッション 7 件なら 1 GiB 以上が必要)。プールが飽和するとアイドルセッションが退避され、そのどれかに触れるたびに数秒間イベントループをブロックしうる同期コールドロードが発生します (#4893)。コンプレッションの恒久拒否ログには、超えて設定すべき値が記載されます。メモリが少ないマシンではこれを下げる。 | | `sessions.hardMaxBytes` | number | (same as `sessions.residentMaxBytes`) | BILI_SESSION_RESIDENT_HARD_MAX_BYTES | セッションごとの推定リザident バイトのハード上限 (#4788, 決定 #4792 D1-A)。プールソフト上限とは異なり — それは他のコールドセッションのみを退避でき、単独アクティブセッションには決して触れない — これは 1 つのセッションを制限する: リクエスト終了境界で上限超過時、そのドロップ可能なフィールド (フォールドブロックのオリジナル、メタデータ台帳、有界ビューを超える生テール) はプール免除セッションであっても強制的にディスクへ戻され、次のターンは狭いディスク読み取りを通じて必要なものを透明に再読み取りする。最後の保存が確実に着地したことが証明される限り、安全なドロップはすべてのリクエスト境界で実行される; 上限はセッションごとのコールアウト (警告、60 秒にスロットリング) を追加する。`0` は上限チェックを無効にする。 | | `sessions.contentStorePin` | boolean | false | BILI_SESSION_CONTENT_STORE_PIN | #4788 フェーズ2の常駐ドロップのエスケープハッチ: 各セッションのコンテンツストアをメモリに固定する(折りたたみは行われない)。デフォルトはオフ: 検証済みの保存が完了するたびに、アイドル状態のセッションのコンテンツストアはリクエスト間でドロップされ、統合インデックスミラーまたはサイドカーファイルからオンデマンドで再読み込みされる。検証済みのコピーがないストアを持つセッション(例: 新しいフォーク子プロセス)は自動的に常駐する。RAMを犠牲にしてゼロの再読み込みレイテンシが必要な場合にこれを設定する。 | | `sessions.gc.enabled` | boolean | false | BILI_SESSION_GC | 古い永続化セッションのオプトインによるガベージコレクション(このフラグなしでユーザーデータを静かに削除することはない)。 | @@ -1047,7 +1047,7 @@ - **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` は LRU エビクションによりメモリ内のセッション数を制限する(対応する環境変数 `BILI_MAX_SESSIONS`;ディスクは依然として真実のソースである)。`warmMax`/`warmMaxBytes` は起動時のウォームキャッシュを、`residentMaxBytes` はアイドル時の常駐目標を制限する(#2803 有界な起動: 起動時に最も最近のウォームセットのみがハイドレーションされ、それ以外はオンデマンドで再読み込みされる;アクティブ/進行中の状態は決してエビクションされない)。`gc` は古いセッションファイルのクリーンアップを制御する(対応する環境変数 `BILI_SESSION_GC*`) — **オプトイン**であり、セッションファイルはユーザーデータであるため:圧縮されたセッションは決して削除されず、削除は監査ログに記録され、経過日数およびロスレスサイズのゲートが適用される。詳細は [env table](#config-file-keys-for-environment-knobs-2030) を参照。 +- **Description:** `max` は LRU エビクションによりメモリ内のセッション数を制限する(対応する環境変数 `BILI_MAX_SESSIONS`;ディスクは依然として真実のソースである)。`warmMax`/`warmMaxBytes` は起動時のウォームキャッシュを、`residentMaxBytes` はアイドル時の常駐目標を制限する(#2803 有界な起動: 起動時に最も最近のウォームセットのみがハイドレーションされ、それ以外はオンデマンドで再読み込みされる;アクティブ/進行中の状態は決してエビクションされない)。同時に開いている複数の大容量セッションの合計重さより `residentMaxBytes` を大きく設定してください (#4893) — プールが飽和しているとき、退避されたセッションに触れるたびに数秒級の同期コールドロードが発生します。`gc` は古いセッションファイルのクリーンアップを制御する(対応する環境変数 `BILI_SESSION_GC*`) — **オプトイン**であり、セッションファイルはユーザーデータであるため:圧縮されたセッションは決して削除されず、削除は監査ログに記録され、経過日数およびロスレスサイズのゲートが適用される。詳細は [env table](#config-file-keys-for-environment-knobs-2030) を参照。 ### `plugin` diff --git a/docs/configuration.md b/docs/configuration.md index bae6ef4768..3bc91dc3a1 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -217,7 +217,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 | 4294967296 | BILI_SESSION_RESIDENT_MAX_BYTES | Soft target for estimated resident session bytes (#2803; raised from 512 MiB to 4 GiB in #5779 — single sessions routinely exceed half a GiB and ping-ponged against the smaller budget forever). Active/in-flight state stays pinned above it; when over target, idle state discharges back to disk as requests complete. Lower it if your machine has little RAM. | +| `sessions.residentMaxBytes` | number | 4294967296 | BILI_SESSION_RESIDENT_MAX_BYTES | Soft target for estimated resident session bytes (#2803; raised from 512 MiB to 4 GiB in #5779 — single sessions routinely exceed half a GiB and ping-ponged against the smaller budget forever). 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. Lower it if your machine has little RAM. | | `sessions.hardMaxBytes` | number | (same as `sessions.residentMaxBytes`) | BILI_SESSION_RESIDENT_HARD_MAX_BYTES | Per-SESSION hard cap on estimated resident bytes (#4788, decision #4792 D1-A). Unlike the pool soft cap — which can only evict OTHER cold sessions and never touches a sole-active session — this bounds ONE session: over the cap at a request-end boundary, its droppable fields (folded-block originals, metadata ledger, the raw tail beyond the bounded view) are forced back to disk even for a pool-exempt session, and the next turn transparently re-reads what it needs via narrow disk reads. Safe drops run at every request boundary as long as the last save has provably landed; the cap adds the per-session call-out (warn, throttled to 60 s). `0` disables the cap check. | | `sessions.contentStorePin` | boolean | false | BILI_SESSION_CONTENT_STORE_PIN | Escape hatch for the #4788 phase-2 resident drop: keep each session's content store pinned in memory (nothing ever folded away). Default off: after every proven-landed save, idle sessions' content stores are dropped between requests and re-read on demand from the unified index mirror or the sidecar file; sessions whose store has no provably-landed copy (e.g. fresh fork children) stay resident automatically. Set this if you need zero re-read latency at the cost of RAM. | | `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). | @@ -1045,7 +1045,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/docs/configuration.zh-CN.md b/docs/configuration.zh-CN.md index 45861d8461..1d9dd49b89 100644 --- a/docs/configuration.zh-CN.md +++ b/docs/configuration.zh-CN.md @@ -217,7 +217,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 | 4294967296 | BILI_SESSION_RESIDENT_MAX_BYTES | 驻留会话估算字节的软目标(#2803;#5779 从 512 MiB 提高到 4 GiB——单个会话经常就超过半 GiB,旧预算下会被反复逐出、永远驻留不下来)。活跃/在途状态始终固定保留;超过目标时,空闲状态随请求完成回写磁盘释放。内存小的机器可调低。 | +| `sessions.residentMaxBytes` | number | 4294967296 | BILI_SESSION_RESIDENT_MAX_BYTES | 驻留会话估算字节的软目标(#2803;#5779 从 512 MiB 提高到 4 GiB——单个会话经常就超过半 GiB,旧预算下会被反复逐出、永远驻留不下来)。活跃/在途状态始终固定保留;超过目标时,空闲状态随请求完成回写磁盘释放。若同时保持多个大会话打开,请按它们的合计权重上调(例如七个 ~136 MiB 会话需要 ≥1 GiB):池子饱和时空闲会话被逐出,每次触碰都要付一次同步冷加载,可阻塞事件循环数秒(#4893);压缩永久拒绝的日志会给出应上调到的具体值。内存小的机器可调低。 | | `sessions.hardMaxBytes` | number | (same as `sessions.residentMaxBytes`) | BILI_SESSION_RESIDENT_HARD_MAX_BYTES | 单会话驻留字节的硬上限(#4788,决策 #4792 D1-A)。不同于池软上限——它只能逐出其他冷会话、从不触碰唯一活跃会话——它约束单个会话:在请求结束边界超过上限时,其可丢弃字段(已折叠块的原文、元数据账本、超出有界视图的原始尾巴)会被强制回写磁盘,即使该会话被池逐出豁免;下一轮通过窄盘读透明地重新读取所需内容。只要上一次保存已被证明落盘,安全丢弃就在每个请求边界运行;该上限额外加入单会话告警(warn,限流至 60 秒)。`0` 关闭该检查。 | | `sessions.contentStorePin` | boolean | false | BILI_SESSION_CONTENT_STORE_PIN | #4788 二期驻留丢弃的逃生门:把会话内容存储钉在内存(永不折叠)。默认关闭:每次已证明落盘的保存之后,空闲会话的内容存储在请求间隙被释放,需要时从统一索引镜像或伴生文件按需重读;没有可证明落盘副本的会话(如新建 fork 子会话)自动保持驻留。需要零重读延迟且愿意用内存换时可设此项。 | | `sessions.gc.enabled` | boolean | false | BILI_SESSION_GC | 过期持久化会话的可选垃圾回收(未开启时用户数据绝不被悄悄清理)。 | @@ -1039,7 +1039,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` diff --git a/website/config-reference/process.yaml b/website/config-reference/process.yaml index 6a0632a4e6..86ac8c8618 100644 --- a/website/config-reference/process.yaml +++ b/website/config-reference/process.yaml @@ -487,9 +487,9 @@ entries: default: "4294967296" env: BILI_SESSION_RESIDENT_MAX_BYTES group: process - desc_en: "Soft target for estimated resident session bytes (#2803; raised from 512 MiB to 4 GiB in #5779 — single sessions routinely exceed half a GiB and ping-ponged against the smaller budget forever). Active/in-flight state stays pinned above it; when over target, idle state discharges back to disk as requests complete. Lower it if your machine has little RAM." - desc_zh: "驻留会话估算字节的软目标(#2803;#5779 从 512 MiB 提高到 4 GiB——单个会话经常就超过半 GiB,旧预算下会被反复逐出、永远驻留不下来)。活跃/在途状态始终固定保留;超过目标时,空闲状态随请求完成回写磁盘释放。内存小的机器可调低。" - desc_ja: "推定リザident セッションバイトのソフトターゲット (#2803; #5779 で 512 MiB から 4 GiB に引き上げ — 単一のセッションは通常 512 MiB を超え、より小さい予算に対して永遠にピンポンしていた)。アクティブ/進行中の状態はそれより上にピン留めされる; ターゲット超過時、アイドル状態はリクエスト完了時にディスクへ排出される。メモリが少ないマシンではこれを下げる。" + desc_en: "Soft target for estimated resident session bytes (#2803; raised from 512 MiB to 4 GiB in #5779 — single sessions routinely exceed half a GiB and ping-ponged against the smaller budget forever). 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. Lower it if your machine has little RAM." + desc_zh: "驻留会话估算字节的软目标(#2803;#5779 从 512 MiB 提高到 4 GiB——单个会话经常就超过半 GiB,旧预算下会被反复逐出、永远驻留不下来)。活跃/在途状态始终固定保留;超过目标时,空闲状态随请求完成回写磁盘释放。若同时保持多个大会话打开,请按它们的合计权重上调(例如七个 ~136 MiB 会话需要 ≥1 GiB):池子饱和时空闲会话被逐出,每次触碰都要付一次同步冷加载,可阻塞事件循环数秒(#4893);压缩永久拒绝的日志会给出应上调到的具体值。内存小的机器可调低。" + desc_ja: "推定リザident セッションバイトのソフトターゲット (#2803; #5779 で 512 MiB から 4 GiB に引き上げ — 単一のセッションは通常 512 MiB を超え、より小さい予算に対して永遠にピンポンしていた)。アクティブ/進行中の状態はそれより上にピン留めされる; ターゲット超過時、アイドル状態はリクエスト完了時にディスクへ排出される。複数の大容量セッションを同時に開いたままにする場合は、それらの合計重さより大きく設定してください (例: 約 136 MiB のセッション 7 件なら 1 GiB 以上が必要)。プールが飽和するとアイドルセッションが退避され、そのどれかに触れるたびに数秒間イベントループをブロックしうる同期コールドロードが発生します (#4893)。コンプレッションの恒久拒否ログには、超えて設定すべき値が記載されます。メモリが少ないマシンではこれを下げる。" - key: sessions.hardMaxBytes type: number default: "(same as `sessions.residentMaxBytes`)"