Skip to content

CLI surface for storage maintenance: bili sessions ls/rm/archive/restore + bili storage gc (re-scoped from #3860) #3928

Closed

Description

@ranxianglei

What

#3911 gave storage maintenance an HTTP surface (POST /__bili/storage/gc, POST /__bili/storage/restore, ?vacuum=full, storage.archiveAfterDays default 365). It deliberately shipped without a CLI entry. This issue tracks the CLI follow-up re-scoped out of #3860 (closed): a thin command layer over the same store APIs.

Scope

  • bili sessions ls — id, label, size (decoded bytes), last-updated, storage status (active/archived).
  • bili sessions rm <id> — full delete (the existing deleteSession discipline: content refcount release incl. media, tombstone-free).
  • bili sessions archive <id> / restore <id> — wrap archiveSession/restoreArchived (single archive.jsonl log).
  • bili storage gc [--days N] [--vacuum full|incremental] [--dry-run] — wrap store.gc(), print the sweep plan (sessions to archive, rows to release, pages to reclaim) before executing; --dry-run prints only.

Non-goals

Acceptance

  • ls/rm/archive/restore/gc --dry-run demonstrated against a scratch store in tests; gc end-to-end matches the HTTP path's results (same archived/contentRowsDeleted numbers).
  • Docs: README storage section + CONFIGURATION mention the CLI forms.

Context: re-filed from #3860 (superseded by #3911 for the store layer).

Activity

  1. ranxianglei commented on Oct 20, 2026

    @ranxianglei
    OwnerAuthor

    🤖 Powered by ework · qwen3.8-27b

    (ai: vllm-qwen/qwen3.8-27b)

    查重: 不重复。#3860(原 bili sessions ls/rm/prune PR)已由你关闭并明确重定为本 issue;#3911 已合入 master(store 层 + HTTP 面);本地留有 #3860 的分支 2026-10-19_sessions-cleanup 作先前实现参考(其 store 层部分基于 #3911 之前的代码,CLI 接线与安全语义可复用)。无其他开放条目涉及该 CLI 面。

    标签: scope/storage + p2(存储维护入口缺失家族,与 #3830/#3860 同档)。功能请求,不打 bug。

    开工前三个范围判断(都按 issue 字面执行,如有异议喊停):

    1. rm 保持薄封装——直接走既有 deleteSession(含 media/CAS 引用计数释放、tombstone-free),不加 [PR] feat: add supported session cleanup (bili sessions ls/rm/prune + VACUUM) #3860 里的「活跃会话拒绝 + --force」层。理由:issue 非目标写明「纯 CLI 管道 + 人类可读输出」,且用户显式输入了精确 id。删除前打印一行将被释放的规模摘要(消息数/内容行数),不做交互确认(脚本友好)。
    2. ls 在 shadow 模式下降级为 JSON 树视图(与 bili export 列表同路径),unified/full 模式走 DB 汇总行——两模式都有输出,不静默空表。
    3. gc --dry-run 的计划用只读查询拼出(按 cutoff 筛选待归档会话 + 零引用行数 + 页数估算),不改任何 store 语义;若现有公开方法不足以拼计划,最多加一个只读方法,绝不动写路径。

    开始动手:先核对 ff 后 master 上的 API 形态,再落 src/cli.ts 接线 + 新模块 + 测试(scratch store 演示 ls/rm/archive/restore/gc --dry-run,gc 端到端数字对齐 HTTP 路径),最后补 README/CONFIGURATION 文档。

  2. ranxianglei commented on Oct 20, 2026

    @ranxianglei
    OwnerAuthor

    🤖 Powered by ework · qwen3.8-27b

    (ai: vllm-qwen/qwen3.8-27b)

    **PR: #3958 #3928)。分支 2026-10-20_storage-maintenance-cli,单 commit c62da893f,typecheck 干净,定向测试全绿(新套件 7/7 + storage-archive-gc 5/5 + cli-export 2/2),全量回归交给 CI。

    交付的命令面

    bili sessions ls                          # id、label、解码后大小、最后更新、存储状态(active/archived)
    bili sessions rm <id> [--no-vacuum]       # 完整删除(走既有 deleteSession 引用计数纪律,含媒体),随后收缩 index.db
    bili sessions archive <id>                # 导出到单一追加日志 archive/archive.jsonl + 清行(墓碑保留身份)
    bili sessions restore <id>                # 从日志行恢复
    bili storage gc [--days N] [--vacuum full|incremental] [--dry-run]   # 先打印清扫计划再执行;--dry-run 只打印
    

    全部支持 --json;archive/restore/gc 在 legacy-only 安装上拒绝并给出 BILI_STORAGE_UNIFIED 提示(与 HTTP 侧 501 同措辞);--days 默认走既有的 storage.archiveAfterDays(365)解析链。首条回复里说明的三个范围决定(rm 保持薄封装、ls 大小取文件解码字节+DB 状态、gc 计划只读查询)均已按此实现。

    结构化八问

    1. 是什么问题:存储维护([PR] Storage wrap-up, nine items in one batch: GC/archive + reap ledger + media CAS + incremental pointers + dsh generation c | 存储收尾九项一车:GC/archive + reap 台账 + 媒体 CAS + 增量指针 + dsh 代压缩默认开 + 多实例文档 (#3901) #3911)只有 HTTP 入口,没有 CLI——用户不开代理、不 curl 面板就无法查看/删除/归档/恢复会话或触发 gc。
    2. 什么原因导致的:不是缺陷,是 [PR] Storage wrap-up, nine items in one batch: GC/archive + reap ledger + media CAS + incremental pointers + dsh generation c | 存储收尾九项一车:GC/archive + reap 台账 + 媒体 CAS + 增量指针 + dsh 代压缩默认开 + 多实例文档 (#3901) #3911 的范围决策(HTTP 先行、CLI 另立 issue),本 issue 即那个后续。
    3. 影响范围与严重程度:纯新增命令面,不触碰任何既有路径;此前该操作仅 HTTP 可达(需要代理在跑)。
    4. 怎么修复的:薄命令层——cli.ts 只做参数解析与分发,全部存储访问收敛在新模块 src/storage-maintenance.ts,复用与 HTTP 端点相同的 facade 方法(unifiedGc/unifiedArchiveSession/unifiedRestoreArchived)。gc 的 --dry-run 用只读查询(gcPlan(),与 gc() 同一 cutoff SQL)打印计划后执行同一个 unifiedGc() 调用,所以 CLI 与 HTTP 的结果数字结构性一致——测试里对等价 scratch store 直接调 store.gc() 钉死了 archived/contentRowsDeleted 相等。
    5. 是否有回归问题:审过的既有行为:removeLegacyFile 重构为委托共享的 removeSessionFiles(候选集逐一对齐:relPathFor×2 + flatFileNameFor + content-store 配对);sessionSummaries()/webSummaryRows() 新增 status 字段(additive,/__bili/sessions JSON 每行多一个 key,无既有字段变动);store 写路径与 gc 语义零改动(gcPlan 纯 SELECT,vacuum(mode) 是物理收缩原语,SQLITE_BUSY 重试沿用 [PR] feat: add supported session cleanup (bili sessions ls/rm/prune + VACUUM) #3860 验证过的写法)。相邻套件本地通过;高危模式逐项过:无语义漂移、无吞错变化、无阈值/时序/输出格式变动。
    6. 是否破坏缓存:不涉及(未触碰缓存/重试/增量游标/去重键)。
    7. 是否改了设计方向:不涉及——按 issue 非目标执行:无新 store 语义、无调度器(按需运行)。
    8. 是否引入了新的配置:无——--days 映射到既有 storage.archiveAfterDays,没有新 env/config 字段。

    store 层的四处 additive 能力(gcPlan/contentZeroRefReport/sessionStorageStats/vacuum(mode) + summaries 的 status 列)在 PR 描述里已逐一点名;#3860 旧分支的安全语义与 stats/vacuum SQL 已适配到 #3911/#3927 单日志存储层并在此复用。等 CI 绿后可合。

  3. 4 remaining items

  4. added a commit that references this issue on Oct 24, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions