diff --git a/CONFIGURATION.md b/CONFIGURATION.md index 27aab63a54..8e7473ecc0 100644 --- a/CONFIGURATION.md +++ b/CONFIGURATION.md @@ -362,7 +362,7 @@ This index is generated from `website/config-reference/*.yaml` — edit the seed | `BILI_STORAGE_BACKEND` | sqlite\|mysql | sqlite | — | Env tier for storage.backend (#3931): sqlite (default) or mysql (fully wired, #3388 steps 2+3 - saves ingest through the async shadow queue, sync reads ride the JSON envelope, replicas/ext/GC/fork via the async twins (#4911); export too). Wins over the file tier. | | `BILI_MYSQL_DSN` | string | unset | — | MySQL DSN (mysql://user:pass@host:3306/db) for storage.backend="mysql" (#3388, #3931). Wins over the file key storage.mysql.dsn. Empty = the mysql backend cannot open; the documented error names both knobs. The pool opens lazily; closeQuietlyAsync drains the ingest queue and closes it. | | `BILI_STORAGE_ARCHIVE_AFTER_DAYS` | integer | 365 | — | GC age sweep window in days (#3463): sessions idle longer than this are archived (one JSON line appended to the single archive log (archive/archive.jsonl) + tombstone row + content/media refs released). 0 disables the age sweep; the manual entry POST /__bili/storage/gc always runs. Config-file key storage.archiveAfterDays is the persistent form. | -| `BILI_STORAGE_QUICK_CHECK` | string | on | — | Storage integrity self-check at open (#4175): every index.db open runs PRAGMA quick_check BEFORE migrations; if a corruption is PROVEN by THIS BOOT's own scan NOTHING is moved, copied or rebuilt automatically (auto-recovery was withdrawn #4609/#4626-era: with BILI_STORAGE_JSON_WRITER=off the index is the SOLE durable copy, so an automatic move or rebuild cannot guarantee full data recovery) and bili STARTS ANYWAY — serving from the JSON envelopes with a loud, actionable alarm naming the manual fix (back up then move index.db/-wal/-shm aside BY HAND, then start again — a fresh index rebuilds from the JSON envelopes). A successful PASS is cached so later starts skip the rescan; a FAIL verdict is NEVER persisted (2026-10-30 owner policy): runtime/background findings are alarms only (loud logs + runtime-status, the process keeps serving — JSON envelopes remain the recovery source) and every boot decides again from a fresh scan of the CURRENT file set, so a stale FAIL left behind by an older version can never block future boots. There is NO automatic rename/repair AND no legacy-only fallback: continuing legacy-only would fork the JSON envelopes from the dead index forever (never reconcilable). TRANSIENT open failures (no SQLite engine / CANTOPEN / second writer / readonly / backend DSN) make bili REFUSE TO START loudly with an actionable error — no silent legacy fallback for environment problems either (2026-10-30 owner policy); deployments that genuinely want JSON-only serve explicitly (BILI_STORAGE_UNIFIED=legacy or unset). Set 0 only for boot-time-sensitive huge deployments where the check's cost matters. | +| `BILI_STORAGE_QUICK_CHECK` | string | on | — | Storage integrity self-check at open (#4175): every index.db open runs PRAGMA quick_check BEFORE migrations; if a corruption is PROVEN by THIS BOOT's own scan NOTHING is moved, copied or rebuilt automatically (auto-recovery was withdrawn #4609/#4626-era: with BILI_STORAGE_JSON_WRITER=off the index is the SOLE durable copy, so an automatic move or rebuild cannot guarantee full data recovery) and bili STARTS ANYWAY — serving from the JSON envelopes with a loud, actionable alarm naming the manual fix (back up then move index.db/-wal/-shm aside BY HAND, then start again — a fresh index rebuilds from the JSON envelopes). A successful PASS is cached so later starts skip the rescan; a FAIL verdict is NEVER persisted (2026-10-30 owner policy): runtime/background findings are alarms only (loud logs + runtime-status, the process keeps serving — JSON envelopes remain the recovery source) and every boot decides again from a fresh scan of the CURRENT file set, so a stale FAIL left behind by an older version can never block future boots. There is NO automatic rename/repair AND no legacy-only fallback: continuing legacy-only would fork the JSON envelopes from the dead index forever (never reconcilable). TRANSIENT open failures (no SQLite engine / CANTOPEN / readonly / backend DSN) make bili REFUSE TO START loudly with an actionable error — no silent legacy fallback for environment problems either (2026-10-30 owner policy; a live second writer left this refusal list on 2026-10-31 — sharing one local-disk index.db is the supported topology, informational only, never blocking); deployments that genuinely want JSON-only serve explicitly (BILI_STORAGE_UNIFIED=legacy or unset). Set 0 only for boot-time-sensitive huge deployments where the check's cost matters. | | `BILI_SNAPSHOT_SHADOW` | boolean | true (on) | — | Snapshot-render shadow observability (#3756 follow-up): compute the outbound snapshot view on every armed turn WITHOUT using it, classify the diff against the legacy outbound, and surface per-session counters in the web panel + the snapshot-shadow diagnostics topic. 0/false/off disables; 1/true/on enables; otherwise the config-file snapshot.shadow boolean applies (default on). The render lane itself stays rollout-gated (BILI_ROLLOUT_SNAPSHOT_RENDER), so the shadow lane never changes outbound bytes - it is the dry-run evidence that flips the rollout later. | | `BILI_CONFIG_FILE` | string | unset (XDG config path) | — | Override the config file path (path relocation). | | `BILI_SESSIONS_DIR` | string | unset (XDG state path) | — | Where session records are stored (path relocation). | diff --git a/CONFIGURATION.zh-CN.md b/CONFIGURATION.zh-CN.md index 155f596e3b..fe9a5f140c 100644 --- a/CONFIGURATION.zh-CN.md +++ b/CONFIGURATION.zh-CN.md @@ -362,7 +362,7 @@ | `BILI_STORAGE_BACKEND` | sqlite\|mysql | sqlite | — | storage.backend 的环境变量层(#3931):sqlite(默认)或 mysql(已接线,#3388 第二+三步 —— 保存经异步影子队列入 mysql,同步读走 JSON 信封,replicas/ext/GC/fork 走异步孪生(#4911);export 同样支持)。优先于文件层。 | | `BILI_MYSQL_DSN` | string | unset | — | storage.backend="mysql" 的 MySQL DSN(mysql://user:pass@host:3306/db)(#3388,#3931)。优先于文件键 storage.mysql.dsn。留空 = mysql 后端无法打开;文档化错误会列出两个旋钮。连接池惰性打开;closeQuietlyAsync 排空入队事务并关闭。 | | `BILI_STORAGE_ARCHIVE_AFTER_DAYS` | integer | 365 | — | GC 年龄清扫窗口(天,#3463):闲置超过该时长的会话被归档(单文件归档日志 archive/archive.jsonl 追加一行 + 墓碑行保留标签 + 释放内容/媒体引用)。0 关闭年龄清扫;手动入口 POST /__bili/storage/gc 始终可用。配置文件键 storage.archiveAfterDays 为持久形式。 | -| `BILI_STORAGE_QUICK_CHECK` | string | on | — | 存储开库自检(#4175):每次 index.db 打开在迁移之前先跑 PRAGMA quick_check;一旦由本次启动自己的扫描证实损坏,文件原样保留在原地——不做任何自动搬移、复制或重建(自动恢复已撤回:BILI_STORAGE_JSON_WRITER=off 时索引是唯一的持久副本,自动操作无法保证完整数据恢复)——bili 照常启动,改用 JSON 信封服务,并给出响亮、可操作的告警指明手工修复步骤(备份后把 index.db/-wal/-shm 手工移开再启动——全新索引会从 JSON 信封重建)。PASS 判定会被缓存,之后的启动跳过重扫;FAIL 判定永不持久化(2026-10-30 owner 策略):运行期/后台发现只是告警(响亮日志 + runtime-status,进程继续服务——JSON 信封始终是恢复来源),每次启动都对当前文件集做新鲜扫描再判定,旧版本遗留的陈旧 FAIL 永远不能阻断后续启动。既没有自动改名/修复,也没有 legacy-only 兜底(继续以 legacy-only 运行会让 JSON 信封与死掉的索引永久分叉、再无对账可能)。瞬态打开失败(无引擎 / CANTOPEN / 第二写者 / 只读 / 后端 DSN)仍响亮地拒绝启动并给出可操作的错误——环境类问题同样不允许静默走 legacy 兜底;真正需要纯 JSON 服务的部署请显式设置 BILI_STORAGE_UNIFIED=legacy(或留空)。仅当超大部署对启动耗时敏感、检测成本构成问题时才设 0 跳过。 | +| `BILI_STORAGE_QUICK_CHECK` | string | on | — | 存储开库自检(#4175):每次 index.db 打开在迁移之前先跑 PRAGMA quick_check;一旦由本次启动自己的扫描证实损坏,文件原样保留在原地——不做任何自动搬移、复制或重建(自动恢复已撤回:BILI_STORAGE_JSON_WRITER=off 时索引是唯一的持久副本,自动操作无法保证完整数据恢复)——bili 照常启动,改用 JSON 信封服务,并给出响亮、可操作的告警指明手工修复步骤(备份后把 index.db/-wal/-shm 手工移开再启动——全新索引会从 JSON 信封重建)。PASS 判定会被缓存,之后的启动跳过重扫;FAIL 判定永不持久化(2026-10-30 owner 策略):运行期/后台发现只是告警(响亮日志 + runtime-status,进程继续服务——JSON 信封始终是恢复来源),每次启动都对当前文件集做新鲜扫描再判定,旧版本遗留的陈旧 FAIL 永远不能阻断后续启动。既没有自动改名/修复,也没有 legacy-only 兜底(继续以 legacy-only 运行会让 JSON 信封与死掉的索引永久分叉、再无对账可能)。瞬态打开失败(无引擎 / CANTOPEN / 只读 / 后端 DSN)仍响亮地拒绝启动并给出可操作的错误——环境类问题同样不允许静默走 legacy 兜底(活的第二写者已于 2026-10-31 移出该拒绝清单:多进程共享一个本地盘 index.db 是受支持拓扑,只提示、永不阻断启动);真正需要纯 JSON 服务的部署请显式设置 BILI_STORAGE_UNIFIED=legacy(或留空)。仅当超大部署对启动耗时敏感、检测成本构成问题时才设 0 跳过。 | | `BILI_SNAPSHOT_SHADOW` | boolean | true (on) | — | 快照渲染影子对账(#3756 后续):每轮已折叠会话都用引擎现算一次出站快照视图但不使用,与 legacy 实际出站比对分类,逐会话计数进 web 面板与 snapshot-shadow 诊断主题。0/false/off 关闭;1/true/on 开启;否则读配置文件 snapshot.shadow 布尔(默认开)。渲染车道本身仍受灰度开关控制(BILI_ROLLOUT_SNAPSHOT_RENDER),影子车道绝不改变出站字节 —— 它是后续翻转灰度的干跑证据。 | | `BILI_CONFIG_FILE` | string | unset (XDG config path) | — | 覆盖配置文件路径(路径重定位)。 | | `BILI_SESSIONS_DIR` | string | unset (XDG state path) | — | 会话记录的存放目录(路径重定位)。 | diff --git a/README.md b/README.md index 115f2a67ba..d05e873b06 100644 --- a/README.md +++ b/README.md @@ -645,20 +645,24 @@ Consequences for anyone tempted to put several instances behind one Service: single-instance by design. **Single machine, multiple installs (#5046).** The topology above covers -deployment replicas; one desktop has a sibling hazard: two installs on ONE +deployment replicas; one desktop has a sibling situation: two installs on ONE machine (e.g. two DSH profiles — desktop + bot, or a global npm copy beside a host-tree copy) each start their own proxy and, unless isolated, both resolve -the SAME default XDG sessions directory and the same config file. With -`storage.unified` on (shadow/full), two processes then double-write one -`index.db`: the log shows `[instances] another bili instance is running …` -and, for overlapping lanes, `[storage] … two processes on one index.db -corrupt it`; SQLite write-lock contention (`SQLITE_BUSY` / `database is -locked`) can fail whole model turns, and sustained double-writing risks -corruption. The fix is isolation: give each install its own -`BILI_SESSIONS_DIR` (plus `BILI_CONFIG_FILE` when the config should differ -too) through that install's launcher/profile environment — no global env -changes needed. Once isolated, the installs coexist safely and the -`[instances]` notice drops to info level (different dirs ⇒ no shared state). +the SAME default XDG sessions directory and the same config file. Multiple +processes writing ONE local-disk `index.db` is the SUPPORTED topology +(#5082/#5091) — SQLite WAL is multi-process safe on a local filesystem — so +startup NEVER blocks on a live foreign writer: the peer shows up as an +info-level `[storage] process pid … is also using …` line plus the status wire, +nothing more (policy settled 2026-10-31, withdrawing the #5046/B-era +refuse-to-start for exactly this shape). What genuinely remains hazardous is +two installs walking the SAME *session* concurrently — that case alarms +separately (split-brain contest, #3923). If you still want strictly separate +histories and stores per install, give each its own `BILI_SESSIONS_DIR` (plus +`BILI_CONFIG_FILE` when the config should differ too) through that install's +launcher/profile environment — no global env changes needed. Once isolated, +the `[instances]` notice drops off entirely. Note the distinction from the +deployment case above: local disk with SQLite WAL tolerates many writers; +shared RWX/NFS storage does NOT and keeps requiring one writer per volume. Naming note: `POST /__bili/replicas` creates a session **checkpoint fork** (from stored checkpoints), not a pod replica — read it as `/__bili/checkpoints`. diff --git a/src/storage-maintenance.ts b/src/storage-maintenance.ts index 376de522e8..6b64d06a21 100644 --- a/src/storage-maintenance.ts +++ b/src/storage-maintenance.ts @@ -7,7 +7,6 @@ import { existsSync, statSync } from "node:fs"; import { join } from "node:path"; import { SessionStore } from "./persist.js"; -import { StorageSecondWriterError } from "./storage/store.js"; import type { GcPlan } from "./storage/store.js"; import { fileStorageArchiveAfterDays, resolveArchiveAfterDays } from "./knobs.js"; @@ -278,17 +277,11 @@ export async function runStorageGcCommand(opts: { try { store = new SessionStore({ dir: opts.dir, enabled: true }); } catch (err) { - // #4612: under the no-degradation policy a live foreign writer makes the - // unified open REFUSE (constructor throws) before runGc's own guard can - // answer. Surface the same actionable refusal the in-process guard - // produces instead of leaking a stack trace through the CLI. - if (err instanceof StorageSecondWriterError) { - const reason = `refused: another process (pid ${err.pid}) is actively writing index.db — 'storage gc --vacuum full' rewrites the whole database under an exclusive write lock and would starve the other instance's writes until its storage layer degrades. Stop the other process (or wait for it to exit) and retry, or use --vacuum incremental for an online-safe shrink.`; - if (opts.dryRun) return { code: 0, text: `${reason}\ndry-run: nothing executed\n` }; - const data: Record = { refused: true, writerPid: err.pid, vacuum: opts.vacuum ?? "full", dryRun: false }; - if (opts.json) return { code: 1, text: `${JSON.stringify(data, null, 2)}\n` }; - return { code: 1, text: `${reason}\n` }; - } + // #4612: a live foreign writer does NOT make the unified open refuse + // anymore (owner decision 2026-10-31: second-writer conditions are + // informational, never blocking) — the full-VACUUM starvation guard + // lives in runGc itself (store.unifiedActiveWriter()), so no special + // branch is needed here. throw err; } try { diff --git a/src/storage/runtime-status.ts b/src/storage/runtime-status.ts index d27712ac22..28d555ba11 100644 --- a/src/storage/runtime-status.ts +++ b/src/storage/runtime-status.ts @@ -208,8 +208,6 @@ function degradeReason(): string { } if (state.sidecarOpenError) { const e = shortenError(state.sidecarOpenError); - // #5046/B: shadow.ts records second-writer refusals pre-formatted (already names the fix + what's lost) — render verbatim instead of wrapping them as "index database failed to open". - if (e.startsWith("second-writer:")) return e; // The driver's no-engine error surfaces through the same open path — // say what it actually is instead of "index database failed to open". if (isNoEngineError(e)) { diff --git a/src/storage/shadow.ts b/src/storage/shadow.ts index a1ef117d7a..e6528d39c9 100644 --- a/src/storage/shadow.ts +++ b/src/storage/shadow.ts @@ -28,7 +28,7 @@ import { log as loggerLog } from "../logger.js"; import { planIngest, planIngestDelta, loadLegacyView, LegacyViewBuilder, appendBlockContents, mergeOrphanBlockContents, completeBlockContents, type LegacySessionLike } from "./ingest.ts"; import type { BlockView } from "../session.js"; import { resolveStorageMode, resolveStorageWalJournalSizeLimit, type StorageMode } from "../knobs.ts"; -import { UnifiedStore, StorageIntegrityError, StorageSecondWriterError, type CheckpointRow, type SessionSummaryRow, type WebSummaryRow } from "./store.ts"; +import { UnifiedStore, StorageIntegrityError, type CheckpointRow, type SessionSummaryRow, type WebSummaryRow } from "./store.ts"; import path from "node:path"; import { resolveBackendName, backendSelectionNotice, selectedBackendRaw, openBackend, type StorageBackend } from "./backend.ts"; import { canonicalDigest, canonicalize, sha256 } from "./canonical.ts"; @@ -254,10 +254,8 @@ export class UnifiedShadow { let store: UnifiedStore; try { try { - store = UnifiedStore.open(`${dir}/index.db`, undefined, { walJournalSizeLimitBytes: walLimit, secondWriterPolicy: "degrade" }); + store = UnifiedStore.open(`${dir}/index.db`, undefined, { walJournalSizeLimitBytes: walLimit }); } catch (err) { - // #5046/B: a live foreign writer owns this db — never touch it (the file is NOT corrupt) and never take over its lock; the outer catch REFUSES. - if (err instanceof StorageSecondWriterError) throw err; // #4175: anything else throwing StorageIntegrityError means quick_check // proved the file set corrupt — handled below WITHOUT moving any file // (#4626-era owner decision, 2026-10-30). @@ -291,15 +289,6 @@ export class UnifiedShadow { // per session re-establishes trust from its own view. store.resetAllIngestWatermarks(); } catch (err) { - // #5046/B (owner decision 2026-10-29): refuse to become a persistent second writer — degrade to legacy-only with ONE actionable error. Availability is preserved (legacy persist keeps compression working); CCR / checkpoints / the unified fast-read path are off until isolated. The status wire carries the same fact via recordSidecarOpenFailure (#3040). - if (err instanceof StorageSecondWriterError) { - loggerLog( - "error", - `[storage] unified storage REFUSED for this instance (pid ${process.pid}): another bili process (pid ${err.pid}) already writes ${err.dbPath} — sharing one sessions dir across lanes is the supported topology (#5082/#5091), but two processes writing the SAME sessions dir can split-brain it (#3923/#3959), so this one refuses to co-write and REFUSES TO START until isolated (#5046 owner chain 2026-10-30: no silent degradation of any kind). Fix: give each install its own sessions dir — set BILI_SESSIONS_DIR (and BILI_CONFIG_FILE if the configs differ) for THIS install, then restart (README "Running multiple instances", #5046/#5068); or force legacy explicitly (BILI_STORAGE_UNIFIED=legacy).`, - ); - recordSidecarOpenFailure(`second-writer: another bili process (pid ${err.pid}) owns index.db — isolate via BILI_SESSIONS_DIR(+BILI_CONFIG_FILE); refusing to start until then (#5046)`); - throw err; - } const errStr = String(err); // Deleting the index cannot fix a no-engine failure (this Node.js has neither builtin // node:sqlite nor a loadable better-sqlite3), and it cannot clear an OS-level refusal @@ -310,7 +299,7 @@ export class UnifiedShadow { // above handles them (loud alarm + boot WITHOUT the index). // #4626-era owner decision chain (2026-10-30): every OTHER // sidecar-open failure REFUSES TO START instead of degrading — - // no-engine/CANTOPEN/readonly/second-writer: availability at the + // no-engine/CANTOPEN/readonly/OS-level: availability at the // price of a silently different storage path was withdrawn by // owner instruction "在任何情况下不降级". Intentional opt-outs // (legacy mode / encryption opt-out / persistence off) resolve to diff --git a/src/storage/store.ts b/src/storage/store.ts index c798c263f8..39be0366d6 100644 --- a/src/storage/store.ts +++ b/src/storage/store.ts @@ -386,12 +386,18 @@ function processAlive(pid: number): boolean { } } -/** #5046/B: a live foreign bili process holds .lock and this open is not - * a benign cross-lane share — thrown when the caller opted into - * secondWriterPolicy:"degrade" so it can REFUSE to become a persistent - * second writer instead of reporting-and-running (#3923/#3959). The foreign - * lockfile is left untouched and the raw handle is closed before the throw - * (a leaked WAL handle would defeat the isolation on Windows). */ +/** @deprecated Public export surface only — no code path inside this repo + * throws it anymore (owner decision 2026-10-31: whatever lanes are involved, + * a second-writer condition NEVER blocks startup, it reports and coexists). + * Under the withdrawn #5046/B policy (2026-10-29→10-30) callers could opt + * into secondWriterPolicy:"degrade" and this error made the open REFUSE when + * a live foreign bili process held .lock outside a proven cross-lane + * share (#3923/#3959). Owner decision 2026-10-31: multiple processes writing + * one index.db IS the supported topology (#5082/#5091) — SQLite WAL is + * multi-process safe on a local filesystem — so the condition went back to + * informational reporting plus the web/status surface; the genuine hazard, + * two instances writing the SAME session, alarms via the split-brain contest. + * Kept exported for external code that still imports/catches it. */ export class StorageSecondWriterError extends Error { readonly pid: number; readonly dbPath: string; @@ -432,7 +438,7 @@ export class UnifiedStore { static open( path: string, engine?: SqliteEngineName, - opts?: { walJournalSizeLimitBytes?: number; secondWriterPolicy?: "report" | "degrade" }, + opts?: { walJournalSizeLimitBytes?: number }, ): UnifiedStore { mkdirSync(dirname(path), { recursive: true }); const { db, engine: used, source } = openSqliteDatabase(path, engine); @@ -502,18 +508,17 @@ export class UnifiedStore { integrityOk = true; } // #4175: second-process-on-the-same-db detection. A live foreign pid - // is surfaced (web wire + banner); the default policy never blocks - // (blocking would brick the second lane outright) — a caller that opts - // into secondWriterPolicy:"degrade" may instead refuse unified storage - // and degrade to legacy-only (#5046/B), which preserves availability. - // #5082: coexistence on one index.db - // is the SUPPORTED topology — SQLite WAL is multi-process safe on a - // local filesystem and the machine-global sessions dir is - // deliberately shared — so the foreign pid is informational WHATEVER - // lane it maps to (or none: inline lanes never register). The real - // hazard, two instances writing the SAME session, has its own - // per-session alarm (the #3923 split-brain contest). A dead pid means - // a stale lock: take it over. + // is surfaced (web wire + banner) as INFORMATIONAL ONLY. #5082: sharing + // one index.db is the SUPPORTED topology — SQLite WAL is multi-process + // safe on a local filesystem and the machine-global sessions dir is + // deliberately shared — so coexistence with a live foreign writer never + // blocks startup, whatever lane the foreign pid maps to (or none: + // inline lanes never register). Owner decision 2026-10-31: the former + // #5046/B refuse-to-start policy for risky double-write shapes was + // withdrawn — no lane condition blocks anymore. The real hazard, two + // instances writing the SAME session, has its own per-session alarm + // (the #3923 split-brain contest). A dead pid means a stale lock: + // take it over. const lockPath = `${path}.lock`; let foreignLockHolder: { pid: number } | null = null; try { @@ -527,21 +532,13 @@ export class UnifiedStore { const peer = listInstances() .filter((e) => e.pid === pid) .reduce((best, e) => (best === undefined || (e.startedAt ?? 0) > (best.startedAt ?? 0) ? e : best), undefined); - // #5046/B (owner decision 2026-10-29): the degrade POLICY decides whether - // THIS caller may become a persistent second writer. Cross-lane sharing is - // the supported topology (#5082/#3923) — stay open. Same-lane, or a peer whose - // lane is unknown (inline lanes never register / pre-#5046 markers carry none), - // is the risky double-write shape — refuse BEFORE taking over the lockfile when - // degrade is opted in; the caller owns the actionable user-facing line. - const ownLane = process.env.BILI_LAUNCHER_LANE?.trim() || undefined; - const crossLaneSafe = peer !== undefined && ownLane !== undefined && peer.lane !== undefined && peer.lane !== ownLane; - if (opts?.secondWriterPolicy === "degrade" && !crossLaneSafe) { - db.close(); - throw new StorageSecondWriterError(pid, path); - } - // #5091/#5082: reporting is INFORMATIONAL for every live foreign holder — - // SQLite WAL multi-process open is safe on a local disk; the real hazard (two - // instances writing the SAME session) alarms separately (split-brain contest). + // #5091/#5082 (owner decision 2026-10-31): reporting is + // INFORMATIONAL for every live foreign holder — whatever + // its lane identity (same lane, cross-lane, or unregistered + // inline/pre-#5046 marker). SQLite WAL multi-process open + // is safe on a local disk; the real hazard (two instances + // writing the SAME session) alarms separately (split-brain + // contest). const peerOf = peer !== undefined ? ` (lane ${peer.lane ?? "?"}, instance ${peer.instanceId.slice(0, 8)})` : ""; loggerLog("info", `[storage] process pid ${pid}${peerOf} is also using ${path} — multiple instances sharing one sessions dir is the supported topology (#5082/#3923); two instances walking the SAME session alarm separately (split-brain contest)`); recordSecondProcessOwner(pid, { lane: peer?.lane, instanceId: peer?.instanceId, benign: true }); @@ -549,8 +546,6 @@ export class UnifiedStore { } writeFileSync(lockPath, JSON.stringify({ pid: process.pid, boot: Date.now() })); } catch (err) { - // #5046/B: a second-writer refusal is a decision, not a skipped discipline — it must propagate to the caller's degrade path, not be absorbed here. - if (err instanceof StorageSecondWriterError) throw err; loggerLog("warn", `[storage] lockfile discipline skipped for ${path}: ${String(err)}`); } try { diff --git a/tests/issue5046-second-writer-degrade.test.ts b/tests/issue5046-second-writer-degrade.test.ts index 31a3be3d83..3db55fcbe7 100644 --- a/tests/issue5046-second-writer-degrade.test.ts +++ b/tests/issue5046-second-writer-degrade.test.ts @@ -1,13 +1,25 @@ /** - * #5046/B (owner decision chain 2026-10-29 → 2026-10-30): a live foreign - * bili process holding .lock must make the proxy sidecar REFUSE TO START - * (throw StorageSecondWriterError — no-degradation-in-any-case) with one - * actionable error line (names BILI_SESSIONS_DIR + BILI_CONFIG_FILE) and - * status-wire visibility. Both directions pinned: live same-lane/unknown-lane - * foreign holder ⇒ refuse; no foreign holder ⇒ the original fast path is - * unchanged; dead-pid stale lock ⇒ takeover unchanged; cross-lane live holder - * ⇒ still opens (#5091 supported shared topology); the report-only default - * policy (CLI/export open paths) stays byte-identical. + * #5046/B policy evolution — final form (owner decision 2026-10-31): + * a live foreign bili process holding .lock NEVER blocks startup again, + * whatever lanes are involved. The 2026-10-29→30 refuse-to-start policy + * (same-lane / unknown-lane double-write shapes threw StorageSecondWriterError + * so boot died before listen) was withdrawn because sharing one index.db IS + * the supported topology (#5082/#5091): SQLite WAL is multi-process safe on a + * local filesystem, inline lanes never register in the instance registry, and + * real mixed-version fleets coexisted on one store for hours without incident. + * The condition stays LOUD (no silent degradation): an info-level log line + * names the peer, and the web/status wire surfaces the foreign pid via + * recordSecondProcessOwner. The genuine hazard — two instances writing the + * SAME session — keeps its own per-session alarm (the #3923 split-brain + * contest, pinned in tests/issue-split-brain-surface.test.ts). + * + * Pinned here: live same-lane foreign holder ⇒ still opens (regression of the + * exact bricked shape); mixed-version fleet marker WITHOUT lane ⇒ still opens + * (regression of the pi-inline shape); cross-lane live holder ⇒ opens + * (supported topology unchanged); dead-pid stale lock ⇒ takeover unchanged; + * no foreign holder ⇒ original fast path unchanged; the + * StorageSecondWriterError export survives for external code that still + * imports/catches it even though nothing inside this repo throws it anymore. */ import assert from "node:assert"; import { spawn } from "node:child_process"; @@ -103,7 +115,7 @@ after(() => { else process.env.BILI_LAUNCHER_LANE = savedLauncherLane; }); -test("#5046/B: live same-lane foreign holder ⇒ open REFUSES TO START (throw), lock untouched, actionable error + status wire", () => { +test("#5046/B final (2026-10-31): live SAME-lane foreign holder ⇒ open succeeds (the formerly-bricked shape), info reported, lock taken over, status wire names the peer", () => { if (!engineAvailable) return; _resetStorageRuntimeStatusForTest(); const state = freshState(); @@ -113,26 +125,38 @@ test("#5046/B: live same-lane foreign holder ⇒ open REFUSES TO START (throw), const logs: string[] = []; setLogCapture((_level, msg) => logs.push(msg)); withEnv({ XDG_STATE_HOME: state, BILI_LAUNCHER_LANE: "dsh" }, () => { - // 2026-10-30 "no degradation in any case": refused co-writing must - // THROW so boot dies before listen(), not return null + run legacy. - assert.throws( - () => UnifiedShadow.maybeOpen(sessions, { BILI_STORAGE_UNIFIED: "shadow" }, (r) => r as LegacySessionLike), - (err: unknown) => err instanceof StorageSecondWriterError, - "must REFUSE with StorageSecondWriterError, not open a second writer", - ); - const refused = logs.find((m) => m.includes("unified storage REFUSED")); - assert.ok(refused, `actionable error line expected, got: ${logs.join(" | ")}`); - assert.ok(refused!.includes("REFUSES TO START"), "the refusal must state its consequence"); - assert.ok(refused!.includes("BILI_SESSIONS_DIR") && refused!.includes("BILI_CONFIG_FILE"), "the fix must name both isolation vars"); - assert.equal(lockHolderPid(sessions), foreign.pid, "the foreign lock must NOT be stolen"); - // Pre-death diagnostic surface (#3040 visibility): the failure is - // recorded BEFORE the throw so post-crash forensics can read why. + // Owner decision 2026-10-31: whatever the lane math says, startup must + // NOT be blocked by a live second writer — this used to THROW here. + const shadow = UnifiedShadow.maybeOpen(sessions, { BILI_STORAGE_UNIFIED: "shadow" }, (r) => r as LegacySessionLike); + assert.ok(shadow, "a live same-lane foreign holder must NOT block startup anymore"); + assert.ok(logs.some((m) => m.includes("supported topology")), "#5082/#5091 shared-topology info notice expected"); + assert.ok(!logs.some((m) => m.includes("REFUSED")), "no refusal wording may remain"); + assert.equal(lockHolderPid(sessions), process.pid, "lockfile takeover behavior is unchanged"); + // Loud-but-not-blocking: the web/status wire still surfaces the peer. withEnv({ BILI_STORAGE_UNIFIED: "shadow" }, () => { const wire = storageStatusWire(); - assert.equal(wire.degraded, true, "status wire must record the failed open"); - assert.ok(wire.reason?.startsWith("second-writer:"), `reason should be the pre-formatted refusal, got: ${wire.reason}`); - assert.ok((wire.reason ?? "").includes("BILI_SESSIONS_DIR"), "wire reason must carry the fix"); + assert.ok(!wire.degraded, "coexistence is not a degradation"); + assert.equal(wire.secondProcess?.pid, foreign.pid, "live foreign pid stays surfaced on the status wire"); }); + shadow!.close(); + }); + setLogCapture(null); +}); + +test("#5046/B final: mixed-version fleet — old marker WITHOUT lane (inline/pre-#5046) ⇒ open succeeds (formerly refused)", () => { + if (!engineAvailable) return; + _resetStorageRuntimeStatusForTest(); + const state = freshState(); + const sessions = freshSessions(); + writeMarker(state, undefined); + writeLock(sessions, foreign.pid!); + const logs: string[] = []; + setLogCapture((_level, msg) => logs.push(msg)); + withEnv({ XDG_STATE_HOME: state, BILI_LAUNCHER_LANE: "dsh" }, () => { + const shadow = UnifiedShadow.maybeOpen(sessions, { BILI_STORAGE_UNIFIED: "shadow" }, (r) => r as LegacySessionLike); + assert.ok(shadow, "an unknown-lane peer must NOT block startup anymore (owner decision 2026-10-31)"); + assert.ok(!logs.some((m) => m.includes("REFUSED")), "no refusal wording may remain"); + shadow!.close(); }); setLogCapture(null); }); @@ -191,41 +215,11 @@ test("#5046/B negative: no foreign holder ⇒ original fast path (ENABLED line, setLogCapture(null); }); -test("#5046/B: mixed-version fleet — old marker WITHOUT lane ⇒ conservative branch REFUSES", () => { - if (!engineAvailable) return; - _resetStorageRuntimeStatusForTest(); - const state = freshState(); - const sessions = freshSessions(); - writeMarker(state, undefined); - writeLock(sessions, foreign.pid!); - const logs: string[] = []; - setLogCapture((_level, msg) => logs.push(msg)); - withEnv({ XDG_STATE_HOME: state, BILI_LAUNCHER_LANE: "dsh" }, () => { - assert.throws( - () => UnifiedShadow.maybeOpen(sessions, { BILI_STORAGE_UNIFIED: "shadow" }, (r) => r as LegacySessionLike), - (err: unknown) => err instanceof StorageSecondWriterError, - "unknown peer lane must stay conservative and refuse (no info-level amnesty)", - ); - assert.ok(logs.some((m) => m.includes("unified storage REFUSED"))); - }); - setLogCapture(null); -}); - -test("#5046/B: default policy (CLI/export direct open) stays report-only — store returned, lock taken over", () => { - if (!engineAvailable) return; - _resetStorageRuntimeStatusForTest(); - const state = freshState(); - const sessions = freshSessions(); - writeMarker(state, "dsh"); - writeLock(sessions, foreign.pid!); - const logs: string[] = []; - setLogCapture((_level, msg) => logs.push(msg)); - withEnv({ XDG_STATE_HOME: state, BILI_LAUNCHER_LANE: "dsh" }, () => { - const store = UnifiedStore.open(path.join(sessions, "index.db")); - assert.ok(store, "report-only paths (export/maintenance) keep running as before"); - assert.ok(logs.some((m) => m.includes("supported topology")), "#5091 report-only coexistence info line"); - assert.equal(lockHolderPid(sessions), process.pid, "report-only takeover unchanged"); - store.close(); - }); - setLogCapture(null); +test("#5046/B compat surface: StorageSecondWriterError is still exported (external importers/catch sites keep working) though nothing internal throws it", () => { + const err = new StorageSecondWriterError(12345, "/tmp/index.db"); + assert.ok(err instanceof StorageSecondWriterError); + assert.ok(err instanceof Error); + assert.equal(err.name, "StorageSecondWriterError"); + assert.equal(err.pid, 12345); + assert.equal(err.dbPath, "/tmp/index.db"); }); diff --git a/tests/multi-instance-live.test.ts b/tests/multi-instance-live.test.ts index 6ea8a5d74e..263ec264db 100644 --- a/tests/multi-instance-live.test.ts +++ b/tests/multi-instance-live.test.ts @@ -8,23 +8,34 @@ import { mkdtempSync, readdirSync, readFileSync } from "node:fs"; import { join } from "node:path"; import { rmrf } from "./tmp-rm.ts"; -// One LIVE proxy instance serving a session, plus a SECOND instance whose -// boot over the SAME sessions dir must be REFUSED (owner decision chain -// #5046 -> 2026-10-30 "no degradation in any case"). End-to-end proof that: -// 1. the surviving instance (A) keeps serving through real traffic and the -// on-disk record stays a valid envelope at EVERY observed moment -// (atomic tmp+rename), with stats.requests NEVER decreasing (#405 -// monotonic-counter guard under real traffic); -// 2. the late-starting instance B dies at boot with ONE actionable error -// (isolate via BILI_SESSIONS_DIR / BILI_CONFIG_FILE) and a non-zero -// exit code — NOT the old legacy-degraded coexistence. The old -// serve-guard-converge interleave (#394/#2401, former phases 2-4) is -// unreachable by construction now: the double-writer never starts. Its -// envelope guards remain pinned at unit level in -// tests/multi-instance-persist.test.ts and stay reachable through manual -// file edits. Cross-lane sharing (distinct lanes, one dir) stays SUPPORTED -// (#5082/#5091) and is pinned in -// tests/issue5046-second-writer-degrade.test.ts. +// Two LIVE proxy instances over one sessions dir (#394 shape, end-to-end). +// +// What is proven here — the documented contract only, not multi-writer +// coherence (src/persist.ts deliberately rejects an election/lock): +// 1. both instances keep serving through interleaved turns on the SAME +// session id (no crash, no head-of-line poisoning across processes); +// 2. the on-disk record stays a valid envelope at EVERY observed moment +// (atomic tmp+rename) while two processes write it; +// 3. stats.requests on disk NEVER decreases (the #405 monotonic-counter +// guard holds under real traffic, not just unit-shaped writes); +// 4. a stale resident's write is rejected AND the resident converges to the +// newer disk lineage (#2401) — observable as: A's post-convergence write +// is accepted and continues the DISK counter, not A's stale one; +// 5. the late-starting instance warns about the overlap (#394) at +// registration. +// +// NOT proven (documented residuals, pinned separately in +// tests/multi-instance-persist.test.ts): tie passthrough, counter catch-up +// re-clobber, content-store last-writer-wins. +// +// History: commit 5159ce9e (2026-10-30, #5046 "no degradation in any case") +// rewrote phases 2-4 into a boot-refusal assertion because a same-lane +// second writer over the unified index.db REFUSED to start. Owner decision +// 2026-10-31 withdrew that block (whatever lanes are involved, a second-writer +// condition never blocks startup — sharing one index.db is the supported +// topology, #5082/#5091), and this suite restored the serve/guard/converge +// interleave. Both children now run BILI_STORAGE_UNIFIED=full so they share +// the SAME live index.db, exactly the fleet shape the refusal had bricked. const SESSION = "mi-live-session"; const MODEL = "claude-sonnet-4-5"; @@ -52,49 +63,6 @@ interface Child { stderr: string[]; } -interface Refusal { - exitCode: number | null; - stderr: string; -} - -/** Spawns a child that is expected to DIE AT BOOT (no MI_READY) and collects - * its exit code + full stderr — the refusal-policy counterpart of - * spawnChild's success path. */ -async function spawnChildRefusing(upstreamPort: number | string, env: NodeJS.ProcessEnv): Promise { - const proc = spawn(process.execPath, ["--import", "tsx", join(import.meta.dirname, "fixtures/multi-instance-child.ts"), String(upstreamPort)], { - env, - stdio: ["pipe", "pipe", "pipe"], - }); - let ready = false; - let stdoutBuf = ""; - const stderrChunks: string[] = []; - proc.stdout!.setEncoding("utf8"); - proc.stdout!.on("data", (c: string) => { - stdoutBuf += c; - if (stdoutBuf.includes("MI_READY")) ready = true; - }); - proc.stderr!.setEncoding("utf8"); - proc.stderr!.on("data", (c: string) => stderrChunks.push(c)); - const code = await new Promise((resolve, reject) => { - const timer = setTimeout(() => reject(new Error("child did not refuse within 30s")), 30_000); - proc.on("exit", (c) => { - clearTimeout(timer); - resolve(c); - }); - // A child that DID become ready violated the expectation — fail fast. - const poll = setInterval(() => { - if (ready) { - clearInterval(poll); - clearTimeout(timer); - proc.kill("SIGTERM"); - reject(new Error("child became READY — expected a boot refusal")); - } - }, 100); - proc.on("exit", () => clearInterval(poll)); - }); - return { exitCode: code, stderr: stderrChunks.join("") }; -} - async function spawnChild(upstreamPort: number | string, env: NodeJS.ProcessEnv): Promise { const proc = spawn(process.execPath, ["--import", "tsx", join(import.meta.dirname, "fixtures/multi-instance-child.ts"), String(upstreamPort)], { env, @@ -209,10 +177,11 @@ test("two live instances over one sessions dir: serve, guard, converge (#394/#40 const childEnv = (p: number): NodeJS.ProcessEnv => ({ ...process.env, // The global baseline preload pins BILI_STORAGE_UNIFIED=legacy process-wide; - // spread into every child it would keep them BOTH legacy — A would never - // write the sidecar lockfile and B would have nothing to refuse over - // (boot-refusal needs a live foreign writer holding the shared index.db). - // Pin the production default so the refusal contract runs like a real boot. + // spread into every child it would keep them BOTH legacy — neither would + // open the shared index.db, and this suite exists precisely to run two + // unifications over ONE live index.db (the fleet shape the 2026-10-30 + // refusal had bricked, restored per owner decision 2026-10-31). Pin the + // production default so both children run like real boots. BILI_STORAGE_UNIFIED: "full", BILI_SESSIONS_DIR: sessionsDir, XDG_STATE_HOME: stateDir, @@ -247,31 +216,45 @@ test("two live instances over one sessions dir: serve, guard, converge (#394/#40 const warmed = await waitFor(sessionsDir, (v) => v.requests >= 3, "A's 3 turns persisted"); assert.equal(warmed.requests, 3, "each turn must count exactly once"); - // Phase 2 (rewritten 2026-10-30, owner chain "#5046 -> no degradation - // in any case"): instance B booting over the SAME sessions dir now - // REFUSES TO START — exit 1 with the actionable isolation error — - // instead of the old serve-legacy-degraded coexistence. Consequence: - // the former Phase 3/4 stale-write + converge/tie interleave below is - // UNREACHABLE BY CONSTRUCTION (the second writer never runs); those - // envelope guards stay pinned at unit level in - // tests/multi-instance-persist.test.ts and remain reachable through - // manual/multi-process file edits. Cross-LANE sharing (distinct - // BILI_LAUNCHER_LANE) remains the supported shared topology (#5082/ - // #5091, pinned in tests/issue5046-second-writer-degrade.test.ts). - const b = await spawnChildRefusing(upstreamPort, childEnv(2)); - assert.equal(b.exitCode, 1, "instance B must die at boot, not serve degraded"); - assert.ok( - b.stderr.includes("unified storage REFUSED") && b.stderr.includes("REFUSES TO START"), - `B's death must carry the actionable refusal (stderr tail: ${b.stderr.slice(-400)})`, - ); - assert.ok(b.stderr.includes("BILI_SESSIONS_DIR"), "refusal names the fix"); + // Phase 2 — instance B boots over the SAME dir (boot-hydrates the + // session), serves 2 turns. B's writes must be fresh (accepted). + // Owner decision 2026-10-31: B sees a LIVE foreign writer holding the + // shared index.db — that must NEVER block startup, so B comes up fully. + children.push(await spawnChild(upstreamPort, childEnv(2))); + const B = children[1]!; + await turn(B, 4); + await turn(B, 5); + await waitFor(sessionsDir, (v) => v.requests >= 5, "B's turns persisted (fresh lineage accepted)"); + + // B registered last: it must have seen A and warned (#394). + const bErr = B.stderr.join(""); + assert.ok(bErr.includes("#394"), "late starter must warn about the overlapping instance"); + assert.ok(bErr.includes("another bili instance"), `unexpected warn text: ${bErr.slice(-400)}`); + + // Phase 3 — the STALE resident: A never re-read the file (its pool + // entry is resident), so A's counter (3+1=4) is behind disk (5). Its + // write must be REJECTED (#405) and A must converge (#2401). + await turn(A, 6); + await new Promise((r) => setTimeout(r, 300)); + const aErr1 = A.stderr.join(""); + assert.ok(aErr1.includes("rejected stale snapshot"), `stale write must be rejected (stderr tail: ${aErr1.slice(-500)})`); + + // Phase 4 — A's next write continues from the CONVERGED (disk) + // counter: 5+1=6, accepted; disk must show exactly 6. + await turn(A, 7); + const converged = await waitFor(sessionsDir, (v) => v.requests >= 6, "A's post-convergence write accepted"); + assert.equal(converged.requests, 6, "converged resident must continue the DISK counter, not its stale one"); - // A is UNAFFECTED by B's refused boot: it keeps serving fresh turns - // and the on-disk counter advances exactly as before. - await turn(A, 4); - await turn(A, 5); - const servedAfterRefusal = await waitFor(sessionsDir, (v) => v.requests >= 5, "A kept serving through B's refused boot"); - assert.equal(servedAfterRefusal.requests, 5, "A's turns count exactly once each"); + // End-state: the session still serves through BOTH instances. B is now + // itself behind (its resident counter is 5, disk is 6 after A's accepted + // write), so B's turn lands on the documented TIE: equal request + // counters + equal nextBlockId → staleDiskPayload returns null → the + // write passes through (last-writer-wins on ties, persist.ts:76-87). + // Either way the file must stay valid and the counter non-decreasing — + // the reader loop below is the real teeth for that. + await turn(B, 8); + const final2 = await waitFor(sessionsDir, (v) => v.requests >= 6, "B serves after A's convergence"); + assert.equal(final2.requests, 6, "disk counter reflects the last accepted lineage (B tie-passthrough at 6)"); // Reader loop verdict. clearInterval(reader); assert.ok(reads > 10, `reader loop ran (reads=${reads})`); diff --git a/website/config-reference/env-only.yaml b/website/config-reference/env-only.yaml index 4326d25d69..9c20d49708 100644 --- a/website/config-reference/env-only.yaml +++ b/website/config-reference/env-only.yaml @@ -55,9 +55,9 @@ entries: default: "on" kind: env-only audience: user - desc_zh: "存储开库自检(#4175):每次 index.db 打开在迁移之前先跑 PRAGMA quick_check;一旦由本次启动自己的扫描证实损坏,文件原样保留在原地——不做任何自动搬移、复制或重建(自动恢复已撤回:BILI_STORAGE_JSON_WRITER=off 时索引是唯一的持久副本,自动操作无法保证完整数据恢复)——bili 照常启动,改用 JSON 信封服务,并给出响亮、可操作的告警指明手工修复步骤(备份后把 index.db/-wal/-shm 手工移开再启动——全新索引会从 JSON 信封重建)。PASS 判定会被缓存,之后的启动跳过重扫;FAIL 判定永不持久化(2026-10-30 owner 策略):运行期/后台发现只是告警(响亮日志 + runtime-status,进程继续服务——JSON 信封始终是恢复来源),每次启动都对当前文件集做新鲜扫描再判定,旧版本遗留的陈旧 FAIL 永远不能阻断后续启动。既没有自动改名/修复,也没有 legacy-only 兜底(继续以 legacy-only 运行会让 JSON 信封与死掉的索引永久分叉、再无对账可能)。瞬态打开失败(无引擎 / CANTOPEN / 第二写者 / 只读 / 后端 DSN)仍响亮地拒绝启动并给出可操作的错误——环境类问题同样不允许静默走 legacy 兜底;真正需要纯 JSON 服务的部署请显式设置 BILI_STORAGE_UNIFIED=legacy(或留空)。仅当超大部署对启动耗时敏感、检测成本构成问题时才设 0 跳过。" + desc_zh: "存储开库自检(#4175):每次 index.db 打开在迁移之前先跑 PRAGMA quick_check;一旦由本次启动自己的扫描证实损坏,文件原样保留在原地——不做任何自动搬移、复制或重建(自动恢复已撤回:BILI_STORAGE_JSON_WRITER=off 时索引是唯一的持久副本,自动操作无法保证完整数据恢复)——bili 照常启动,改用 JSON 信封服务,并给出响亮、可操作的告警指明手工修复步骤(备份后把 index.db/-wal/-shm 手工移开再启动——全新索引会从 JSON 信封重建)。PASS 判定会被缓存,之后的启动跳过重扫;FAIL 判定永不持久化(2026-10-30 owner 策略):运行期/后台发现只是告警(响亮日志 + runtime-status,进程继续服务——JSON 信封始终是恢复来源),每次启动都对当前文件集做新鲜扫描再判定,旧版本遗留的陈旧 FAIL 永远不能阻断后续启动。既没有自动改名/修复,也没有 legacy-only 兜底(继续以 legacy-only 运行会让 JSON 信封与死掉的索引永久分叉、再无对账可能)。瞬态打开失败(无引擎 / CANTOPEN / 只读 / 后端 DSN)仍响亮地拒绝启动并给出可操作的错误——环境类问题同样不允许静默走 legacy 兜底(活的第二写者已于 2026-10-31 移出该拒绝清单:多进程共享一个本地盘 index.db 是受支持拓扑,只提示、永不阻断启动);真正需要纯 JSON 服务的部署请显式设置 BILI_STORAGE_UNIFIED=legacy(或留空)。仅当超大部署对启动耗时敏感、检测成本构成问题时才设 0 跳过。" group: envonly - desc_en: "Storage integrity self-check at open (#4175): every index.db open runs PRAGMA quick_check BEFORE migrations; if a corruption is PROVEN by THIS BOOT's own scan NOTHING is moved, copied or rebuilt automatically (auto-recovery was withdrawn #4609/#4626-era: with BILI_STORAGE_JSON_WRITER=off the index is the SOLE durable copy, so an automatic move or rebuild cannot guarantee full data recovery) and bili STARTS ANYWAY — serving from the JSON envelopes with a loud, actionable alarm naming the manual fix (back up then move index.db/-wal/-shm aside BY HAND, then start again — a fresh index rebuilds from the JSON envelopes). A successful PASS is cached so later starts skip the rescan; a FAIL verdict is NEVER persisted (2026-10-30 owner policy): runtime/background findings are alarms only (loud logs + runtime-status, the process keeps serving — JSON envelopes remain the recovery source) and every boot decides again from a fresh scan of the CURRENT file set, so a stale FAIL left behind by an older version can never block future boots. There is NO automatic rename/repair AND no legacy-only fallback: continuing legacy-only would fork the JSON envelopes from the dead index forever (never reconcilable). TRANSIENT open failures (no SQLite engine / CANTOPEN / second writer / readonly / backend DSN) make bili REFUSE TO START loudly with an actionable error — no silent legacy fallback for environment problems either (2026-10-30 owner policy); deployments that genuinely want JSON-only serve explicitly (BILI_STORAGE_UNIFIED=legacy or unset). Set 0 only for boot-time-sensitive huge deployments where the check's cost matters." + desc_en: "Storage integrity self-check at open (#4175): every index.db open runs PRAGMA quick_check BEFORE migrations; if a corruption is PROVEN by THIS BOOT's own scan NOTHING is moved, copied or rebuilt automatically (auto-recovery was withdrawn #4609/#4626-era: with BILI_STORAGE_JSON_WRITER=off the index is the SOLE durable copy, so an automatic move or rebuild cannot guarantee full data recovery) and bili STARTS ANYWAY — serving from the JSON envelopes with a loud, actionable alarm naming the manual fix (back up then move index.db/-wal/-shm aside BY HAND, then start again — a fresh index rebuilds from the JSON envelopes). A successful PASS is cached so later starts skip the rescan; a FAIL verdict is NEVER persisted (2026-10-30 owner policy): runtime/background findings are alarms only (loud logs + runtime-status, the process keeps serving — JSON envelopes remain the recovery source) and every boot decides again from a fresh scan of the CURRENT file set, so a stale FAIL left behind by an older version can never block future boots. There is NO automatic rename/repair AND no legacy-only fallback: continuing legacy-only would fork the JSON envelopes from the dead index forever (never reconcilable). TRANSIENT open failures (no SQLite engine / CANTOPEN / readonly / backend DSN) make bili REFUSE TO START loudly with an actionable error — no silent legacy fallback for environment problems either (2026-10-30 owner policy; a live second writer left this refusal list on 2026-10-31 — sharing one local-disk index.db is the supported topology, informational only, never blocking); deployments that genuinely want JSON-only serve explicitly (BILI_STORAGE_UNIFIED=legacy or unset). Set 0 only for boot-time-sensitive huge deployments where the check's cost matters." - key: BILI_SNAPSHOT_SHADOW type: boolean default: "true (on)"